XGameSave le permite administrar blobs y contenedores para gestionar los datos de Game Saves. Recomendamos XGameSaveFiles para Game Saves en títulos de Microsoft Game Development Kit (GDK). Use XGameSave si XGameSaveFiles no es una opción.
Para consultar la referencia de la API del sistema de XGameSave, vea XGameSave (contenido de la API).
Los siguientes términos aparecen con frecuencia en XGameSave.
- Bloqueo (lock): mecanismo que concede acceso exclusivo a los Game Saves de un título para un usuario específico en el dispositivo que está usando activamente. Garantiza que ningún otro dispositivo pueda modificar los Game Saves del usuario mientras se mantiene el bloqueo.
- Por ejemplo, si un usuario juega al Título T en el dispositivo A, este tiene un bloqueo del Título T para ese usuario.
- Proveedor: proceso intermediario que se comunica con el sistema de Game Save y es responsable de administrar los datos del título. El proveedor también administra el bloqueo de un usuario en un dispositivo.
- Contenedores: análogos a carpetas.
- Blobs: análogos a archivos individuales.
Administración del proveedor
Para adquirir un espacio de almacenamiento, el juego debe inicializar un proveedor. Después de la conexión, el título intenta adquirir un bloqueo del almacenamiento en la nube del título llamando aXGameSaveInitializeProvider o XGameSaveInitializeProviderAsync.
Si el título no puede sincronizarse desde la nube debido a una pérdida de conexión, determine si los usuarios pueden seguir jugando en modo sin conexión.
El título debe cerrar el proveedor con XGameSaveCloseProvider cuando un título se suspende o finaliza. El proveedor no se puede reutilizar a través de los límites de suspensión y reanudación.
Este problema solo se aplica a
XGameSave. XGameSaveFiles cierra el proveedor automáticamente.Administración de contenedores
Para evitar la pérdida de datos al acceder a los contenedores, como crear contenedores antes de que se complete la sincronización, llame aXGameSaveEnumerateContainerInfo o XGameSaveEnumerateContainerInfoByName para ver los contenedores que tiene un usuario.
Use XGameSaveCreateContainer para obtener un identificador de contenedor de un contenedor nuevo o existente. Si el contenedor ya existe, se proporciona su identificador. Si el contenedor no existe, se crea un contenedor nuevo y se proporciona su identificador.
Use XGameSaveDeleteContainer para eliminar un contenedor. Todos los blobs dentro del contenedor también se eliminan.
Para evitar fugas de identificadores, cierre todos los identificadores de contenedor con XGameSaveCloseContainer cuando el contenedor ya no se use o cuando el título se suspenda o finalice.
Administración de blobs
La manipulación de datos dentro de un contenedor se realiza llamando aXGameSaveCreateUpdate.
Los detalles siguientes describen cómo XGameSaveUpdate administra los cambios de blobs dentro de un contenedor y cómo se crea, modifica y envía cada actualización.
- Una actualización se aplica a un contenedor.
- Una actualización puede escribir como máximo GS_MAX_BLOB_SIZE (16 MB).
- Se pueden modificar varios blobs en una sola actualización.
- Un blob individual solo puede tener una modificación por actualización.
-
Enviar una actualización consume el identificador de
XGameSaveUpdate. Cierre el identificador tanto si el envío se realizó correctamente como si falló. - Las actualizaciones son atómicas. Si falla cualquiera de sus partes, falla toda la actualización.
-
XGameSaveCreateUpdatecrea un contexto de actualización para almacenar todas las modificaciones de blobs. -
XGameSaveSubmitBlobWriteescribe datos en un blob nuevo o existente y requiere un contexto de actualización. -
XGameSaveSubmitBlobDeleteelimina el blob. -
XGameSaveSubmitUpdateenvía el contexto de actualización. -
XGameSaveCloseUpdatecierra el identificador de actualización. El título lo llama después de cada envío para evitar fugas. -
Use
XGameSaveEnumerateBlobInfooXGameSaveEnumerateBlobInfoByNamepara acceder a todos los blobs de un contenedor.
Los datos escritos en blobs se representan como
Base64 cuando los datos se exportan en XML.Implementación
Los pasos siguientes muestran el flujo general de una implementación deXGameSave.
- Al iniciar o reanudar el título, inicialice el proveedor.
- Enumere y cree identificadores de contenedor.
- Envíe periódicamente
XGameSaveUpdatescon modificaciones de blobs y limpie el identificador de actualización al enviar. - Cierre los identificadores de contenedor y de proveedor cuando el título se suspenda o finalice.
Llame a
XGameSaveInitializeProvider cuando el título se inicie y cuando se reanude. Esta llamada garantiza que el proveedor se inicialice correctamente y permanezca activo mientras el título se ejecuta. Si no se llama, el título puede comportarse de forma impredecible.Ejemplo de código
Para ver un ejemplo de código que muestra cómo usar las API deXGameSave, consulte GameSaveCombo.
Flujo de Game Saves
Este es un diagrama de flujo del flujo simplificado de Game Saves. Se explica a continuación.
Inicio del título
El inicio del título se produce cuando el usuario inicia o reanuda el título.Inicio de sesión del usuario
El título inicia el inicio de sesión del usuario. Esta llamada también es donde se invocaXGameSaveInitializeProvider.
Para obtener más información sobre la configuración de usuarios, consulte Modelos de usuario.
Comprobación de conexión
El título determina si puede conectarse a la red de XBOX. Si no puede, depende de usted habilitar el modo sin conexión para su título.Comprobación de propiedad de los datos
El dispositivo comprueba si el usuario está jugando actualmente en otros dispositivos. Solo un dispositivo a la vez puede acceder a los datos del usuario para un título específico.Sincronización de datos con la nube
El dispositivo sincroniza los datos del almacenamiento local de Game Saves con la nube. Si hay un conflicto, el sistema pide al usuario que lo resuelva con un diálogo de resolución de conflictos. Diálogo: ¿Cuál desea usar? Cuando los datos del dispositivo son más recientes que los datos de la nube, el título pide al usuario que elija entre usar los datos locales o los datos de la nube.Bucle de juego
El título puede leer y escribir libremente en el almacenamiento local de Game Saves.Fin de la sesión de juego
Cuando la sesión de juego finaliza, el sistema intenta cargar automáticamente los datos en la nube. Asegúrese de que su título llame aXGameSaveUninitializeProvider durante su flujo de salida para evitar dejar un proveedor inicializado. Un cierre estructurado garantiza que los datos se guarden correctamente antes de salir.
Para obtener información detallada sobre la sincronización, consulte Descripción del flujo de sincronización de Game Saves.
Límites y cuotas
Límites
XGameSaveUpdate limita cada actualización a 16 MB. Como resultado, XGameSave solo puede administrar actualizaciones de archivos individuales de hasta 16 MB. Este límite difiere de XGameSaveFiles, que admite archivos de hasta 64 MB.
Cuotas
La cantidad máxima de datos que un usuario puede guardar por título es de 256 MB. Use XGameSaveGetRemainingQuota para obtener la cuota restante. Para obtener una extensión de almacenamiento para su título, póngase en contacto con su Developer Partner Manager (DPM).Procedimientos recomendados
- No guarde datos e inmediatamente los consulte para pedir los mismos datos de vuelta.
- Las dependencias de datos entre contenedores no son confiables. Cada llamada a
XGameSaveSubmitUpdateaplica todos los cambios de forma atómica o no aplica ninguno. - Cuantos más blobs use por llamada de actualización, más tiempo se requiere para completar las operaciones atómicas necesarias del sistema de archivos para almacenar los datos.
Preguntas frecuentes
Estoy actualizando mi implementación de Game Saves. ¿Cuál es el enfoque correcto?
Use XGameSaveFiles.¿Puedo usar XGameSave con XGameSaveFiles?
Sí. Sin embargo, hágalo solo para migraciones. Para obtener información detallada, consulte Interoperabilidad entre XGameSave y XGameSaveFiles.¿En qué ruta de archivo guarda XGameSave?
Consola: se proporciona una ruta temporal mientras el título está activo. No se puede acceder a los archivos de la consola mediante el Explorador de archivos. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
Tenga en cuenta que la ruta de PC de XGameSave es diferente de la de XGameSaveFiles. Esta usa xgs.