> ## 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.
# Tutoriales y ejemplos de Game Saves
> Tutoriales paso a paso de Game Saves de XBOX para la configuración de Partner Center, los patrones de escritura segura, el manejo sin conexión, las pruebas de escenarios de sincronización y la migración de títulos.
Este artículo proporciona instrucciones paso a paso para escenarios comunes de desarrollo y migración al usar Game Saves. Cubre la configuración esencial en Microsoft Partner Center, los procedimientos recomendados para escribir datos de forma segura, la administración de guardados específica de cada plataforma y los procedimientos de prueba recomendados.
## Configuraciones de Partner Center
### Habilitación de los servicios de XBOX y Game Saves para el título
Para usar las API de Game Saves, complete los siguientes pasos en Partner Center.
* Habilite los servicios de XBOX.
1. Inicie sesión en [Partner Center](https://partner.microsoft.com/dashboard/home).
2. Vaya a su título y, a continuación, habilite los servicios de XBOX en la configuración. Para obtener más información sobre este paso, consulte [Configuración de una aplicación o un juego en Partner Center, para socios administrados](/services/xbox-services/fundamentals/portal-config/live-setup-partner-center-partners#2-contact-your-microsoft-representative-to-enable-your-app-or-game).
* Obtenga el identificador de configuración de servicio (SCID). Todas las operaciones de lectura y escritura deben estar asociadas a un SCID. El SCID también se usa para la inicialización de Game Saves.
* En Partner Center, encuentre el SCID en la pestaña **XBOX services** > **XBOX settings** del título. También puede encontrar el App ID de cuenta Microsoft (MSA) (MSAAppID) en esta página.
Después de obtener el SCID y el MSAAppID, agregue este App ID al archivo de configuración (.mgc) del título.
Para obtener más información sobre los archivos de configuración del juego, consulte [Creación del archivo Microsoft Game Config .mgc](/build/core-features/common/game-config/MicrosoftGameConfig-Overview).
## Escenarios de desarrollo
### ¿Dónde integro Game Saves en el código?
La lógica de Game Saves depende del inicio de sesión del usuario. Agregue el código de Game Saves junto al flujo de inicio de sesión del usuario.
### ¿Cómo me aseguro de que los datos de guardado del juego no se dañen?
Para guardar datos de forma segura y evitar daños, siga estos pasos. Esta orientación se aplica a todas las operaciones de guardado.
1. Escriba en un archivo temporal.
* Serialice los datos de guardado en un archivo nuevo (por ejemplo, `save.tmp`) en lugar de sobrescribir el guardado activo. Este paso protege el guardado existente en caso de que el proceso se interrumpa en mitad de la escritura.
2. Cierre el identificador de escritura después de que la escritura se haya confirmado por completo en el disco.
3. Reemplace el archivo de guardado antiguo de forma atómica por el nuevo archivo temporal mediante la función de Win32 [ReplaceFile](https://learn.microsoft.com/windows/win32/api/winbase/nf-winbase-replacefilea).
### ¿Cómo admito dispositivos sin conexión?
Usted es responsable de determinar cómo se comporta el título si hay una pérdida de conexión, tanto antes como después de inicializar Game Saves.
Para obtener más información sobre el comportamiento sin conexión, consulte [Descripción del flujo de sincronización de Game Saves](/build/core-features/common/game-save/game-saves-syncing#connection-check).
### ¿Qué interacciones del usuario debo tener en cuenta?
El sistema operativo muestra avisos del sistema cuando una acción requiere la intervención del usuario. Para obtener información sobre estos avisos, consulte [Cuadros de diálogo de Game Saves](/build/core-features/common/game-save/game-saves-dialogues).
### ¿Hay alguna forma de guardar localmente y solo en el dispositivo?
Si pasa un identificador de usuario `null` al proceso de inicialización de Game Save, el sistema crea un proveedor solo de máquina. Los datos se almacenan localmente y persisten en el dispositivo, con un límite máximo de 256 MB. Los datos no se sincronizan con la nube.
Para obtener más información sobre el almacenamiento de Game Saves, consulte [Sistemas de almacenamiento de Game Saves](/build/core-features/common/game-save/game-saves-storage-systems).
### Administración de Game Saves a través del dispositivo
#### Acceso a las Game Saves locales en PC mediante el Explorador de archivos
Si el título se ejecuta en PC, tiene acceso directo a los archivos. Según la implementación de la API de Game Saves, puede acceder a sus Game Saves locales en las siguientes ubicaciones.
| API de Game Saves | Ruta de acceso de archivo |
| :---------------- | :---------------------------------------------------------------------------- |
| XGameSaveFiles | `%AppData%\Local\Packages\\SystemAppData\xgs\_\` |
| XGameSave | `%AppData%\Local\Packages\\SystemAppData\wgs\_\` |
Cuando manipula datos en PC, la lógica de sincronización sigue aplicándose. Por ejemplo, modificar datos cuando el título no tiene un bloqueo provoca conflictos.
#### Acceso a las Game Saves locales en la consola
Administre los datos de guardado de la consola a través de la interfaz de usuario de XBOX. Acceda a ellos mediante los siguientes pasos.
1. Seleccione el botón **Home** en el mando de XBOX.
2. Seleccione **My games & apps** > **See all**.
3. Sitúese sobre su juego y, a continuación, seleccione el botón **View**.
4. Seleccione **Saved data**.
Tenga en cuenta lo siguiente cuando manipule datos directamente en la consola.
* Eliminar datos en la consola mediante la interfaz de usuario del sistema no quita la copia almacenada en la nube. Cuando vuelva a iniciar el título, este sincroniza los datos desde la nube.
* Los datos del proveedor de máquina aparecen como un usuario sin nombre. Estos datos permanecen en el dispositivo, no se sincronizan con la nube y están vinculados al dispositivo.
Para obtener más información sobre el proveedor de máquina, consulte [Sistemas de almacenamiento de Game Saves](/build/core-features/common/game-save/game-saves-storage-systems#game-saves-storage-systems).
Para un control más detallado de las Game Saves, use las [Herramientas de Game Saves](/build/core-features/common/game-save/game-saves-tools#manipulating-game-saves).
## Escenarios de prueba
Cuando cree casos de prueba, separe la validación de los datos de la lógica de guardado del juego.
### Probar si las Game Saves se sincronizan correctamente con la nube y desde ella
Use los siguientes pasos para probar que la sincronización sea correcta. Los flujos de prueba verifican el comportamiento.
`XGameSaveFiles`:
1. Confirme que el SCID es correcto.
2. Confirme que está usando el identificador de usuario correcto.
3. Confirme que el título llama a `XGameSaveFilesGetFolderWithUIAsync` durante la sesión de juego actual. Si el título se reanuda desde un estado de suspensión, llame a la función.
1. Use Fiddler para confirmar que se adquirió el bloqueo.
2. Guarde esta ruta de acceso y úsela más adelante para confirmar que los datos se están cargando.
4. Escriba algunos datos en la ruta de acceso de archivo proporcionada por `XGameSaveFilesGetFolderWithUIAsync`.
5. Finalice o suspenda el título.
6. Espere entre 10 y 30 segundos para que el sistema operativo cargue automáticamente los datos en la nube y libere el bloqueo.
1. Confirme que los datos se cargaron y que el bloqueo se liberó mediante Fiddler.
7. Elimine manualmente los datos de la carpeta proporcionada por `XGameSaveFilesGetFolderWithUIAsync`.
1. En la consola, acceda a estos datos a través de la configuración del jugador.
8. Vuelva a iniciar el título y, a continuación, intente iniciar la sesión del usuario.
9. Aparece un cuadro de diálogo de sincronización que muestra una sincronización de descarga activa desde la nube.
Para ayudar a probar una sincronización correcta, consulte los siguientes recursos:
* [Herramientas de Game Saves para inspeccionar el tráfico y manipular guardados](/build/core-features/common/game-save/game-saves-tools)
* [Descripción del flujo de sincronización de Game Saves](/build/core-features/common/game-save/game-saves-syncing)
### Probar si las Game Saves se mueven correctamente entre dispositivos
Para obtener un plan de pruebas que confirme si los datos se mueven correctamente, consulte el [Plan de pruebas XR-052-06](https://learn.microsoft.com/build/store/policies/XR/XR052#052-06-cloud-storage-roaming).
## Escenarios de migración
### Compartición de Game Saves entre títulos
Para transferir datos de un título a otro o acceder a ellos, complete dos pasos.
1. Modifique las directivas de acceso del título al que quiere acceder en Partner Center.
2. Inicialice los proveedores de Game Saves de ambos títulos en el código fuente.
#### Modificación de las directivas de acceso
Un título controla qué títulos tienen acceso a sus datos de Game Saves mediante la configuración de directivas de acceso.
1. Vaya a [Partner Center](https://partner.microsoft.com/dashboard).
2. Seleccione **Apps and games** > **\** > **Gameplay settings**.
3. En **Gameplay Settings**, seleccione **Access Policies** y, a continuación, expanda **Connected Storage**.
4. Seleccione **Add app/service** y, a continuación, agregue los títulos a los que quiere proporcionar acceso.
5. Cuando termine de agregar los títulos, seleccione **Save** y, a continuación, seleccione **Publish**. Los cambios surten efecto en un plazo de una hora.
La siguiente captura de pantalla muestra un ejemplo de cómo hacer que el título GameSaveFilesCombo sea totalmente accesible para el título GameSaveSample.
#### Inicialización de los proveedores de Game Save
Ahora que tiene permiso para acceder al primer título, puede leer los datos de `XGameSave` del otro título.
* Si usa `XGameSave`, llame a `XGameSaveInitializeProvider` o `XGameSaveInitializeProviderAsync` para cada título.
* Si usa `XGameSaveFiles`, los proveedores se inicializan implícitamente. Llame a `XGameSaveFilesGetFolderWithUiAsync` para cada título.
### Interoperabilidad entre XGameSave y XGameSaveFiles
Un título podría necesitar usar `XGameSave` junto con `XGameSaveFiles`. Los motivos habituales podrían ser los siguientes:
* El publicador tiene un título existente en la consola que ya usa `XGameSave`.
* El publicador no quiere actualizar ese título existente para usar `XGameSaveFiles`.
* El publicador considera que agregar `XGameSaveFiles` a un título de PC es más fácil que usar `XGameSave`, pero aun así quiere admitir guardados cruzados entre PC, consola y la transmisión de juegos de XBOX.
Pasar de `XGameSave` a `XGameSaveFiles` y viceversa es bastante sencillo. Cuando el título llama a [XGameSaveFilesGetFolderWithUiAsync](/reference/system/xgamesavefiles/functions/xgamesavefilesgetfolderwithuiasync), asigna los contenedores y blobs a directorios y archivos mediante las siguientes reglas:
* Cualquier barra diagonal (/) en el nombre del contenedor crea la estructura de directorios en la que reside el archivo.
* Los siguientes caracteres no son válidos para `XGameSaveFiles`. Si el sistema encuentra estos caracteres, los asigna a un guion bajo (\_):
* Caracteres desde \0 hasta \001f, ambos inclusive.
* Los siguientes caracteres no son válidos para `XGameSaveFiles`. Si el sistema encuentra estos caracteres, los asigna a un punto (.):
* Comillas (")
* Signo menor que (\<)
* Signo mayor que (>)
* Barra vertical (|)
* Asterisco (\*)
* Signo de interrogación (?)
* Barra diagonal inversa (\\)
* Una barra diagonal (/) en el nombre del blob se asigna a un punto (.) en el nombre del archivo.
* Los archivos están limitados a 16 MB. `XGameSave` admite un tamaño máximo de carga de 16 MB.
Cuando el título vuelve de `XGameSaveFiles` a `XGameSave`, restaura los nombres originales de los contenedores y blobs si los nombres de archivo permanecen sin cambios o no se mueven.
### Portabilidad de títulos anteriores a Game Saves de PC con guardados en la nube sin código
Algunos títulos que porta a PC Game Pass podrían requerir una solución de guardado en la nube sin código. Este requisito puede darse en los siguientes escenarios:
* El título se ejecuta como una aplicación x86. Usa el Microsoft Game Development Kit (GDK) solo en su forma empaquetada.
* El título se crea sin código personalizado, mediante herramientas como Blueprint en Unreal Engine o Bolt en Unity.
Los títulos que usan guardados en la nube sin código leen y escriben en su directorio de guardado designado a través de las API estándar de E/S de archivos de Win32. El sistema sincroniza automáticamente los datos. No es necesario escribir código especial para manejar la sincronización y la carga. La sincronización se produce antes de que se inicie el título.
Los guardados en la nube sin código se cargan cuando el título ya no se está ejecutando en el PC. La carga se produce cuando se cumple una de las siguientes condiciones:
* El título finaliza.
* El usuario del que se hace seguimiento cierra la sesión.
* El estado de energía del PC cambia.
* Han pasado 30 minutos desde que el título escribió por última vez en el área de guardado designada.
La solución de guardados en la nube sin código está construida sobre `XGameSaveFiles` y comparte todas sus limitaciones con respecto a los tamaños de archivo y los límites de almacenamiento por usuario. Los archivos están limitados a 64 MB (o 16 MB si se necesita interoperación entre `XGameSave` o Connected Storage). De forma predeterminada, el almacenamiento por usuario está limitado a 256 MB. Los títulos que necesiten límites de almacenamiento por usuario más grandes pueden trabajar con su administrador de socios de desarrollo (DPM) para solicitar una excepción.
Existen convenciones de nomenclatura y límites de caracteres específicos para los directorios y los nombres de archivo. Para obtener más información, consulte [Lógica de rutas de acceso de XGameSaveFiles](/build/core-features/common/game-save/xgamesavefiles#xgamesavefiles-path-logic).
Los guardados en la nube sin código solo se admiten en PC. El título requiere el [modelo de usuario simplificado](/build/core-features/common/user/users-opting-into-simplified-model). Este garantiza que un usuario haya iniciado sesión antes de que se inicie el título. Si un usuario no puede iniciar sesión en el título, este no se inicia. Si el usuario cierra la sesión durante el juego, el título finaliza.
Los guardados en la nube sin código requieren que el título se inicie como una compilación empaquetada mediante `wdapp install`. Iniciar el archivo `.exe` directamente no activa la redirección de guardados en la nube.
Cuando se ejecuta una compilación empaquetada, los guardados escritos a través de `NoCodePCRoot` se redirigen al almacenamiento administrado por `XGameSaveFiles`. Un inicio directo posterior del `.exe` lee en su lugar la carpeta física `NoCodePCRoot`, que podría estar vacía, lo que hace que los guardados parezcan perdidos. Para evitar este problema, pruebe siempre los guardados en la nube sin código con compilaciones empaquetadas mediante `wdapp install`.
### Habilitación de los guardados en la nube sin código
Para habilitar los guardados en la nube sin código, complete los siguientes pasos:
1. Modifique el archivo `MicrosoftGame.config`.
2. Habilite el modelo de usuario simplificado.
3. Especifique la carpeta raíz de los archivos de guardado.
4. Proporcione el SCID correspondiente del título.
El siguiente ejemplo de código muestra este proceso.
```xml theme={null}
test\path
DF9D8061-4790-4B84-86B4-CD060B00B4DD
256
false
```
La carpeta raíz que especifique para `NoCodePCRoot` debe ser relativa a una de las opciones de una pequeña colección.
| RelativeTo | Ubicación de la carpeta en PC |
| ----------------- | ------------------------------------------------- |
| `AppData` | Se asigna a la variable de entorno %APPDATA% |
| `Public` | Se asigna a la variable de entorno %PUBLIC% |
| `LocalAppData` | Se asigna a la variable de entorno %LOCALAPPDATA% |
| `LocalAppDataLow` | Se asigna a %USERPROFILE%\AppData\LocalLow |
| `ProgramData` | Se asigna a la variable de entorno %PROGRAMDATA% |
| `SavedGames` | Se asigna a %USERPROFILE%\Saved Games |
| `UserProfile` | Se asigna a la variable de entorno %USERPROFILE% |
Use `SavedGames` como valor de `RelativeTo`. La carpeta Saved Games (`%USERPROFILE%\Saved Games`) corresponde al identificador de carpeta conocida de Windows `FOLDERID_SavedGames`. OneDrive no sincroniza esta carpeta de forma predeterminada.
Evite usar otras ubicaciones como `AppData` (`%APPDATA%`). OneDrive puede sincronizar estas ubicaciones y podría provocar conflictos con la sincronización de guardados en la nube.
Para obtener más información sobre `FOLDERID_SavedGames`, consulte [SHGetKnownFolderPath](https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-shgetknownfolderpath).
*No puede colocar archivos directamente en el directorio raíz*. Anídelos dentro de al menos una subcarpeta a partir de la carpeta raíz. Por ejemplo, usar un nombre de archivo directamente, como `savegame1.sav`, no es válido porque savegame1.sav se ignora. `` está pensado para definir una ruta de acceso de directorio, no un archivo específico.
## Ejemplos de código
* [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/)
* [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/)
## Documentación de referencia de la API
* [XGameSaveFiles (contenido de la API)](/reference/system/xgamesavefiles/xgamesavefiles_members)
* Funciones
* [XGameSaveFilesGetFolderWithUiAsync](/reference/system/xgamesavefiles/functions/xgamesavefilesgetfolderwithuiasync)
## Consulte también
[TOC de Game Saves](/build/core-features/common/game-save/game-saves-toc)
## Related topics
- [Información general de Game Saves](/es/build/core-features/common/game-save/game-saves-overview.md)
- [Game Saves (contenido)](/es/build/core-features/common/game-save/game-saves-toc.md)
- [Referencia del método Save de XGameSave Provider](/es/reference/system/Wrappers/classes/provider/methods/xgamesave_wrapper_provider_save.md)
- [Inicio rápido de Game Saves](/es/services/playfab/player-progression/game-saves/quickstart.md)
- [Conflictos de Game Saves](/es/services/playfab/player-progression/game-saves/conflicts.md)