> ## 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. # Inicio rápido de Game Saves > El inicio rápido de PlayFab Game Saves le guía por la configuración inicial, las llamadas al SDK y la lectura y escritura de datos de guardado en la nube para que pueda integrar los guardados rápidamente. # Inicio rápido de Game Saves PlayFab Game Saves permite que los jugadores continúen su progreso sin problemas entre dispositivos mediante la sincronización de los datos de guardado con la nube. Esta guía de inicio rápido le guía por la implementación de una solución completa de guardado de juegos para las plataformas XBOX y Windows. ## Requisitos previos Antes de comenzar, asegúrese de haber: * Completado la [incorporación](/services/playfab/player-progression/game-saves/onboarding) a Game Saves * Revisado los requisitos de implementación en la sección de [información general](/services/playfab/player-progression/game-saves/overview) * Completado los requisitos que se enumeran a continuación * (Opcional) Clonado o revisado el **ejemplo de Game Saves** de un extremo a otro para Windows en GitHub: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows). El ejemplo demuestra los flujos de inicialización, sincronización, control de conflictos y carga a los que se hace referencia en este inicio rápido. ## Qué aprenderá En esta guía aprenderá a: * Inicializar el sistema Game Saves * Descargar datos de guardado existentes desde la nube * Cargar datos de guardado locales en la nube * Controlar conflictos y devoluciones de llamada de la interfaz de usuario * Administrar escenarios de dispositivo activo ## Requisitos de desarrollo ### Requisitos de software * Una [cuenta de desarrollador de PlayFab](https://developer.playfab.com) * Se recomienda Visual Studio 2019 o Visual Studio 2022 para el desarrollo con Gaming Runtime. Consulte [https://learn.microsoft.com/en-us/gaming/gdk/docs/gdk-dev/get-started/overviews/sdk-and-tools#install-visual-studio](https://learn.microsoft.com/en-us/gaming/gdk/docs/gdk-dev/get-started/overviews/sdk-and-tools#install-visual-studio) para obtener más información. * Acceso a la versión más reciente del [Microsoft Game Development Kit (GDK)](https://learn.microsoft.com/gaming/gdk/) ## Información general del flujo de Game Saves El sistema Game Saves sigue un patrón sencillo que funciona sin problemas entre dispositivos: ### Configuración inicial (una vez por sesión de juego) 1. **Inicializar los servicios**: Configure los módulos PlayFab Core y Game Saves 2. **Autenticar al usuario**: Inicie la sesión del jugador mediante la autenticación de XBOX 3. **Descargar los guardados existentes**: Sincronice los datos de guardado de otros dispositivos con el dispositivo local 4. **Obtener la ubicación de guardado**: Obtenga la carpeta raíz de guardado local donde su juego debe escribir los archivos de guardado ### Durante el juego 5. **Escribir archivos de guardado**: Su juego escribe los datos de guardado en la carpeta raíz de guardado local como de costumbre 6. **Cargar los cambios**: Cargue periódicamente los archivos de guardado modificados en la nube 7. **Continuar jugando**: Repita los pasos 5 y 6 según sea necesario durante la sesión de juego ### Fin de la sesión 8. **Carga final**: Cargue los cambios finales antes de que el jugador salga 9. **Sincronización en segundo plano**: En XBOX/Windows, el sistema controla automáticamente las cargas finales cuando el juego se cierra ### Ventajas clave * **Compatibilidad sin conexión**: Los jugadores pueden empezar a jugar incluso sin conexión a Internet * **Resolución automática de conflictos**: La interfaz de usuario integrada controla los conflictos de guardado entre dispositivos * **Cargas incrementales**: Solo se cargan los archivos modificados, lo que mejora el rendimiento * **Continuidad entre dispositivos**: Experiencia sin problemas al cambiar entre dispositivos ## Detalles de implementación Las secciones siguientes proporcionan ejemplos de código detallados para cada paso: ## Paso 1: Inicializar Game Saves Game Saves está diseñado para funcionar tanto en línea como sin conexión, lo que lo diferencia de otras API de PlayFab. Mantiene una identidad de usuario local persistente que funciona incluso cuando el dispositivo se inicia sin conexión. ### Conceptos clave * **PFLocalUserHandle**: Un identificador de usuario persistente que funciona sin conexión * **PFServiceConfigHandle**: Configuración de su título de PlayFab * **Diseño sin conexión primero**: El sistema funciona de inmediato, incluso sin conectividad a Internet ### Requisitos previos Antes de inicializar Game Saves, asegúrese de haber: * Llamado a `XGameRuntimeInitialize()` para inicializar el entorno de ejecución de XBOX * Llamado a `XUserAddAsync()` para iniciar la sesión de un usuario y obtener un `XUserHandle` * Su Title ID de PlayFab de Game Manager ### Implementación ```cpp theme={null} // Step 1: Initialize PlayFab Core HRESULT hr = PFInitialize(nullptr); if (FAILED(hr)) { // Handle initialization failure - log error and exit gracefully return hr; } // Step 2: Create service config handle with your title information PFServiceConfigHandle serviceConfigHandle{ nullptr }; hr = PFServiceConfigCreateHandle( "https://.playfabapi.com", // Replace with your actual PlayFab Title ID "", // Replace with your actual PlayFab Title ID &serviceConfigHandle); if (FAILED(hr)) { // Handle service config creation failure return hr; } // Step 3: Initialize the Game Saves module PFGameSaveInitArgs args = {}; // Set args.saveFolder here if you are targetting platforms such as Steam // where you need to provide root of where the game saves are hr = PFGameSaveFilesInitialize(&args); if (FAILED(hr)) { // Handle Game Saves initialization failure return hr; } // Step 4: Create a local user handle // NOTE: Assumes you have already obtained 'xuserHandle' from XUserAddAsync PFLocalUserHandle localUserHandle; hr = PFLocalUserCreateHandleWithXboxUser(serviceConfigHandle, xuserHandle, nullptr, &localUserHandle); if (FAILED(hr)) { // Handle local user creation failure return hr; } // Success! The Game Saves system is now initialized and ready to use ``` Reemplace `` por su Title ID de PlayFab real de Game Manager. El `xuserHandle` debe obtenerse de una llamada correcta a `XUserAddAsync`. ### Plataformas alternativas Para plataformas sin autenticación de XBOX y sin compatibilidad sin conexión, use otras versiones de `PFLocalUserCreateHandle` o `PFLocalUserCreateHandleWithPersistedLocalId` en su lugar. Consulte la documentación específica de la plataforma para obtener detalles de implementación. Por ejemplo: ```cpp theme={null} PFLocalUserHandle localUserHandle; hr = PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, nullptr, &localUserHandle); if (FAILED(hr)) { // Handle local user creation failure return hr; } ``` ## Paso 2: Sincronizar los datos de guardado desde la nube Después de la inicialización, agregue el usuario al sistema Game Saves para sincronizar los datos de guardado existentes de otros dispositivos. Este paso también configura la carpeta raíz de guardado local donde su juego leerá y escribirá los archivos de guardado. ### Cuándo llamar a esto * Una vez por sesión de juego, después de la autenticación del usuario * Cuando el usuario vuelve al menú principal del juego * Después de reanudar desde la suspensión o el segundo plano ### Qué hace este paso 1. **Descarga los guardados existentes** de otros dispositivos (solo los archivos nuevos o modificados) 2. **Conserva las marcas de tiempo de los archivos** cuando es posible para un control de versiones adecuado 3. **Controla los conflictos** automáticamente mediante la interfaz de usuario integrada 4. **Establece el dispositivo como activo** para este usuario 5. **Proporciona la ruta de la carpeta de guardado** donde su juego debe escribir los archivos ### Limitaciones importantes * Solo se puede llamar **correctamente una vez** por sesión de Game Saves * Requiere volver a inicializar el sistema Game Saves para llamarla de nuevo * Desencadena avisos de la interfaz de usuario por conflictos, problemas de almacenamiento y contención de dispositivos ### Implementación ```cpp theme={null} // Add user to Game Saves system and sync from cloud HRESULT hr; XAsyncBlock async{}; hr = PFGameSaveFilesAddUserWithUiAsync(localUserHandle, PFGameSaveFilesAddUserOptions::None, &async); if (FAILED(hr)) { // Handle API call failure return hr; } // Wait for the operation to complete // For production code, consider using a callback instead of blocking hr = XAsyncGetStatus(&async, true); if (FAILED(hr)) { // Handle async operation failure (network issues, user cancellation, etc.) return hr; } hr = PFGameSaveFilesAddUserWithUiResult(&async); if (FAILED(hr)) { // Handle specific operation failures (conflicts, storage issues, etc.) return hr; } // Get the local save root folder path for your game char saveFolder[1024] = { 0 }; hr = PFGameSaveFilesGetFolder(localUserHandle, 1024, saveFolder, nullptr); if (FAILED(hr)) { // Handle folder retrieval failure return hr; } // Check remaining cloud storage quota int64_t remainingQuota{ 0 }; hr = PFGameSaveFilesGetRemainingQuota(localUserHandle, &remainingQuota); if (FAILED(hr)) { // Handle quota retrieval failure return hr; } // Success! You can now read/write save files in the saveFolder directory printf("Save folder: %s\n", saveFolder); printf("Remaining quota: %lld bytes\n", remainingQuota); ``` ### Pasos siguientes Una vez que esta llamada se completa correctamente: * Su juego puede leer los archivos de guardado existentes del directorio `saveFolder` * Escriba nuevos archivos de guardado y cree subdirectorios según sea necesario * El dispositivo ahora se considera "activo" para este usuario * Otros dispositivos mostrarán una advertencia si el usuario intenta sincronizar en ellos ## Paso 3: Cargar los datos de guardado en la nube Una vez que su juego haya escrito archivos de guardado y subcarpetas en la carpeta raíz de guardado local, use este paso para cargar los cambios en la nube. El sistema detecta y carga automáticamente solo los archivos y subcarpetas que han cambiado desde la última carga. Las eliminaciones de archivos y carpetas también se sincronizan automáticamente con la nube. ### Puntos sugeridos para realizar la carga * **Después de un progreso significativo**: Cuando el jugador alcanza un punto de control o completa un nivel * **Antes de las transiciones de menú**: Al volver al menú principal o cambiar de modo de juego * **Al salir del juego**: Antes de que el jugador salga del juego * **Guardados periódicos**: Cada pocos minutos durante sesiones de juego prolongadas ### Opciones de carga * **`KeepDeviceActive`**: El dispositivo permanece activo, lo que permite cargas adicionales más adelante * **`ReleaseDeviceAsActive`**: Libera el dispositivo como activo, lo que permite una sincronización sin problemas en otros dispositivos ### Comportamiento por plataforma * **XBOX/Windows**: La carga continúa en segundo plano después de que el juego se cierra * **Otras plataformas** (Steam Deck, etc.): La carga debe completarse antes de salir del juego, o los datos de guardado no llegarán a la nube ### Implementación ```cpp theme={null} // Upload save files to cloud XAsyncBlock async{}; HRESULT hr = PFGameSaveFilesUploadWithUiAsync( localUserHandle, PFGameSaveFilesUploadOption::KeepDeviceActive, // Use ReleaseDeviceAsActive when quitting &async); if (FAILED(hr)) { // Handle API call failure return hr; } // Wait for upload to complete // Consider using callbacks for better user experience hr = XAsyncGetStatus(&async, true); if (FAILED(hr)) { // Handle async operation failure (network issues, storage full, etc.) return hr; } hr = PFGameSaveFilesUploadWithUiResult(&async); if (FAILED(hr)) { // Handle upload failure return hr; } // Success! Save data is now safely stored in the cloud ``` ### ¿Cuándo puedo volver a escribir en la carpeta de guardado? Durante la carga, el sistema lee y comprime sus archivos de guardado locales antes de cargarlos. Una vez que el estado de sincronización pasa a `Uploading` (notificado mediante `PFGameSaveFilesUiProgressCallback`), el sistema ha terminado de leer sus archivos y es seguro volver a escribir en la carpeta de guardado. No es necesario esperar a que se complete toda la carga antes de reanudar los guardados. Si no usa la devolución de llamada de progreso, espere a que se complete el `XAsyncBlock` antes de escribir nuevos datos de guardado. ### Procedimientos recomendados 1. **Controle los errores correctamente**: Los problemas de red no deben bloquear su juego 2. **Use las opciones adecuadas**: * Use `KeepDeviceActive` durante el juego para realizar cargas adicionales * Use `ReleaseDeviceAsActive` cuando el jugador vaya a salir o a volver al menú 3. **Advierta a los usuarios en plataformas que no sean XBOX**: Informe a los jugadores de que no deben salir durante la carga ### Consideraciones sobre la frecuencia * Se admiten varias cargas por sesión y son eficientes * Solo se cargan los archivos modificados, lo que minimiza el uso de ancho de banda * Consulte la [documentación de límites](/services/playfab/player-progression/game-saves/limits) para conocer las cuotas y restricciones específicas ## Paso 4: Controlar las devoluciones de llamada de la interfaz de usuario (opcional) Game Saves proporciona una interfaz de usuario integrada para las plataformas XBOX y Windows. En otras plataformas (como Steam Deck), su juego debe proporcionar su propia interfaz de usuario mediante el control de las devoluciones de llamada. Las devoluciones de llamada de la interfaz de usuario se activan durante `PFGameSaveFilesAddUserWithUiAsync` y `PFGameSaveFilesUploadWithUiAsync`. Cada devolución de llamada pausa la operación asincrónica hasta que su juego responde: la devolución de llamada de `XAsyncBlock` no se activa hasta que se resuelven todas las devoluciones de llamada de la interfaz de usuario. ```cpp theme={null} // Set up custom UI callbacks (call this before AddUser or Upload operations) // See sample for detailed examples of these callbacks. PFGameSaveUICallbacks callbacks{}; callbacks.progressCallback = MyProgressCallback; callbacks.syncFailedCallback = MySyncFailedCallback; callbacks.activeDeviceContentionCallback = MyActiveDeviceContentionCallback; callbacks.conflictCallback = MyConflictCallback; callbacks.outOfStorageCallback = MyOutOfStorageCallback; HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks); ``` Para ver la lista completa de tipos de devolución de llamada, API de respuesta, acciones de usuario y detalles sobre cómo funciona la máquina de estados, consulte [Devoluciones de llamada de la interfaz de usuario de Game Saves](/services/playfab/player-progression/game-saves/ui-callbacks). ## Descripción de los conflictos de guardado Los conflictos de guardado se producen cuando los mismos datos del juego se han modificado en varios dispositivos. Game Saves trata cada subcarpeta de nivel raíz como una unidad atómica para la resolución de conflictos, y los jugadores pueden elegir conservar los datos locales o los de la nube cuando surgen conflictos. Para conocer escenarios detallados de control de conflictos y procedimientos recomendados, consulte [Conflictos de Game Saves](/services/playfab/player-progression/game-saves/conflicts). ## Descripción del modo sin conexión de Game Saves Game Saves funciona tanto en línea como sin conexión. Cuando está conectado a la nube, todas las API funcionan con normalidad. Cuando está sin conexión o desconectado, los guardados locales siguen funcionando, pero las operaciones en la nube devuelven `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`. Use `PFGameSaveFilesIsConnectedToCloud()` para comprobar el estado de la conexión e implemente devoluciones de llamada de error de sincronización para controlar correctamente los problemas de red. Para conocer el comportamiento detallado sin conexión y los procedimientos recomendados, consulte [Modo sin conexión de Game Saves](/services/playfab/player-progression/game-saves/offline). ## Descripción de los cambios de dispositivo activo de Game Saves Cuando un jugador cambia de dispositivo a mitad de sesión, es importante evitar que pierda progreso accidentalmente por jugar en varios dispositivos a la vez. Si su juego solo inicia sesión mediante la característica **Single Point of Presence (SPOP)** de XBOX, este escenario se evita automáticamente. SPOP garantiza que un usuario solo pueda tener la sesión iniciada en un dispositivo XBOX a la vez. De lo contrario, también debe implementar la devolución de llamada de cambio de dispositivo activo para controlar los escenarios en los que un jugador cambia de dispositivo a mitad de sesión Para conocer el comportamiento detallado y los procedimientos recomendados, consulte [Cambios de dispositivo activo de Game Saves](/services/playfab/player-progression/game-saves/activedevicechanges). ## Depuración La manera más sencilla de ver los resultados y depurar cualquier llamada en el SDK es habilitar el [seguimiento de depuración](/services/playfab/sdks/c/tracing). Habilitar el seguimiento de depuración le permite ver los resultados en la ventana de salida del depurador y conectar los resultados a los registros propios de su juego. ## Related topics - [Devoluciones de llamada de la interfaz de usuario de Game Saves](/es/services/playfab/player-progression/game-saves/ui-callbacks.md) - [Implementación de Game Saves con el GDK de octubre de 2025](/es/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md) - [Estrategias de vinculación de cuentas para PlayFab Game Saves](/es/services/playfab/player-progression/game-saves/linking.md) - [Guía de implementación en Steam Deck para PlayFab Game Saves](/es/services/playfab/player-progression/game-saves/steam-deck-implementation.md) - [Inicio rápido de Data Connections](/es/services/playfab/data-analytics/export-data/data-connection-quickstart.md)