Ciclo de vida del juego de XBOX

Este tema presenta los conceptos y eventos que componen el ciclo de vida del juego. Muestra cómo implementar el estado del juego y los eventos de cambio de estado en su juego para proporcionar una experiencia fluida a los usuarios. También le muestra cómo superar los requisitos de certificación y presenta las herramientas y características disponibles para depurar estos eventos. Los juegos de Microsoft Game Development Kit (GDK) tienen varios estados de recursos entre los que realizan transiciones a lo largo de su vida. Cambiar entre estos estados permite a la consola XBOX proporcionar la experiencia multitarea con capacidad de respuesta que los usuarios esperan. También garantiza que los juegos obtengan la mayor cantidad de recursos posible de la consola cuando los usuarios juegan. Sin embargo, para lograrlo, hay algunos eventos e interacciones que los juegos de Microsoft Game Development Kit (GDK) deben estar preparados para controlar.
Introducción Estados del ciclo de vida del juego Transiciones de estado del ciclo de vida Devoluciones de llamada de eventos del ciclo de vida Respuesta a Suspender y Reanudar Respuesta a Restringir y Anular restricción Inicio Eventos relacionados con el ciclo de vida Trabajar con tiempos de espera del GDK Reanudación rápida Herramientas y características de depuración Apéndice

Introducción

Los estados y eventos del ciclo de vida del juego hacen posible que los usuarios cambien entre juegos, el shell de XBOX y otras aplicaciones de forma rápida y eficaz. Este proceso requiere alguna acción por parte de los juegos y las aplicaciones para que puedan controlar las transiciones entre los estados del ciclo de vida. Si se controla bien, el trabajo proporciona una experiencia fluida y sin interrupciones para los usuarios cuando cambian hacia y desde su juego. Este tema explica los diversos aspectos de la administración del ciclo de vida de su juego y describe las herramientas que están disponibles para apoyar esos aspectos. Si está familiarizado con la administración de la duración de procesos (PLM) de las aplicaciones de XBOX One Software Development Kit o de la Plataforma universal de Windows (UWP), esta información le resultará familiar. Tenga en cuenta que hay algunas diferencias clave y mejoras para las aplicaciones del GDK. Este tema comienza con:

Un análisis de los diferentes estados del ciclo de vida.
Las transiciones entre ellos.
Las devoluciones de llamada asociadas a ellos.

A continuación, este tema explica los requisitos para controlar estas transiciones correctamente a fin de superar los requisitos de XBOX (XR) y analiza casos de uso comunes que la mayoría de los juegos deberían considerar. Por último, este tema presenta las herramientas y las características de depuración que facilitan la comprensión y la corrección de los problemas de transición de estado.

Estados del ciclo de vida del juego

Un juego de Microsoft Game Development Kit (GDK) instalado en una consola XBOX siempre está en uno de los siguientes cinco estados posibles.

En ejecución
Restringido
En suspensión
Suspendido
No en ejecución

Puede determinar el estado de un juego comprobando:

El State que aparece en la vista Home de XBOX Manager.
El valor que aparece en Dev Home junto a un juego en la vista Games & apps.
El XBOX Device Portal.
La herramienta de línea de comandos xbapp query.

En ejecución

Cuando un juego está en ejecución, se ejecuta con disponibilidad completa de recursos. El juego tiene el foco de entrada y su ventana es visible para el usuario. La disponibilidad completa de recursos significa que el juego se está ejecutando con:

Seis núcleos de CPU físicos (core0-core5), más entre el 50 y el 90 por ciento del núcleo de CPU core6 en dispositivos de la familia XBOX One, y el 100 por ciento del núcleo de CPU core6 en las consolas XBOX Series.
Entre el 97 y el 100 por ciento de uso de la GPU. Tenga en cuenta que el sistema operativo puede usar hasta un 3 por ciento de la GPU.
Entre 5 y 13 GB de memoria, según la configuración de MicrosoftGame.config y la consola en la que se ejecute el juego. Para obtener más información, consulte Configuración de la memoria del título.

Para ilustrar mejor los cambios de recursos de CPU entre el estado En ejecución y el estado Restringido, considere el siguiente diagrama que muestra el estado de los núcleos de la CPU cuando un juego está en el estado En ejecución.

Diagrama que muestra el estado de los núcleos de la CPU cuando el juego está en el estado En ejecución

Las consolas XBOX Series pueden habilitar el multithreading simultáneo (SMT), lo que cambia ligeramente el diagrama. Para obtener más información sobre SMT, consulte la comparación de CPU y memoria de XBOX One frente a XBOX Series X|S y el apéndice para ver diagramas que detallan los núcleos de la CPU mediante SMT.

Restringido

Cuando un juego se ejecuta en el estado de ejecución Restringido, se ejecuta con una disponibilidad de recursos reducida. El juego no puede recibir entradas del usuario en este estado. Es probable que la ventana del juego esté parcialmente oscurecida o no sea visible para el usuario. Un juego pasa a este estado cuando el usuario interactúa con alguna característica o experimenta algo distinto del juego activo, como interactuar con un menú como la Guía, una aplicación del sistema como Configuración o una interfaz de usuario invocable por el título (TCUI) como el selector de cuentas. Cuando un juego está Restringido, sus recursos disponibles se reducen a los siguientes estados.

Cuatro núcleos de CPU físicos. Los subprocesos se pliegan con el siguiente patrón.
- Los subprocesos de core0 y core1 no se ven afectados.
- Los subprocesos de core2 y core3 se dividen en el tiempo en un núcleo de CPU físico.
- Los subprocesos de core4, core5 y core6 se dividen en el tiempo en un núcleo de CPU físico.
Aproximadamente el 45 por ciento de la GPU.
La misma memoria disponible que en el estado En ejecución. Tenga en cuenta que estar Restringido no cambia la cantidad de memoria disponible para el juego.

La siguiente ilustración muestra el estado de los núcleos de la CPU cuando un juego está en el estado Restringido.

Ilustración que muestra el estado de los núcleos de la CPU cuando un juego está en el estado Restringido

En suspensión

Cuando un juego se ejecuta en el estado de ejecución En suspensión, se ejecuta con los mismos recursos que en Restringido, salvo que indica que la consola ha iniciado el proceso de transición del juego al estado Suspendido. En suspensión es un estado transitorio. Por ello, dependiendo de la frecuencia con la que consulte el estado de ejecución, el estado de ejecución En suspensión puede ser difícil de observar.

Suspendido

Cuando un juego está en el estado de ejecución Suspendido, sigue residiendo en la memoria, pero ya no se está ejecutando. Sus subprocesos no se programan y, en consecuencia, no está usando nada del tiempo de la CPU ni de la GPU. Si un juego está suspendido, todo el Game OS dentro del cual se ejecuta el juego se suspende de forma similar, y el estado del sistema operativo y de la memoria permanece intacto hasta que se produce otra transición de estado.

No en ejecución

Este es el estado de un juego que no se está ejecutando, no está cargado en memoria y no está usando ninguno de los recursos de la consola. Tenga en cuenta que algunas herramientas (como xbapp query) pueden notificar este estado de ejecución como estado de ejecución del paquete 0 (desconocido).

Transiciones de estado del ciclo de vida

Esta sección explica cada una de las transiciones de estado del ciclo de vida y proporciona causas de ejemplo para cada una. Algunas interacciones del usuario con la consola pueden hacer que muchos de estos eventos ocurran de forma secuencial, y a veces muy rápidamente, pero el juego sigue pasando por todas estas transiciones. El siguiente diagrama muestra las transiciones de estado entre los estados del ciclo de vida. Para simplificar, el diagrama muestra solo las transiciones sin error. Tenga en cuenta que un juego puede seguir pasando de cualquier estado al estado No en ejecución como resultado de un bloqueo.

Transición de En ejecución a Restringido (Restringir)

Esta transición representa la reducción de los recursos disponibles para el juego. El juego puede registrarse para recibir una devolución de llamada cuando esto ocurre llamando a RegisterAppConstrainChangeNotification. Esta transición se produce cuando:

Un usuario abre la Guía.
Se presenta la TCUI (como el selector de cuentas).
Un usuario vuelve a Inicio.
El juego pierde el foco.

Transición de Restringido a En suspensión (Suspensión iniciada)

Cuando un juego está en proceso de suspenderse, primero pasa al estado En suspensión. Se activan todas las devoluciones de llamada registradas con RegisterAppStateChangeNotification. El juego permanece en el estado En suspensión hasta que regresa de todos los controladores de devolución de llamada, o hasta que se produce un tiempo de espera de un segundo. Si los controladores regresan antes del tiempo de espera, el juego completa entonces su suspensión. De lo contrario, el juego se termina. Un juego comienza a suspenderse cuando:

La consola se pone en modo de espera conectado.
El juego no ha estado visible durante 10 minutos.
Se produce la primera fase de la terminación de un juego, como cuando se inicia un juego nuevo.

Esta transición a veces se denomina quiesce.

Transición de En suspensión a Suspendido (Suspensión completada)

Esta transición se produce automáticamente cuando un juego que está en el estado En suspensión regresa de sus controladores de devolución de llamada registrados con RegisterAppStateChangeNotification. Los subprocesos de un juego dejan de ejecutarse en cuanto entra en este estado.

Transición de Suspendido a No en ejecución (Terminar)

Esta transición representa la eliminación del juego de la memoria. Un juego no tiene ningún control ni interacción con esta transición porque un juego suspendido no se está ejecutando. Una terminación se produce:

Cuando el usuario decide salir del juego desde Inicio.
Cuando la consola se apaga (sin pasar al modo de espera conectado).
En la fase final del cierre de un juego, como cuando se inicia un juego nuevo.
Cuando los datos guardados del juego no están sincronizados con la nube. Consulte Terminación por el sistema de almacenamiento conectado para obtener más detalles.

Transición de No en ejecución a En ejecución (Iniciar)

Esta transición de estado representa la carga del juego y su ejecución dentro del Game OS y a menudo coincide con el inicio del propio Game OS. Esto ocurre siempre que un usuario:

Selecciona el icono de un juego.
Acepta una invitación de juego.
Interactúa con referencias al juego en el shell y el sistema de XBOX.

Transición de Suspendido a Restringido (Reanudar)

Esta transición de estado suele ir seguida de un evento de anulación de restricción. Representa que los subprocesos del juego comienzan a ejecutarse de nuevo, y la transición comienza con devoluciones de llamada a cualquier controlador de RegisterAppStateChangeNotification. Un juego se reanuda cuando estaba previamente en el estado Suspendido y se lleva al primer plano (normalmente a partir de las mismas interacciones que iniciarían el juego si hubiera estado en el estado No en ejecución).

Transición de Restringido a En ejecución (Anular restricción)

Esta transición de estado es la inversa de la transición Restringir. Representa la promoción de los recursos disponibles para el juego de nuevo hasta la cantidad completa del estado En ejecución. Esta transición también tiene una devolución de llamada asociada a cualquier controlador de RegisterAppConstrainChangeNotification y se produce cada vez que el juego se convierte en la aplicación en primer plano. Cuando un juego se termina debido a interacciones típicas con la consola, como iniciar otro juego o apagar la consola, sigue pasando primero al estado Suspendido antes de la terminación. Esto garantiza que el juego que se está ejecutando actualmente tenga la posibilidad de guardar el estado antes de que se cierre. Sin embargo, si un juego se bloquea o no consigue suspenderse, pasa directamente al estado No en ejecución.

Terminación por el sistema de almacenamiento conectado

Si los datos guardados locales del juego no están sincronizados con la nube, el sistema de almacenamiento conectado terminará el juego la próxima vez que se suspenda. Esto le permite sincronizar los datos guardados más recientes cuando se inicie de nuevo. La terminación por esta razón no es un bloqueo y no provocará un error de XR-001. Este caso no es común, pero puede ocurrir si inicia un juego mientras la consola no está conectada a la red de XBOX (también conocida como XBOX Live) y, después, se vuelve a conectar mientras se está ejecutando. Esto también puede ocurrir durante el desarrollo si el almacenamiento conectado no está configurado correctamente para el título. Puede reconocer este caso buscando líneas como las siguientes en xbWatson o en la ventana XBOX System Monitor de Visual Studio:

 [ConsoleEtw] [1] SuspendComplete
 [ConsoleEtw] TerminateApplicationAfterSuspend <package name>
 [ConsoleEtw] Eviction of package <package name> because -2138890207
 [ConsoleEtw] [1] TerminateBegin Successful
 [ConsoleEtw] [1] TerminateComplete

SuspendComplete indica que el juego se suspendió correctamente y no se bloqueó ni agotó el tiempo de espera. TerminateApplicationAfterSuspend indica que la terminación fue iniciada por el sistema después de una suspensión correcta. El valor -2138890207 es un HRESULT, CS_E_TERMINATEDTITLE_NOLOCK, que muestra el motivo de la terminación.

Devoluciones de llamada de eventos del ciclo de vida

Esta sección explica cómo los juegos realizan la transición entre estados. También explica cómo los juegos determinan cuándo se producen estas transiciones y cómo responden después a estas transiciones. Para los juegos de Microsoft Game Development Kit (GDK), hay dos eventos en los que puede registrarse para recibir información de cambio de estado. Esto se muestra en el siguiente ejemplo de código.

ULONG RegisterAppStateChangeNotification(
    _In_ PAPPSTATE_CHANGE_ROUTINE Routine,
    _In_opt_ PVOID Context,
    _Out_ PAPPSTATE_REGISTRATION* Registration
    );

ULONG RegisterAppConstrainedChangeNotification(
    _In_ PAPPCONSTRAIN_CHANGE_ROUTINE Routine,
    _In_opt_ PVOID Context,
    _Out_ PAPPCONSTRAIN_REGISTRATION* Registration
    );

Para obtener más información, consulte RegisterAppStateChangeNotification.

La notificación de cambio de restricción es específica de las consolas XBOX y actualmente no tiene una página de referencia de API. La API es muy similar, con solo el ligero cambio de “State” a “Constrained” en el nombre y los parámetros.

El PVOID Context puede ser cualquier cosa, y se pasa a la función Routine cuando se le llama. Puede conservar Registration para anular el registro de estos eventos con UnregisterAppStateChangeNotification y UnregisterAppConstrainedChangeNotification. A Routine, que se pasa a las funciones de registro, se le llama en un subproceso del grupo de subprocesos predeterminado dentro del título cuando se produce el evento asociado. A todas las rutinas registradas con esta función se les llama de forma asincrónica en subprocesos independientes del grupo de subprocesos. Esto puede ocurrir en cualquier momento durante un fotograma. Para RegisterAppStateChangeNotification, se llama a Routine con un valor booleano de true en cuanto la consola ha establecido el juego en el estado En suspensión y ha iniciado el tiempo de espera de suspensión. Se llama a Routine con un valor booleano de false al reanudar el juego del estado Suspendido al estado En ejecución. Para RegisterAppConstrainedChangeNotification, se llama a Routine con un valor booleano de true cuando la consola establece el juego en el estado Restringido. Se llama a Routine con un valor booleano de false al anular la restricción del juego del estado Restringido al estado En ejecución. Para ver un ejemplo que demuestra cómo configurar y controlar estos eventos y garantizar que se controlan en el subproceso principal en un punto coherente del fotograma de un juego, consulte el código de ejemplo en Guía de portabilidad de Microsoft Game Development Kit para XBOX One. También puede consultar main.cpp del ejemplo SimplePLM, o de la plantilla de proyecto Direct3D 12 XBOX Game de Microsoft Game Development Kit (GDK) en Visual Studio. Puede descargar ejemplos de XBOX Developer Downloads. Al examinar los minivolcados de bloqueo durante el quiesce, es posible que se encuentre con la situación bastante confusa de no ver sus devoluciones de llamada registradas en las pilas de ninguno de los subprocesos. Esto se debe a la optimización de llamadas de cola; para evitarlo, simplemente encapsule su devolución de llamada en:

#pragma optimize( "", off ) 
/* ... */
#pragma optimize( "", on )

Los juegos de Microsoft Game Development Kit (GDK) que se ejecutan en un equipo Windows no se suspenderán. En un equipo Windows, estos juegos aún pueden llamar a RegisterAppStateChangeNotification, pero tenga en cuenta que la devolución de llamada PAPPSTATE_CHANGE_ROUTINE no se activará.

Respuesta a Suspender y Reanudar

Hay algunas cosas que un juego debe hacer para suspenderse de modo que pueda proporcionar una experiencia fluida a los usuarios que cambian hacia y desde el juego y garantizar que el juego supere los XR.

Tiempo de espera de suspensión

Para completar una suspensión (lo que es necesario para superar XR-001), un juego debe tener al menos una rutina de devolución de llamada registrada con RegisterAppStateChangeNotification. Cuando se activa la devolución de llamada, se llama a todas las rutinas registradas de forma asincrónica en subprocesos independientes del grupo de subprocesos predeterminado. El juego tiene un segundo para regresar de todas las rutinas registradas, lo que indica al sistema que el juego puede pasar al estado Suspendido. Si el juego no regresa de las rutinas de suspensión en el plazo de un segundo, o si no hay ninguna devolución de llamada registrada, el juego se termina y pasa al estado No en ejecución (lo que supone un error de XR-001). Este proceso garantiza que la consola pueda cambiar entre juegos rápidamente, a la vez que garantiza que el juego esté preparado para la suspensión antes de entrar en el estado suspendido.

Direct3D

En respuesta a la llamada a la rutina de suspensión, y antes de regresar de ella, el juego debe llamar a SuspendX en su ID3D12CommandQueue desde su subproceso de representación. Esto garantiza que el estado de la GPU se guarde en preparación para la suspensión. Al reanudar, el juego debe llamar a ResumeX para restaurar el estado. Llamar a cualquier API de Direct3D entre las llamadas a SuspendX y ResumeX da como resultado que se produzca una excepción, lo que provoca un bloqueo. No llamar a SuspendX antes de regresar de las rutinas de suspensión hace que la suspensión falle y que el título se termine (de nuevo, un error de XR-001). Para obtener más información, consulte la compatibilidad de Direct3D con la suspensión y la reanudación.

API de XGameSave

Cuando un juego recibe la notificación de suspensión, tiene un segundo de tiempo de ejecución antes de que deba suspenderse. Cuando un juego está en el estado Suspendido, podría pasar al estado No en ejecución sin ningún tiempo de ejecución adicional. Esto significa que, durante ese segundo de tiempo de suspensión, el juego debe guardar todos los datos de usuario no guardados antes de entrar en el estado Suspendido. Las API de XGameSave están diseñadas para admitir el guardado en este período de tiempo limitado. La API de XGameSave usa RAM fuera de la reserva del título como primer punto de almacenamiento para maximizar la velocidad de escritura del título durante la corta ventana de tiempo de suspensión. XR-052: User State establece que los títulos no deben causar una pérdida involuntaria de datos de usuario, lo que incluye el progreso y el estado del usuario según corresponda. En general, los juegos deben asegurarse de que parte de su control de suspensión incluya el guardado de los datos de usuario. También es una buena idea guardar con más frecuencia que solo durante la suspensión. Esto garantiza que el juego no tenga que preparar un guardado grande durante el tiempo de espera, o que cosas como un corte de energía no den lugar a una pérdida significativa de datos de usuario. Para obtener más información, consulte Información general de los guardados de juego y el ejemplo GameSave. Tenga en cuenta que es preferible usar las versiones asincrónicas de las API de XGameSave. Esto permitirá que un título continúe con el resto de su código de suspensión mientras el sistema escribe los datos guardados del juego. Para ver un ejemplo de cómo se hace esto, consulte XGameSaveSubmitUpdateAsync. Antes de reanudar el juego, el sistema operativo comprobará si el juego guardado se ha modificado en otro dispositivo mientras el juego estaba suspendido. Si el dispositivo está en línea y esta comprobación indica que los guardados se han modificado, el juego se terminará y se volverá a iniciar para que el juego quede en un estado coherente. Si el dispositivo está sin conexión cuando se realiza la comprobación, el juego podrá iniciarse de todos modos. Al reanudar, los juegos siempre deben intentar volver a adquirir su proveedor de guardado de juego llamando a XGameSaveInitializeProvider o a XGameSaveInitializeProviderAsync. Volver a inicializar el proveedor garantiza que estén disponibles los datos guardados más recientes.

Usuarios y emparejamiento de usuario y mando

XR-112: Establishing a User and Controller During Initial Activation and Resume establece que, cuando se reanuda un título, este debe validar el emparejamiento de usuario/mando y reaccionar en consecuencia reanudando la sesión del usuario anterior o adquiriendo un usuario nuevo (o usuarios nuevos). El comportamiento exacto puede depender de cómo el juego controle sus usuarios y mandos. Es importante no confiar en ninguna información sobre el estado de los usuarios o los mandos antes de la suspensión, y restablecer el estado de los usuarios y los mandos al reanudarse. Debe conservar XUserHandle durante un ciclo de suspensión/reanudación porque es así como el juego obtiene actualizaciones sobre el estado del usuario. Además, las devoluciones de llamada registradas con XUserRegisterForChangeEvent y XUserRegisterForDeviceAssociationChanged se activan durante una reanudación para actualizar el juego con los cambios de estado que se han producido. Para obtener más información sobre la administración de usuarios y dispositivos, consulte Identidad de usuario y XUser, y Usuarios y dispositivos de entrada. Para ver un ejemplo de cómo podrían controlar esto los juegos, consulte el ejemplo UserManagement.

Permisos y privilegios

Mientras un juego está suspendido, los usuarios pueden cambiar la configuración de la cuenta que determina lo que pueden hacer en línea y cómo pueden comunicarse con otras personas. Cuando se reanuda un juego, este debe volver a comprobar todos los permisos o privilegios antes de habilitar o deshabilitar la funcionalidad relacionada, de modo que el comportamiento del juego refleje el estado actual de la configuración del usuario. XR-015: Managing Player Communication detalla los permisos para la comunicación por texto y voz. XR-045: XBOX Live and Account Privileges detalla los privilegios para permitir o impedir acciones relacionadas con los servicios de XBOX.

Redes

Dado que un juego suspendido no tiene ningún subproceso programado, cuando un juego se reanuda, debe esperar que las comunicaciones de red se hayan visto afectadas. Para obtener orientación sobre cómo controlar esta situación, consulte Introducción a las API de redes. Para obtener detalles específicos de los servicios de XBOX, consulte Introducción a las API de servicios de XBOX. Para obtener más información sobre las sesiones multijugador, consulte Temas avanzados de sesiones multijugador.

API asincrónicas

Algunas API asincrónicas que requieren comunicación con el System OS podrían fallar si estaban en curso cuando se suspendió el juego. Si esto ocurre, las API de Xasync deben fallar con E_ABORT. Esto no está relacionado con ningún XR. En su lugar, es algo que hay que tener en cuenta al llamar a las API asincrónicas. Asegúrese de que dispone de control de errores para gestionar esta posibilidad de forma correcta. Si una llamada falla de esta manera, normalmente la mejor forma de actuar es simplemente reintentarla cuando el juego se haya reanudado.

API del Gaming Runtime

Después de que el juego complete su controlador de AppStateChangedNotification para el evento de suspensión, el Gaming Runtime se suspenderá automáticamente. El runtime se reanudará inmediatamente antes de invocar el controlador del juego para el evento de reanudación. Si se llama a alguna API del Gaming Runtime en otros subprocesos mientras el runtime está suspendido, estas fallarán con E_GAMERUNTIME_SUSPENDED. Esto puede ocurrir, por ejemplo, si se llama a una API asincrónica poco antes de que finalice el controlador de suspensión. La devolución de llamada podría activarse después de que el runtime se haya suspendido, pero antes de que el juego deje de programar subprocesos. Siempre que sea posible, evite realizar llamadas al Gaming Runtime que puedan ejecutarse durante esta ventana mientras el Gaming Runtime está suspendido. Cuando esto no se pueda evitar, puede detectar el error y reintentar la llamada después de recibir la AppStateChangedNotification para el evento de reanudación.

Audio

Al suspenderse, los juegos no deben conservar ningún objeto obtenido de un IMMDeviceEnumerator, incluidos IMMDevice, IMMDeviceCollection o IMMEndpointDevice. Intentar usar estas interfaces después de una reanudación sin usar primero IMMDeviceEnumerator para actualizarlas da como resultado un comportamiento indefinido. Sin embargo, si el juego conserva IMMNotificationClient, ese cliente sigue funcionando con normalidad durante la suspensión y la reanudación. También es un procedimiento recomendado (aunque no es obligatorio) detener las secuencias de audio durante la suspensión y reiniciarlas al reanudarse. Durante la reanudación, las secuencias de audio del juego también quedarán invalidadas y requerirán reinicialización. Los juegos deben actuar para recuperarse de estas invalidaciones durante la ejecución de su controlador de reanudación o después de esta. Para obtener más información, consulte la comparación de las API de audio de XBOX One Software Development Kit y Microsoft Game Development Kit.

Intentar reinicializar las secuencias de audio antes de que el controlador de reanudación empiece a ejecutarse podría dar como resultado un comportamiento indefinido.

Tratamiento de los cambios de hora durante la suspensión

Mientras el juego está suspendido, pueden ocurrir muchas cosas. La única certeza es que el tiempo avanzará mientras el juego está suspendido. Los juegos deben tener esto en cuenta y asegurarse de que, al calcular métricas como el tiempo dedicado a jugar, no incluyan involuntariamente el tiempo transcurrido mientras el juego estaba suspendido. A partir del GDK de junio de 2021, cuando el juego se suspende, el contador de marca de tiempo (TSC) se congela y no avanzará hasta que el juego se reanude más tarde. Además, el TSC no incluirá el tiempo transcurrido durante la suspensión. Esto significa que los juegos pueden confiar en lo siguiente para notificar con precisión el tiempo transcurrido mientras el juego se está ejecutando:

__rdtscp
QueryPerformanceCounter

Aunque el TSC no avanzará durante la suspensión, la hora del reloj de pared sí avanzará. Esto significa que, si el juego llama a GetSystemTime o GetLocalTime, verá que el tiempo ha avanzado.

Respuesta a Restringir y Anular restricción

A diferencia de la notificación de suspensión, en la que se espera que el juego realice acciones específicas y la consola está esperando a que la rutina regrese, no se requiere nada en respuesta a la notificación de cambio de restricción de la aplicación. Cuando se recibe el evento, la transición al estado Restringido o al estado En ejecución ya se ha producido. En su lugar, este evento notifica al juego que sus recursos disponibles han cambiado y que debe reducir o aumentar su uso de recursos en consecuencia. A la hora de decidir cómo debe controlar un juego el estado restringido, tenga en cuenta el hecho de que un juego solo se restringirá si no tiene el foco de entrada. Por lo tanto, un usuario no puede interactuar con el juego mientras está restringido. Por ello, la mayoría de los juegos deberían pausar la partida (o lo que sea más parecido a una pausa) mientras están restringidos. Sin embargo, un juego puede seguir siendo visible mientras está restringido, por lo que es importante seguir representando algo para que el usuario pueda ver el estado del juego. También es probable que el usuario devuelva el juego al primer plano en breve, por lo que mantener las partidas multijugador y otras comunicaciones de red probablemente será una mejor experiencia para el usuario. En última instancia, el único objetivo al controlar Restringir es mantener el juego en ejecución mientras se ajusta al tiempo reducido de CPU y GPU. La mejor manera de lograrlo depende de las necesidades individuales de su juego.

Inicio

Los juegos de Microsoft Game Development Kit (GDK) tienen un diseño Win32, completo con un bucle de mensajes de Windows tradicional. Como tal, cuando se inician, el primer punto de entrada de código orientado al desarrollador son los parámetros que se pasan a WinMain. Como alternativa, el juego podría consultar los parámetros con los que se inició usando la función GetCommandLine. A diferencia de las ERA de XBOX One o las UWP, los juegos de Microsoft Game Development Kit (GDK) no están sujetos a un tiempo de espera de activación y no tienen un controlador de eventos Activated. Además, a diferencia de las ERA de XBOX One o las UWP, los juegos de Microsoft Game Development Kit (GDK) no controlan las invitaciones de juego mediante parámetros de activación o de inicio. En su lugar, los juegos de Microsoft Game Development Kit (GDK) que deban controlar invitaciones de juego deben registrarse para esos eventos mediante XGameInviteRegisterForEvent. Cuando el juego realiza su registro, obtiene entonces las invitaciones pendientes disponibles.

Eventos relacionados con el ciclo de vida

Estos eventos no son realmente eventos del ciclo de vida. Son eventos relacionados con las causas y las condiciones de las transiciones de estado. Pueden ser útiles para determinar cómo identificar estos eventos y responder a ellos en consecuencia.

Foco de entrada

Para saber cuándo el juego tiene el foco de entrada, los juegos de Microsoft Game Development Kit (GDK) pueden escuchar la notificación de ventana WM_ACTIVATEAPP en la devolución de llamada WindowProc. Esto es lo mismo que la implementación Win32 de Windows PC, y se aplica la misma documentación. Para obtener más información, consulte Mensaje WM_ACTIVATEAPP. El siguiente ejemplo de código demuestra cómo escuchar este evento.

// Windows procedure.
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_ACTIVATEAPP:
        OutputDebugString((wParam) ? L"Activated\n" : L"Deactivated\n");
        break;
    ...

Visibilidad

Para determinar si la ventana del juego es visible (de forma similar al foco de entrada), los juegos de Microsoft Game Development Kit (GDK) pueden escuchar la notificación de ventana WM_SHOWWINDOW en la devolución de llamada WindowProc. Para obtener más información, consulte Mensaje WM_SHOWWINDOW. El siguiente ejemplo de código demuestra cómo escuchar la notificación de ventana WM_SHOWWINDOW en la devolución de llamada WindowProc.

// Windows procedure.
LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_SHOWWINDOW:
        OutputDebugString((wParam) ? L"Visible\n" : L"Not Visible\n");
        break;
    ...

Trabajar con tiempos de espera del GDK

Los desarrolladores de XBOX One ERA y UWP trabajan con una variedad de tiempos de espera diferentes para la activación, la suspensión y la detección de bloqueos. Los juegos de Microsoft Game Development Kit (GDK) tienen un diseño Win32 y, en su mayor parte, no tienen nociones comparables, excepto cuando se ejecutan en consolas, donde poder cambiar los estados de recursos es necesario para garantizar la mayor disponibilidad de recursos para el juego en ejecución. La siguiente tabla compara los distintos comportamientos entre las diferentes plataformas.

Controlador/tiempo de espera	Microsoft Game Development Kit (GDK)	XBOX One ERA	UWP
Controlador de activación	No aplicable	`CoreApplicationView:: Activated`	`CoreApplicationView::Activated`
Tiempo de espera de activación	No aplicable	45 s	10 s
Controlador de suspensión	`RegisterAppStateChangeNotification`	`CoreApplication:: Suspending`	`CoreApplication:: Suspending`
Tiempo de espera de suspensión	1 s	1 s	5 s
Controlador de reanudación	`RegisterAppStateChangeNotification`	`CoreApplication:: Resuming`	`CoreApplication:: Resuming`
Tiempo de espera de reanudación	No aplicable	No aplicable	No aplicable
Controlador de restricción	`RegisterAppConstrainedChangeNotification`	`CoreApplication:: ResourceAvailabilityChanged`	No aplicable
Tiempo de espera de restricción	No aplicable	No aplicable	No aplicable
Tiempo de espera de bloqueo	No aplicable	2 s	2 s

Reanudación rápida

La reanudación rápida es una nueva característica de la recuperación de junio de 2020 en las consolas XBOX Series. Proporciona una manera de que los usuarios cambien entre juegos más rápido que antes, manteniendo los juegos suspendidos mientras se ejecuta otro juego. En todos los dispositivos de la familia XBOX One, y en las consolas XBOX Series antes de la recuperación de junio, cuando un juego se está ejecutando (o está restringido o suspendido) y el usuario selecciona un juego nuevo, el primer juego se termina y se inicia el juego nuevo. En las consolas XBOX Series con la recuperación de junio de 2020 y posteriores, el primer juego puede en cambio suspenderse y, después, todo el Game OS y su memoria pueden guardarse en el estado suspendido. Cuando el usuario vuelve a cambiar, se restaura el Game OS. Entonces el juego se puede reanudar. El Game OS guardado puede incluso restaurarse después de un reinicio de la consola. Desde la perspectiva del juego, esto es idéntico a una suspensión/reanudación normal. No se necesitan pasos ni código adicionales. Si un juego puede suspenderse y reanudarse correctamente, también admite plenamente la reanudación rápida. Debido a la reanudación rápida, es más fácil que un juego esté en ejecución durante cientos de horas dentro de una sesión de inicio. Los juegos pueden permanecer suspendidos durante días, semanas o incluso meses seguidos. Esto significa que es importante asegurarse de que la información de estado que se estableció antes de la suspensión (especialmente la información sobre los usuarios) no se asuma como cierta al reanudarse. Por ejemplo, si su juego aprovecha las relaciones sociales profundas, podrían haberse agregado nuevos amigos y haberse eliminado otros. Si usa información de presencia de los amigos, es poco probable que lo que estaban haciendo la semana pasada sea exactamente lo mismo que estén haciendo cuando el juego se reanude. Problemas similares se aplican a las preferencias de accesibilidad, los privilegios y las tablas de clasificación.

Asegúrese de volver a consultar el estado que puede cambiar fácilmente con el tiempo.

Herramientas y características de depuración

Esta sección describe algunas de las herramientas, los registros y las características que ayudan a depurar y probar el ciclo de vida de un juego.

Herramientas de transición del ciclo de vida

Para la depuración y las pruebas, es importante saber en qué estado se encuentra un juego y hacer que un juego realice transiciones entre estados. Hay algunas herramientas que puede usar para consultar el estado actual del ciclo de vida y realizar transiciones de estado. XBOX Manager, el XBOX Device Portal y la herramienta de línea de comandos xbapp muestran todos el estado actual de una aplicación. Todos ellos proporcionan comandos para realizar las distintas transiciones. Por ejemplo, la siguiente captura de pantalla muestra los menús State y Actions de XBOX Manager.

Captura de pantalla que muestra los menús State y Actions de XBOX Manager

Para proporcionar tiempos de iteración más rápidos y flexibilidad para las pruebas, si se usa el comando ‘terminate’ en un juego sin empaquetar, este pasará directamente al estado No en ejecución en lugar de suspenderse primero. Para terminar un juego de la forma en que se terminaría normalmente, simplemente suspéndalo primero con el comando suspend.

La transición de en ejecución a suspendido también se puede desencadenar usando uno de los botones del panel frontal de un kit de desarrollo. El script Suspend_Title que se incluye en Microsoft Game Development Kit (GDK) se puede asignar a un botón del panel frontal mediante XBOX Manager o XBOX Device Portal. Tenga en cuenta que la transición a un estado reanudado no se puede desencadenar desde un botón del panel frontal. La reanudación debe realizarse desde el shell de la consola seleccionando el icono del juego desde Inicio o Mis juegos y aplicaciones, o usando otra herramienta como xbApp, Visual Studio o XBOX Manager.

Registro de transiciones de estado en xbWatson y Visual Studio

Saber cuándo se producen las transiciones de estado es tan importante como conocer el estado actual del ciclo de vida. En xbWatson y en la ventana XBOX System Monitor de Visual Studio se muestra una cantidad significativa de compatibilidad de registro para las transiciones de estado del ciclo de vida. Ahora, cada vez que hay una transición de estado, se registra junto con información sobre otros eventos relacionados con la aplicación, como las fases del inicio de la aplicación y los cambios de foco en todo el sistema. La siguiente captura de pantalla muestra cuándo se producen las transiciones de estado usando xbWatson.

Captura de pantalla que muestra cuándo se producen las transiciones de estado usando xbWatson

La nueva característica de registro también incluye errores y fallos de los eventos del ciclo de vida. Comprobar este registro puede ayudarle a identificar cuándo algo va mal, o puede proporcionar más información sobre cualquier caso de error. Si se produce un error y se notifica un HRESULT, puede encontrar más información consultando la herramienta de línea de comandos xberror. En el caso de error que se muestra en la captura de pantalla anterior, xberror muestra que el título agotó el tiempo de espera durante su controlador de suspensión (E_GAME_SUSPEND_TITLE_TIMEOUT).

Interrupción en el tiempo de espera de suspensión

Una nueva característica del Microsoft Game Development Kit (GDK) de junio de 2020 es la capacidad de Visual Studio de interrumpir automáticamente si está depurando un juego de Microsoft Game Development Kit (GDK) y este no consigue suspenderse debido al tiempo de espera de un segundo. Esta configuración está desactivada de forma predeterminada. Sin embargo, puede cambiarla en las propiedades de depuración del proyecto, como se muestra en la siguiente captura de pantalla.

También puede cambiar esta configuración para un juego instalado usando la ventana XBOX Gaming Explorer, incluso si no tiene su proyecto abierto. Seleccione el juego en XBOX Gaming Explorer y, después, cambie la configuración Break on Suspend Timeout en la ventana de herramientas Properties. Para obtener más detalles, consulte XBOX Gaming Explorer. Esto puede ser excelente para depurar errores de suspensión, donde puede haber un bloqueo o cuando alguna parte del proceso de suspensión tarda más de lo esperado. El depurador lo hace insertando un nuevo subproceso en el proceso del juego con un INT3 para provocar una interrupción. Esto significa que el depurador se interrumpirá inicialmente en un subproceso aparentemente vacío, pero que los demás subprocesos se interrumpirán allí donde estén cuando se produzca el tiempo de espera de un segundo. Para obtener más información sobre la depuración de los estados del ciclo de vida del juego con Visual Studio, consulte Depuración de proyectos de XBOX con Visual Studio.

Volcados automáticos de errores de suspensión

Cada vez que se produce un error de suspensión, se registra un volcado de memoria de diagnóstico automático en la consola. El volcado también se carga en el portal para desarrolladores. Estos volcados se guardan en la consola en D:\LocalDumps\. Con la actualización de junio de 2020, xbWatson también muestra los volcados disponibles en la consola. También tiene una opción para descargar los volcados desde el menú. Estos se denominan volcados de memoria de quiesce porque quiesce es otro nombre para la suspensión. La siguiente captura de pantalla muestra los volcados de memoria de quiesce que están disponibles en la consola.

Captura de pantalla que muestra los volcados de memoria de quiesce que están disponibles en la consola

Los volcados de diagnóstico también se crean cuando se habría invocado la devolución de llamada de suspensión (PAPPSTATE_CHANGE_ROUTINE), pero no hay un controlador de suspensión registrado. Los volcados de diagnóstico también se crean si no se llamó a ID3D12CommandQueue::SuspendX antes de salir del controlador de suspensión.

Provocar transiciones de estado manualmente

Puede desencadenar manualmente cada una de las transiciones de estado interactuando con la consola. La siguiente tabla enumera formas de desencadenar cada una de las transiciones de estado sin ninguna herramienta (suponiendo que el juego esté en un estado inicial adecuado para la transición).

Transición	Acción
Iniciar	Seleccione el icono del juego desde Inicio o Mis juegos y aplicaciones.
Restringir	Presione el botón XBOX del mando para abrir la Guía.
Suspender	Apague la consola cuando el modo de energía esté establecido en Encendido instantáneo.
Terminar	Con el icono del juego seleccionado, presione el botón Menú del mando y, después, seleccione Salir.
Reanudar	Seleccione el icono del juego desde Inicio o Mis juegos y aplicaciones. Para evitar también la anulación de la restricción, abra la Guía durante la transición.
Anular restricción	Presione el botón XBOX del mando para cerrar la Guía.

Apéndice

Ver los XR

Para descargar la lista de XR

Vaya a XBOX Developer Downloads.
Como tipo de archivo, seleccione Partner, Publishing, and Release Management Information.
Seleccione Confirm.
Como número de compilación/versión, seleccione la versión de XGD Partner Documentation que coincida con la versión que esté usando.
Seleccione Confirm. Aparece el botón Download Now, que le pide que descargue la documentación.

Telemetría de diagnóstico para eventos del ciclo de vida

La plataforma de la consola envía telemetría para los eventos que se muestran en la siguiente tabla.

Evento	Descripción
Tiempo de inicio	El tiempo entre el momento en que se llamó a `CreateProcess` para iniciar el juego y el momento en que el juego realiza su primera llamada de presentación.
Tiempo de reanudación	El tiempo entre el momento en que se reanuda la partición del juego y el momento en que el juego realiza su siguiente presentación.

Diagramas de recursos de CPU para consolas XBOX Series con SMT habilitado

Para obtener más información sobre SMT, consulte la comparación de CPU y memoria de XBOX One frente a XBOX Series X|S.

En ejecución

El siguiente diagrama muestra la asignación entre los núcleos de la CPU y los núcleos virtuales para un juego En ejecución.

Restringido

El siguiente diagrama muestra la asignación entre los núcleos de la CPU y los núcleos virtuales para un juego Restringido.

Última modificación el 5 de octubre de 2026

⌘I

​Ciclo de vida del juego de XBOX

​Introducción

​Estados del ciclo de vida del juego

​En ejecución

​Restringido

​En suspensión

​Suspendido

​No en ejecución

​Transiciones de estado del ciclo de vida

​Transición de En ejecución a Restringido (Restringir)

​Transición de Restringido a En suspensión (Suspensión iniciada)

​Transición de En suspensión a Suspendido (Suspensión completada)

​Transición de Suspendido a No en ejecución (Terminar)

​Transición de No en ejecución a En ejecución (Iniciar)

​Transición de Suspendido a Restringido (Reanudar)

​Transición de Restringido a En ejecución (Anular restricción)

​Terminación por el sistema de almacenamiento conectado

​Devoluciones de llamada de eventos del ciclo de vida

​Respuesta a Suspender y Reanudar

​Tiempo de espera de suspensión

​Direct3D

​API de XGameSave

​Usuarios y emparejamiento de usuario y mando

​Permisos y privilegios

​Redes

​API asincrónicas

​API del Gaming Runtime

​Audio

​Tratamiento de los cambios de hora durante la suspensión

​Respuesta a Restringir y Anular restricción

​Inicio

​Eventos relacionados con el ciclo de vida

​Foco de entrada

​Visibilidad

​Trabajar con tiempos de espera del GDK

​Reanudación rápida

​Herramientas y características de depuración

​Herramientas de transición del ciclo de vida

​Registro de transiciones de estado en xbWatson y Visual Studio

​Interrupción en el tiempo de espera de suspensión

​Volcados automáticos de errores de suspensión

​Provocar transiciones de estado manualmente

​Apéndice

​Ver los XR

​Para descargar la lista de XR

​Telemetría de diagnóstico para eventos del ciclo de vida

​Diagramas de recursos de CPU para consolas XBOX Series con SMT habilitado

​En ejecución

​Restringido

Ciclo de vida del juego de XBOX

Introducción

Estados del ciclo de vida del juego

En ejecución

Restringido

En suspensión

Suspendido

No en ejecución

Transiciones de estado del ciclo de vida

Transición de En ejecución a Restringido (Restringir)

Transición de Restringido a En suspensión (Suspensión iniciada)

Transición de En suspensión a Suspendido (Suspensión completada)

Transición de Suspendido a No en ejecución (Terminar)

Transición de No en ejecución a En ejecución (Iniciar)

Transición de Suspendido a Restringido (Reanudar)

Transición de Restringido a En ejecución (Anular restricción)

Terminación por el sistema de almacenamiento conectado

Devoluciones de llamada de eventos del ciclo de vida

Respuesta a Suspender y Reanudar

Tiempo de espera de suspensión

Direct3D

API de XGameSave

Usuarios y emparejamiento de usuario y mando

Permisos y privilegios

Redes

API asincrónicas

API del Gaming Runtime

Audio

Tratamiento de los cambios de hora durante la suspensión

Respuesta a Restringir y Anular restricción

Inicio

Eventos relacionados con el ciclo de vida

Foco de entrada

Visibilidad

Trabajar con tiempos de espera del GDK

Reanudación rápida

Herramientas y características de depuración

Herramientas de transición del ciclo de vida

Registro de transiciones de estado en xbWatson y Visual Studio

Interrupción en el tiempo de espera de suspensión

Volcados automáticos de errores de suspensión

Provocar transiciones de estado manualmente

Apéndice

Ver los XR

Para descargar la lista de XR

Telemetría de diagnóstico para eventos del ciclo de vida

Diagramas de recursos de CPU para consolas XBOX Series con SMT habilitado

En ejecución

Restringido