게임 저장이 포함된 Win32 파일 IO(XGameSaveFiles)

아티클
05/10/2023

XGameSaveFiles는 콘솔, PC 및 xCloud에서 클라우드 저장을 위한 대체 솔루션을 제공합니다. 개발자는 XGameSaveFiles를 사용하여 저장 시스템에서 CreateFile 및 WriteFile과 같은 일반적인 Win32 파일 IO 함수를 사용할 수 있습니다.

XGameSaveFiles와 XGameSave 비교

다음 표에서는 XGameSaveFiles와 XGameSave의 차이점을 보여 줍니다.

기능	XGameSaveFiles	XGameSave
Win32 파일 IO API 지원	예	아니요
일괄 처리된 업데이트 지원	아니요	예
업데이트는 게임 플레이 중에 업로드됩니다.	아니요	예
주문형 동기화 지원	아니요	예
Xbox/xCloud에서 VM 간 쓰기	아니요	예
초기화 API	XGameSaveFilesGetFolderWithUiAsync	XGameSaveInitalizeProviderAsync
사용자당 기본 저장소 용량 한도	256MB	256MB
파일 크기 제한	64 MB*	16MB

* 게임에서 XGameSaveFiles와 XGameSave 간의 interop을 지원해야 하는 경우 게임은 파일 크기를 16MB로 제한해야 합니다.

게임은 XGameSaveFiles의 사용량을 XGameSave 사용량과 혼합할 수 없습니다. 게임은 사용하려는 클라우드 저장 시스템을 많이 선택합니다. 게임이 XGameSaveFiles를 사용하고 나중에 XGameSaveInitializeProvider를 호출하면 E_GS_PROVIDER_MISMATCH와 함께 오류가 발생합니다. 마찬가지로 게임에서 XGameSave를 사용하고 나중에 XGameSaveFilesGetFolderWithUiAsync를 호출하면 E_GS_PROVIDER_MISMATCH와 함께 오류도 발생합니다.

XGameSaveFiles 및 XGameSave 사용 중 선택

XGameSave 및 XGameSaveFiles는 모두 콘솔, PC 및 xCloud 간에 공유할 수 있는 클라우드 저장을 허용하는 저장 시스템을 제공합니다.

위 표에 강조 표시된 차이점 외에도 XGameSave는 개발자가 쓰기를 쉽게 일괄 처리하고 이러한 쓰기가 원자적 작업으로 발생하도록 할 수 있는 가장 강력한 솔루션을 제공합니다. XGameSaveFiles는 이미 PC에 Win32 스타일 저장 시스템이 있고 해당 솔루션을 PC Game Pass에서 작동하는 것으로 포팅하는 비용을 최소화하려는 개발자에게 최적입니다.

XGameSaveFiles로 업데이트를 업로드하는 경우

게임을 저장하기 위한 업데이트는 게임에서 책임지지 않으며 게임이 "활성" 상태가 아닐 때 자동으로 처리됩니다. "활성" 상태가 아니라는 것은 플랫폼마다 다른 의미를 갖습니다.

콘솔 또는 xCloud에서 "활성"이 아님은 다음을 의미합니다.

게임이 일시 중단됨
게임이 종료되었습니다
저장이 추적되는 사용자가 로그아웃되었습니다.

PC에서 "활성" 상태가 아니라는 것은 다음을 의미합니다.

게임이 종료되었습니다
저장이 추적되는 사용자가 로그아웃되었습니다.
PC의 전원 상태 변경
게임이 백그라운드에 있거나 게임이 XGameSaveFiles에 새로운 쓰기를 수행하지 않은 경우 30분이 경과했습니다.

XGameSaveFile 사용

XGameSaveFiles를 사용하려면 개발자가 XGameSaveFilesGetFolderWithUiAsync를 호출하고 저장을 관리할 사용자의 XUser 핸들과 게임의 SCID(Xbox 서비스 구성 ID)를 전달해야 합니다. 그런 다음 개발자가 XGameSaveFilesGetFolderWithUiResult를 호출하면 CreateFile, WriteFile 등과 같은 표준 Win32 파일 IO API를 사용하여 해당 폴더에 대한 읽기 및 쓰기 모두에서 게임 저장에 사용할 수 있는 폴더를 얻게 됩니다.

개발자는 게임을 다시 시작되면 저장 데이터가 완전히 최신 상태인지 확인하기 위해 XGameSaveFilesGetFolderWithUiAsync를 호출해야 합니다.

개발자는 Win32 파일 IO API가 다음 오류를 반환한다는 사실을 알고 있어야 합니다.

Error	XGameSaveFiles 컨텍스트의 설명
STATUS_NAME_TOO_LONG	디렉터리 이름이 너무 깁니다.
STATUS_OBJECT_NAME_INVALID	디렉터리 이름에 클라우드 서비스에서 유효하지 않은 문자가 포함되어 있습니다.
STATUS_NAME_TOO_LONG	파일 이름(디렉터리 할인)이 너무 깁니다.
STATUS_FILE_TOO_LARGE	파일 크기가 64MB를 초과했습니다.
STATUS_FILE_TOO_LARGE	게임이 게임 저장에 대한 사용자당 최대 할당량을 초과했습니다.
STATUS_INSUFFICIENT_RESOURCES	게임이 장치에 할당된 저장소 공간을 초과했습니다.

사용자당 할당량이 얼마나 남았는지 알고 싶은 개발자는 XGameSaveFilesGetRemainingQuota를 호출할 수 있습니다.

XGameSaveFiles의 디렉터리 및 파일 이름 제한

XGameSaveFiles는 개발자로부터 클라우드 저장 시스템의 세부 정보 대부분을 숨기지만 Azure Blob Storage에서 지원하기 때문에 디렉터리 및 파일 이름 제한이 있습니다. 상위 수준에서 전체 디렉터리 경로는 컨테이너에 매핑되고 파일 이름은 Blob에 매핑됩니다. 게임이 저장에 사용할 수 있는 다음 예를 고려하세요.

[ROOT]/Save1/BraveNewWorld/state001.dat

"[ROOT]"는 XGameSaveFilesGetFolderWithUiAsync에 의해 반환되는 것입니다.
마지막 슬래시를 포함하여 "[ROOT]" 뒤에 오는 모든 항목이 컨테이너에 매핑됩니다.
- 컨테이너 이름은 대문자(A-Z), 소문자(a-z), 숫자(0-9), 밑줄(_), 마침표(.), 하이픈(-) 및 슬래시(/)로 제한됩니다.
- 컨테이너 이름은 256자로 제한됩니다.
- 컨테이너 이름은 마침표로 끝나거나 두 개의 연속된 마침표를 포함하거나 마침표나 하이픈으로 시작할 수 없습니다.
마지막 슬래시(파일 이름) 뒤에 오는 모든 항목은 blob에 매핑됩니다.
- 파일 이름은 65자로 제한되지만 그렇지 않으면 NTFS에서 지원되는 유니코드 문자일 수 있습니다.
파일 이름을 포함한 전체 결과 경로("[ROOT]" 제외)는 MAX_PATH(260자) 미만이어야 합니다.

XGameSaveFiles 개발 도구

XGameSaveFiles는 XGameSave와 동일한 개발 도구를 사용합니다. API는 다르지만 정확히 동일한 XGameSave 저장소 공간과 데이터를 활용합니다. 다음 도구는 XGameSaveFiles 개발에 도움이 됩니다.

xbstorage
xgamesaveutil
Fiddler

콘솔에서 xbstorage를 사용하여 XGameSave 데이터 관리하기

Xbstorage.exe는 개발 PC에서 Xbox 개발 키트의 로컬 XGameSave 데이터를 관리할 수 있는 개발 도구입니다.

이 도구를 사용하면 하드 드라이브에서 로컬 XGameSave 저장소 공간을 지울 수 있을 뿐만 아니라 .xml 파일을 사용하여 개별 사용자와 연결되거나 컴퓨터에 연결된 저장소 공간을 가져오고 내보낼 수 있습니다.

로컬 XGameSave 저장소 공간에서 작업을 수행하면 마치 작업이 앱 자체에 의해 수행되는 것처럼 시스템이 동작합니다. XGameSave 저장소 공간에서 로컬 파일로 데이터를 복사하면 복사하기 전에 클라우드와 동기화됩니다.

마찬가지로, 개발 PC의 .xml 파일에서 Xbox One 개발 키트의 XGameSave 스토리지 컨테이너로 데이터를 복사하면 콘솔이 해당 데이터를 클라우드에 업로드하기 시작합니다. 예외는 개발 키트에서 잠금을 획득할 수 없거나 본체의 컨테이너와 클라우드의 컨테이너 간에 충돌이 발생하는 경우입니다. 이러한 경우 콘솔은 사용자가 충돌을 해결하지 않기로 결정한 것처럼 작동합니다(예: 보관할 컨테이너 버전 선택). 콘솔은 다음에 타이틀이 시작될 때까지 오프라인으로 플레이되는 것처럼 작동합니다.

xbstorage reset 명령은 모든 SCID(서비스 구성 식별자)의 로컬 저장소와 사용자의 저장된 데이터를 지우지만 클라우드에 저장된 데이터는 변경하지 않습니다. 이 방법은 사용자가 본체로 이동하고 타이틀을 플레이하면서 클라우드에서 데이터를 다운로드한 것 같은 상태로 본체를 설정하려 할 때 유용합니다.

xbstorage.exe에 대한 자세한 내용은 콘솔(xbstorage.exe)에서 XGameSave 데이터 관리(NDA 주제)권한 부여 필요를 참조하세요.

PC에서 xgamesaveutil로 XGameSave 데이터 관리하기

Xgamesaveutil.exe는 PC에서 실행되는 게임에 대한 로컬 XGameSave 데이터를 관리할 수 있는 개발 도구입니다. 콘솔에서 저장을 관리하는 데 사용되는 xbstorage 도구와 동일한 기능을 가지고 있습니다.

xgamesaveutil.exe에 대한 자세한 내용은 PC에서 XGameSave 데이터 관리(xgamesaveutil.exe)를 참조하세요.

Fiddler를 사용하여 XGameSave 네트워크 활동 모니터링

클라우드 저장 작업이 수행될 때 장치가 서비스와 상호 작용하는지 여부를 확인하는 것이 도움이 될 수 있습니다. Fiddler를 사용하면 장치가 서비스를 성공적으로 호출하는지 또는 승인 오류가 발생하는지 확인하는 데 도움이 될 수 있습니다.

콘솔에서 Fiddler를 설정하는 방법에 대한 자세한 내용은 Xbox 콘솔에서 Fiddler를 사용하는 방법을 참조하세요.

PC에서 Fiddler를 설정하는 방법에 대한 자세한 내용은 Windows PC에서 Fiddler를 참조하세요.

XGameSaveFiles와 XGameSave 및 연결된 저장소 간의 상호 운용성

XGameSave 및 Connected Storage는 게임 작성 코드 없이도 저장 상태를 쉽게 공유할 수 있지만 XGameSaveFiles를 활용하여 동일한 저장을 게임으로 이동하려고 할 때는 완전히 동일하지 않습니다. 이것은 일반적인 시나리오는 아니지만 게임이 XGameSaveFiles와 상호 운용성을 원할 수 있는 상황이 있습니다. 일반적인 이유는 다음과 같습니다.

게시자는 연결된 저장소 또는 XGameSave를 이미 사용 중인 콘솔에 기존 게임이 있습니다.
게시자는 XGameSaveFiles를 사용하도록 기존 게임을 업데이트하고 싶지 않습니다.
게시자는 XGameSaveFiles를 PC 게임에 추가하는 것이 XGameSave보다 쉽다고 생각하면서도 PC와 콘솔 및 xCloud 간의 교차 저장 진행을 지원하고 싶어합니다.

XGameSave와 XGameSaveFiles 사이를 이동하는 것은 매우 간단합니다. 타이틀이 XGameSaveFilesGetFolderWithUiAsync를 호출하면 다음 규칙을 사용하여 디렉터리 및 파일에 대한 컨테이너 및 Blob 매핑이 발생합니다.

컨테이너 이름의 슬래시(L'/')는 파일이 상주할 디렉터리 구조를 만드는 데 사용됩니다.
다음 문자는 XGameSaveFiles에 유효하지 않으며 만나면 밑줄(L'_')로 매핑됩니다.
- L'\0'부터 L'\001f'까지의 모든 문자(포함)
다음 문자는 XGameSaveFiles에 유효하지 않으며 발견되면 마침표(L'.')에 매핑됩니다.
- 큰따옴표(L'"')
- 보다 작음(L'<')
- 보다 큼(L'>')
- 파이프 기호(L'|')
- 별표(L'*')
- 물음표(L'?')
- 백 슬래시(L'\')
Blob 이름의 슬래시(L'/')는 파일 이름의 마침표(L'.')에 매핑됩니다.

XGameSaveFiles에서 XGameSave로 다시 이동할 때 파일 이름이 변경되거나 이동되지 않았다고 가정하고 원래 컨테이너 및 blob 이름이 복원됩니다.

참고 항목

XGameSaveFiles 참조

다음을 통해 공유