XGameSaveFilesGetFolderWithUIAsync. También describe el comportamiento recomendado de sincronización automática con la nube de Win32, los pasos de depuración, las orientaciones sobre cuotas y diagnóstico, los procedimientos recomendados de rendimiento y las respuestas a preguntas comunes.
XGameSaveFiles proporciona API que permiten a su título leer y escribir datos de usuario, conservarlos entre sesiones y sincronizarlos sin problemas con la nube para que los jugadores puedan usar sus datos en cualquier dispositivo. Use XGameSaveFiles para los guardados de partidas en títulos de Microsoft Game Development Kit (GDK). Use XGameSave solo cuando XGameSaveFiles no esté disponible para su escenario.
Para consultar la referencia de la API del sistema de XGameSaveFiles, vea XGameSaveFiles (contenido de la API).
Los siguientes términos aparecen con frecuencia en XGameSaveFiles.
- 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 guardados de partidas 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.
Lógica de rutas de XGameSaveFiles
XGameSaveFiles proporciona una ruta de archivo que puede usar para interactuar con el sistema de Game Saves. La ruta de archivo se integra con la sincronización en la nube, de modo que los datos guardados en la ruta se sincronizan automáticamente con la nube. Use las API de FileIO de Win32 en la ruta proporcionada. Para títulos de GDK, use XGameSaveFiles como enfoque de Game Saves. XGameSaveFiles asigna los conceptos de contenedores a carpetas y de blobs a archivos.
Aunque XGameSaveFiles oculta la mayor parte de la complejidad del sistema de guardado en la nube, sigue aplicando límites de nombres de directorios y archivos porque la característica se basa en Microsoft Azure Blob Storage. Considere el siguiente código de ejemplo de lo que un título podría usar para su guardado.
XGameSaveFilesGetFolderWithUiAsyncdevuelve el [ROOT].- Todo lo que sigue a [ROOT], hasta la última barra diagonal inclusive, se asigna a un contenedor.
- Los nombres de contenedor se limitan a letras mayúsculas (A-Z), letras minúsculas (a-z), números (0-9), guiones bajos (_), puntos (.), guiones (-) y barras diagonales (/).
- Los nombres de contenedor se limitan a 256 caracteres.
- Los nombres de contenedor no pueden terminar en un punto, contener dos puntos consecutivos ni comenzar con un punto o un guión.
- Todo lo que sigue a la última barra diagonal en el nombre de archivo se asigna a un blob.
- Los nombres de archivo se limitan a 65 caracteres, pero por lo demás pueden ser caracteres Unicode compatibles con el sistema de archivos New Technology File System (NTFS).
- La ruta completa resultante, incluido el nombre de archivo (pero no el [ROOT]), debe ser inferior a
MAX_PATH(260 caracteres).
Implementación de XGameSaveFiles
Los pasos siguientes muestran la implementación general deXGameSaveFiles.
- Al iniciar o reanudar el título, llame a
XGameSaveFilesGetFolderWithUIAsyncpara inicializar el proveedor y obtener la ruta de archivo. - Lea y escriba libremente en la ruta de archivo durante el juego.
XGameSaveFilesGetFolderWithUIAsync administra automáticamente la duración del proveedor de Game Saves y configura el espacio de almacenamiento local de Game Saves.
Llame a
XGameSaveFilesGetFolderWithUIAsync cuando el título se inicie y cuando se reanude. Esta llamada inicializa el proveedor de Game Saves y lo mantiene activo mientras se ejecuta la sesión de juego. Si omite este paso, el sistema puede comportarse de forma impredecible.Ejemplo de código
Para ver un ejemplo de código que muestra cómo usar las API deXGameSaveFiles para acceder a carpetas en XBOX, consulte GameSaveFilesCombo.
Flujo de Game Saves
Este es un diagrama de flujo del flujo simplificado de Game Saves.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 comienza el proceso de inicio de sesión del usuario. Esta operación también es donde se llama aXGameSaveFilesGetFolderWithUIAsync. 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, deberá habilitar el modo sin conexión para el 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? Si 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 la ruta de carpeta proporcionada porXGameSaveFilesGetFolderWithUIAsync.
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. Este proceso se produce entre 10 y 30 segundos después de que el título finalice. 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
El tamaño máximo de archivo que puede guardar medianteXGameSaveFiles es de 64 MB. Este comportamiento difiere de XGameSave, que limita cada archivo a 16 MB.
Cuotas
La cantidad máxima de datos que un usuario puede guardar por título es de 256 MB. Use XGameSaveFilesGetRemainingQuota para obtener la cuota restante. Para obtener una extensión de almacenamiento de modo que su título tenga un límite de almacenamiento por usuario mayor, póngase en contacto con su Developer Program Manager (DPM).Preguntas frecuentes
¿Puedo usar XGameSaveFiles con XGameSave?
Sí. Sin embargo, use este enfoque solo para migraciones. Para obtener información detallada, consulte Interoperabilidad entre XGameSave y XGameSaveFiles.¿En qué ruta de archivo guarda XGameSaveFiles?
Consola: el título proporciona una ruta temporal mientras está activo. No se puede acceder a los archivos de la consola mediante el Explorador de archivos. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
La ruta de PC de XGameSaveFiles es diferente de la de XGameSave. Esta usa wgs.
¿Puedo especificar la ruta donde se deben guardar los datos?
Sí, pero solo para PC. Recomendamos este enfoque solo si está portando su solución desde otro título. Esta solución usa guardados en la nube sin código.Documentación de referencia de la API
Consulte también
Tabla de contenido de Game Saves Sí, pero solo para PC. Portar su solución desde otro título podría requerir este enfoque. Esta solución usa guardados en la nube sin código.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 .exe directamente no activa la redirección del guardado en la nube. Alternar entre inicios empaquetados y directos del .exe puede hacer que los datos guardados parezcan perdidos. Para obtener más información, consulte Portar títulos anteriores a Game Saves de PC con guardados en la nube sin código.