​

Inicio rápido de Game Saves

​

Requisitos previos

• Completado la incorporación a Game Saves
• Revisado los requisitos de implementación en la sección de información general
• 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. 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á

• 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
• 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 para obtener más información.
• Acceso a la versión más reciente del Microsoft Game Development Kit (GDK)

​

Información general del flujo de Game Saves

​

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

​

Paso 1: Inicializar Game Saves

​

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

• 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

// 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://<titleId>.playfabapi.com",    // Replace <titleId> with your actual PlayFab Title ID
    "<titleId>",                           // Replace <titleId> 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

​

Plataformas alternativas

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

​

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

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

• 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

​

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

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

​

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 para conocer las cuotas y restricciones específicas

​

Paso 4: Controlar las devoluciones de llamada de la interfaz de usuario (opcional)

// 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);

​

Descripción de los conflictos de guardado

​

Descripción del modo sin conexión de Game Saves

​

Descripción de los cambios de dispositivo activo de Game Saves

​

Depuración