> ## 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. # Implementación de Game Saves con el GDK de octubre de 2025 > Guía esencial para implementar PlayFab Game Saves con el GDK de octubre de 2025 (2510), incluidos los requisitos para nuevas implementaciones e instrucciones de migración Esta guía cubre la implementación de PlayFab Game Saves con el GDK de octubre de 2025 (versión 2510). Tanto si es nuevo en Game Saves como si está migrando desde una implementación anterior, este documento proporciona los requisitos esenciales y las instrucciones de configuración, con especial atención a la compatibilidad con Steam Deck. ## Información general de los requisitos de implementación Al implementar PlayFab Game Saves con el GDK de octubre de 2025, necesita comprender cuatro componentes clave: 1. **Nuevo diseño de carpetas del GDK**: Estructura de directorios del SDK centrada en la plataforma 2. **Integración de XGameRuntime**: Entorno de ejecución multiplataforma con requisitos de implementación específicos 3. **SDK unificado de PlayFab**: Arquitectura de SDK moderna para todos los componentes de PlayFab 4. **Otros componentes del SDK unificado**: Componentes actualizados de Party y Multiplayer (si se usan) Los tres primeros componentes son **obligatorios** para todas las implementaciones de Game Saves con el GDK de octubre de 2025 y posteriores, incluida la compatibilidad con Steam Deck. El cuarto componente solo se aplica si su juego usa las características de PlayFab Party o Multiplayer. **¿Es nuevo en Game Saves?** Comience con la [Información general de Game Saves](/services/playfab/player-progression/game-saves/overview) y la [Guía de inicio rápido](/services/playfab/player-progression/game-saves/quickstart) para comprender los conceptos básicos y luego vuelva aquí para conocer los detalles de implementación específicos del GDK de octubre de 2025. ## 1. Diseño de carpetas del GDK y configuración de rutas ### Estructura actual del GDK El GDK de octubre de 2025 usa una estructura de directorios plana y centrada en la plataforma. Comprender este diseño es esencial para configurar correctamente su sistema de compilación. **Diseño del GDK de octubre de 2025**: ``` \Microsoft GDK\251000\windows\include \Microsoft GDK\251000\xbox\lib\x64 \Microsoft GDK\251000\xbox\bin\x64 ``` **¿Migra desde un GDK anterior?** La estructura de carpetas anterior (`$(GDK)\GRDK\ and $(GDK)\GXDK\`) se ha reemplazado. Actualice sus scripts de compilación en consecuencia. ### Configuración de su sistema de compilación #### Configuración de rutas obligatoria Configure su sistema de compilación para usar las rutas correctas específicas de la plataforma: #### Ejemplo de configuración del sistema de compilación **Configuración de CMake**: ```cmake theme={null} # Configure GDK paths for your target platform if(CMAKE_SYSTEM_NAME STREQUAL "Windows") set(GDK_INCLUDE_DIR "${GDK_PATH}/windows/include") set(GDK_LIB_DIR "${GDK_PATH}/windows/lib/x64") elseif(XBOX) set(GDK_INCLUDE_DIR "${GDK_PATH}/xbox/include") set(GDK_LIB_DIR "${GDK_PATH}/xbox/lib/x64") endif() ``` **Configuración de MSBuild**: ```xml theme={null} $(GDK)\windows\include;$(IncludePath) $(GDK)\windows\lib\x64;$(LibraryPath) ``` #### Detalles de compatibilidad de plataformas * **XBOX**: Usa las carpetas `xbox` para todas las generaciones recientes de consolas XBOX * **Windows**: Todas las plataformas Windows (PC, Steam PC, Steam Deck-Proton) usan la carpeta `windows` * **Steam Deck**: A pesar de ejecutar SteamOS, usa la carpeta `windows` por compatibilidad con la emulación de Proton ### Pasos de implementación 1. **Configure su sistema de compilación** * Configure las rutas de inclusión y de bibliotecas con la nueva estructura del GDK * Agregue lógica de detección de plataforma si su destino son varias plataformas * Pruebe la compilación en todas las plataformas de destino 2. **Valide la integración de Game Saves** * Asegúrese de que todas las bibliotecas necesarias se vinculan correctamente * Pruebe la funcionalidad en sus plataformas de destino * Compruebe la conectividad con el servicio de PlayFab ## 2. Integración de XGameRuntime ### Descripción de XGameRuntime XGameRuntime proporciona la base para los servicios de XBOX Live y la funcionalidad de Game Saves en todas las plataformas. Esto es lo que necesita saber: #### Componentes principales **xgameruntime.lib (biblioteca de importación)** * Se vincula a su proyecto de juego en tiempo de compilación * Localiza y carga automáticamente el archivo DLL del entorno de ejecución * Controla la detección de servicios (local frente al sistema) **xgameruntime.dll (biblioteca en tiempo de ejecución)** * Implementa la funcionalidad de XBOX Live y Game Saves * Ubicación: `{GDK}\windows\bin\xgameruntime.dll` * **Fundamental para las compilaciones de Steam**: Debe implementarse con su juego ### Requisitos de implementación #### 1. Integración básica Todas las implementaciones de Game Saves requieren la inicialización de XGameRuntime: ```cpp theme={null} // Initialize XGameRuntime - required for all Game Saves implementations HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { // Handle initialization failure return hr; } ``` #### 2. Requisitos de la plataforma Steam **Esencial para las compilaciones de Steam**: Al compilar para Steam, **debe** incluir `xgameruntime.dll` en el directorio de su juego. Sin este archivo DLL, al ejecutar en Steam Deck: * La autenticación de XBOX Live fallará * La funcionalidad de Game Saves no estará disponible **Estructura de implementación**: ``` YourGame/ ├── YourGame.exe ├── xgameruntime.dll // Required for Steam/Steam Deck ├── Steam_api64.dll └── Other game files... ``` Las **compilaciones de Microsoft Store** cargan automáticamente XGameRuntime desde el sistema y no requieren la implementación del archivo DLL. #### 3. Implementación automatizada de archivos DLL **Configuración de CMake**: ```cmake theme={null} # Automatically copy XGameRuntime DLL for Steam builds if(STEAM_BUILD) add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different "${GDK_PATH}/windows/bin/xgameruntime.dll" $) endif() ``` **Configuración de MSBuild**: ```xml theme={null} ``` ### Comportamiento del entorno de ejecución específico de la plataforma | Plataforma | Origen del archivo DLL | Modo de ejecución | Compatibilidad con Game Saves | Comportamiento de sincronización | | --------------- | ---------------------- | ----------------- | ---------------------------------------- | --------------------------------------------- | | Microsoft Store | DLL del sistema | GRTS | Compatibilidad completa | Fuera de proceso, continúa después del cierre | | Steam PC | DLL del sistema | GRTS | Compatibilidad completa | Fuera de proceso, continúa después del cierre | | Steam Deck | DLL local | Servicios locales | Compatibilidad durante la vida del juego | **Solo en proceso, se detiene al cerrar** | La compatibilidad con Steam Deck requiere específicamente la implementación del archivo DLL local. El sistema no puede recurrir a los servicios del sistema como en otras plataformas. Además, el motor de sincronización se ejecuta en proceso, lo que significa que los juegos deben asegurarse de que los datos de guardado críticos se sincronizan antes del cierre. ## 3. Integración del SDK unificado de PlayFab ### ¿Qué es el SDK unificado de PlayFab? El SDK unificado de PlayFab es un SDK moderno y cohesivo que reúne todos los componentes de PlayFab bajo una única arquitectura. Game Saves ahora forma parte de este sistema unificado, lo que proporciona: **Ventajas para el desarrollo con Game Saves**: * Administración de memoria unificada en todos los componentes de PlayFab * Patrones coherentes de operaciones asincrónicas * Seguimiento y diagnóstico integrados * Carga modular de componentes (incluya solo lo que necesita) **¿Es nuevo en PlayFab?** El SDK unificado simplifica la integración al proporcionar un patrón de API único y coherente en todos los servicios de PlayFab. Si va a implementar Game Saves o cualquier otro servicio de PlayFab por primera vez, le conviene empezar con esta arquitectura moderna. ### Componentes obligatorios del SDK Las implementaciones de Game Saves necesitan estos componentes del SDK unificado: **Componentes esenciales**: * **libHttpClient**: Comunicación HTTP/WebSocket multiplataforma * **PlayFab Core**: Autenticación, administración de entidades y configuración * **PlayFab GameSave**: Funcionalidad específica de Game Saves **Componentes opcionales**: * **PlayFab Services**: Servicios compartidos para LiveOps, administración de cuentas y otros sistemas de progresión (recomendado si usa otros servicios de PlayFab) ### Requisitos de bibliotecas y archivos DLL #### Bibliotecas necesarias para la vinculación ``` Link these .lib files in your project: - libHttpClient.lib - PlayFabCore.lib - PlayFabServices.lib (optional, but recommended for additional PlayFab features) - PlayFabGameSave.lib - xgameruntime.lib ``` #### Archivos DLL necesarios para la implementación ``` Deploy these .dll files with Steam builds: - libHttpClient.dll - PlayFabCore.dll - PlayFabServices.dll (optional, but recommended) - PlayFabGameSave.dll - xgameruntime.dll ``` ### Configuración del sistema de compilación #### Configuración de MSBuild Configure su proyecto de Visual Studio para vincular el SDK unificado: ```xml theme={null} libHttpClient.lib; PlayFabCore.lib; PlayFabServices.lib; PlayFabGameSave.lib; xgameruntime.lib; %(AdditionalDependencies) ``` **¿Migra desde un GDK anterior?** Reemplace las rutas antiguas como `$(GDK)\GRDK\...\include` por la nueva estructura que se muestra arriba. #### Configuración de CMake Para proyectos basados en CMake, configure las dependencias y la implementación: ```cmake theme={null} # Link all required Unified SDK libraries target_link_libraries(${PROJECT_NAME} PRIVATE libHttpClient PlayFabCore PlayFabServices PlayFabGameSave xgameruntime ) # Automatically deploy DLLs for Steam builds if(STEAM_BUILD) set(UNIFIED_SDK_DLLS "${GDK_PATH}/windows/bin/libHttpClient.dll" "${GDK_PATH}/windows/bin/PlayFabCore.dll" "${GDK_PATH}/windows/bin/PlayFabServices.dll" "${GDK_PATH}/windows/bin/PlayFabGameSave.dll" "${GDK_PATH}/windows/bin/xgameruntime.dll" ) foreach(DLL ${UNIFIED_SDK_DLLS}) add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${DLL} $) endforeach() endif() ``` ### Implementación de código #### Encabezados necesarios Incluya los encabezados necesarios del SDK unificado en su proyecto: ```cpp theme={null} // Essential headers for Game Saves implementation #include #include #include #include ``` #### Secuencia de inicialización Siga este orden de inicialización para una configuración correcta de Game Saves: ```cpp theme={null} // 1. Initialize XGameRuntime (foundation for Xbox Live services) HRESULT hr = XGameRuntimeInitialize(); if (FAILED(hr)) { // Handle initialization failure return hr; } // 2. Initialize PlayFab Core (authentication and entity management) hr = PFInitialize(nullptr); if (FAILED(hr)) { // Handle PlayFab Core initialization failure return hr; } // 3. Initialize PlayFab Services (optional - only if using other PlayFab services) hr = PFServicesInitialize(nullptr); if (FAILED(hr)) { // Handle PlayFab Services initialization failure return hr; } // 4. Create service configuration (connects to your PlayFab title) PFServiceConfigHandle serviceConfigHandle{ nullptr }; hr = PFServiceConfigCreateHandle( "https://YOUR_TITLE_ID.playfabapi.com", // Replace with your endpoint "YOUR_TITLE_ID", // Replace with your Title ID &serviceConfigHandle); if (FAILED(hr)) { // Handle service config creation failure return hr; } // 5. Initialize Game Saves with your service configuration hr = PFGameSaveFilesInitialize(serviceConfigHandle); if (FAILED(hr)) { // Handle Game Saves initialization failure return hr; } // Game Saves is now ready for use! ``` Obtenga su Title ID y el punto de conexión de la API en [PlayFab Game Manager](https://developer.playfab.com), en la configuración de su título. #### Secuencia de limpieza correcta Al cerrar la aplicación, limpie los recursos en orden inverso: ```cpp theme={null} // Clean up Game Saves PFGameSaveFilesUninitialize(); // Close service configuration PFServiceConfigCloseHandle(serviceConfigHandle); serviceConfigHandle = nullptr; // Async cleanup for PlayFab Services (only if initialized) XAsyncBlock async{}; HRESULT hr = PFServicesUninitializeAsync(&async); hr = XAsyncGetStatus(&async, true); // Wait for completion // Async cleanup for PlayFab Core hr = PFUninitializeAsync(&async); hr = XAsyncGetStatus(&async, true); // Wait for completion // Clean up XGameRuntime XGameRuntimeUninitialize(); ``` Use siempre el patrón de limpieza asincrónica para PlayFab Services y Core a fin de garantizar la liberación correcta de los recursos. ## 4. Otros componentes del SDK unificado de PlayFab ### Cambios en las API de Party y Multiplayer Aunque no son directamente necesarios para la funcionalidad de Game Saves, el GDK de octubre de 2025 también incluye versiones actualizadas de los componentes PlayFab Party y PlayFab Multiplayer como parte del SDK unificado. Estos componentes tienen API nuevas que se integran mejor con el sistema de autenticación unificado. #### Cambios clave respecto a los SDK independientes **Integración de la autenticación**: * **Patrón heredado**: Anteriormente, los títulos que usaban los SDK independientes de Party/Multiplayer tenían que administrar manualmente `EntityID` y `EntityToken` de los resultados de inicio de sesión de PlayFab y pasarlos a las API de Party/Multiplayer * **Patrón del SDK unificado**: Party y Multiplayer ahora aceptan `PFEntityHandle` directamente, lo que elimina la administración manual de tokens **Nuevas API disponibles**: * Party: API nuevas que aceptan `PFEntityHandle` para la autenticación de usuarios * Multiplayer: API nuevas que aceptan `PFEntityHandle` para operaciones de salas y emparejamiento **Ventajas de la migración** (si usa Party/Multiplayer): * Flujo de autenticación simplificado con actualización automática de tokens * Patrones de control de errores coherentes en todos los componentes de PlayFab * Administración de memoria unificada y patrones de operaciones asincrónicas **Componentes de Party y Multiplayer**: Si su juego usa PlayFab Party o Multiplayer, considere migrar a las nuevas API unificadas que aceptan `PFEntityHandle` directamente para mejorar la integración. Sin embargo, esto no es obligatorio para la funcionalidad de Game Saves: puede omitir con seguridad la sección 4 si solo usa Game Saves. ## 5. Implementación en Steam Deck La compatibilidad de PlayFab Game Saves con Steam Deck requiere una implementación adicional considerable más allá de las compilaciones estándar para PC, incluidos flujos de autenticación personalizados, devoluciones de llamada de interfaz de usuario completas y estrategias de sincronización cuidadosas. **Complejidad de la implementación en Steam Deck**: La integración con Steam Deck implica flujos de autenticación personalizados, implementación de devoluciones de llamada de interfaz de usuario y diferencias fundamentales en el comportamiento de sincronización. Debido a la complejidad y la extensión de los requisitos de implementación, la implementación en Steam Deck se encuentra en su propia [guía dedicada](/services/playfab/player-progression/game-saves/steam-deck-implementation). ### Consideraciones clave de Steam Deck **Diferencia crítica en el comportamiento de sincronización**: * **PC con Windows**: Game Saves se ejecuta fuera de proceso y puede seguir sincronizando después del cierre del juego * **Steam Deck**: Game Saves se ejecuta solo en proceso y deja de sincronizar cuando el juego se cierra **Requisitos de implementación**: * Todos los archivos DLL del SDK unificado deben implementarse con su compilación de Steam * Flujo de autenticación de XUser personalizado con devoluciones de llamada de interfaz de usuario * Configuración del Registro para pruebas en sandbox no comercial * Patrones de sincronización frecuente para evitar la pérdida de datos **Recomendaciones de sincronización universales** (beneficiosas para todas las plataformas): Aunque estos patrones son obligatorios para Steam Deck, son muy recomendables para todas las plataformas, especialmente los dispositivos portátiles donde los apagados repentinos son habituales: * Sincronice los datos de guardado con frecuencia (después de cada nivel, punto de control o progreso significativo) * Sincronice siempre antes de mostrar las confirmaciones de "salir del juego" * Considere la sincronización en segundo plano durante las transiciones del juego * Implemente indicadores de progreso de sincronización para garantizar la finalización antes del cierre ### Implementación completa en Steam Deck Para obtener detalles completos de la implementación en Steam Deck, incluidos: * Configuración detallada del flujo de autenticación * Implementación completa de las devoluciones de llamada de la interfaz de usuario * Secuencia de inicialización paso a paso * Guía de solución de problemas * Referencias de código de ejemplo **Consulte la [Guía de implementación en Steam Deck](/services/playfab/player-progression/game-saves/steam-deck-implementation) dedicada** Comience primero con los requisitos de este documento y luego pase a la guía de Steam Deck para conocer los detalles de implementación específicos de la plataforma. ## 6. Lista de comprobación de implementación ### Primeros pasos (implementaciones nuevas) * [ ] **Configure el GDK de octubre de 2025** y compruebe la instalación * [ ] **Configure el sistema de compilación** con las rutas del GDK y las referencias de bibliotecas correctas * [ ] **Agregue las bibliotecas del SDK unificado** a la configuración de vinculación de su proyecto * [ ] **Incluya los encabezados necesarios** en su código fuente * [ ] **Implemente la secuencia de inicialización** siguiendo el patrón del SDK unificado * [ ] **Configure la implementación de archivos DLL** para las compilaciones de Steam (4 DLL obligatorios, 1 opcional) * [ ] **Pruebe la funcionalidad básica** en sus plataformas de destino ### Migración (implementaciones existentes) * [ ] **Actualice las rutas del sistema de compilación** de la estructura antigua del GDK al nuevo diseño * [ ] **Reemplace las bibliotecas independientes** por los componentes del SDK unificado * [ ] **Actualice las inclusiones de encabezados** para usar los nuevos encabezados del SDK unificado * [ ] **Modifique la secuencia de inicialización** para usar las nuevas API del SDK unificado * [ ] **Actualice la secuencia de limpieza** con el patrón de limpieza asincrónica correcto * [ ] **Agregue los archivos DLL adicionales** a la implementación de Steam (1 DLL → 4-5 DLL) * [ ] **Compruebe que la funcionalidad** permanece intacta después de la migración ### Configuración del sistema de compilación * [ ] **Rutas de inclusión**: Establecidas en `$(GDK)\windows\include` (o el equivalente de la plataforma) * [ ] **Rutas de bibliotecas**: Establecidas en `$(GDK)\windows\lib\x64` (o el equivalente de la plataforma) * [ ] **Vinculación de bibliotecas**: Agregue los archivos .lib necesarios a las dependencias del enlazador (4 obligatorios, 1 opcional) * [ ] **Implementación de archivos DLL**: Configure la copia automática para las compilaciones de Steam * [ ] **Detección de plataforma**: Agregue lógica si compila para varias plataformas ### Tareas de implementación de código * [ ] **Encabezados**: Incluya todos los encabezados necesarios del SDK unificado * [ ] **Inicialización**: Implemente la secuencia de inicialización correcta de 5 pasos * [ ] **Control de errores**: Agregue la comprobación de errores adecuada para cada paso de inicialización * [ ] **Limpieza**: Implemente la limpieza en orden inverso con patrones asincrónicos * [ ] **Configuración**: Reemplace los valores codificados de forma rígida por su Title ID y punto de conexión de PlayFab ### Requisitos de pruebas * [ ] **PC con Windows**: Compruebe la funcionalidad de Game Saves * [ ] **Steam Deck**: Complete la implementación con la [Guía de implementación en Steam Deck](/services/playfab/player-progression/game-saves/steam-deck-implementation) * [ ] **Microsoft Store**: Confirme que no hay regresiones en la funcionalidad * [ ] **Multiplataforma**: Pruebe la sincronización de guardados entre todas las plataformas (PC, Steam Deck, XBOX) ## 7. Recursos y soporte técnico ### Vínculos de documentación * [Información general de Game Saves](/services/playfab/player-progression/game-saves/overview) * [Inicio rápido de Game Saves](/services/playfab/player-progression/game-saves/quickstart) * [Guía de implementación en Steam Deck](/services/playfab/player-progression/game-saves/steam-deck-implementation) ### Referencias de código de ejemplo * **Ejemplo de Game Saves para Windows**: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/PlayFabGameSaveSample-Windows) * `GameSaveIntegration.cpp/.h`: integración principal de Game Saves * `SteamIntegration.cpp/.h`: implementación específica de Steam Deck (consulte la guía de Steam Deck) * `GameSaveIntegrationUI.cpp/.h`: implementaciones de devoluciones de llamada de interfaz de usuario (consulte la guía de Steam Deck) ## Related topics - [Guía de implementación en Steam Deck para PlayFab Game Saves](/es/services/playfab/player-progression/game-saves/steam-deck-implementation.md) - [Uso de Clang/LLVM con el GDK](/es/tools/tools-pc/visualstudio/gr-vs-clang.md) - [Información general de la API XGameSaveFiles](/es/build/core-features/common/game-save/xgamesavefiles.md) - [Empaquetado e implementación para títulos de XBOX con el GDK](/es/build/core-features/common/packaging/index.md) - [Tutoriales y ejemplos de Game Saves](/es/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md)