Implementación de Game Saves con el GDK de octubre de 2025

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:

Nuevo diseño de carpetas del GDK: Estructura de directorios del SDK centrada en la plataforma
Integración de XGameRuntime: Entorno de ejecución multiplataforma con requisitos de implementación específicos
SDK unificado de PlayFab: Arquitectura de SDK moderna para todos los componentes de PlayFab
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 y la Guía de inicio rápido 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:

# 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:

<!-- Set include paths for Game Saves development -->
<IncludePath>$(GDK)\windows\include;$(IncludePath)</IncludePath>
<LibraryPath>$(GDK)\windows\lib\x64;$(LibraryPath)</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

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
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:

// 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:

# 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"
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
endif()

Configuración de MSBuild:

<Target Name="CopySteamRuntimeDll" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <Copy SourceFiles="$(GDK)\windows\bin\xgameruntime.dll" 
        DestinationFolder="$(OutDir)" />
</Target>

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:

<!-- Link all required Unified SDK libraries -->
<AdditionalDependencies>
  libHttpClient.lib;
  PlayFabCore.lib;
  PlayFabServices.lib;
  PlayFabGameSave.lib;
  xgameruntime.lib;
  %(AdditionalDependencies)
</AdditionalDependencies>

<!-- Automatically deploy DLLs for Steam builds -->
<Target Name="CopyUnifiedSDKDlls" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <ItemGroup>
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\libHttpClient.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabCore.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabServices.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabGameSave.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\xgameruntime.dll" />
  </ItemGroup>
  </ItemGroup>
  <Copy SourceFiles="@(UnifiedSDKDlls)" DestinationFolder="$(OutDir)" />
</Target>

¿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:

# 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} $<TARGET_FILE_DIR:${PROJECT_NAME}>)
    endforeach()
endif()

Implementación de código

Encabezados necesarios

Incluya los encabezados necesarios del SDK unificado en su proyecto:

// Essential headers for Game Saves implementation
#include <playfab/core/PFCore.h>
#include <playfab/services/PFServices.h>
#include <playfab/gamesave/PFGameSave.h>
#include <XGameRuntimeInit.h>

Secuencia de inicialización

Siga este orden de inicialización para una configuración correcta de Game Saves:

// 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, en la configuración de su título.

Secuencia de limpieza correcta

Al cerrar la aplicación, limpie los recursos en orden inverso:

// 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.

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 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
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

Referencias de código de ejemplo

Ejemplo de Game Saves para Windows: 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)

Última modificación el 28 de agosto de 2026

Temas relacionados

Guía de implementación en Steam Deck para PlayFab Game Saves Uso de Clang/LLVM con el GDK Información general de la API XGameSaveFiles Empaquetado e implementación para títulos de XBOX con el GDK Tutoriales y ejemplos de Game Saves

⌘I

​Información general de los requisitos de implementación

​1. Diseño de carpetas del GDK y configuración de rutas

​Estructura actual del GDK

​Configuración de su sistema de compilación

​Configuración de rutas obligatoria

​Ejemplo de configuración del sistema de compilación

​Detalles de compatibilidad de plataformas

​Pasos de implementación

​2. Integración de XGameRuntime

​Descripción de XGameRuntime

​Componentes principales

​Requisitos de implementación

​1. Integración básica

​2. Requisitos de la plataforma Steam

​3. Implementación automatizada de archivos DLL

​Comportamiento del entorno de ejecución específico de la plataforma

​3. Integración del SDK unificado de PlayFab

​¿Qué es el SDK unificado de PlayFab?

​Componentes obligatorios del SDK

​Requisitos de bibliotecas y archivos DLL

​Bibliotecas necesarias para la vinculación

​Archivos DLL necesarios para la implementación

​Configuración del sistema de compilación

​Configuración de MSBuild

​Configuración de CMake

​Implementación de código

​Encabezados necesarios

​Secuencia de inicialización

​Secuencia de limpieza correcta

​4. Otros componentes del SDK unificado de PlayFab

​Cambios en las API de Party y Multiplayer

​Cambios clave respecto a los SDK independientes

​5. Implementación en Steam Deck

​Consideraciones clave de Steam Deck

​Implementación completa en Steam Deck

​6. Lista de comprobación de implementación

​Primeros pasos (implementaciones nuevas)

​Migración (implementaciones existentes)

​Configuración del sistema de compilación

​Tareas de implementación de código

​Requisitos de pruebas

​7. Recursos y soporte técnico

​Vínculos de documentación

​Referencias de código de ejemplo

Información general de los requisitos de implementación

1. Diseño de carpetas del GDK y configuración de rutas

Estructura actual del GDK

Configuración de su sistema de compilación

Configuración de rutas obligatoria

Ejemplo de configuración del sistema de compilación

Detalles de compatibilidad de plataformas

Pasos de implementación

2. Integración de XGameRuntime

Descripción de XGameRuntime

Componentes principales

Requisitos de implementación

1. Integración básica

2. Requisitos de la plataforma Steam

3. Implementación automatizada de archivos DLL

Comportamiento del entorno de ejecución específico de la plataforma

3. Integración del SDK unificado de PlayFab

¿Qué es el SDK unificado de PlayFab?

Componentes obligatorios del SDK

Requisitos de bibliotecas y archivos DLL

Bibliotecas necesarias para la vinculación

Archivos DLL necesarios para la implementación

Configuración del sistema de compilación

Configuración de MSBuild

Configuración de CMake

Implementación de código

Encabezados necesarios

Secuencia de inicialización

Secuencia de limpieza correcta

4. Otros componentes del SDK unificado de PlayFab

Cambios en las API de Party y Multiplayer

Cambios clave respecto a los SDK independientes

5. Implementación en Steam Deck

Consideraciones clave de Steam Deck

Implementación completa en Steam Deck

6. Lista de comprobación de implementación

Primeros pasos (implementaciones nuevas)

Migración (implementaciones existentes)

Configuración del sistema de compilación

Tareas de implementación de código

Requisitos de pruebas

7. Recursos y soporte técnico

Vínculos de documentación

Referencias de código de ejemplo