> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # XGameSaveFiles API 개요 > XGameSaveFilesGetFolderWithUIAsync, Win32 클라우드 동기화 동작, 할당량, 디버깅 및 성능 모범 사례를 다루는 XBOX XGameSaveFiles 참조입니다. 이 문서에서는 `XGameSaveFilesGetFolderWithUIAsync`를 초기화하는 방법을 설명합니다. 또한 권장되는 Win32 자동 클라우드 동기화 동작, 디버깅 단계, 할당량 및 진단 지침, 성능 모범 사례, 자주 묻는 질문에 대한 답변을 설명합니다. `XGameSaveFiles`는 타이틀이 사용자 데이터를 읽고 쓰고, 세션 간에 유지하며, 플레이어가 어떤 디바이스에서도 데이터를 사용할 수 있도록 클라우드와 원활하게 동기화할 수 있게 해 주는 API를 제공합니다. Microsoft Game Development Kit(GDK) 타이틀의 게임 저장에는 `XGameSaveFiles`를 사용하세요. 해당 시나리오에서 `XGameSaveFiles`를 사용할 수 없는 경우에만 `XGameSave`를 사용하세요. `XGameSaveFiles`에 대한 시스템 API 참조는 [XGameSaveFiles(API 콘텐츠)](/reference/system/xgamesavefiles/xgamesavefiles_members)를 참조하세요. `XGameSaveFiles`에서 다음 용어가 자주 나타납니다. * **잠금:** 활성적으로 사용하는 디바이스에서 특정 사용자에 대한 타이틀의 게임 저장에 대한 배타적 접근을 부여하는 메커니즘입니다. 잠금이 유지되는 동안 다른 디바이스가 사용자의 게임 저장을 수정할 수 없도록 보장합니다. * 예를 들어, 사용자가 디바이스 A에서 타이틀 T를 플레이하면 해당 사용자의 타이틀 T에 대한 잠금을 갖게 됩니다. * **공급자:** 게임 저장 시스템과 통신하며 타이틀 데이터 관리를 담당하는 중개 프로세스입니다. 공급자는 또한 디바이스에서 사용자의 잠금을 관리합니다. * **컨테이너**: 폴더에 해당합니다. * **Blob**: 개별 파일에 해당합니다. ## XGameSaveFiles 경로 로직 `XGameSaveFiles`는 게임 저장 시스템과 상호 작용하는 데 사용할 수 있는 파일 경로를 제공합니다. 이 파일 경로는 클라우드 동기화와 통합되어 있으므로 경로에 저장된 데이터가 클라우드에 자동으로 동기화됩니다. 제공된 경로에서 Win32 `FileIO` API를 사용하세요. GDK 타이틀의 경우, 게임 저장 접근 방식으로 `XGameSaveFiles`를 사용하세요. `XGameSaveFiles`는 컨테이너 개념을 폴더에, blob을 파일에 매핑합니다. `XGameSaveFiles`는 클라우드 저장 시스템의 복잡성 대부분을 숨기지만, 이 기능이 Microsoft Azure Blob Storage에 의존하기 때문에 여전히 디렉터리 및 파일 이름 제한을 적용합니다. 타이틀이 저장에 사용할 수 있는 예제 코드를 살펴보세요. ``` [ROOT]/Save1/WingtipToys/state001.dat ``` * `XGameSaveFilesGetFolderWithUiAsync`는 \[ROOT]를 반환합니다. * \[ROOT] 뒤부터 마지막 슬래시까지를 포함한 모든 것은 컨테이너에 매핑됩니다. * 컨테이너 이름은 대문자(A-Z), 소문자(a-z), 숫자(0-9), 밑줄(\_), 마침표(.), 하이픈(-), 슬래시(/)로 제한됩니다. * 컨테이너 이름은 256자로 제한됩니다. * 컨테이너 이름은 마침표로 끝날 수 없고, 두 개의 연속된 마침표를 포함할 수 없으며, 마침표나 하이픈으로 시작할 수 없습니다. * 파일 이름의 마지막 슬래시 뒤에 오는 모든 것은 blob에 매핑됩니다. * 파일 이름은 65자로 제한되지만, 그 외에는 NTFS(New Technology File System)가 지원하는 유니코드 문자일 수 있습니다. * 파일 이름을 포함한 전체 결과 경로(단, \[ROOT]는 제외)는 `MAX_PATH`(260자)보다 작아야 합니다. Win32 및 파일 관리에 대한 자세한 내용은 [파일 관리(로컬 파일 시스템)](https://learn.microsoft.com/windows/win32/fileio/file-management)를 참조하세요. ## XGameSaveFiles 구현 다음 단계에서는 `XGameSaveFiles`의 일반적인 구현을 보여 줍니다. 1. 타이틀 시작 또는 재개 시 `XGameSaveFilesGetFolderWithUIAsync`를 호출하여 공급자를 초기화하고 파일 경로를 가져옵니다. 2. 게임 플레이 중에 파일 경로에 자유롭게 읽고 씁니다. `XGameSaveFilesGetFolderWithUIAsync`는 자동으로 게임 저장 공급자의 수명을 관리하고 게임 저장 로컬 스토리지 공간을 설정합니다. 타이틀이 시작될 때와 재개될 때 `XGameSaveFilesGetFolderWithUIAsync`를 호출하세요. 이 호출은 게임 저장 공급자를 초기화하고 게임 세션이 실행되는 동안 활성 상태로 유지합니다. 이 단계를 건너뛰면 시스템이 예측할 수 없게 동작할 수 있습니다. ### 코드 샘플 XBOX에서 폴더에 접근하기 위해 `XGameSaveFiles` API를 사용하는 방법을 보여 주는 코드 샘플은 [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/)를 참조하세요. ## 게임 저장 흐름 다음은 단순화된 게임 저장 흐름의 순서도입니다. 단순화된 게임 저장 동기화 프로세스의 순서도. ### 타이틀 시작 타이틀 시작은 사용자가 타이틀을 실행하거나 재개할 때 발생합니다. ### 사용자 사인인 타이틀이 사용자 사인인 프로세스를 시작합니다. 이 작업에서 `XGameSaveFilesGetFolderWithUIAsync`도 호출합니다. 사용자 설정에 대한 자세한 내용은 [사용자 모델](/build/core-features/common/game-save/game-saves-developer-guide#user-models)을 참조하세요. ### 연결 확인 타이틀이 XBOX 네트워크에 연결할 수 있는지 결정합니다. 연결할 수 없으면 타이틀에 대한 [오프라인 모드](/build/core-features/common/game-save/game-saves-syncing#connection-check)를 활성화해야 합니다. ### 데이터 소유권 확인 디바이스는 사용자가 현재 다른 디바이스에서 플레이하고 있는지 확인합니다. 한 번에 하나의 디바이스만 특정 타이틀에 대한 사용자의 데이터에 접근할 수 있습니다. ### 클라우드와 데이터 동기화 디바이스가 게임 저장 로컬 스토리지 데이터를 클라우드와 동기화합니다. 충돌이 있는 경우 시스템은 충돌 해결 대화상자로 사용자에게 요청합니다. 대화상자: [어느 것을 사용하시겠습니까?](/build/core-features/common/game-save/game-saves-dialogues#which-one-do-you-want-to-use) 디바이스의 데이터가 클라우드 데이터보다 최신인 경우, 타이틀은 사용자에게 로컬 데이터를 사용할지 클라우드 데이터를 사용할지 선택하도록 요청합니다. ### 게임 플레이 루프 타이틀은 `XGameSaveFilesGetFolderWithUIAsync`가 제공한 폴더 경로에 자유롭게 읽고 쓸 수 있습니다. ### 게임 세션 종료 게임 세션이 종료되면 시스템은 자동으로 클라우드에 데이터 업로드를 시도합니다. 이 프로세스는 타이틀이 종료된 후 약 10\~30초 후에 발생합니다. 자세한 동기화 정보는 [게임 저장 동기화 흐름 이해](/build/core-features/common/game-save/game-saves-syncing)를 참조하세요. ## 제한 및 할당량 ### 제한 `XGameSaveFiles`를 사용하여 저장할 수 있는 최대 파일 크기는 64MB입니다. 이 동작은 각 파일을 16MB로 제한하는 `XGameSave`와 다릅니다. ### 할당량 사용자가 타이틀당 저장할 수 있는 최대 데이터는 256MB입니다. 남은 할당량을 가져오려면 [XGameSaveFilesGetRemainingQuota](/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota)를 사용합니다. 타이틀에 더 큰 사용자당 스토리지 제한을 부여하기 위해 스토리지 확장을 얻으려면 개발자 프로그램 관리자(DPM)에게 문의하세요. ## FAQ ### XGameSaveFiles를 XGameSave와 함께 사용할 수 있나요? 예. 그러나 마이그레이션 목적으로만 이 접근 방식을 사용하세요. 자세한 내용은 [XGameSave와 XGameSaveFiles 간 상호 운용성](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#interop-between-xgamesave-and-xgamesavefiles)을 참조하세요. ### XGameSaveFiles는 어떤 파일 경로에 저장하나요? **콘솔**: 타이틀은 활성 상태인 동안 임시 경로를 제공합니다. 파일 탐색기를 사용하여 콘솔 파일에 접근할 수 없습니다. **PC**: `%AppData%\Local\Packages\\SystemAppData\xgs\_\` `XGameSaveFiles`의 PC 경로는 `XGameSave`와 다릅니다. `wgs`를 사용합니다. ### 데이터가 저장되어야 하는 경로를 지정할 수 있나요? 예. 하지만 PC에서만 가능합니다. 다른 타이틀에서 솔루션을 이식하는 경우에만 이 접근 방식을 권장합니다. 이 솔루션은 [코드 없는 클라우드 저장](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)을 사용합니다. ## 참고 API 문서 * [XGameSaveFiles(API 콘텐츠)](/reference/system/xgamesavefiles/xgamesavefiles_members) * 함수 * [XGameSaveFilesGetRemainingQuota](/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota) ## 참고 항목 [게임 저장 TOC](/build/core-features/common/game-save/game-saves-toc) 예. 하지만 PC에서만 가능합니다. 다른 타이틀에서 솔루션을 이식하려면 이 접근 방식이 필요할 수 있습니다. 이 솔루션은 [코드 없는 클라우드 저장](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)을 사용합니다. 코드 없는 클라우드 저장에는 `wdapp install`을 사용하여 타이틀을 패키지된 빌드로 실행해야 합니다. .exe를 직접 실행하면 클라우드 저장 리디렉션이 활성화되지 않습니다. 패키지된 실행과 직접 .exe 실행 사이를 번갈아 사용하면 저장 데이터가 누락된 것처럼 나타날 수 있습니다. 자세한 내용은 [코드 없는 클라우드 저장으로 이전 타이틀을 PC 게임 저장으로 이식](/build/core-features/common/game-save/game-saves-walkthroughs-and-samples#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves)을 참조하세요. ## Related topics - [게임 저장 개요](/ko/build/core-features/common/game-save/game-saves-overview.md) - [XGameSaveFilesGetRemainingQuota](/ko/reference/system/xgamesavefiles/functions/xgamesavefilesgetremainingquota.md) - [XGameSaveFiles](/ko/reference/system/xgamesavefiles/xgamesavefiles_members.md) - [XGameSave API 개요](/ko/build/core-features/common/game-save/xgamesave.md) - [게임 저장 워크스루 및 샘플](/ko/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md)