Ciclo de vida de jogos do XBOX

Este tópico apresenta os conceitos e eventos que compõem o ciclo de vida do jogo. Ele demonstra como implementar o estado do jogo e os eventos de alteração de estado no seu jogo para oferecer uma experiência fluida aos usuários. Ele também mostra como cumprir os requisitos de certificação e apresenta as ferramentas e os recursos disponíveis para depurar esses eventos. Os jogos do Microsoft Game Development Kit (GDK) têm vários estados de recursos entre os quais fazem a transição ao longo de sua vida útil. A alternância entre esses estados permite que o console XBOX ofereça a experiência de multitarefa responsiva que os usuários esperam. Isso também garante que os jogos obtenham o máximo de recursos possível do console quando os usuários jogam. Para isso, no entanto, há alguns eventos e interações que os jogos do Microsoft Game Development Kit (GDK) devem estar preparados para tratar.
Introdução Estados do ciclo de vida do jogo Transições de estado do ciclo de vida Retornos de chamada de eventos do ciclo de vida Responder à suspensão e à retomada Responder à restrição e à remoção da restrição Inicialização Eventos relacionados ao ciclo de vida Trabalhar com tempos limite do GDK Quick Resume Ferramentas e recursos de depuração Apêndice

Introdução

Os estados e eventos do ciclo de vida do jogo permitem que os usuários alternem entre jogos, o shell do XBOX e outros aplicativos de forma rápida e eficiente. Esse processo exige alguma ação dos jogos e aplicativos para que eles possam tratar as transições entre os estados do ciclo de vida. Se bem tratado, esse trabalho proporciona uma experiência suave e contínua para os usuários quando eles alternam para o seu jogo e saem dele. Este tópico explica os vários aspectos do gerenciamento do ciclo de vida do seu jogo e descreve as ferramentas disponíveis para dar suporte a esses aspectos. Se você conhece o gerenciamento do tempo de vida do processo (PLM) de aplicativos do XBOX One Software Development Kit ou da Plataforma Universal do Windows (UWP), essas informações serão familiares. Observe que há algumas diferenças e melhorias importantes para aplicativos do GDK. Este tópico começa com:

Uma discussão sobre os diferentes estados do ciclo de vida.
As transições entre eles.
Os retornos de chamada associados a eles.

Em seguida, este tópico explica os requisitos para tratar essas transições com êxito a fim de cumprir os XBOX Requirements (XRs) e discute casos de uso comuns que a maioria dos jogos deve considerar. Por fim, este tópico apresenta as ferramentas e os recursos de depuração que facilitam a compreensão e a correção de problemas de transição de estado.

Estados do ciclo de vida do jogo

Um jogo do Microsoft Game Development Kit (GDK) instalado em um console XBOX está sempre em um dos cinco estados possíveis a seguir.

Em execução
Restrito
Suspendendo
Suspenso
Não está em execução

Você pode determinar o estado de um jogo verificando:

O State listado no modo de exibição Home do XBOX Manager.
O valor listado no Dev Home ao lado de um jogo no modo de exibição Games & apps.
O XBOX Device Portal.
A ferramenta de linha de comando xbapp query.

Em execução

Quando um jogo está em execução, ele é executado com disponibilidade total de recursos. O jogo tem o foco de entrada, e sua janela fica visível para o usuário. Disponibilidade total de recursos significa que o jogo está sendo executado com:

Seis núcleos físicos de CPU (core0-core5), mais 50–90% do núcleo de CPU core6 em dispositivos da família XBOX One, e 100% do núcleo de CPU core6 nos consoles XBOX Series.
97–100% de uso da GPU. Observe que o sistema operacional pode usar até 3% da GPU.
5–13 GB de memória, dependendo das configurações em MicrosoftGame.config e do console em que o jogo está sendo executado. Para obter mais informações, consulte Configurar a memória do título.

Para ilustrar melhor as alterações de recursos de CPU entre o estado Em execução e o estado Restrito, considere o diagrama a seguir, que mostra o estado dos núcleos de CPU quando um jogo está no estado Em execução.

Diagrama que mostra o estado dos núcleos de CPU quando o jogo está no estado Em execução

Os consoles XBOX Series podem habilitar o multithreading simultâneo (SMT), o que altera um pouco o diagrama. Para obter mais informações sobre SMT, consulte CPU e memória do XBOX One em comparação com o XBOX Series X|S e o apêndice para ver diagramas que detalham os núcleos de CPU usando SMT.

Restrito

Quando um jogo é executado no estado de execução Restrito, ele é executado com disponibilidade reduzida de recursos. O jogo não pode receber entrada do usuário nesse estado. É provável que a janela do jogo esteja parcialmente encoberta ou não esteja visível para o usuário. Um jogo é colocado nesse estado quando o usuário interage com algum recurso ou utiliza algo diferente do jogo ativo, como interagir com um menu como o Guia, um aplicativo do sistema como Configurações ou uma interface do usuário que pode ser chamada pelo título (TCUI), como o Seletor de Contas. Quando um jogo está Restrito, seus recursos disponíveis são reduzidos aos estados a seguir.

Quatro núcleos físicos de CPU. Os threads são agrupados de acordo com o seguinte padrão.
- Os threads em core0 e core1 não são afetados.
- Os threads em core2 e core3 são divididos em fatias de tempo em um único núcleo físico de CPU.
- Os threads em core4, core5 e core6 são divididos em fatias de tempo em um único núcleo físico de CPU.
Aproximadamente 45% da GPU.
A mesma memória disponível que no estado Em execução. Observe que estar Restrito não altera a quantidade de memória disponível para o jogo.

A ilustração a seguir mostra o estado dos núcleos de CPU quando um jogo está no estado Restrito.

Ilustração que mostra o estado dos núcleos de CPU quando um jogo está no estado Restrito

Suspendendo

Quando um jogo é executado no estado de execução Suspendendo, ele é executado com os mesmos recursos do estado Restrito, exceto pelo fato de indicar que o console iniciou o processo de transição do jogo para o estado Suspenso. Suspendendo é um estado transitório. Assim, dependendo da frequência com que você consulta o estado de execução, pode ser difícil observar o estado de execução Suspendendo.

Suspenso

Quando um jogo está no estado de execução Suspenso, ele ainda reside na memória, mas não está mais em execução. Seus threads não são agendados e, consequentemente, ele não está usando nenhum tempo da CPU ou da GPU. Se um jogo é suspenso, todo o Game OS no qual o jogo é executado também é suspenso, e o estado do sistema operacional e da memória permanece intocado até que ocorra outra transição de estado.

Não está em execução

Esse é o estado de um jogo que não está em execução, não está carregado na memória e não está usando nenhum dos recursos do console. Observe que algumas ferramentas (como xbapp query) podem relatar esse estado de execução como o estado de execução do pacote 0 (desconhecido).

Transições de estado do ciclo de vida

Esta seção explica cada uma das transições de estado do ciclo de vida e fornece exemplos de causas para cada uma. Algumas interações do usuário com o console podem fazer com que muitos desses eventos ocorram em sequência, às vezes muito rapidamente, mas o jogo ainda passa por todas essas transições. O diagrama a seguir mostra as transições entre os estados do ciclo de vida. Para simplificar, o diagrama mostra apenas as transições sem erro. Observe que um jogo ainda pode fazer a transição de qualquer estado para o estado Não está em execução como resultado de uma falha.

Transição de Em execução para Restrito (Restringir)

Essa transição representa a redução dos recursos disponíveis para o jogo. O jogo pode se registrar para receber um retorno de chamada quando isso ocorrer chamando RegisterAppConstrainChangeNotification. Essa transição ocorre quando:

Um usuário abre o Guia.
A TCUI é apresentada (como o Seletor de Contas).
Um usuário retorna à página inicial.
O jogo perde o foco.

Transição de Restrito para Suspendendo (Suspensão iniciada)

Quando um jogo está em processo de suspensão, ele primeiro faz a transição para o estado Suspendendo. Todos os retornos de chamada registrados com RegisterAppStateChangeNotification são disparados. O jogo permanece no estado Suspendendo até retornar de todos os manipuladores de retorno de chamada ou até que ocorra um tempo limite de um segundo. Se os manipuladores retornarem antes do tempo limite, o jogo concluirá sua suspensão. Caso contrário, o jogo será encerrado. Um jogo começa a ser suspenso quando:

O console é colocado em Espera Conectada.
O jogo não fica visível por 10 minutos.
Ocorre a primeira etapa do encerramento de um jogo, como quando um novo jogo é iniciado.

Às vezes, essa transição é chamada de quiesce.

Transição de Suspendendo para Suspenso (Suspensão concluída)

Essa transição ocorre automaticamente quando um jogo que está no estado Suspendendo retorna de seus manipuladores de retorno de chamada registrados com RegisterAppStateChangeNotification. Os threads de um jogo param de ser executados assim que ele entra nesse estado.

Transição de Suspenso para Não está em execução (Encerrar)

Essa transição representa a remoção do jogo da memória. Um jogo não tem nenhum controle sobre essa transição nem interação com ela, pois um jogo suspenso não está em execução. Um encerramento ocorre:

Quando o usuário opta por sair do jogo na página inicial.
Quando o console é desligado (sem fazer a transição para a Espera Conectada).
Na etapa final do desligamento de um jogo, como quando um novo jogo é iniciado.
Quando os dados salvos do jogo estão fora de sincronia com a nuvem. Consulte Encerramento pelo sistema Connected Storage para obter detalhes.

Transição de Não está em execução para Em execução (Iniciar)

Essa transição de estado representa o carregamento do jogo e sua execução dentro do Game OS e geralmente coincide com a inicialização do próprio Game OS. Isso ocorre sempre que um usuário:

Seleciona o bloco de um jogo.
Aceita um convite para um jogo.
Interage com referências ao jogo em todo o shell e o sistema do XBOX.

Transição de Suspenso para Restrito (Retomar)

Essa transição de estado geralmente é seguida por um evento de Remoção da restrição. Ela representa o reinício da execução dos threads do jogo, e a transição começa com retornos de chamada para todos os manipuladores de RegisterAppStateChangeNotification. Um jogo é retomado quando estava anteriormente no estado Suspenso e é trazido para o primeiro plano (geralmente pelas mesmas interações que iniciariam o jogo se ele estivesse no estado Não está em execução).

Transição de Restrito para Em execução (Remover restrição)

Essa transição de estado é o inverso da transição Restringir. Ela representa a promoção dos recursos disponíveis para o jogo de volta à quantidade total do estado Em execução. Essa transição também tem um retorno de chamada associado para todos os manipuladores de RegisterAppConstrainChangeNotification e ocorre sempre que o jogo se torna o aplicativo em primeiro plano. Quando um jogo é encerrado devido a interações típicas com o console, como iniciar outro jogo ou desligar o console, ele ainda faz a transição para o estado Suspenso antes do encerramento. Isso garante que o jogo em execução no momento possa salvar o estado antes de ser desligado. No entanto, se um jogo falhar ou não conseguir ser suspenso, ele fará a transição diretamente para o estado Não está em execução.

Encerramento pelo sistema Connected Storage

Se os dados salvos locais do jogo estiverem fora de sincronia com a nuvem, o sistema Connected Storage encerrará o jogo na próxima vez que ele for suspenso. Isso permite sincronizar os dados salvos mais recentes quando o jogo for iniciado novamente. O encerramento por esse motivo não é uma falha e não causará uma reprovação no XR-001. Esse caso não é comum, mas pode ocorrer se você iniciar um jogo enquanto o console não está conectado à rede XBOX (também conhecida como XBOX Live) e depois se reconectar enquanto ele estiver em execução. Isso também pode ocorrer durante o desenvolvimento se o Connected Storage não estiver configurado corretamente para o título. Você pode reconhecer esse caso procurando linhas como as seguintes no xbWatson ou na janela XBOX System Monitor no 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 o jogo foi suspenso com êxito e não falhou nem atingiu o tempo limite. TerminateApplicationAfterSuspend indica que o encerramento foi iniciado pelo sistema após uma suspensão bem-sucedida. O valor -2138890207 é um HRESULT, CS_E_TERMINATEDTITLE_NOLOCK, que mostra o motivo do encerramento.

Retornos de chamada de eventos do ciclo de vida

Esta seção explica como os jogos fazem a transição entre estados. Ela também explica como os jogos determinam quando essas transições ocorrem e como eles respondem a essas transições. Para jogos do Microsoft Game Development Kit (GDK), há dois eventos nos quais você pode se registrar para receber informações sobre alterações de estado. Isso é mostrado no exemplo de código a seguir.

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 obter mais informações, consulte RegisterAppStateChangeNotification.

A notificação de alteração de restrição é específica dos consoles XBOX e atualmente não tem uma página de referência de API. A API é muito semelhante, com apenas a pequena alteração de “State” para “Constrained” no nome e nos parâmetros.

O PVOID Context pode ser qualquer coisa e é passado para a função Routine quando ela é chamada. Você pode manter Registration para cancelar o registro desses eventos com UnregisterAppStateChangeNotification e UnregisterAppConstrainedChangeNotification. Routine, passada para as funções de registro, é chamada em um thread do pool de threads padrão dentro do título quando o evento associado ocorre. Todas as rotinas registradas com essa função são chamadas de forma assíncrona em threads separados do pool de threads. Isso pode acontecer em qualquer ponto durante um quadro. Para RegisterAppStateChangeNotification, Routine é chamada com um valor booliano true assim que o console define o jogo para o estado Suspendendo e inicia o tempo limite de suspensão. Routine é chamada com um valor booliano false ao retomar o jogo do estado Suspenso para o estado Em execução. Para RegisterAppConstrainedChangeNotification, Routine é chamada com um valor booliano true quando o console define o jogo para o estado Restrito. Routine é chamada com um valor booliano false ao remover a restrição do jogo, passando do estado Restrito para o estado Em execução. Para ver um exemplo que demonstra como configurar e tratar esses eventos e garantir que eles sejam tratados no thread principal em um ponto consistente do quadro de um jogo, consulte o código de exemplo no Guia de portabilidade do Microsoft Game Development Kit para XBOX One. Você também pode examinar o main.cpp do exemplo SimplePLM ou do modelo de projeto Direct3D 12 XBOX Game do Microsoft Game Development Kit (GDK) no Visual Studio. Você pode baixar exemplos em XBOX Developer Downloads. Ao examinar minidespejos de travamento de quiesce, é possível que você se depare com a situação bastante confusa de não ver seus retornos de chamada registrados nas pilhas de nenhum dos threads. Isso ocorre devido à otimização de chamada final (tail call optimization). Para contornar isso, basta envolver seu retorno de chamada com:

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

Jogos do Microsoft Game Development Kit (GDK) executados em um PC com Windows não serão suspensos. No PC com Windows, esses jogos ainda podem chamar RegisterAppStateChangeNotification, mas esteja ciente de que o retorno de chamada PAPPSTATE_CHANGE_ROUTINE não será disparado.

Responder à suspensão e à retomada

Há algumas coisas que um jogo deve fazer para ser suspenso de modo a oferecer uma experiência contínua para os usuários que alternam para o jogo e saem dele e garantir que o jogo cumpra os XRs.

Tempo limite de suspensão

Para concluir uma suspensão (o que é necessário para cumprir o XR-001), um jogo deve ter pelo menos uma rotina de retorno de chamada registrada com RegisterAppStateChangeNotification. Quando o retorno de chamada é disparado, todas as rotinas registradas são chamadas de forma assíncrona em threads separados do pool de threads padrão. O jogo tem um segundo para retornar de todas as rotinas registradas, o que sinaliza ao sistema que o jogo pode passar para o estado Suspenso. Se o jogo não retornar das rotinas de suspensão em um segundo, ou se nenhum retorno de chamada estiver registrado, o jogo será encerrado e passará para o estado Não está em execução (o que é uma reprovação no XR-001). Esse processo garante que o console possa alternar entre jogos rapidamente e, ao mesmo tempo, que o jogo esteja preparado para a suspensão antes de entrar no estado suspenso.

Direct3D

Em resposta à chamada da rotina de suspensão, e antes de retornar dela, o jogo deve chamar SuspendX em sua ID3D12CommandQueue a partir de seu thread de renderização. Isso garante que o estado da GPU seja salvo em preparação para a suspensão. Ao retomar, o jogo deve chamar ResumeX para restaurar o estado. Chamar qualquer API do Direct3D entre as chamadas de SuspendX e ResumeX resulta no lançamento de uma exceção, resultando em uma falha. Não chamar SuspendX antes de retornar das rotinas de suspensão faz com que a suspensão falhe e o título seja encerrado (novamente, uma reprovação no XR-001). Para obter mais informações, consulte Suporte do Direct3D à suspensão e retomada.

APIs XGameSave

Quando um jogo recebe a notificação de suspensão, ele tem um segundo de tempo de execução antes de precisar ser suspenso. Quando um jogo está no estado Suspenso, ele pode passar para o estado Não está em execução sem nenhum tempo de execução adicional. Isso significa que, durante esse um segundo de tempo de suspensão, o jogo deve salvar todos os dados do usuário não salvos antes de entrar no estado Suspenso. As APIs XGameSave foram projetadas para dar suporte ao salvamento nesse período limitado. A API XGameSave usa a RAM fora da reserva do título como primeiro ponto de armazenamento para maximizar a velocidade de gravação do título durante a curta janela de tempo de suspensão. O XR-052: Estado do usuário determina que os títulos não devem causar perda não intencional de dados do usuário, o que inclui o progresso e o estado do usuário, conforme apropriado. Em geral, os jogos devem garantir que parte do tratamento da suspensão inclua salvar os dados do usuário. Também é uma boa ideia salvar com mais frequência do que apenas durante a suspensão. Isso garante que o jogo não precise preparar um salvamento grande durante o tempo limite, ou que coisas como uma queda de energia não resultem em uma perda significativa de dados do usuário. Para obter mais informações, consulte Visão geral dos salvamentos de jogos e o exemplo GameSave. Observe que é preferível usar as versões assíncronas das APIs XGameSave. Isso permitirá que um título continue o restante de seu código de suspensão enquanto o sistema grava os dados salvos do jogo. Para ver um exemplo de como isso é feito, consulte XGameSaveSubmitUpdateAsync. Antes de retomar o jogo, o sistema operacional verificará se o jogo salvo foi modificado em outro dispositivo enquanto o jogo estava suspenso. Se o dispositivo estiver online e essa verificação indicar que os salvamentos foram modificados, o jogo será encerrado e reiniciado para que fique em um estado consistente. Se o dispositivo estiver offline quando a verificação for feita, o jogo ainda poderá ser iniciado. Ao retomar, os jogos devem sempre tentar readquirir seu provedor de jogos salvos chamando XGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync. Reinicializar o provedor garante que os dados salvos mais recentes estejam disponíveis.

Usuários e emparelhamento de usuário e controle

O XR-112: Estabelecer um usuário e um controle durante a ativação inicial e a retomada determina que, quando um título é retomado, ele deve validar o emparelhamento de usuário/controle e reagir de acordo, retomando a sessão do usuário anterior ou adquirindo um novo usuário (ou usuários). O comportamento exato pode depender de como o jogo trata seus usuários e controles. É importante não confiar em nenhuma informação sobre o estado dos usuários ou controles anterior à suspensão e restabelecer o estado dos usuários e controles ao retomar. Você deve manter o XUserHandle durante um ciclo de suspensão/retomada, pois é assim que o jogo recebe atualizações sobre o estado do usuário. Além disso, os retornos de chamada registrados com XUserRegisterForChangeEvent e XUserRegisterForDeviceAssociationChanged são disparados durante uma retomada para atualizar o jogo com as alterações de estado que ocorreram. Para obter mais informações sobre o gerenciamento de usuários e dispositivos, consulte Identidade do usuário e XUser e Usuários e dispositivos de entrada. Para ver um exemplo de como os jogos podem tratar isso, consulte o exemplo UserManagement.

Permissões e privilégios

Enquanto um jogo está suspenso, os usuários podem alterar as configurações da conta que determinam o que eles têm permissão para fazer online e como podem se comunicar com outras pessoas. Quando um jogo é retomado, ele deve verificar novamente todas as permissões ou privilégios antes de habilitar ou desabilitar a funcionalidade relacionada, para que o comportamento do jogo reflita o estado atual das configurações do usuário. O XR-015: Gerenciar a comunicação entre jogadores detalha as permissões para comunicação por texto e voz. O XR-045: XBOX Live e privilégios da conta detalha os privilégios para permitir ou impedir ações relacionadas aos XBOX services.

Rede

Como um jogo Suspenso não tem nenhum thread agendado, quando um jogo é retomado, ele deve esperar que as comunicações de rede tenham sido afetadas. Para obter orientações sobre como tratar essa situação, consulte Introdução às APIs de rede. Para obter detalhes específicos dos XBOX services, consulte Introdução às APIs dos XBOX services. Para obter mais informações sobre sessões multijogador, consulte Tópicos avançados de sessões multijogador.

APIs assíncronas

Algumas APIs assíncronas que exigem comunicação com o System OS podem falhar se estavam em andamento quando o jogo foi suspenso. Se isso ocorrer, as APIs Xasync devem falhar com E_ABORT. Isso não está relacionado a nenhum XR. Em vez disso, é algo a ser considerado ao chamar APIs assíncronas. Verifique se você tem tratamento de erros implementado para lidar com essa possibilidade de forma adequada. Se uma chamada falhar dessa forma, geralmente a melhor ação é simplesmente tentar novamente quando o jogo for retomado.

APIs do Gaming Runtime

Depois que o jogo conclui seu manipulador AppStateChangedNotification para o evento de suspensão, o Gaming Runtime é suspenso automaticamente. O runtime é retomado imediatamente antes de invocar o manipulador do jogo para o evento de retomada. Se alguma API do Gaming Runtime for chamada em outros threads enquanto o runtime estiver suspenso, ela falhará com E_GAMERUNTIME_SUSPENDED. Isso pode ocorrer, por exemplo, se uma API assíncrona for chamada pouco antes de o manipulador de suspensão terminar. O retorno de chamada pode ser disparado depois que o runtime foi suspenso, mas antes que o jogo pare de agendar threads. Sempre que possível, evite fazer chamadas ao Gaming Runtime que possam ser executadas durante essa janela em que o Gaming Runtime está suspenso. Quando isso não puder ser evitado, você poderá detectar o erro e tentar a chamada novamente após receber a AppStateChangedNotification para o evento de retomada.

Áudio

Ao suspender, os jogos não devem manter nenhum objeto obtido de um IMMDeviceEnumerator, incluindo IMMDevice, IMMDeviceCollection ou IMMEndpointDevice. Tentar usar essas interfaces após uma retomada sem primeiro usar IMMDeviceEnumerator para atualizá-las resulta em comportamento indefinido. No entanto, se o jogo mantiver IMMNotificationClient, esse cliente continuará funcionando normalmente durante a suspensão e a retomada. Também é uma prática recomendada (embora não obrigatória) interromper todos os fluxos de áudio durante a suspensão e reiniciá-los na retomada. Durante a retomada, os fluxos de áudio do jogo também serão invalidados e exigirão reinicialização. Os jogos devem agir para se recuperar dessas invalidações durante ou após a execução do manipulador de retomada. Para obter mais informações, consulte Comparação entre as APIs de áudio do XBOX One Software Development Kit e do Microsoft Game Development Kit.

Tentar reinicializar os fluxos de áudio antes que o manipulador de retomada comece a ser executado pode resultar em comportamento indefinido.

Lidar com alterações de horário durante a suspensão

Enquanto o jogo está suspenso, muitas coisas podem acontecer. A única certeza é que o tempo continuará passando enquanto o jogo estiver suspenso. Os jogos precisam levar isso em conta e garantir que, ao calcular métricas como o tempo gasto jogando, não incluam involuntariamente o tempo em que o jogo esteve suspenso. A partir do GDK de junho de 2021, quando o jogo é suspenso, o contador de carimbo de data/hora (TSC) é congelado e não avança até que o jogo seja retomado posteriormente. Além disso, o TSC não incluirá o tempo passado durante a suspensão. Isso significa que os jogos podem confiar no seguinte para relatar com precisão o tempo gasto enquanto o jogo está em execução:

__rdtscp
QueryPerformanceCounter

Embora o TSC não avance durante a suspensão, o horário do relógio de parede avança. Isso significa que, se o jogo chamar GetSystemTime ou GetLocalTime, verá que o tempo avançou.

Responder à restrição e à remoção da restrição

Ao contrário da notificação de suspensão, em que se espera que o jogo execute ações específicas e o console aguarda o retorno da rotina, nada é necessário em resposta à notificação de alteração de restrição do aplicativo. Quando o evento é recebido, a transição para o estado Restrito ou para o estado Em execução já ocorreu. Em vez disso, esse evento notifica o jogo de que seus recursos disponíveis foram alterados e de que ele deve reduzir ou aumentar seu uso de recursos de acordo. Ao decidir como um jogo deve tratar a restrição, considere o fato de que um jogo só será restringido se não tiver o foco de entrada. Portanto, um usuário não pode interagir com o jogo enquanto ele está restrito. Por isso, a maioria dos jogos deve pausar a jogabilidade (ou o que for mais próximo de uma pausa) enquanto estiver restrita. No entanto, um jogo ainda pode estar visível enquanto restrito, portanto é importante continuar renderizando algo para que o usuário possa ver o estado do jogo. Também é provável que o usuário traga o jogo de volta ao primeiro plano em breve, portanto manter as partidas multijogador e outras comunicações de rede provavelmente proporcionará uma experiência melhor ao usuário. Em última análise, o único objetivo ao tratar a Restrição é manter o jogo em execução enquanto se ajusta ao tempo reduzido de CPU e GPU. A melhor maneira de conseguir isso depende das necessidades individuais do seu jogo.

Inicialização

Os jogos do Microsoft Game Development Kit (GDK) são Win32 por design, com um loop de mensagens tradicional do Windows. Assim, quando são iniciados, o primeiro ponto de entrada de código voltado ao desenvolvedor são os parâmetros passados para WinMain. Como alternativa, o jogo pode consultar os parâmetros com os quais foi iniciado usando a função GetCommandLine. Ao contrário das ERAs do XBOX One ou dos UWPs, os jogos do Microsoft Game Development Kit (GDK) não estão sujeitos a um tempo limite de ativação e não têm um manipulador de eventos Activated. Além disso, ao contrário das ERAs do XBOX One ou dos UWPs, os jogos do Microsoft Game Development Kit (GDK) não tratam convites para jogos usando parâmetros de ativação ou de inicialização. Em vez disso, os jogos do Microsoft Game Development Kit (GDK) que precisam tratar convites para jogos devem se registrar nesses eventos usando XGameInviteRegisterForEvent. Quando o jogo realiza seu registro, ele recebe todos os convites pendentes disponíveis.

Eventos relacionados ao ciclo de vida

Esses eventos não são, na verdade, eventos do ciclo de vida. São eventos relacionados às causas e condições das transições de estado. Eles podem ser úteis para determinar como identificar esses eventos e responder a eles de acordo.

Foco de entrada

Para saber quando o jogo tem o foco de entrada, os jogos do Microsoft Game Development Kit (GDK) podem escutar a notificação de janela WM_ACTIVATEAPP no retorno de chamada WindowProc. Isso é o mesmo que a implementação Win32 para PC com Windows, e a mesma documentação se aplica. Para obter mais informações, consulte Mensagem WM_ACTIVATEAPP. O exemplo de código a seguir demonstra como escutar esse 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;
    ...

Visibilidade

Para determinar se a janela do jogo está visível (de forma semelhante ao foco de entrada), os jogos do Microsoft Game Development Kit (GDK) podem escutar a notificação de janela WM_SHOWWINDOW no retorno de chamada WindowProc. Para obter mais informações, consulte Mensagem WM_SHOWWINDOW. O exemplo de código a seguir demonstra como escutar a notificação de janela WM_SHOWWINDOW no retorno de chamada 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;
    ...

Trabalhar com tempos limite do GDK

Os desenvolvedores de ERA do XBOX One e de UWP trabalham com diversos tempos limite diferentes para ativação, suspensão e detecção de travamentos. Os jogos do Microsoft Game Development Kit (GDK) são Win32 por design e, na maior parte, não têm noções comparáveis, exceto quando executados em consoles, onde a capacidade de alterar os estados de recursos é necessária para garantir a maior disponibilidade de recursos para o jogo em execução. A tabela a seguir compara os vários comportamentos entre as diferentes plataformas.

Manipulador/tempo limite	Microsoft Game Development Kit (GDK)	ERA do XBOX One	UWP
Manipulador de ativação	Não aplicável	`CoreApplicationView:: Activated`	`CoreApplicationView::Activated`
Tempo limite de ativação	Não aplicável	45 s	10 s
Manipulador de suspensão	`RegisterAppStateChangeNotification`	`CoreApplication:: Suspending`	`CoreApplication:: Suspending`
Tempo limite de suspensão	1 s	1 s	5 s
Manipulador de retomada	`RegisterAppStateChangeNotification`	`CoreApplication:: Resuming`	`CoreApplication:: Resuming`
Tempo limite de retomada	Não aplicável	Não aplicável	Não aplicável
Manipulador de restrição	`RegisterAppConstrainedChangeNotification`	`CoreApplication:: ResourceAvailabilityChanged`	Não aplicável
Tempo limite de restrição	Não aplicável	Não aplicável	Não aplicável
Tempo limite de travamento	Não aplicável	2 s	2 s

Quick Resume

O Quick Resume é um novo recurso da recuperação de junho de 2020 nos consoles XBOX Series. Ele oferece aos usuários uma maneira de alternar entre jogos mais rapidamente do que antes, mantendo os jogos suspensos enquanto outro jogo está em execução. Em todos os dispositivos da família XBOX One, e nos consoles XBOX Series antes da recuperação de junho, quando um jogo está em execução (ou restrito ou suspenso) e o usuário seleciona um novo jogo, o primeiro jogo é encerrado e o novo jogo é iniciado. Nos consoles XBOX Series com a recuperação de junho de 2020 e posteriores, o primeiro jogo pode, em vez disso, ser suspenso, e então todo o Game OS e sua memória podem ser salvos no estado suspenso. Quando o usuário volta, o Game OS é restaurado. O jogo pode então ser retomado. O Game OS salvo pode ser restaurado até mesmo após uma reinicialização do console. Da perspectiva do jogo, isso é idêntico a uma suspensão/retomada normal. Nenhuma etapa ou código adicional é necessário. Se um jogo pode ser suspenso e retomado com êxito, ele também dá suporte total ao Quick Resume. Por causa do Quick Resume, é mais fácil um jogo ficar em execução por centenas de horas em uma única sessão de inicialização. Os jogos podem permanecer suspensos por dias, semanas ou até meses. Isso significa que é importante garantir que as informações de estado estabelecidas antes da suspensão (especialmente informações sobre os usuários) não sejam consideradas verdadeiras ao retomar. Por exemplo, se o seu jogo aproveita relacionamentos sociais profundos, novos amigos podem ter sido adicionados e outros amigos removidos. Se você usa informações de presença dos amigos, é improvável que o que eles estavam fazendo na semana passada seja exatamente o que estão fazendo quando o jogo é retomado. Problemas semelhantes se aplicam a preferências de acessibilidade, privilégios e placares de líderes.

Certifique-se de consultar novamente os estados que podem mudar facilmente com o tempo.

Ferramentas e recursos de depuração

Esta seção descreve algumas das ferramentas, logs e recursos que ajudam na depuração e no teste do ciclo de vida de um jogo.

Ferramentas de transição do ciclo de vida

Para depuração e teste, é importante saber em que estado um jogo está e fazer um jogo passar de um estado para outro. Há algumas ferramentas que você pode usar para consultar o estado atual do ciclo de vida e realizar transições de estado. O XBOX Manager, o XBOX Device Portal e a ferramenta de linha de comando xbapp listam o estado atual de um aplicativo. Todos eles fornecem comandos para realizar as várias transições. Por exemplo, a captura de tela a seguir mostra os menus State e Actions do XBOX Manager.

Captura de tela que mostra os menus State e Actions do XBOX Manager

Para proporcionar tempos de iteração mais rápidos e dar suporte à flexibilidade nos testes, se o comando ‘terminate’ for usado em um jogo não empacotado, ele fará a transição diretamente para o estado Não está em execução em vez de ser suspenso primeiro. Para encerrar um jogo da maneira como ele normalmente seria encerrado, basta suspendê-lo primeiro com o comando suspend.

A transição de em execução para suspenso também pode ser acionada usando um dos botões do painel frontal de um devkit. O script Suspend_Title fornecido com o Microsoft Game Development Kit (GDK) pode ser mapeado para um botão do painel frontal usando o XBOX Manager ou o XBOX Device Portal. Observe que a transição para um estado retomado não pode ser acionada por um botão do painel frontal. A retomada deve ser feita no shell do console, selecionando o bloco do jogo em Página Inicial ou em Meus jogos e aplicativos, ou usando outra ferramenta, como o xbApp, o Visual Studio ou o XBOX Manager.

Registro em log de transições de estado no xbWatson e no Visual Studio

Saber quando as transições de estado ocorrem é tão importante quanto saber o estado atual do ciclo de vida. Uma quantidade significativa de suporte de registro em log para transições de estado do ciclo de vida é exibida no xbWatson e na janela XBOX System Monitor no Visual Studio. Agora, sempre que há uma transição de estado, ela é registrada junto com informações sobre outros eventos relacionados ao aplicativo, como as etapas da inicialização do aplicativo e as alterações de foco em todo o sistema. A captura de tela a seguir mostra quando as transições de estado ocorrem usando o xbWatson.

Captura de tela que mostra quando as transições de estado ocorrem usando o xbWatson

O novo recurso de registro em log também inclui erros e falhas de eventos do ciclo de vida. Verificar esse log pode ajudar você a identificar quando algo dá errado ou pode fornecer mais informações sobre qualquer caso de erro. Se ocorrer um erro e um HRESULT for relatado, você poderá encontrar mais informações usando a ferramenta de linha de comando xberror. No caso de erro mostrado na captura de tela anterior, xberror mostra que o título atingiu o tempo limite durante seu manipulador de suspensão (E_GAME_SUSPEND_TITLE_TIMEOUT).

Interromper no tempo limite de suspensão

Um novo recurso do Microsoft Game Development Kit (GDK) de junho de 2020 é a capacidade do Visual Studio de interromper automaticamente a execução se estiver depurando um jogo do Microsoft Game Development Kit (GDK) e ele não conseguir ser suspenso devido ao tempo limite de um segundo. Essa configuração fica desativada por padrão. No entanto, você pode alterá-la nas propriedades de depuração do projeto, conforme mostrado na captura de tela a seguir.

Captura de tela que mostra a interrupção no tempo limite de suspensão

Você também pode alterar essa configuração para um jogo instalado usando a janela XBOX Gaming Explorer, mesmo que não esteja com o projeto aberto. Selecione o jogo no XBOX Gaming Explorer e altere a configuração Break on Suspend Timeout na janela de ferramentas Properties. Para obter mais detalhes, consulte XBOX Gaming Explorer. Isso pode ser ótimo para depurar falhas de suspensão, em que pode haver um travamento ou quando alguma parte do processo de suspensão demora mais do que o esperado. O depurador faz isso inserindo um novo thread no processo do jogo com um INT3 para causar uma interrupção. Isso significa que o depurador inicialmente interromperá em um thread aparentemente vazio, mas os outros threads serão interrompidos onde estiverem quando ocorrer o tempo limite de um segundo. Para obter mais informações sobre como depurar os estados do ciclo de vida do jogo com o Visual Studio, consulte Depurar projetos do XBOX usando o Visual Studio.

Despejos automáticos de falhas de suspensão

Sempre que há uma falha de suspensão, um despejo de memória de diagnóstico automático é gravado no console. O despejo também é carregado no portal do desenvolvedor. Esses despejos são salvos no console em D:\LocalDumps\. Com a atualização de junho de 2020, o xbWatson também lista os despejos disponíveis no console. Ele também tem uma opção no menu para baixar os despejos. Eles são chamados de despejos de memória de quiesce, pois quiesce é outro nome para suspensão. A captura de tela a seguir mostra os despejos de memória de quiesce disponíveis no console.

Captura de tela que mostra os despejos de memória de quiesce disponíveis no console

Despejos de diagnóstico também são criados quando o retorno de chamada de suspensão (PAPPSTATE_CHANGE_ROUTINE) teria sido invocado, mas não há um manipulador de suspensão registrado. Despejos de diagnóstico também são criados se ID3D12CommandQueue::SuspendX não foi chamado antes de sair do manipulador de suspensão.

Causar transições de estado manualmente

Você pode acionar manualmente cada uma das transições de estado interagindo com o console. A tabela a seguir lista maneiras de acionar cada uma das transições de estado sem nenhuma ferramenta (supondo que o jogo esteja em um estado inicial adequado para a transição).

Transição	Ação
Iniciar	Selecione o bloco do jogo em Página Inicial ou em Meus jogos e aplicativos.
Restringir	Pressione o botão XBOX no controle para abrir o Guia.
Suspender	Desligue o console quando o modo de energia estiver definido como Ligar Instantaneamente.
Encerrar	Com o bloco do jogo selecionado, pressione o botão Menu no controle e selecione Sair.
Retomar	Selecione o bloco do jogo em Página Inicial ou em Meus jogos e aplicativos. Para evitar também a remoção da restrição, abra o Guia durante a transição.
Remover restrição	Pressione o botão XBOX no controle para fechar o Guia.

Apêndice

Visualizar os XRs

Para baixar a lista de XRs

Acesse XBOX Developer Downloads.
Em tipo de arquivo, selecione Partner, Publishing, and Release Management Information.
Selecione Confirm.
Em número de build/versão, selecione a versão da XGD Partner Documentation que corresponde à versão que você está usando.
Selecione Confirm. O botão Download Now é exibido, solicitando que você baixe a documentação.

Telemetria de diagnóstico para eventos do ciclo de vida

A plataforma do console envia telemetria para os eventos mostrados na tabela a seguir.

Evento	Descrição
Tempo de inicialização	O tempo entre a chamada de `CreateProcess` para iniciar o jogo e a primeira chamada do jogo para apresentar.
Tempo de retomada	O tempo entre a retomada da partição do jogo e a próxima apresentação do jogo.

Diagramas de recursos de CPU para consoles XBOX Series com SMT habilitado

Para obter mais informações sobre SMT, consulte CPU e memória do XBOX One em comparação com o XBOX Series X|S.

Em execução

O diagrama a seguir mostra o mapeamento entre núcleos de CPU e núcleos virtuais para um jogo Em execução.

Restrito

O diagrama a seguir mostra o mapeamento entre núcleos de CPU e núcleos virtuais para um jogo Restrito.

Last modified on October 6, 2026

⌘I

​Ciclo de vida de jogos do XBOX

​Introdução

​Estados do ciclo de vida do jogo

​Em execução

​Restrito

​Suspendendo

​Suspenso

​Não está em execução

​Transições de estado do ciclo de vida

​Transição de Em execução para Restrito (Restringir)

​Transição de Restrito para Suspendendo (Suspensão iniciada)

​Transição de Suspendendo para Suspenso (Suspensão concluída)

​Transição de Suspenso para Não está em execução (Encerrar)

​Transição de Não está em execução para Em execução (Iniciar)

​Transição de Suspenso para Restrito (Retomar)

​Transição de Restrito para Em execução (Remover restrição)

​Encerramento pelo sistema Connected Storage

​Retornos de chamada de eventos do ciclo de vida

​Responder à suspensão e à retomada

​Tempo limite de suspensão

​Direct3D

​APIs XGameSave

​Usuários e emparelhamento de usuário e controle

​Permissões e privilégios

​Rede

​APIs assíncronas

​APIs do Gaming Runtime

​Áudio

​Lidar com alterações de horário durante a suspensão

​Responder à restrição e à remoção da restrição

​Inicialização

​Eventos relacionados ao ciclo de vida

​Foco de entrada

​Visibilidade

​Trabalhar com tempos limite do GDK

​Quick Resume

​Ferramentas e recursos de depuração

​Ferramentas de transição do ciclo de vida

​Registro em log de transições de estado no xbWatson e no Visual Studio

​Interromper no tempo limite de suspensão

​Despejos automáticos de falhas de suspensão

​Causar transições de estado manualmente

​Apêndice

​Visualizar os XRs

​Para baixar a lista de XRs

​Telemetria de diagnóstico para eventos do ciclo de vida

​Diagramas de recursos de CPU para consoles XBOX Series com SMT habilitado

​Em execução

​Restrito

Ciclo de vida de jogos do XBOX

Introdução

Estados do ciclo de vida do jogo

Em execução

Restrito

Suspendendo

Suspenso

Não está em execução

Transições de estado do ciclo de vida

Transição de Em execução para Restrito (Restringir)

Transição de Restrito para Suspendendo (Suspensão iniciada)

Transição de Suspendendo para Suspenso (Suspensão concluída)

Transição de Suspenso para Não está em execução (Encerrar)

Transição de Não está em execução para Em execução (Iniciar)

Transição de Suspenso para Restrito (Retomar)

Transição de Restrito para Em execução (Remover restrição)

Encerramento pelo sistema Connected Storage

Retornos de chamada de eventos do ciclo de vida

Responder à suspensão e à retomada

Tempo limite de suspensão

Direct3D

APIs XGameSave

Usuários e emparelhamento de usuário e controle

Permissões e privilégios

Rede

APIs assíncronas

APIs do Gaming Runtime

Áudio

Lidar com alterações de horário durante a suspensão

Responder à restrição e à remoção da restrição

Inicialização

Eventos relacionados ao ciclo de vida

Foco de entrada

Visibilidade

Trabalhar com tempos limite do GDK

Quick Resume

Ferramentas e recursos de depuração

Ferramentas de transição do ciclo de vida

Registro em log de transições de estado no xbWatson e no Visual Studio

Interromper no tempo limite de suspensão

Despejos automáticos de falhas de suspensão

Causar transições de estado manualmente

Apêndice

Visualizar os XRs

Para baixar a lista de XRs

Telemetria de diagnóstico para eventos do ciclo de vida

Diagramas de recursos de CPU para consoles XBOX Series com SMT habilitado

Em execução

Restrito