XGameSaveFilesGetFolderWithUIAsync를 초기화하는 방법을 설명합니다. 또한 권장되는 Win32 자동 클라우드 동기화 동작, 디버깅 단계, 할당량 및 진단 지침, 성능 모범 사례, 자주 묻는 질문에 대한 답변을 설명합니다.
XGameSaveFiles는 타이틀이 사용자 데이터를 읽고 쓰고, 세션 간에 유지하며, 플레이어가 어떤 디바이스에서도 데이터를 사용할 수 있도록 클라우드와 원활하게 동기화할 수 있게 해 주는 API를 제공합니다. Microsoft Game Development Kit(GDK) 타이틀의 게임 저장에는 XGameSaveFiles를 사용하세요. 해당 시나리오에서 XGameSaveFiles를 사용할 수 없는 경우에만 XGameSave를 사용하세요.
XGameSaveFiles에 대한 시스템 API 참조는 XGameSaveFiles(API 콘텐츠)를 참조하세요.
XGameSaveFiles에서 다음 용어가 자주 나타납니다.
- 잠금: 활성적으로 사용하는 디바이스에서 특정 사용자에 대한 타이틀의 게임 저장에 대한 배타적 접근을 부여하는 메커니즘입니다. 잠금이 유지되는 동안 다른 디바이스가 사용자의 게임 저장을 수정할 수 없도록 보장합니다.
- 예를 들어, 사용자가 디바이스 A에서 타이틀 T를 플레이하면 해당 사용자의 타이틀 T에 대한 잠금을 갖게 됩니다.
- 공급자: 게임 저장 시스템과 통신하며 타이틀 데이터 관리를 담당하는 중개 프로세스입니다. 공급자는 또한 디바이스에서 사용자의 잠금을 관리합니다.
- 컨테이너: 폴더에 해당합니다.
- Blob: 개별 파일에 해당합니다.
XGameSaveFiles 경로 로직
XGameSaveFiles는 게임 저장 시스템과 상호 작용하는 데 사용할 수 있는 파일 경로를 제공합니다. 이 파일 경로는 클라우드 동기화와 통합되어 있으므로 경로에 저장된 데이터가 클라우드에 자동으로 동기화됩니다. 제공된 경로에서 Win32 FileIO API를 사용하세요. GDK 타이틀의 경우, 게임 저장 접근 방식으로 XGameSaveFiles를 사용하세요. XGameSaveFiles는 컨테이너 개념을 폴더에, blob을 파일에 매핑합니다.
XGameSaveFiles는 클라우드 저장 시스템의 복잡성 대부분을 숨기지만, 이 기능이 Microsoft Azure Blob Storage에 의존하기 때문에 여전히 디렉터리 및 파일 이름 제한을 적용합니다. 타이틀이 저장에 사용할 수 있는 예제 코드를 살펴보세요.
XGameSaveFilesGetFolderWithUiAsync는 [ROOT]를 반환합니다.- [ROOT] 뒤부터 마지막 슬래시까지를 포함한 모든 것은 컨테이너에 매핑됩니다.
- 컨테이너 이름은 대문자(A-Z), 소문자(a-z), 숫자(0-9), 밑줄(_), 마침표(.), 하이픈(-), 슬래시(/)로 제한됩니다.
- 컨테이너 이름은 256자로 제한됩니다.
- 컨테이너 이름은 마침표로 끝날 수 없고, 두 개의 연속된 마침표를 포함할 수 없으며, 마침표나 하이픈으로 시작할 수 없습니다.
- 파일 이름의 마지막 슬래시 뒤에 오는 모든 것은 blob에 매핑됩니다.
- 파일 이름은 65자로 제한되지만, 그 외에는 NTFS(New Technology File System)가 지원하는 유니코드 문자일 수 있습니다.
- 파일 이름을 포함한 전체 결과 경로(단, [ROOT]는 제외)는
MAX_PATH(260자)보다 작아야 합니다.
XGameSaveFiles 구현
다음 단계에서는XGameSaveFiles의 일반적인 구현을 보여 줍니다.
- 타이틀 시작 또는 재개 시
XGameSaveFilesGetFolderWithUIAsync를 호출하여 공급자를 초기화하고 파일 경로를 가져옵니다. - 게임 플레이 중에 파일 경로에 자유롭게 읽고 씁니다.
XGameSaveFilesGetFolderWithUIAsync는 자동으로 게임 저장 공급자의 수명을 관리하고 게임 저장 로컬 스토리지 공간을 설정합니다.
타이틀이 시작될 때와 재개될 때
XGameSaveFilesGetFolderWithUIAsync를 호출하세요. 이 호출은 게임 저장 공급자를 초기화하고 게임 세션이 실행되는 동안 활성 상태로 유지합니다. 이 단계를 건너뛰면 시스템이 예측할 수 없게 동작할 수 있습니다.코드 샘플
XBOX에서 폴더에 접근하기 위해XGameSaveFiles API를 사용하는 방법을 보여 주는 코드 샘플은 GameSaveFilesCombo를 참조하세요.
게임 저장 흐름
다음은 단순화된 게임 저장 흐름의 순서도입니다.타이틀 시작
타이틀 시작은 사용자가 타이틀을 실행하거나 재개할 때 발생합니다.사용자 사인인
타이틀이 사용자 사인인 프로세스를 시작합니다. 이 작업에서XGameSaveFilesGetFolderWithUIAsync도 호출합니다. 사용자 설정에 대한 자세한 내용은 사용자 모델을 참조하세요.
연결 확인
타이틀이 XBOX 네트워크에 연결할 수 있는지 결정합니다. 연결할 수 없으면 타이틀에 대한 오프라인 모드를 활성화해야 합니다.데이터 소유권 확인
디바이스는 사용자가 현재 다른 디바이스에서 플레이하고 있는지 확인합니다. 한 번에 하나의 디바이스만 특정 타이틀에 대한 사용자의 데이터에 접근할 수 있습니다.클라우드와 데이터 동기화
디바이스가 게임 저장 로컬 스토리지 데이터를 클라우드와 동기화합니다. 충돌이 있는 경우 시스템은 충돌 해결 대화상자로 사용자에게 요청합니다. 대화상자: 어느 것을 사용하시겠습니까? 디바이스의 데이터가 클라우드 데이터보다 최신인 경우, 타이틀은 사용자에게 로컬 데이터를 사용할지 클라우드 데이터를 사용할지 선택하도록 요청합니다.게임 플레이 루프
타이틀은XGameSaveFilesGetFolderWithUIAsync가 제공한 폴더 경로에 자유롭게 읽고 쓸 수 있습니다.
게임 세션 종료
게임 세션이 종료되면 시스템은 자동으로 클라우드에 데이터 업로드를 시도합니다. 이 프로세스는 타이틀이 종료된 후 약 10~30초 후에 발생합니다. 자세한 동기화 정보는 게임 저장 동기화 흐름 이해를 참조하세요.제한 및 할당량
제한
XGameSaveFiles를 사용하여 저장할 수 있는 최대 파일 크기는 64MB입니다. 이 동작은 각 파일을 16MB로 제한하는 XGameSave와 다릅니다.
할당량
사용자가 타이틀당 저장할 수 있는 최대 데이터는 256MB입니다. 남은 할당량을 가져오려면 XGameSaveFilesGetRemainingQuota를 사용합니다. 타이틀에 더 큰 사용자당 스토리지 제한을 부여하기 위해 스토리지 확장을 얻으려면 개발자 프로그램 관리자(DPM)에게 문의하세요.FAQ
XGameSaveFiles를 XGameSave와 함께 사용할 수 있나요?
예. 그러나 마이그레이션 목적으로만 이 접근 방식을 사용하세요. 자세한 내용은 XGameSave와 XGameSaveFiles 간 상호 운용성을 참조하세요.XGameSaveFiles는 어떤 파일 경로에 저장하나요?
콘솔: 타이틀은 활성 상태인 동안 임시 경로를 제공합니다. 파일 탐색기를 사용하여 콘솔 파일에 접근할 수 없습니다. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
XGameSaveFiles의 PC 경로는 XGameSave와 다릅니다. wgs를 사용합니다.
데이터가 저장되어야 하는 경로를 지정할 수 있나요?
예. 하지만 PC에서만 가능합니다. 다른 타이틀에서 솔루션을 이식하는 경우에만 이 접근 방식을 권장합니다. 이 솔루션은 코드 없는 클라우드 저장을 사용합니다.참고 API 문서
참고 항목
게임 저장 TOC 예. 하지만 PC에서만 가능합니다. 다른 타이틀에서 솔루션을 이식하려면 이 접근 방식이 필요할 수 있습니다. 이 솔루션은 코드 없는 클라우드 저장을 사용합니다.코드 없는 클라우드 저장에는
wdapp install을 사용하여 타이틀을 패키지된 빌드로 실행해야 합니다. .exe를 직접 실행하면 클라우드 저장 리디렉션이 활성화되지 않습니다. 패키지된 실행과 직접 .exe 실행 사이를 번갈아 사용하면 저장 데이터가 누락된 것처럼 나타날 수 있습니다. 자세한 내용은 코드 없는 클라우드 저장으로 이전 타이틀을 PC 게임 저장으로 이식을 참조하세요.