XGameSave API를 사용하면 게임 저장 데이터를 관리하기 위한 blob과 컨테이너를 관리할 수 있습니다. Microsoft Game Development Kit(GDK) 타이틀의 게임 저장에는 XGameSaveFiles를 권장합니다. XGameSaveFiles가 옵션이 아닐 때는 XGameSave를 사용하세요.
XGameSave에 대한 시스템 API 참조는 XGameSave(API 콘텐츠)를 참조하세요.
XGameSave에서 다음 용어가 자주 나타납니다.
- 잠금: 활성적으로 사용하는 디바이스에서 특정 사용자에 대한 타이틀의 게임 저장에 대한 배타적 접근을 부여하는 메커니즘입니다. 잠금이 유지되는 동안 다른 디바이스가 사용자의 게임 저장을 수정할 수 없도록 보장합니다.
- 예를 들어, 사용자가 디바이스 A에서 타이틀 T를 플레이하면 해당 사용자의 타이틀 T에 대한 잠금을 갖게 됩니다.
- 공급자: 게임 저장 시스템과 통신하며 타이틀 데이터 관리를 담당하는 중개 프로세스입니다. 공급자는 또한 디바이스에서 사용자의 잠금을 관리합니다.
- 컨테이너: 폴더에 해당합니다.
- Blob: 개별 파일에 해당합니다.
공급자 관리
저장 공간을 획득하려면 게임이 공급자를 초기화해야 합니다. 연결 후 타이틀은XGameSaveInitializeProvider 또는 XGameSaveInitializeProviderAsync를 호출하여 타이틀의 클라우드 스토리지에 대한 잠금을 획득하려고 시도합니다.
타이틀이 연결 손실로 인해 클라우드에서 동기화하는 데 실패하는 경우, 사용자가 오프라인 모드에서 계속 플레이할 수 있는지 여부를 결정하세요.
타이틀은 일시 중단되거나 종료될 때 XGameSaveCloseProvider로 공급자를 닫아야 합니다. 공급자는 일시 중단-재개 경계를 넘어 다시 사용할 수 없습니다.
이 문제는
XGameSave에만 적용됩니다. XGameSaveFiles는 자동으로 공급자를 닫습니다.컨테이너 관리
동기화가 완료되기 전에 컨테이너를 만드는 것과 같이 컨테이너에 접근할 때 데이터 손실을 피하려면XGameSaveEnumerateContainerInfo 또는 XGameSaveEnumerateContainerInfoByName을 호출하여 사용자가 가진 컨테이너를 확인하세요.
XGameSaveCreateContainer를 사용하여 새 컨테이너 또는 기존 컨테이너에 대한 컨테이너 핸들을 가져옵니다. 컨테이너가 이미 있으면 해당 핸들이 제공됩니다. 컨테이너가 없으면 새 컨테이너가 만들어지고 해당 핸들이 제공됩니다.
컨테이너를 삭제하려면 XGameSaveDeleteContainer를 사용합니다. 컨테이너 내의 모든 blob도 삭제됩니다.
핸들 누수를 방지하려면 컨테이너가 더 이상 사용되지 않거나 타이틀이 일시 중단되거나 종료될 때 XGameSaveCloseContainer로 모든 컨테이너 핸들을 닫으세요.
Blob 관리
컨테이너 내의 데이터 조작은XGameSaveCreateUpdate를 호출하여 수행됩니다.
다음 세부 정보는 XGameSaveUpdate가 컨테이너 내 blob 변경 사항을 관리하는 방법과 각 업데이트가 어떻게 만들어지고, 수정되고, 제출되는지를 개괄합니다.
- 업데이트는 하나의 컨테이너에 적용됩니다.
- 업데이트는 최대 GS_MAX_BLOB_SIZE(16MB)를 쓸 수 있습니다.
- 하나의 업데이트에서 여러 blob을 수정할 수 있습니다.
- 단일 blob은 업데이트당 하나의 수정만 가질 수 있습니다.
-
업데이트를 제출하면
XGameSaveUpdate핸들이 소비됩니다. 제출이 성공하든 실패하든 핸들을 닫으세요. - 업데이트는 원자적입니다. 일부가 실패하면 전체 업데이트가 실패합니다.
-
XGameSaveCreateUpdate는 모든 blob 수정 사항을 저장할 업데이트 컨텍스트를 만듭니다. -
XGameSaveSubmitBlobWrite는 새 blob 또는 기존 blob에 데이터를 쓰며 업데이트된 컨텍스트가 필요합니다. -
XGameSaveSubmitBlobDelete는 blob을 삭제합니다. -
XGameSaveSubmitUpdate는 업데이트 컨텍스트를 제출합니다. -
XGameSaveCloseUpdate는 업데이트 핸들을 닫습니다. 누수를 방지하기 위해 타이틀은 매 제출 후에 이를 호출합니다. -
컨테이너 내의 모든 blob에 접근하려면
XGameSaveEnumerateBlobInfo또는XGameSaveEnumerateBlobInfoByName을 사용합니다.
Blob에 쓰인 데이터는 XML로 내보낼 때
Base64로 표현됩니다.구현
다음 단계에서는XGameSave 구현의 일반적인 흐름을 보여 줍니다.
- 타이틀 시작 또는 재개 시 공급자를 초기화합니다.
- 컨테이너 핸들을 열거하고 만듭니다.
- Blob 수정 사항이 포함된
XGameSaveUpdates를 주기적으로 제출하고 제출 시 업데이트 핸들을 정리합니다. - 타이틀 일시 중단 또는 종료 시 컨테이너 및 공급자 핸들을 닫습니다.
타이틀이 시작될 때와 재개될 때
XGameSaveInitializeProvider를 호출합니다. 이 호출은 공급자가 올바르게 초기화되고 타이틀이 실행되는 동안 활성 상태로 유지되도록 보장합니다. 호출되지 않으면 타이틀이 예측할 수 없게 동작할 수 있습니다.코드 샘플
XGameSave API 사용 방법을 보여 주는 코드 샘플은 GameSaveCombo를 참조하세요.
게임 저장 흐름
다음은 단순화된 게임 저장 흐름의 순서도입니다. 다음과 같이 설명됩니다.타이틀 시작
타이틀 시작은 사용자가 타이틀을 실행하거나 재개할 때 발생합니다.사용자 사인인
타이틀이 사용자 사인인을 시작합니다.XGameSaveInitializeProvider도 이 호출에서 호출합니다.
사용자 설정에 대한 자세한 내용은 사용자 모델을 참조하세요.
연결 확인
타이틀이 XBOX 네트워크에 연결할 수 있는지 결정합니다. 연결할 수 없으면 타이틀에 대한 오프라인 모드를 활성화하는 것은 사용자의 몫입니다.데이터 소유권 확인
디바이스는 사용자가 현재 다른 디바이스에서 플레이하고 있는지 확인합니다. 한 번에 하나의 디바이스만 특정 타이틀에 대한 사용자의 데이터에 접근할 수 있습니다.클라우드와 데이터 동기화
디바이스가 게임 저장 로컬 스토리지 데이터를 클라우드와 동기화합니다. 충돌이 있는 경우 시스템은 충돌 해결 대화상자로 사용자에게 요청합니다. 대화상자: 어느 것을 사용하시겠습니까? 디바이스의 데이터가 클라우드 데이터보다 최신인 경우, 타이틀은 사용자에게 로컬 데이터를 사용할지 클라우드 데이터를 사용할지 선택하도록 요청합니다.게임 플레이 루프
타이틀은 게임 저장 로컬 스토리지에 자유롭게 읽고 쓸 수 있습니다.게임 세션 종료
게임 세션이 종료되면 시스템은 자동으로 클라우드에 데이터 업로드를 시도합니다. 공급자를 초기화된 상태로 두지 않도록 타이틀이 종료 흐름에서XGameSaveUninitializeProvider를 호출하는지 확인하세요. 구조화된 종료는 종료하기 전에 데이터가 깔끔하게 저장되도록 보장합니다.
자세한 동기화 정보는 게임 저장 동기화 흐름 이해를 참조하세요.
제한 및 할당량
제한
XGameSaveUpdate는 각 업데이트를 16MB로 제한합니다. 따라서 XGameSave는 최대 16MB까지의 개별 파일 업데이트만 관리할 수 있습니다. 이 제한은 최대 64MB까지의 파일을 지원하는 XGameSaveFiles와 다릅니다.
할당량
사용자가 타이틀당 저장할 수 있는 최대 데이터는 256MB입니다. 남은 할당량을 가져오려면 XGameSaveGetRemainingQuota를 사용합니다. 타이틀의 스토리지 확장을 위해서는 개발자 파트너 관리자(DPM)에게 문의하세요.모범 사례
- 데이터를 저장한 다음 즉시 동일한 데이터를 다시 쿼리하고 요청하지 마세요.
- 컨테이너 간 데이터 종속성은 신뢰할 수 없습니다. 각
XGameSaveSubmitUpdate호출은 모든 변경 사항을 원자적으로 적용하거나 전혀 적용하지 않습니다. - 업데이트 호출당 사용하는 blob이 많을수록 데이터 저장을 위한 파일 시스템 작업의 필요한 원자적 작업을 완료하는 데 더 많은 시간이 필요합니다.
FAQ
게임 저장 구현을 업그레이드하고 있습니다. 올바른 접근 방식은 무엇인가요?
XGameSaveFiles를 사용하세요.XGameSave를 XGameSaveFiles와 함께 사용할 수 있나요?
예. 그러나 마이그레이션 목적으로만 사용하세요. 자세한 내용은 XGameSave와 XGameSaveFiles 간 상호 운용성을 참조하세요.XGameSave는 어떤 파일 경로에 저장하나요?
콘솔: 타이틀이 활성 상태인 동안 임시 경로가 제공됩니다. 콘솔 파일은 파일 탐색기를 사용하여 접근할 수 없습니다. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
XGameSave의 PC 경로는 XGameSaveFiles와 다릅니다. xgs를 사용합니다.