Preguntas frecuentes sobre el control de errores de Game Saves
En este artículo se responden preguntas comunes sobre cómo Game Saves notifica los errores: qué errores son transitorios (vale la pena reintentar), cuáles significan que ha pasado algo incorrecto (corrija la llamada) y cuándo el sistema entra en modo sin conexión en lugar de devolver un error. Game Saves se ejecuta de una de dos maneras según la plataforma, y el control de errores difiere ligeramente entre ellas:- Fuera de proceso: el servicio integrado de la plataforma realiza la sincronización y muestra su propia interfaz de usuario del sistema. Game Saves siempre se ejecuta de esta manera en XBOX y Windows.
- En proceso: el SDK realiza la sincronización en la nube por sí mismo, en plataformas donde el servicio de la plataforma no está disponible (por ejemplo, Steam Deck). Su juego controla la interfaz de usuario mediante devoluciones de llamada.
¿Cuándo pasa Game Saves al modo sin conexión en lugar de devolver un error?
El modo sin conexión es un resultado correcto, no un error. La sincronización inicial (PFGameSaveFilesAddUserWithUiAsync) solo entra en modo sin conexión cuando el jugador elige explícitamente Use Offline / Play offline en un mensaje de error de sincronización (o cuando otro dispositivo pasa a ser el dispositivo activo). En ese caso, la operación asincrónica se completa con S_OK y PFGameSaveFilesIsConnectedToCloud() devuelve false. Sigue obteniendo una carpeta de guardado local utilizable.
En cambio, una cancelación deliberada por parte del jugador se completa con E_PF_GAMESAVE_USER_CANCELLED y no proporciona ninguna carpeta de guardado; trátelo como “no permitir jugar”. Si su juego cancela la operación asincrónica por sí mismo con XAsyncCancel, se completa con E_ABORT, también sin carpeta de guardado; trate E_ABORT como su propia cancelación.
Para ver la tabla de decisiones completa y la referencia de códigos de error, consulte Modo sin conexión de Game Saves.
¿Puede PFGameSaveFilesInitialize fallar de forma transitoria?
No. PFGameSaveFilesInitialize solo valida sus argumentos y configura el estado; no accede a la red. Todos los errores que devuelve son deterministas:
E_INVALIDARG: falta un argumento obligatorio o no es válido. En proceso, esto incluye unsaveFolderque falta o no es válido (en esas plataformas se requiere una carpeta válida; en XBOX/GDK la ubicación es fija y el argumento se omite).E_PF_GAMESAVE_ALREADY_INITIALIZED: lo llamó dos veces sin una llamada intermedia aPFGameSaveFilesUninitializeAsync.
Initialize falla, reintentar no servirá de nada; corrija la entrada. Si se ejecuta correctamente una vez para una configuración determinada, no empezará a fallar más adelante por sí solo.
¿Puede PFGameSaveFilesAddUserWithUiAsync fallar de forma transitoria?
Sí: esta es la llamada que realiza la sincronización de red, por lo que puede encontrar errores transitorios (red no disponible, errores del servicio, actualización de token, falta de espacio en disco). Las llamadas HTTP se reintentan según la configuración de reintentos HTTP del título (PFHttpRetrySettings), pero no hay garantía de que un error transitorio se resuelva antes de que su juego lo vea.
Cuando esos reintentos no resuelven un error transitorio, este se muestra a través de la interfaz de usuario de error de sincronización, donde el jugador elige Retry, Use Offline o Cancel; o bien, en proceso y sin ninguna devolución de llamada de error de sincronización registrada, se devuelve como un HRESULT sin procesar. Por tanto, un error transitorio normalmente se resuelve en conexión, sin conexión o cancelación en lugar de un error sin procesar, con una diferencia importante entre las dos rutas (consulte la siguiente pregunta).
PFGameSaveFilesAddUserWithUiAsync también puede devolver errores deterministas que no son transitorios y no se pueden reintentar:
E_INVALIDARG: identificador o async nulos, u opciones en conflicto.E_PF_GAMESAVE_NOT_INITIALIZED: se llamó antes deInitialize.E_PF_GAMESAVE_USER_ALREADY_ADDED: el usuario ya se agregó (y sigue conectado).
¿Necesito registrar devoluciones de llamada de la interfaz de usuario para obtener la opción sin conexión?
Esta es la diferencia clave entre las dos rutas:- En proceso: sí. La reserva sin conexión ante un error de sincronización transitorio solo se produce si registró una devolución de llamada de error de sincronización (mediante
PFGameSaveFilesSetUiCallbacks) antes de llamar aPFGameSaveFilesAddUserWithUiAsync. Si no hay ninguna devolución de llamada registrada, un error transitorio completa la operación con el HRESULT de error sin procesar; no hay Retry ni Use Offline. En plataformas sin interfaz de usuario integrada de Game Saves, es obligatorio registrar las devoluciones de llamada. - Fuera de proceso: no para los errores de sincronización habituales. La interfaz de usuario del sistema integrada de la plataforma proporciona automáticamente las opciones Try again / Play offline, por lo que los errores de red habituales durante la sincronización ofrecen al jugador una opción sin conexión sin ninguna devolución de llamada del juego. Aun así, puede registrar devoluciones de llamada para proporcionar su propia interfaz de usuario.
¿Hay errores que se produzcan antes de que aparezca cualquier interfaz de usuario?
Solo fuera de proceso. Antes de que pueda aparecer la interfaz de usuario de sincronización,PFGameSaveFilesAddUserWithUiAsync recopila la configuración del servicio y (opcionalmente) inicia la sesión del usuario. Los errores de configuración iniciales, por ejemplo, que el servicio de la plataforma no esté disponible momentáneamente o que el título no esté configurado para Game Saves, pueden completar la llamada con un HRESULT sin procesar antes de que se muestre cualquier cuadro de diálogo. Algunos de ellos son transitorios (reintente todo PFGameSaveFilesAddUserWithUiAsync un momento después); otros indican problemas de configuración (deterministas). Los errores de inicio de sesión o de token se controlan correctamente y no hacen fallar la llamada por sí solos.
En proceso, AddUserWithUiAsync no tiene esta categoría de configuración inicial: los errores se producen durante la sincronización y pasan por la interfaz de usuario de error de sincronización (sujeta al requisito de devolución de llamada anterior).
¿Se puede cancelar una carga?
Sí.PFGameSaveFilesUploadWithUiAsync muestra una interfaz de usuario (un indicador de progreso y un mensaje de error de sincronización si encuentra un error), y el jugador puede salir de cualquiera de ellos. Cuando lo hace, la operación se completa con E_PF_GAMESAVE_USER_CANCELLED (0x800704C7) y la partida guardada no se carga.
A diferencia de la sincronización inicial, una carga no tiene un resultado correcto Use Offline. Sus resultados finales son:
- Correcto (
S_OK): se guardó en la nube. - Cancelado (
E_PF_GAMESAVE_USER_CANCELLED): el jugador salió. - Cancelado por su juego (
E_ABORT): su juego llamó aXAsyncCancelen la carga. - Error: todo lo demás (por ejemplo,
E_PF_GAMESAVE_NETWORK_FAILUREoE_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE).
E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD y PFGameSaveFilesIsConnectedToCloud() devuelve false a continuación, cuando la sesión ya estaba sin conexión, cuando la nube tiene una partida guardada más reciente de otro dispositivo o cuando el jugador elige Use Offline en el mensaje de rebloqueo que sigue a una carga anterior que falló parcialmente. Consulte Cuándo una carga deja la sesión sin conexión.
Controle E_PF_GAMESAVE_USER_CANCELLED de forma distinta a los demás errores para poder diferenciar “el jugador canceló” de “la carga produjo un error”. Es el mismo código de cancelación que usa la sincronización inicial, por lo que una sola comprobación abarca ambas operaciones.
¿Qué errores indican “ha pasado algo incorrecto” frente a un problema transitorio?
Consulte la referencia completa de HRESULT en Modo sin conexión de Game Saves.
Recomendaciones
- Trate los errores de
PFGameSaveFilesInitializecomo errores de código que debe corregir (argumentos o configuración incorrectos), no como condiciones en tiempo de ejecución que deban reintentarse. - En proceso: registre siempre sus devoluciones de llamada de la interfaz de usuario (como mínimo, la devolución de llamada de error de sincronización) antes de
PFGameSaveFilesAddUserWithUiAsync, para que los errores transitorios ofrezcan al jugador Retry/Use Offline en lugar de un error definitivo. - Fuera de proceso: esté preparado para un error sin procesar de
PFGameSaveFilesAddUserWithUiAsyncantes de cualquier interfaz de usuario (servicio o configuración). Reintente los transitorios; muestre los problemas de configuración como errores. - Condicione el juego al resultado final:
S_OK+ conectado → jugar en línea;S_OK+ no conectado → jugar sin conexión (advierta al jugador de que las partidas guardadas no se sincronizarán); cancelación o error sin carpeta → bloquear el juego.