เอกสาร Steamworks
คลาวด์บน Steam
In Brief
Steam Cloud automatically stores files from your game on Steam's servers so your players can log into Steam and access their saved games from any computer.
Level of integration
Configuration of file paths required on Steamworks website. Optionally, some API calls required from within game code to Steamworks for upload, download, enumerate, and delete.

ภาพรวมคลาวด์บน Steam

The Steam Cloud provides an easy and transparent remote file storage system for your game. Files specified in the Auto-Cloud configuration or written to disk (created, modified, deleted, etc.) using the Cloud API will automatically be replicated to the Steam servers after the game exits.

If the user changes computers, the files are automatically downloaded to the new computer prior to the game launching. The game can then access the files by reading them through the Cloud API or reading them directly from disk as usual. Avoid machine specific configurations such as video settings.

The Steam Client does the work of ensuring that the files are kept synchronized across all computers the user may be accessing.

Users can globally disable Cloud synchronization in the Steam Settings under Cloud by unchecking "Enable Steam Cloud synchronization for applications which support it."

Users can also disable the Cloud synchronization on a per game basis in each games properties.

Spacewar_Cloud_Properties.png

Notes and Best Practices


It is important to remember that Steam will synchronize the user's Steam Cloud files for your game before and after every session. Any matching files which change during the session will be uploaded to Cloud storage immediately afterward. If your game writes very large files, or many small files, to Steam Cloud, then this may cause a noticeable impact on the user's internet bandwidth and also delay their ability to shut down Steam or re-launch the game.

As a general rule, smaller files will work better. If the saved state for a given user can be split up into different categories - things which may change frequently, and things which may not change often - then we recommend using separate files for those categories. That way, the un-changed state will not be re-uploaded after every session.

File Size Limits


The absolute limits on file sizes for Steam Cloud may change over time. Here are some current limits and thresholds:

SizeRestriction
100MBMaximum size for a call to ISteamRemoteStorage::FileWrite or ISteamRemoteStorage::FileWriteStreamWriteChunk
256MBMay result in a non-optimal storage endpoint choice for the user's location, negatively impacting upload/download performance

Initial Setup

To set up Steam Cloud you must set the Byte quota per user and Number of files allowed per user options on the Steam Cloud Settings page in the Steamworks App Admin panel.

This quota is enforced on each Cloud-enabled game, on a per-user-per-game basis. It's recommended to set the values to reasonable amounts for your game title.

หมายเหตุ: Don't forget to click Save at the bottom of the page, and Publish your updated settings. Once published the cloud icon will be visible in the Steam client for anyone that owns your game.

If your game has already been released to the public then you can check the box labeled Enable cloud support for developers only. If developers-only mode is enabled then only the steam accounts which own a "Developer Comp" license for your title will see the cloud icon and will be able to use the Steam Cloud. This is useful to safely test Steam Cloud integration without breaking the public user experience. This has no effect on unreleased games since no one owns the game yet, they won't be able to see or access any cloud storage for the specific app ID.

You are able to share Cloud storage space between two app IDs by filling out the Shared cloud APP ID field. This is most commonly used to share saved games between a demo and a full game. A value of 0 disables this feature.

Steam Cloud API and Steam Auto-Cloud

Steam provides two different methods of utilizing the Steam Cloud, read up on how the two methods differ, and determine which would be the best for your application.

First up is the Steam Cloud API.
The Cloud API provides a series of functions which allows you to directly integrate the Steam Cloud into your game. The Cloud API isolates individual Steam users files from each other and provides a greater level of control over the Steam Cloud.

The Steam Cloud API is exposed via the ISteamRemoteStorage API interface, and you can find example usage in the แอปพลิเคชันตัวอย่างของ Steamworks API (SpaceWar) project.

The second is Steam Auto-Cloud.
Steam Auto-Cloud was designed for games where you choose to not integrate the Steam Cloud API. It provides a quick and easy way to get started but lacks the flexibility that is available with the Steam Cloud API.

If you prefer a deeper integration with Steam Cloud (for example, allowing to choose which save files are stored in the cloud), then you should use the Cloud API. Otherwise you can use Steam Auto-Cloud.

Steam Auto-Cloud

Steam Auto-Cloud is an alternative to the Steam Cloud API that allows apps to use Steam Cloud without writing code or modifying the game in any way. It only requires that you specify the file groups which you want persisted to the Cloud. Steam will automatically sync the groups of files when the application launches and exits. Avoid machine specific configurations such as video quality.
Note: The file steam_autocloud.vdf will be created in each location specified by your Steamworks cloud paths. ไฟล์นี้ใช้โดย Steam และเกมของคุณสามารถละเว้นได้

Setup

หลังจากดำเนินการ Initial Setup เสร็จแล้ว หมวดการกำหนดค่าคลาวด์อัตโนมัติบน Steam จะปลดล็อคบนหน้า การตั้งค่าคลาวด์บน Steam

Root Paths describe groups of files which will be persisted to the Steam Cloud. Each Root Path can be as specific as a single file or as wide as all files under a given subfolder. Use a new path for each group of files to sync.

A Root Path is composed of 5 parts:
  1. รูท

    รายการดังต่อไปนี้เป็นรายการของตำแหน่งที่กำหนดไว้ล่วงหน้า โดยเป็นสถานที่ที่ใช้เก็บบันทึกเกมตามปกติ
    รูทระบบปฏิบัติการที่รองรับตำแหน่งที่เกี่ยวข้อง
    App Install Directoryทั้งหมด[Steam Install]\SteamApps\common\[โฟลเดอร์เกม]\
    SteamCloudDocumentsทั้งหมดตำแหน่งที่เฉพาะเจาะจงต่อแพลตฟอร์ม เช่น บน Linux: ~/.SteamCloud/[ชื่อผู้ใช้]/[โฟลเดอร์เกม]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. ไดเรกทอรีย่อย

    ตำแหน่งไดเรกทอรีย่อยไปยังไฟล์บนคลาวด์ที่สัมพันธ์กับรูท ให้ใช้ `.` หากไม่มีไดเรกทอรีย่อย

    ค่าตำแหน่งพิเศษของคลาวด์อัตโนมัติ
    Auto-Cloud จะอนุญาตให้ใช้งานตัวบ่งชี้ผู้ใช้ Steam เฉพาะได้ในตำแหน่ง ไดเรกทอรีย่อย ซึ่งก็จะอนุญาตให้คุณจัดเก็บไฟล์เซฟให้กับผู้ใช้ Steam แต่ละคนแยกจากกันได้ บนเครื่องคอมพิวเตอร์เดียวกัน คุณสามารถใช้ ISteamUser::GetSteamID ในเกมของคุณเพื่อเรียกรับ SteamID หรือ AccountID ของผู้ใช้ปัจจุบันที่จะจัดเก็บและอ่านได้
    • {64BitSteamID} - ใช้ตัวแปรนี้ในตำแหน่งของ Steam เพื่อแทรกไอดี Steam แบบ 64 บิตของผู้ใช้ ไอดี Steam แบบ 64 บิต จะมีลักษณะดังนี้: 76561198027391269
    • {Steam3AccountID} - ใช้ตัวแปรนี้ในตำแหน่งของ Steam เพื่อแทรกไอดี Steam แบบ 3 บิตของผู้ใช้ ไอดีบัญชีจะมีลักษณะดังนี้: 67125541
    ตัวอย่างเช่น: SavesDir/{64BitSteamID}
  3. รูปแบบ

    รูปแบบมาสก์ของไฟล์ที่จะเทียบให้ตรงกัน คุณสามารถใช้ * เป็นอักขระตัวแทน (wildcard) ได้ หากคุณต้องการไฟล์ทุกไฟล์ที่อยู่ในไดเรกทอรี ก็ให้ใช้ *

    ตัวอย่างเช่น: *.sav
  4. ระบบปฏิบัติการ

    ใช้ตั้งค่าระบบปฏิบัติการที่ไฟล์เหล่านี้จะได้รับการซิงค์เข้าไป โดยจะจำเป็นต้องใช้ก็ต่อเมื่อไฟล์ดังกล่าวมีความเฉพาะเจาะจงต่อระบบปฏิบัติการ ซึ่งทางเราก็หวังว่าจะไม่มีความจำเป็นต้องใช้!
  5. รีเคอร์ซีฟ

    รวมไดเรกทอรีย่อย เมื่อค้นหาไฟล์ที่ตรงกัน ซึ่งจะมีประโยชน์ในการใช้งานกับไดเรกทอรีย่อยที่ไม่สามารถคาดการณ์ชื่อได้ เช่น ชื่อผู้ใช้ หรือไอดีที่ไม่ใช่ของ Steam เป็นต้น หากมีการใช้งานไอดี Steam เช่นนั้นแล้ว ขอแนะนำเป็นอย่างยิ่งให้ใช้ค่าตำแหน่งพิเศษในช่องข้อมูลไดเรกทอรีย่อย

Root Overrides

หากแอปพลิเคชันของคุณเป็นแบบข้ามแพลตฟอร์มและจำเป็นต้องมีไดเรกทอรีที่แตกต่างกันไปในแต่ละระบบปฏิบัติการ You can use the Root Overrides functionality to specify an override the Root Paths that you set above.

The root paths specified above can be overridden to correspond to a different path on another OS. หากคุณใช้การแทนที่รูท คุณจะต้องระบุเป็น [ระบบปฏิบัติการทั้งหมด] ในเมนูดรอปดาวน์ระบบปฏิบัติการรูทที่อยู่ด้านบน

การแทนที่รูทมีส่วนประกอบทั้งหมด 5 ส่วน
  1. รูทดั้งเดิม

    จะมีค่าเป็นหนึ่งในรูทที่คุณได้ตั้งค่าไว้ข้างต้น
  2. ระบบปฏิบัติการ

    ระบบปฏิบัติการที่จะใช้งานการแทนที่รูทดังกล่าว
  3. รูทใหม่

    ตำแหน่งใหม่ที่รูทดั้งเดิมได้แมปไว้บนระบบปฏิบัติการที่จะใช้งาน
  4. เพิ่ม/แทนที่ตำแหน่ง

    จะอนุญาตให้คุณสามารถเลือกที่จะเพิ่มตำแหน่งไดเรกทอรีย่อยที่แทรกเข้าไปอยู่ระหว่างรูทใหม่และไดเรกทอรีย่อยดั้งเดิมได้
  5. แทนที่ตำแหน่ง

    หากเปิดการใช้งาน ก็จะทำให้ตำแหน่งที่ได้ระบุเอาไว้ใน เพิ่ม/แทนที่ตำแหน่ง เข้าไปแทนที่ไดเรกทอรีย่อยดั้งเดิมทั้งหมดโดยสมบูรณ์

Example: Configuring Auto-Cloud for Unity Applications

ตัวอย่างต่อไปนี้เป็นการตั้งค่าคลาวด์อัตโนมัติสำหรับใช้งานกับ Unity และคุณสมบัติ Application.persistentDataPath ที่ค่าของข้อมูลจะแตกต่างกันไปตามระบบปฏิบัติการแต่ละแบบ The Windows version is configured as the Root Path with the company in Unity set to DefaultCompany and the Project called AutocloudSample. On macOS and Linux/SteamOS, the alternate paths from Application.persistentDataPath are set in the Add/Replace Path field and Replace Path is enabled.

ด้วยการตั้งค่าเหล่านี้ ไฟล์ของคลาวด์อัตโนมัติจะได้รับการซิงค์ไปมาระหว่างโฟลเดอร์ 3 โฟลเดอร์ตามที่ได้แสดงไว้ในตัวอย่าง

Cloud_Unity_Auto-Cloud_Example.png

Pre-release Testing

หากคุณต้องการเพิ่มค่าคลาวด์อัตโนมัติบน Steam ให้เกมที่วางจำหน่ายไปแล้ว และคุณได้เปิดการใช้งานโหมดเฉพาะผู้พัฒนาในระหว่าง Initial Setup คุณก็จะต้องดำเนินการขั้นตอนเพิ่มเติมบางขั้นตอนให้เสร็จสิ้นเพื่อทดสอบการใช้งานเสียก่อน
  1. เข้าสู่ระบบ Steam ด้วยบัญชีที่เป็นเจ้าของแอปที่คุณจะทดสอบ
  2. เปิดคอนโซลของ Steam ขึ้นมาแล้วไปยัง steam://open/consoleที่อยู่ในเบราว์เซอร์ของคุณ
  3. ตั้งค่า testappcloudpaths ลงไปในคอนโซลพร้อมกับไอดีแอปที่ต้องการจะทดสอบ ตัวอย่าง: testappcloudpaths 480
  4. ตั้งค่า set_spew_level 4 4 ลงไปในคอนโซล
  5. เรียกใช้งานแอปของคุณจาก Steam
  6. ตรวจสอบดูการดำเนินการต่าง ๆ ในคอนโซล หากมีไฟล์อยู่ในตำแหน่งของค่าคลาวด์อัตโนมัติเช่นนั้นแล้ว คุณก็ควรจะเห็นว่ากำลังมีการอัปโหลดไฟล์เหล่านั้น หากไม่เช่นนั้นแล้ว ก็ให้จัดเก็บไฟล์จากแอปของคุณ แล้วก็ให้ปิดแอปเสียเพื่อให้เรียกใช้งานกระบวนการซิงค์
  7. ไปยังเครื่องพีซีเครื่องอื่น และทำขั้นตอนต่าง ๆ ข้างต้นนี้ซ้ำอีกครั้ง เพื่อทดสอบการดาวน์โหลดไฟล์ดังกล่าวเหล่านั้นจากค่าคลาวด์อัตโนมัติบน Steam
  8. กรุณาตรวจสอบให้มั่นใจว่าได้ดำเนินการทดสอบกับระบบปฏิบัติการที่ได้รับการรองรับทั้งหมดแล้ว
  9. ตั้งค่า testcloudapppaths 0 และ set_spew_level 0 0 เพื่อสิ้นสุดการทดสอบ จากนั้นคุณสามารถรีสตาร์ตไคลเอนต์ Steam เพื่อปิดแท็บคอนโซลออกไปได้

เมื่อคุณดำเนินการทดสอบเสร็จเรียบร้อยแล้ว อย่าลืมปิดการใช้งานโหมดเฉพาะผู้พัฒนา แล้วเผยแพร่การเปลี่ยนแปลงเหล่านั้น

Dynamic Cloud Sync


Steam Cloud now supports dynamic sync - where changes appearing in the Cloud can be downloaded to the local machine during an application session. The current example is a suspended game session on the Steam Deck. For apps marked as supporting dynamic Cloud sync, Steam will synchronize files up to the Steam Cloud at the suspend time. Then, the user may run the game on another device, which will receive the updates from the Steam Deck session at launch. At exit, those changes will be uploaded to the Steam Cloud. Finally, when the Steam Deck device is awakened, Steam will synchronize the changes down to that device, and post a notification to the application that local files have changed. The application can then iterate those changes and take appropriate action. For instance, the game may be able to simply load the updated progress from disk and allow the user to pick up right where they left off on the other device.

Currently, the ability to flag an application as supporting dynamic Cloud sync is only available to Valve admins. Get in touch with your Valve contacts for more detail.

Note that this feature supports applications whether they use the ISteamRemoteStorage API to manage files, or AutoCloud.

For more details, see the ISteamRemoteStorage documentation, specifically ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, and ISteamRemoteStorage::GetLocalFileChange.

See also ISteamRemoteStorage::BeginFileWriteBatch and ISteamRemoteStorage::EndFileWriteBatch - these wrappers should be used to provide hints to Steam which will help it safely sync up to the Steam Cloud at the time when the user initiates a system suspend.

Debugging

First, always ensure that you have published your changes on the Steam partner website and have waited up to 10 minutes or restarted your Steam client to receive the published changes.

If you run into issues with Steam Cloud you should check the log file located at %Steam Install%\logs\cloud_log.txt.

See การดีบัก Steamworks API for additional information.