[Steam] Steam Cloud

원문: https://partner.steamgames.com/doc/features/cloud 

Steam Cloud (Steamworks Documentation)

Steam Cloud

Steamworks Documentation > Features > Steam Cloud

요약
Steam Cloud는 사용자의 게임 파일을 자동으로 Steam 서버에 저장하여, 플레이어가 Steam에 로그인하고 어느 컴퓨터에서든 저장된 게임에 접근할 수 있게 해줍니다.

통합 수준
Steamworks 웹사이트에서 파일 경로의 설정이 필요합니다. 선택적으로, 업로드, 다운로드, 열거, 삭제를 위해 게임 코드 내에서 Steamworks로 일부 API 호출이 필요합니다.

Steam Cloud 개요

Steam Cloud는 게임에 대해 투명하고 쉬운 원격 파일 저장 시스템을 제공합니다. Auto-Cloud 구성에서 지정된 파일 또는 Cloud API를 사용하여 디스크에 작성된 파일(생성, 수정, 삭제 등)은 게임이 종료된 후 자동으로 Steam 서버에 복제됩니다.

사용자가 컴퓨터를 변경하면, 파일들은 게임이 시작되기 전에 새로운 컴퓨터로 자동 다운로드됩니다. 그러면 게임은 Cloud API를 통해 파일에 접근하거나, 평소처럼 디스크에서 직접 파일을 읽을 수 있습니다. 비디오 설정과 같은 기기 특정 설정은 피하세요.

Steam 클라이언트는 사용자가 접근할 수 있는 모든 컴퓨터에서 파일이 동기화되도록 보장하는 작업을 수행합니다.

사용자는 Steam 설정의 Cloud에서 "Enable Steam Cloud synchronization for applications which support it"를 선택 취소함으로써 전역적으로 Cloud 동기화를 비활성화할 수 있습니다.

사용자는 각 게임의 속성에서 게임별로 Cloud 동기화를 비활성화할 수도 있습니다.

내용과 사용 추천 사항

Steam은 모든 세션 전후로 사용자의 Steam Cloud 파일을 동기화하므로 이 점을 기억하는 것이 중요합니다. 세션 동안 변경되는 일치하는 파일은 세션 직후 즉시 Cloud 저장소에 업로드됩니다. 만약 게임이 매우 큰 파일이나 많은 작은 파일을 Steam Cloud에 작성한다면, 이는 사용자의 인터넷 대역폭에 눈에 띄는 영향을 미치고 Steam을 종료하거나 게임을 재실행하는 능력을 지연시킬 수 있습니다.

일반적으로, 더 작은 파일이 더 잘 작동합니다. 주어진 사용자의 저장 상태를 자주 변경될 수 있는 것과 자주 변경되지 않을 수 있는 것 - 이러한 카테고리로 나눌 수 있다면, 이러한 카테고리에 대해 별도의 파일을 사용하는 것을 추천합니다. 그럼으로써, 변경되지 않은 상태는 모든 세션 후에 다시 업로드되지 않을 것입니다.

파일 크기 제한

Steam Cloud에 대한 파일 크기의 절대적인 제한은 시간이 지남에 따라 변경될 수 있습니다. 다음은 일부 현재 제한과 임계값입니다:

크기	제한
100MB	ISteamRemoteStorage::FileWrite 또는 ISteamRemoteStorage::FileWriteStreamWriteChunk 호출에 대한 최대 크기
256MB	사용자 위치에 대해 최적화되지 않은 저장 엔드포인트 선택으로 이어질 수 있으며, 업로드/다운로드 성능에 부정적인 영향을 미침

저장 파일 경로

저장 파일을 작성할 위치를 결정할 때, 경로가 현재 Steam 사용자에게 고유하게 설정되어야 합니다. 필요한 경우, ISteamUser::GetSteamID를 통해 사용자의 고유한 Steam ID를 얻을 수 있습니다. 그럼으로써, GetAccountID()에서 accountID에 접근할 수 있어, 저장 경로를 구성할 때 고유한 변수를 가질 수 있습니다.

크로스 플랫폼 저장

게임이 여러 플랫폼에서 지원되거나, 심지어 미래에 이를 지원할 계획이 있다면, 게임의 Steam Cloud를 설정할 때 이를 고려해야 합니다.

ISteamRemoteStorage 인터페이스를 통해 파일을 직접 읽고/쓰려는 계획이라면, ISteamRemoteStorage::SetSyncPlatforms를 통해 플랫폼 동기화를 제어할 수 있습니다. 새 파일의 기본 설정은 모든 플랫폼에 동기화하는 것입니다.

Steam Auto-Cloud를 사용할 계획이라면, 알아둘 중요한 점들이 있습니다. 첫째, 새 파일의 기본 설정은 연결된 Auto Cloud Root 경로의 OS 설정에만 동기화하는 것입니다. 이는 각 OS에 대해 별도의 루트를 설정하면, 모든 파일이 플랫폼별로 분할되고, 따라서 크로스 플랫폼 저장 기능이 없을 것이라는 것을 의미합니다.

크로스 플랫폼 저장을 활성화하려면, 대신 단일 Root 경로(아마도 Windows)를 정의하고, 다른 지원 플랫폼들에 대해 Root Overrides를 생성해야 합니다. 플랫폼 Root Overrides가 있는 주어진 Root 경로와 일치하는 파일은 원래의 Root와 모든 Overrides에 있는 모든 플랫폼에 동기화됩니다. 자세한 내용은 Steam Auto-Cloud 문서를 참조하세요.

초기 설정

Steam Cloud를 설정하려면 Steamworks 앱 관리 패널의 Steam Cloud 설정 페이지에서 사용자 당 바이트 할당량과 사용자 당 허용된 파일 수 옵션을 설정해야 합니다.

이 할당량은 각 Cloud 활성화 게임에서 사용자당 게임당 기준으로 적용됩니다. 게임 타이틀에 대해 합리적인 값으로 설정하는 것이 좋습니다.

주의: 페이지 하단에서 저장을 클릭하는 것을 잊지 마시고, 설정을 업데이트하여 게시하세요. 게시하면 Cloud 아이콘이 Steam 클라이언트에서 게임을 소유한 모든 사람에게 보일 것입니다.

게임이 이미 공개로 출시되었다면, '개발자 전용으로 클라우드 지원 활성화' 라벨이 붙은 상자를 체크할 수 있습니다. 개발자 전용 모드가 활성화되면, 게임 타이틀에 대해 "개발자 Comp" 라이선스를 소유한 Steam 계정만이 Cloud 아이콘을 볼 수 있고, Steam Cloud를 사용할 수 있습니다. 이는 공개 사용자 경험을 손상시키지 않고 안전하게 Steam Cloud 통합을 테스트하는 데 유용합니다. 아무도 아직 게임을 소유하지 않은 미출시 게임에는 영향이 없습니다. 그들은 특정 앱 ID에 대한 어떤 클라우드 저장소도 볼 수 없거나 접근할 수 없습니다.

Shared cloud APP ID 필드를 작성함으로써 두 앱 ID간에 Cloud 저장 공간을 공유할 수 있습니다. 이는 주로 데모와 전체 게임 사이에서 저장된 게임을 공유하는 데 가장 자주 사용됩니다. 값이 0이면 이 기능을 비활성화합니다.

Steam Cloud API와 Steam Auto-Cloud

Steam은 Steam Cloud를 활용하는 두 가지 다른 방법을 제공합니다. 두 방법이 어떻게 다른지 알아보고, 어떤 것이 귀하의 애플리케이션에 가장 적합한지 결정하세요.

먼저, Steam Cloud API입니다.
Cloud API는 Steam Cloud를 게임에 직접 통합할 수 있도록 하는 일련의 함수를 제공합니다. Cloud API는 개별 Steam 사용자 파일을 서로 격리하고 Steam Cloud에 대한 보다 높은 수준의 제어를 제공합니다.

Steam Cloud API는 ISteamRemoteStorage API 인터페이스를 통해 공개되며, Steamworks API 예제 애플리케이션(SpaceWar) 프로젝트에서 사용 예제를 찾을 수 있습니다.

두 번째는 Steam Auto-Cloud입니다.
Steam Auto-Cloud는 Steam Cloud API를 통합하지 않기로 선택한 게임을 위해 설계되었습니다. 빠르고 쉽게 시작할 수 있는 방법을 제공하지만, Steam Cloud API에서 가능한 유연성은 부족합니다.

Steam Cloud와 더 깊은 통합을 선호한다면(예를 들어, 클라우드에 저장되는 저장 파일을 선택할 수 있게 하는 등), Cloud API를 사용해야 합니다. 그렇지 않다면 Steam Auto-Cloud를 사용할 수 있습니다.

Steam Auto-Cloud

Steam Auto-Cloud는 코드 작성이나 게임을 어떤 방식으로도 수정하지 않고 앱이 Steam Cloud를 사용하게 해주는 Steam Cloud API의 대안입니다. 단지 Cloud에 유지하려는 파일 그룹을 지정하면 됩니다. Steam은 애플리케이션이 실행되고 종료될 때 자동으로 파일 그룹을 동기화합니다. 비디오 품질과 같은 기계별 설정은 피하세요.

참고: 파일 steam_autocloud.vdf는 Steamworks cloud 경로에 지정된 각 위치에 생성됩니다. 이 파일은 Steam에서 사용되며, 게임에서는 무시할 수 있습니다.

설정

초기 설정을 완료한 후에는 Steam Cloud Settings 페이지에서 Steam Auto-Cloud 설정 섹션을 열 수 있습니다.

루트 경로는 Steam Cloud에 지속적으로 저장될 파일 그룹을 설명합니다. 각 루트 경로는 단일 파일만큼 구체적일 수도 있고 주어진 하위 폴더 아래의 모든 파일을 포함할 수도 있습니다. 동기화할 각 파일 그룹에 대해 새 경로를 사용하세요.

루트 경로는 5부분으로 구성됩니다:

1. Root
게임 저장 파일이 일반적으로 위치하는 경로의 사전 결정된 목록입니다.

Root	지원 OS	실제 경로
App Install Directory	All	[Steam Install]\SteamApps\common[Game Folder]\
SteamCloudDocuments	All	모두 플랫폼별 경로, 예: Linux에서: ~/.SteamCloud/[username]/[Gmae Folder]/
WinMyDocuments	Windows	%USERPROFILE%\My Documents\
WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
WinSavedGame	Windows	%USERPROFILE%\Saved Games\
MacHome	macOS	~/
MacAppSupport	macOS	~/Library/Application Support/
MacDocuments	macOS	~/Documents/
LinuxHome	Linux	~/
LinuxXdgDataHome	Linux	$XDG_DATA_HOME/

Windows %USERPROFILE% 경로에 관한 주의 사항: 위에 나열된 해당 경로는 기본 위치입니다. 이제 사용자가 Windows 설치를 구성하여 이러한 폴더가 다른 위치에 있도록(반드시 %USERPROFILE% 아래에 있는 것은 아님) 설정할 수 있습니다. 기본 위치이든 사용자가 지정한 위치이든 상관없이, Steam은 이 폴더들의 현재 위치를 찾기 위해 필요한 Windows API를 사용합니다.

2. Subdirectory

"Root"에 상대적인 클라우드 파일에 대한 하위 디렉토리 경로입니다. 하위 디렉토리가 없다면 .을 사용하세요.

Auto-Cloud 특수 경로 값
Auto-Cloud는 하위디렉토리 경로에서 고유한 Steam 사용자 식별자의 사용을 허용합니다. 이를 통해 각 Steam 사용자의 저장 파일을 컴퓨터에서 별도로 저장할 수 있습니다. 게임에서 ISteamUser::GetSteamID를 사용하여 현재 사용자의 SteamID 또는 AccountID를 가져와 저장하고 읽을 수 있습니다.

• {64BitSteamID} - 스팀 경로에 이 변수를 사용하여 사용자의 64비트 스팀 ID를 삽입합니다. 64비트 스팀 ID는 이런 식입니다: 76561198027391269
• {Steam3AccountID} - 스팀 경로에 이 변수를 사용하여 사용자의 스팀 3 계정 ID를 삽입합니다. 계정 ID는 이런 식입니다: 67125541

예시: SavesDir/{64BitSteamID}

3. Pattern

일치시키려는 파일들의 유형을 결정합니다. 와일드 카드(해당 확장자 파일 모두 포함)인 *를 사용할 수 있습니다. 디렉토리의 모든 파일을 원한다면 *를 사용하세요.

예시: *.sav
(.sav로 끝나는 모든 종류의 파일 선택)

4. OS

이 파일들이 어느 운영체제로부터/어느 운영체제로 동기화될지 설정합니다. 이는 파일이 운영체제에 특화되어 있는 경우에만 필요하며, 이런 경우는 되도록 피해야 합니다!

5. Recursive(하위 포함)

파일 검색이 하위 디렉토리를 포함할지 여부를 결정하는 기능입니다. 이 기능은 특히 파일이 스팀 사용자 이름 또는 ID와 같은 예측 불가능한 이름을 가진 하위 디렉토리에 위치해 있을 때 유용합니다. 스팀 ID를 사용하는 경우에는 하위 디렉토리 필드에서 특별한 경로 값을 사용하는 것이 좋습니다.

Root Overrides

만약 귀하의 어플리케이션이 다중 플랫폼을 지원하며 각 OS에 대해 다른 디렉토리가 필요한 경우, Root Overrides 기능을 사용하여 위에서 설정한 Root Paths에 대한 오버라이드를 지정할 수 있습니다.

위에서 지정한 root 경로는 다른 OS에서 다른 경로에 해당하도록 오버라이드될 수 있습니다. Root Overrides를 사용하는 경우, 위의 Root OS 드롭다운에서 [All OSes]를 반드시 지정해야 합니다.

Root Override는 5개의 부분으로 구성됩니다.

1. Original Root
   이것은 위에서 설정한 Roots 중 하나에 해당합니다.
2. OS
   오버라이드를 적용할 운영체제입니다.
3. New Root
   지정된 OS에서 Original Root가 매핑되는 새로운 위치입니다.
4. Add/Replace Path
   이 기능을 사용하면 new root와 원래의 subdirectory 사이에 삽입되는 subdirectory path를 선택적으로 추가할 수 있습니다.
5. Replace Path
   이 기능이 활성화되면, Add/Replace Path에서 지정한 경로가 원래의 subdirectory를 완전히 대체하게 됩니다.

예제: 유니티 애플리케이션을 위한 오토-클라우드 설정

다음은 Unity와 Application.persistentDataPath 속성을 사용하여 Auto-Cloud를 설정하는 예제입니다. 이 속성의 값은 OS마다 다릅니다. Windows 버전은 Root Path로 설정되며, Unity의 회사는 DefaultCompany로 설정되고 프로젝트 이름은 AutocloudSample입니다. macOS와 Linux/SteamOS에서는 Application.persistentDataPath에서의 대체 경로가 Add/Replace Path 필드에 설정되며, Replace Path는 활성화됩니다.

이러한 설정을 사용하면 Auto-Cloud 파일이 미리보기 샘플에 표시된 세 폴더 사이에서 동기화됩니다.

사전 릴리스 테스트

이미 출시된 게임에 Steam Auto-Cloud를 추가하고 초기 설정에서 개발자 전용 모드를 활성화한 경우, 기능을 테스트하기 위해 추가적인 단계를 완료해야 합니다.

1. 테스트하려는 앱을 소유한 계정으로 Steam에 로그인합니다.
2. 브라우저에서 steam://open/console로 이동하여 Steam 콘솔을 엽니다.
3. 콘솔에 테스트하려는 특정 앱 ID와 함께 testappcloudpaths <AppId>를 입력합니다. 예: testappcloudpaths 480
   콘솔에 set_spew_level 4 4를 입력합니다.
4. Steam에서 앱을 실행합니다.
5. 콘솔에서 활동을 확인합니다. 
6. Auto-Cloud 경로에 이미 파일이 있으면 업로드되는 것을 볼 수 있어야 합니다. 그렇지 않다면 앱에서 일부 파일을 저장한 다음 앱을 닫아 동기화를 트리거합니다.
7. 다른 PC로 이동하고 위의 단계를 반복하여 Steam Auto-Cloud에서 파일을 다운로드하는 것을 테스트합니다.
8. 모든 지원 운영 체제에서 테스트하는 것이 중요합니다.
9. testappcloudpaths 0과 set_spew_level 0 0를 설정하여 테스트를 종료합니다. 콘솔 탭을 없애려면 Steam 클라이언트를 재시작할 수 있습니다.

테스트를 완료하면 개발자 전용 모드를 비활성화하고 변경 사항을 게시하는 것을 잊지 마세요.

Dynamic Cloud Sync

Steam Cloud는 이제 동적 동기화를 지원합니다 - 클라우드에 나타나는 변경 사항을 애플리케이션 세션이 실행 중인 로컬 기기로 다운로드할 수 있습니다. 현재의 예는 Steam Deck에서 중단된 게임 세션입니다. 동적 클라우드 동기화를 지원한다고 표시된 앱의 경우, Steam은 중단 시점에서 파일을 Steam Cloud까지 동기화합니다. 그런 다음, 사용자는 다른 기기에서 게임을 실행할 수 있으며, 이 기기는 시작 시에 Steam Deck 세션의 업데이트를 받게 됩니다. 종료 시, 해당 변경 사항은 Steam Cloud로 업로드됩니다. 마지막으로, Steam Deck 기기가 깨어나면 Steam은 변경 사항을 해당 기기로 동기화하고, 로컬 파일이 변경되었다는 알림을 애플리케이션에 전달합니다. 그러면 애플리케이션은 그러한 변경 사항을 반복하고 적절한 조치를 취할 수 있습니다. 예를 들어, 게임은 간단히 디스크에서 업데이트된 진행 상황을 로드하고 사용자가 다른 기기에서 마지막으로 중단한 지점에서 계속 진행하도록 할 수 있습니다.

이 기능이 왜 존재하는지, 그리고 이를 어떻게 사용하는지에 대한 더 많은 정보를 얻으려면 저희의 공지 게시물을 확인해보세요.

이 기능은 ISteamRemoteStorage API를 이용해 파일을 관리하거나 Auto-Cloud를 사용하는 애플리케이션을 지원합니다.

자세한 내용은 ISteamRemoteStorage 문서를 참조하십시오. 특히 ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, ISteamRemoteStorage::GetLocalFileChange를 확인해 보세요.

또한 ISteamRemoteStorage::BeginFileWriteBatch 및 ISteamRemoteStorage::EndFileWriteBatch를 참고하십시오 - 이 래퍼들은 사용자가 시스템 중단을 시작할 때 Steam이 Steam Cloud까지 안전하게 동기화할 수 있도록 Steam에 힌트를 제공하는 데 사용해야 합니다.

사전 릴리스 테스트

당신은 로컬에서 당신의 앱에 대해 Dynamic Cloud Sync를 활성화하여 빌드를 테스트 할 수 있습니다 - 이는 Dynamic Cloud Sync를 모든 사용자에게 활성화하면 새로운 API 메소드와 콜백을 처리하지 않는 빌드를 실행할 때 데이터 손실이 발생할 수 있으므로, 이미 출시된 게임에 권장됩니다.

PC에서 로컬로 테스트하려면:

1. 테스트할 앱을 소유한 계정으로 Steam에 로그인합니다.
2. 브라우저에서 steam://open/console로 이동하여 Steam 콘솔을 엽니다. (또는 명령줄 steam -console을 사용하여 Steam을 실행한 다음 직접 콘솔 섹션으로 이동할 수도 있습니다).
3. 콘솔에 @cloud_testdynamicsyncapp <AppId>을 입력하고 테스트하려는 주어진 앱 ID를 사용합니다. 예: @cloud_testdynamicsyncapp 480
4. Steam에서 앱을 시작합니다.
5. 게임을 원하는 양만큼 진행시킵니다.
6. Steam 콘솔에서 prepare_for_suspend를 입력합니다. Steam은 게임 프로세스를 중단하고 변경된 파일을 Steam Cloud에 업로드합니다.
7. 선택 사항: 다른 기기에서 게임을 플레이하여 추가 진행 상황을 만들고, 그런 다음 종료하고 해당 Steam 클라이언트가 진행 상황을 Steam Cloud에 업로드하도록 합니다.
8. 원래의 기기에서, Steam 콘솔에서 resume_suspended_games를 입력합니다. 이렇게 하면 Steam Cloud에서 필요한 파일을 동기화하고, 게임에 관련 API 호출을 게시하고, 게임 프로세스를 다시 시작합니다.

Steam Deck에서 로컬로 테스트하려면:

1. Devkit를 사용하여 Steam Deck를 연결합니다.
2. CEF 콘솔을 사용하려면 이곳을 참조하세요.
3. JS 콘솔에서 SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”)를 입력하여 테스트를 활성화합니다. 그런 다음 SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”)를 입력하여 비활성화 할 수 있습니다.

Debugging

먼저, 항상 Steam 파트너 웹사이트에서 변경 사항을 게시하고 최대 10분 동안 기다리거나 Steam 클라이언트를 재시작하여 게시된 변경 사항을 받았는지 확인해야 합니다.

Steam Cloud에서 문제가 발생하면 %Steam Install%\logs\cloud_log.txt 위치에 있는 로그 파일을 확인해야 합니다.

추가 정보는 'Steamworks API 디버깅하기'를 참조하세요.