Steamworks 문서
Steam Cloud
요약
Steam Cloud는 플레이어가 Steam에 로그인하여 어느 컴퓨터에서도 저장된 게임에 접근할 수 있도록 귀사의 게임 파일을 Steam 서버에 자동 저장합니다.
통합 레벨
Steamworks 웹사이트에서 파일 경로를 구성해야 합니다. 선택 사항으로, 업로드, 다운로드, 열거 및 삭제를 위해 게임 코드에서 Steaworks로 일부 API 호출이 필요합니다.

Steam Cloud 개요

Steam Cloud는 게임을 위한 간편하고 투명한 원격 저장소 시스템을 제공합니다. 자동 클라우드 환경 설정에서 지정한 파일이나, 클라우드 API를 사용하여 디스크에 작성, 생성, 수정, 삭제한 파일은 게임 종료 후 자동으로 Steam 서버에 복제됩니다.

사용자가 다른 컴퓨터를 사용하면 게임이 실행되기 전에 해당 파일이 자동으로 새 컴퓨터에 다운로드됩니다. 다운로드가 완료되면 게임은 클라우드 API를 통해 파일을 읽거나 평소처럼 디스크에서 바로 읽어 파일에 접근할 수 있습니다. 동영상 설정과 같은 기기 전용 구성은 피하세요.

Steam 클라이언트는 사용자의 모든 컴퓨터에서 파일의 동기화를 유지하기 위한 작업을 수행합니다.

클라우드 동기화를 비활성화하려면 Steam 설정에 있는 클라우드에서 "동기화를 지원하는 애플리케이션에 대해 Steam Cloud 동기화 사용"을 선택 해제하세요.

또한, 각 게임의 속성에서 게임별로 클라우드 동기화를 비활성화할 수 있습니다.

Spacewar_Cloud_Properties.png

참고 및 모범 사례


Steam은 게임의 모든 세션 전후로 사용자의 Steam Cloud 파일을 동기화한다는 점을 기억하시길 바랍니다. 세션 중 변경되는 모든 파일은 종료 즉시 클라우드 저장소에 업로드됩니다. 귀사의 게임이 Steam Cloud에 대용량 파일 또는 많은 개수의 작은 파일을 작성하는 경우, 사용자의 인터넷 대역폭에 눈에 띄는 영향을 줄 수 있으며, Steam 종료 또는 게임 재시작 속도를 늦출 수 있습니다.

일반적으로, 더 작은 크기의 파일을 사용하는 것이 효과적입니다. 특정 사용자의 저장 상태를 자주 변경되는 부분과 그렇지 않은 부분 등 다양한 범주로 나눌 수 있는 경우, 해당 범주에 대한 별도의 파일을 사용하는 것이 좋습니다. 이렇게 하면, 변경되지 않은 상태는 매 세션이 끝난 후에 다시 업로드되지 않습니다.

파일 크기 제한


Steam Cloud의 파일 크기 제한은 시간 경과에 따라 변경될 수 있습니다. 제한 및 임계 값은 다음과 같습니다.

크기제한 사항
100MBISteamRemoteStorage::FileWrite 또는 ISteamRemoteStorage::FileWriteStreamWriteChunk 호출을 위한 최대 크기
256MB사용자가 최적화되지 않은 저장 공간을 엔드포인트로 지정했을 경우 업로드 및 다운로드 성능에 부정적인 영향을 미칠 수 있습니다.

Save File Paths

When deciding where to write your save files, be sure the path will be unique for the current Steam user. If needed, you can get the user's unique Steam ID via ISteamUser::GetSteamID. From that, you can access their accountID from GetAccountID(), allowing you to have a unique variable when constructing your save path.

Cross-Platform Saves


If your game is supported on multiple platforms - or even if you plan to support this in the future - you should consider this when setting up Steam Cloud for your game.

If you plan to read/write files directly via the ISteamRemoteStorage interface, then you can control platform sync via ISteamRemoteStorage::SetSyncPlatforms. The default for a new file is to sync to all platforms.

If you plan to use Steam Auto-Cloud, there are some key things to know. First, the default for new files is to sync to only the OS setting on the associated Auto Cloud Root path. This means that if you set up distinct roots for each OS, all files will be partitioned by platform, and hence there will be no cross-platform save functionality.

To enable cross-platform saves, you should instead define a single Root path (likely for Windows), and then create Root Overrides for the other supported platforms. Files matching a given Root path which also has platform Root Overrides will sync to all platforms in both the origianal Root and all Overrides. See the Steam Auto-Cloud documentation for more details.

초기화 설정

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 및 Steam 자동 클라우드

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 Example Application (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 자동 클라우드

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.
참고: steam_autocloud.vdf 파일은 Steamworks 클라우드 경로로 지정된 각각의 위치에 생성됩니다. 이 파일은 Steam에서 사용되며 게임에서 무시할 수도 있습니다.

Setup

After completing the 초기화 설정 the Steam Auto-Cloud configuration section will unlock on the Steam Cloud Settings page.

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. 루트

    게임 내용이 저장되는 위치를 나타내는 경로 목록으로, 미리 정해져 있습니다.
    루트지원되는 OS대응 경로
    앱 설치 디렉터리모두[Steam Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocuments모두플랫폼별로 다른 경로. Linux의 경우: ~/.SteamCloud/[username]/[Game Folder]/
    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/

    A note regarding the Windows %USERPROFILE% paths: The corresponding paths listed above are the default locations. It is now possible for the user to configure their Windows installation so that these folders are in different locations (not necessarily under %USERPROFILE%). Steam uses the necessary Windows APIs to find the current location of these folders, whether they are default or customized.

  2. 하위 디렉터리

    루트와 관련하여 클라우드화된 파일의 하위 디렉터리 경로. 하위 디렉터리가 없으면 `.`을 사용하세요.

    자동 클라우드 특수 경로 값
    자동 클라우드는 Subdirectory 경로에서 Steam 사용자의 고유 식별자 사용을 허용합니다. 이를 통해 각 사용자의 저장 파일을 컴퓨터에 개별적으로 보관할 수 있습니다. 게임에서 ISteamUser::GetSteamID를 사용하면 저장하거나 읽기 위해 현재 사용자의 SteamID 또는 AccountID를 가져올 수 있습니다.
    • {64BitSteamID} - Steam 경로에 이 변수를 사용해 사용자의 64비트 Steam ID를 삽입하세요. 64비트 Steam ID의 예: 76561198027391269
    • {Steam3AccountID} - Steam 경로에 이 변수를 사용해 사용자의 Steam 3 계정 ID를 삽입하세요. 계정 ID의 예: 67125541
    예: SavesDir/{64BitSteamID}
  3. 패턴

    일치를 위한 파일 마스크 패턴. * 기호를 와일드카드로 사용할 수 있습니다. 디렉터리에 있는 모든 파일을 원하는 경우, * 기호를 사용하면 됩니다.

    예: *.sav
  4. OS

    파일과 동기화할 OS를 설정합니다. 이 작업은 파일의 OS가 서로 다른 경우에만 필요하며, 이러한 작업이 필요 없는 편이 더 좋습니다.
  5. 반복

    일치하는 파일을 검색할 때 하위 디렉터리를 포함합니다. 이 방법은 하위 디렉터리의 이름이 Steam 사용자 이름이나 Steam ID가 아닌 불명확한 이름일 경우에 유용합니다. 하위 디렉터리가 Steam ID를 사용할 경우에는 하위 디렉터리 필드에 특수 경로를 사용할 것을 강력 추천합니다.

Root Overrides

If your application is cross-platform and requires different directories for each OS. 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. If you use Root Overrides, you must specify [All OSes] in the Root OS drop down above.

A Root Override consists of 5 parts.
  1. 기본 루트

    기본 루트는 위에서 설정한 루트 중 하나에 해당합니다.
  2. OS

    재정의를 적용할 OS입니다.
  3. 새 루트

    지정된 OS에서 기본 루트가 매핑하는 새로운 위치입니다.
  4. 경로 추가 및 교체

    새 루트와 기본 하위 디렉터리 사이에 하위 디렉터리를 추가할 수 있게 해줍니다.
  5. 경로 교체

    활성화할 경우, ‘원래 하위 디렉터리를 경로 추가 및 교체’에서 지정한 경로로 완전히 교체합니다.

Example: Configuring Auto-Cloud for Unity Applications

The following is an example of setting up Auto-Cloud for use with Unity and the Application.persistentDataPath property where the value is different per OS. 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.

With these settings, Auto-Cloud files will be synchronized between the three folders as shown in the Preview samples.

Cloud_Unity_Auto-Cloud_Example.png

Pre-release Testing

If you are adding Steam Auto-Cloud to a game which is already released and you have enabled developer-only mode during the 초기화 설정 then you must complete some additional steps to test the functionality.
  1. 테스트하고자 하는 앱을 소유하는 계정으로 Steam에 로그인하세요.
  2. 브라우저에서 steam://open/console로 이동하여 Steam 콘솔을 여세요.
  3. 콘솔에 테스트하고자 하는 앱 ID를 testappcloudpaths <AppId>의 형식으로 입력하세요. 예: testappcloudpaths 480
  4. 콘솔에 set_spew_level 4 4를 입력하세요.
  5. Steam에서 앱을 실행하세요.
  6. 콘솔 활동을 확인하세요. 파일이 자동 클라우드 경로에 이미 존재하는 경우 해당 파일이 업로드되는 것을 확인할 수 있습니다. 그렇지 않은 경우, 앱에서 파일 몇 개를 저장한 후 콘솔을 닫아 동기화가 시작되도록 하세요.
  7. 다른 컴퓨터로 위 단계를 반복하여 Steam 자동 클라우드에서 파일을 다운로드하는 테스트를 진행하세요.
  8. 지원되는 모든 시스템에서 테스트해 보세요.
  9. Set testappcloudpaths 0 and set_spew_level 0 0 to end testing. 콘솔 탭을 없애려면 Steam 클라이언트를 다시 시작하세요.

Don't forget to disable developers-only mode and publish the changes when you're done testing.

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.

Check out our announcement post for even more information about why this feature exists, and how to use it.

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

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.

Pre-release Testing


You can locally enable Dynamic Cloud Sync for your app to test your builds - this is recommended for a game that has already shipped, as enabling Dynamic Cloud Sync for all users could lead to data loss when running builds that do not handle the new API methods and callbacks.

To test locally from a PC:

  1. Sign in to Steam with an account that owns the app that you are testing.
  2. Open the Steam Console by navigating to steam://open/console in your browser. (You can also run Steam with the command-line steam -console and then navigate to the Console section directly).
  3. Enter @cloud_testdynamicsyncapp <AppId> into the console with the given App ID that you are testing. Ex: @cloud_testdynamicsyncapp 480
  4. Launch your app from Steam.
  5. Progress through the game to a desired amount
  6. In the Steam Console, enter prepare_for_suspend. Steam will suspend your game process and upload any changed files to the Steam Cloud.
  7. Optional: play the game on another device, creating further progress, and then exit and let that Steam client upload progress to the Steam Cloud.
  8. Back on the original device, in the Steam Console, enter resume_suspended_games. This will sync down any necessary files from the Steam Cloud, post the relevant API calls to your game, then un-suspend your game process.

To test locally from a Steam Deck:

  1. Connect your Steam Deck with a Devkit
  2. To use the CEF Console, see here
  3. In the JS console, enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) to enable testing. You can then enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) to disable it

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 Debugging the Steamworks API for additional information.