Cycle de vie des jeux XBOX

Cette rubrique présente les concepts et les événements qui composent le cycle de vie d’un jeu. Elle montre comment implémenter l’état du jeu et les événements de changement d’état dans votre jeu afin d’offrir une expérience fluide aux utilisateurs. Elle vous montre également comment satisfaire aux exigences de certification et présente les outils et fonctionnalités à votre disposition pour déboguer ces événements. Les jeux conçus avec le Microsoft Game Development Kit (GDK) passent par divers états de ressources tout au long de leur durée de vie. Le passage d’un état à l’autre permet à la console XBOX d’offrir l’expérience multitâche réactive à laquelle les utilisateurs s’attendent. Il garantit aussi que les jeux obtiennent le plus de ressources possible de la console lorsque les utilisateurs y jouent. Pour y parvenir, toutefois, les jeux conçus avec le Microsoft Game Development Kit (GDK) doivent être prêts à gérer quelques événements et interactions.
Introduction États du cycle de vie d’un jeu Transitions d’état du cycle de vie Rappels d’événements du cycle de vie Réponse à la suspension et à la reprise Réponse à la contrainte et à la levée de contrainte Lancement Événements liés au cycle de vie Utilisation des délais d’expiration du GDK Quick Resume Outils et fonctionnalités de débogage Annexe

Introduction

Les états et événements du cycle de vie des jeux permettent aux utilisateurs de passer rapidement et efficacement d’un jeu à l’autre, à l’interface XBOX et à d’autres applications. Ce processus exige certaines actions de la part des jeux et des applications afin qu’ils puissent gérer les transitions entre les états du cycle de vie. Bien géré, ce travail offre une expérience fluide et transparente aux utilisateurs lorsqu’ils passent à votre jeu ou le quittent. Cette rubrique explique les divers aspects de la gestion du cycle de vie de votre jeu et décrit les outils offerts pour prendre en charge ces aspects. Si vous connaissez la gestion de la durée de vie des processus (PLM) des applications conçues avec le Software Development Kit XBOX One ou de la plateforme Windows universelle (UWP), ces renseignements vous seront familiers. Notez qu’il existe certaines différences et améliorations clés pour les applications GDK. Cette rubrique commence par :

Une discussion sur les différents états du cycle de vie.
Les transitions entre ces états.
Les rappels qui y sont associés.

Ensuite, cette rubrique explique les exigences relatives à la gestion réussie de ces transitions afin de satisfaire aux exigences XBOX (XR) et aborde les cas d’utilisation courants que la plupart des jeux devraient prendre en compte. Enfin, cette rubrique présente les outils et les fonctionnalités de débogage qui facilitent la compréhension et la correction des problèmes de transition d’état.

États du cycle de vie d’un jeu

Un jeu conçu avec le Microsoft Game Development Kit (GDK) installé sur une console XBOX se trouve toujours dans l’un des cinq états possibles suivants.

En cours d’exécution (Running)
Contraint (Constrained)
En cours de suspension (Suspending)
Suspendu (Suspended)
Non exécuté (Not Running)

Vous pouvez déterminer l’état d’un jeu en vérifiant :

L’état (State) indiqué dans la vue Home de XBOX Manager.
La valeur indiquée dans Dev Home à côté d’un jeu dans la vue Games & apps.
Le XBOX Device Portal.
L’outil en ligne de commande xbapp query.

En cours d’exécution (Running)

Lorsqu’un jeu est en cours d’exécution, il s’exécute avec la pleine disponibilité des ressources. Le jeu a le focus d’entrée et sa fenêtre est visible pour l’utilisateur. La pleine disponibilité des ressources signifie que le jeu s’exécute avec :

Six cœurs physiques de processeur (core0 à core5), plus 50 à 90 pour cent du cœur core6 sur les appareils de la famille XBOX One, et 100 pour cent du cœur core6 sur les consoles XBOX Series.
97 à 100 pour cent d’utilisation du GPU. Notez que le système d’exploitation peut utiliser jusqu’à 3 pour cent du GPU.
5 à 13 Go de mémoire, selon les paramètres de MicrosoftGame.config et la console sur laquelle le jeu s’exécute. Pour en savoir plus, consultez Configuration de la mémoire du titre.

Pour mieux illustrer les changements de ressources du processeur entre l’état En cours d’exécution et l’état Contraint, examinez le diagramme suivant qui montre l’état des cœurs du processeur lorsqu’un jeu est dans l’état En cours d’exécution.

Diagramme qui montre l'état des cœurs du processeur lorsque le jeu est dans l'état En cours d'exécution

Les consoles XBOX Series peuvent activer le multithreading simultané (SMT), ce qui modifie légèrement le diagramme. Pour en savoir plus sur le SMT, consultez Processeur et mémoire de la XBOX One par rapport à la XBOX Series X|S et l’annexe pour des diagrammes détaillant les cœurs du processeur avec le SMT.

Contraint (Constrained)

Lorsqu’un jeu s’exécute dans l’état d’exécution Contraint, il s’exécute avec une disponibilité réduite des ressources. Le jeu ne peut pas recevoir d’entrées de l’utilisateur dans cet état. Il est probable que la fenêtre du jeu soit partiellement masquée ou ne soit pas visible pour l’utilisateur. Un jeu est placé dans cet état lorsque l’utilisateur interagit avec une fonctionnalité ou vit toute expérience autre que le jeu actif, par exemple en interagissant avec un menu comme le Guide, une application système comme Paramètres ou une interface utilisateur appelable par le titre (TCUI) comme le sélecteur de compte. Lorsqu’un jeu est contraint, ses ressources disponibles sont réduites comme suit.

Quatre cœurs physiques de processeur. Les threads sont regroupés selon le modèle suivant.
- Les threads sur core0 et core1 ne sont pas touchés.
- Les threads sur core2 et core3 se partagent le temps d’un seul cœur physique de processeur.
- Les threads sur core4, core5 et core6 se partagent le temps d’un seul cœur physique de processeur.
Environ 45 pour cent du GPU.
La même mémoire disponible que dans l’état En cours d’exécution. Notez que l’état Contraint ne modifie pas la quantité de mémoire disponible pour le jeu.

L’illustration suivante montre l’état des cœurs du processeur lorsqu’un jeu est dans l’état Contraint.

Illustration qui montre l'état des cœurs du processeur lorsqu'un jeu est dans l'état Contraint

En cours de suspension (Suspending)

Lorsqu’un jeu s’exécute dans l’état d’exécution En cours de suspension, il s’exécute avec les mêmes ressources que dans l’état Contraint, sauf que cet état indique que la console a commencé le processus de transition du jeu vers l’état Suspendu. L’état En cours de suspension est transitoire. Par conséquent, selon la fréquence à laquelle vous interrogez l’état d’exécution, il peut être difficile d’observer l’état En cours de suspension.

Suspendu (Suspended)

Lorsqu’un jeu est dans l’état d’exécution Suspendu, il réside toujours en mémoire, mais il ne s’exécute plus. Ses threads ne sont pas planifiés et, par conséquent, il n’utilise aucun temps du processeur ni du GPU. Si un jeu est suspendu, l’ensemble du Game OS dans lequel le jeu s’exécute est également suspendu, et l’état du système d’exploitation et de la mémoire demeure intact jusqu’à ce qu’une autre transition d’état se produise.

Non exécuté (Not Running)

Il s’agit de l’état d’un jeu qui ne s’exécute pas, n’est pas chargé en mémoire et n’utilise aucune ressource de la console. Notez que certains outils (comme xbapp query) peuvent signaler cet état d’exécution comme l’état d’exécution de package 0 (inconnu).

Transitions d’état du cycle de vie

Cette section explique chacune des transitions d’état du cycle de vie et fournit des exemples de causes pour chacune. Certaines interactions de l’utilisateur avec la console peuvent entraîner plusieurs de ces événements de façon séquentielle, et parfois très rapidement, mais le jeu passe tout de même par toutes ces transitions. Le diagramme suivant montre les transitions entre les états du cycle de vie. Par souci de simplicité, le diagramme montre uniquement les transitions sans erreur. Notez qu’un jeu peut tout de même passer de n’importe quel état à l’état Non exécuté à la suite d’un plantage.

Transition de En cours d’exécution à Contraint (Constrain)

Cette transition représente la réduction des ressources disponibles pour le jeu. Le jeu peut s’inscrire pour recevoir un rappel lorsque cela se produit en appelant RegisterAppConstrainChangeNotification. Cette transition se produit lorsque :

Un utilisateur ouvre le Guide.
Une TCUI est présentée (comme le sélecteur de compte).
Un utilisateur retourne à l’Accueil.
Le jeu perd le focus.

Transition de Contraint à En cours de suspension (Suspend started)

Lorsqu’un jeu est en voie d’être suspendu, il passe d’abord à l’état En cours de suspension. Tous les rappels inscrits avec RegisterAppStateChangeNotification se déclenchent. Le jeu demeure dans l’état En cours de suspension jusqu’à ce qu’il revienne de tous les gestionnaires de rappel, ou jusqu’à l’expiration d’un délai d’une seconde. Si les gestionnaires reviennent avant l’expiration du délai, le jeu termine alors sa suspension. Sinon, le jeu est arrêté. Un jeu commence sa suspension lorsque :

La console est mise en veille connectée.
Le jeu n’a pas été visible pendant 10 minutes.
La première étape de l’arrêt d’un jeu se produit, par exemple lorsqu’un nouveau jeu est lancé.

Cette transition est parfois appelée quiesce (mise au repos).

Transition de En cours de suspension à Suspendu (Suspend completed)

Cette transition se produit automatiquement lorsqu’un jeu dans l’état En cours de suspension revient de ses gestionnaires de rappel inscrits avec RegisterAppStateChangeNotification. Les threads d’un jeu cessent de s’exécuter dès qu’il entre dans cet état.

Transition de Suspendu à Non exécuté (Terminate)

Cette transition représente le retrait du jeu de la mémoire. Un jeu n’a aucun contrôle ni aucune interaction sur cette transition, car un jeu suspendu ne s’exécute pas. Un arrêt se produit :

Lorsque l’utilisateur choisit de quitter le jeu à partir de l’Accueil.
Lorsque la console s’éteint (sans passer en veille connectée).
À la dernière étape de l’arrêt d’un jeu, par exemple lorsqu’un nouveau jeu est lancé.
Lorsque les données de sauvegarde du jeu ne sont pas synchronisées avec le nuage. Pour plus de détails, consultez Arrêt par le système Connected Storage.

Transition de Non exécuté à En cours d’exécution (Launch)

Cette transition d’état représente le chargement du jeu et son exécution dans le Game OS, et coïncide souvent avec le lancement du Game OS lui-même. Cela se produit chaque fois qu’un utilisateur :

Sélectionne la vignette d’un jeu.
Accepte une invitation à un jeu.
Interagit avec des références au jeu dans l’interface XBOX et le système.

Transition de Suspendu à Contraint (Resume)

Cette transition d’état est le plus souvent suivie d’un événement de levée de contrainte (Unconstrain). Elle représente la reprise de l’exécution des threads du jeu, et la transition commence par des rappels à tous les gestionnaires de RegisterAppStateChangeNotification. Un jeu est repris lorsqu’il était auparavant dans l’état Suspendu et qu’il est ramené au premier plan (habituellement par les mêmes interactions qui lanceraient le jeu s’il avait été dans l’état Non exécuté).

Transition de Contraint à En cours d’exécution (Unconstrain)

Cette transition d’état est l’inverse de la transition Constrain. Elle représente le rétablissement des ressources disponibles pour le jeu à la pleine quantité de l’état En cours d’exécution. Cette transition comporte aussi un rappel associé à tous les gestionnaires de RegisterAppConstrainChangeNotification et se produit chaque fois que le jeu devient l’application au premier plan. Lorsqu’un jeu est arrêté en raison d’interactions habituelles avec la console, comme le lancement d’un autre jeu ou l’arrêt de la console, il passe tout de même d’abord à l’état Suspendu avant l’arrêt. Cela garantit que le jeu en cours d’exécution a la possibilité de sauvegarder son état avant d’être arrêté. Cependant, si un jeu plante ou ne parvient pas à se suspendre, il passe directement à l’état Non exécuté.

Arrêt par le système Connected Storage

Si les données de sauvegarde locales du jeu ne sont pas synchronisées avec le nuage, le système Connected Storage arrêtera le jeu la prochaine fois qu’il se suspendra. Cela lui permet de synchroniser les plus récentes données de sauvegarde lors du prochain lancement. Un arrêt pour cette raison n’est pas un plantage et n’entraînera pas d’échec de XR-001. Ce cas n’est pas courant, mais il peut se produire si vous lancez un jeu alors que la console n’est pas connectée au réseau XBOX (aussi appelé XBOX Live), puis vous reconnectez pendant qu’il s’exécute. Cela peut aussi se produire pendant le développement si Connected Storage n’est pas correctement configuré pour le titre. Vous pouvez reconnaître ce cas en recherchant des lignes comme les suivantes dans xbWatson ou dans la fenêtre 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 indique que le jeu s’est suspendu avec succès et n’a ni planté ni dépassé le délai d’expiration. TerminateApplicationAfterSuspend indique que l’arrêt a été déclenché par le système après une suspension réussie. La valeur -2138890207 est un HRESULT, CS_E_TERMINATEDTITLE_NOLOCK, qui indique la raison de l’arrêt.

Rappels d’événements du cycle de vie

Cette section explique comment les jeux passent d’un état à l’autre. Elle explique aussi comment les jeux déterminent le moment où ces transitions se produisent et comment ils y répondent ensuite. Pour les jeux conçus avec le Microsoft Game Development Kit (GDK), vous pouvez vous inscrire à deux événements pour recevoir des renseignements sur les changements d’état. C’est ce que montre l’exemple de code suivant.

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

Pour en savoir plus, consultez RegisterAppStateChangeNotification.

La notification de changement de contrainte est propre aux consoles XBOX et n’a actuellement pas de page de référence d’API. L’API est très semblable, avec seulement le léger changement de « State » à « Constrained » dans le nom et les paramètres.

Le PVOID Context peut être n’importe quoi, et il est passé à la fonction Routine lorsqu’elle est appelée. Vous pouvez conserver Registration pour annuler l’inscription à ces événements avec UnregisterAppStateChangeNotification et UnregisterAppConstrainedChangeNotification. Routine, passée aux fonctions d’inscription, est appelée sur un thread du pool de threads par défaut du titre lorsque l’événement associé se produit. Toutes les routines inscrites avec cette fonction sont appelées de façon asynchrone sur des threads distincts du pool de threads. Cela peut se produire à tout moment pendant une image. Pour RegisterAppStateChangeNotification, Routine est appelée avec la valeur booléenne true dès que la console a placé le jeu dans l’état En cours de suspension et a démarré le délai d’expiration de suspension. Routine est appelée avec la valeur booléenne false lors de la reprise du jeu de l’état Suspendu à l’état En cours d’exécution. Pour RegisterAppConstrainedChangeNotification, Routine est appelée avec la valeur booléenne true lorsque la console place le jeu dans l’état Contraint. Routine est appelée avec la valeur booléenne false lors de la levée de contrainte du jeu, de l’état Contraint à l’état En cours d’exécution. Pour un exemple qui montre comment configurer et gérer ces événements et s’assurer qu’ils sont gérés sur le thread principal à un point constant de l’image d’un jeu, consultez l’exemple de code du guide de portage du Microsoft Game Development Kit pour XBOX One. Vous pouvez aussi consulter le fichier main.cpp de l’exemple SimplePLM ou du modèle de projet Direct3D 12 XBOX Game du Microsoft Game Development Kit (GDK) dans Visual Studio. Vous pouvez télécharger les exemples à partir de XBOX Developer Downloads. Lorsque vous examinez des minividages de blocage de mise au repos (quiesce), vous pourriez vous retrouver dans la situation plutôt déroutante de ne pas voir vos rappels inscrits dans les piles d’aucun des threads. Cela est dû à l’optimisation des appels terminaux (tail call); pour contourner ce problème, enveloppez simplement votre rappel dans :

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

Les jeux conçus avec le Microsoft Game Development Kit (GDK) qui s’exécutent sur un PC Windows ne seront pas suspendus. Sur un PC Windows, ces jeux peuvent tout de même appeler RegisterAppStateChangeNotification, mais sachez que le rappel PAPPSTATE_CHANGE_ROUTINE ne se déclenchera pas.

Réponse à la suspension et à la reprise

Un jeu doit faire certaines choses lors de sa suspension afin d’offrir une expérience transparente aux utilisateurs qui passent au jeu ou le quittent, et de s’assurer que le jeu satisfait aux XR.

Délai d’expiration de suspension

Pour terminer une suspension (ce qui est requis pour satisfaire à XR-001), un jeu doit avoir au moins une routine de rappel inscrite avec RegisterAppStateChangeNotification. Lorsque le rappel se déclenche, toutes les routines inscrites sont appelées de façon asynchrone sur des threads distincts du pool de threads par défaut. Le jeu dispose d’une seconde pour revenir de toutes les routines inscrites, ce qui signale au système que le jeu peut passer à l’état Suspendu. Si le jeu ne revient pas des routines de suspension en moins d’une seconde, ou si aucun rappel n’est inscrit, le jeu est arrêté et passe à l’état Non exécuté (ce qui constitue un échec de XR-001). Ce processus garantit que la console peut passer rapidement d’un jeu à l’autre tout en s’assurant que le jeu est prêt à être suspendu avant d’entrer dans l’état suspendu.

Direct3D

En réponse à l’appel de la routine de suspension, et avant d’en revenir, le jeu doit appeler SuspendX sur son ID3D12CommandQueue à partir de son thread de rendu. Cela garantit que l’état du GPU est sauvegardé en vue de la suspension. Lors de la reprise, le jeu doit appeler ResumeX pour restaurer l’état. L’appel de toute API Direct3D entre les appels à SuspendX et ResumeX entraîne la levée d’une exception, ce qui cause un plantage. Ne pas appeler SuspendX avant de revenir des routines de suspension fait échouer la suspension et entraîne l’arrêt du titre (encore une fois, un échec de XR-001). Pour en savoir plus, consultez Prise en charge de la suspension et de la reprise par Direct3D.

API XGameSave

Lorsqu’un jeu reçoit la notification de suspension, il dispose d’une seconde de temps d’exécution avant de devoir se suspendre. Lorsqu’un jeu est dans l’état Suspendu, il pourrait passer à l’état Non exécuté sans aucun temps d’exécution supplémentaire. Cela signifie que pendant cette seconde de suspension, le jeu doit sauvegarder toutes les données utilisateur non sauvegardées avant d’entrer dans l’état Suspendu. Les API XGameSave sont conçues pour prendre en charge la sauvegarde dans ce délai limité. L’API XGameSave utilise de la RAM à l’extérieur de la réservation du titre comme premier point de stockage afin de maximiser la vitesse d’écriture du titre pendant la courte fenêtre de suspension. XR-052 : État de l’utilisateur stipule que les titres ne doivent pas causer de perte involontaire de données utilisateur, ce qui comprend la progression et l’état de l’utilisateur, le cas échéant. En général, les jeux doivent s’assurer que leur gestion de la suspension comprend la sauvegarde des données utilisateur. Il est également judicieux de sauvegarder plus souvent que seulement lors de la suspension. Cela garantit que le jeu n’a pas à préparer une sauvegarde volumineuse pendant le délai d’expiration, et que des événements comme une panne de courant n’entraînent pas une perte importante de données utilisateur. Pour en savoir plus, consultez Vue d’ensemble des sauvegardes de jeu et l’exemple GameSave. Notez qu’il est préférable d’utiliser les versions asynchrones des API XGameSave. Cela permettra à un titre de poursuivre le reste de son code de suspension pendant que le système écrit les données de sauvegarde du jeu. Pour un exemple de la façon de procéder, consultez XGameSaveSubmitUpdateAsync. Avant de reprendre le jeu, le système d’exploitation vérifiera si la sauvegarde a été modifiée sur un autre appareil pendant que le jeu était suspendu. Si l’appareil est en ligne et que cette vérification indique que les sauvegardes ont été modifiées, le jeu sera arrêté et relancé afin de le ramener dans un état cohérent. Si l’appareil est hors ligne au moment de la vérification, le jeu pourra tout de même être lancé. Lors de la reprise, les jeux doivent toujours tenter de réacquérir leur fournisseur de sauvegarde en appelant XGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync. La réinitialisation du fournisseur garantit que les plus récentes données de sauvegarde sont disponibles.

Utilisateurs et jumelage des utilisateurs et des manettes

XR-112 : Établissement d’un utilisateur et d’une manette lors de l’activation initiale et de la reprise stipule que lorsqu’un titre est repris, il doit valider le jumelage utilisateur/manette et réagir en conséquence en reprenant la session de l’utilisateur précédent ou en acquérant un ou plusieurs nouveaux utilisateurs. Le comportement exact peut dépendre de la façon dont le jeu gère ses utilisateurs et ses manettes. Il est important de ne pas se fier à des renseignements sur l’état des utilisateurs ou des manettes antérieurs à la suspension, et de rétablir l’état des utilisateurs et des manettes lors de la reprise. Vous devez conserver XUserHandle tout au long d’un cycle de suspension/reprise, car c’est ainsi que le jeu obtient les mises à jour sur l’état de l’utilisateur. De plus, les rappels inscrits avec XUserRegisterForChangeEvent et XUserRegisterForDeviceAssociationChanged se déclenchent lors d’une reprise pour informer le jeu des changements d’état qui se sont produits. Pour en savoir plus sur la gestion des utilisateurs et des appareils, consultez Identité de l’utilisateur et XUser ainsi que Utilisateurs et périphériques d’entrée. Pour un exemple de la façon dont les jeux pourraient gérer cette situation, consultez l’exemple UserManagement.

Autorisations et privilèges

Pendant qu’un jeu est suspendu, les utilisateurs peuvent modifier les paramètres de compte qui déterminent ce qu’ils sont autorisés à faire en ligne et la façon dont ils peuvent communiquer avec les autres. Lorsqu’un jeu est repris, il doit vérifier de nouveau toutes les autorisations ou tous les privilèges avant d’activer ou de désactiver la fonctionnalité connexe, afin que le comportement du jeu reflète l’état actuel des paramètres de l’utilisateur. XR-015 : Gestion de la communication entre joueurs détaille les autorisations pour la communication textuelle et vocale. XR-045 : XBOX Live et privilèges de compte détaille les privilèges permettant d’autoriser ou d’empêcher les actions liées aux XBOX services.

Réseau

Comme aucun thread n’est planifié pour un jeu suspendu, lorsqu’un jeu reprend, il doit s’attendre à ce que les communications réseau aient été touchées. Pour obtenir des conseils sur la gestion de cette situation, consultez Présentation des API de réseau. Pour des détails propres aux XBOX services, consultez Prise en main des API des XBOX services. Pour en savoir plus sur les sessions multijoueurs, consultez Rubriques avancées sur les sessions multijoueurs.

API asynchrones

Certaines API asynchrones qui nécessitent une communication avec le System OS peuvent échouer si elles étaient en cours lorsque le jeu a été suspendu. Dans ce cas, les API Xasync devraient échouer avec E_ABORT. Cela n’est lié à aucune XR. Il s’agit plutôt d’un point à garder à l’esprit lors de l’appel d’API asynchrones. Assurez-vous d’avoir une gestion des erreurs en place pour gérer cette possibilité de façon élégante. Si un appel échoue de cette façon, la meilleure solution consiste habituellement à simplement réessayer lorsque le jeu a repris.

API du Gaming Runtime

Une fois que le jeu a terminé son gestionnaire AppStateChangedNotification pour l’événement de suspension, le Gaming Runtime est automatiquement suspendu. Le runtime est repris immédiatement avant l’appel du gestionnaire du jeu pour l’événement de reprise. Si des API du Gaming Runtime sont appelées sur d’autres threads pendant que le runtime est suspendu, elles échoueront avec E_GAMERUNTIME_SUSPENDED. Cela peut se produire, par exemple, si une API asynchrone est appelée peu avant la fin du gestionnaire de suspension. Le rappel pourrait se déclencher après la suspension du runtime, mais avant que le jeu cesse de planifier des threads. Dans la mesure du possible, évitez de faire des appels au Gaming Runtime qui pourraient s’exécuter pendant cette fenêtre où le Gaming Runtime est suspendu. Lorsque c’est inévitable, vous pouvez détecter l’erreur et réessayer l’appel après avoir reçu l’AppStateChangedNotification pour l’événement de reprise.

Audio

Lors de la suspension, les jeux ne doivent conserver aucun objet obtenu à partir d’un IMMDeviceEnumerator, y compris IMMDevice, IMMDeviceCollection ou IMMEndpointDevice. Tenter d’utiliser ces interfaces après une reprise sans d’abord utiliser IMMDeviceEnumerator pour les actualiser entraîne un comportement indéfini. Si le jeu conserve IMMNotificationClient, toutefois, ce client continue de fonctionner normalement pendant la suspension et la reprise. Il est également recommandé (bien que non obligatoire) d’arrêter tous les flux audio pendant la suspension et de les redémarrer lors de la reprise. Lors de la reprise, les flux audio du jeu seront aussi invalidés et devront être réinitialisés. Les jeux doivent procéder à la récupération après ces invalidations pendant ou après l’exécution de leur gestionnaire de reprise. Pour en savoir plus, consultez Comparaison des API audio du Software Development Kit XBOX One et du Microsoft Game Development Kit.

Tenter de réinitialiser les flux audio avant que le gestionnaire de reprise commence à s’exécuter pourrait entraîner un comportement indéfini.

Gestion des changements de temps pendant la suspension

Pendant que le jeu est suspendu, bien des choses peuvent se produire. La seule certitude est que le temps continuera de s’écouler pendant que le jeu est suspendu. Les jeux doivent en tenir compte et s’assurer que, lorsqu’ils calculent des mesures comme le temps passé à jouer, ils n’incluent pas involontairement le temps écoulé pendant que le jeu était suspendu. À partir du GDK de juin 2021, lorsque le jeu est suspendu, le compteur d’horodatage (TSC) est gelé et ne progressera pas tant que le jeu ne sera pas repris. De plus, le TSC n’inclura pas le temps écoulé pendant la suspension. Cela signifie que les jeux peuvent se fier aux éléments suivants pour signaler avec précision le temps écoulé pendant l’exécution du jeu :

__rdtscp
QueryPerformanceCounter

Bien que le TSC n’avance pas pendant la suspension, l’heure réelle (horloge murale) avance. Cela signifie que si le jeu appelle GetSystemTime ou GetLocalTime, il constatera que le temps a avancé.

Réponse à la contrainte et à la levée de contrainte

Contrairement à la notification de suspension, où le jeu doit effectuer des actions précises et où la console attend que la routine revienne, aucune action n’est requise en réponse à la notification de changement de contrainte de l’application. Lorsque l’événement est reçu, la transition vers l’état Contraint ou vers l’état En cours d’exécution a déjà eu lieu. Cet événement informe plutôt le jeu que ses ressources disponibles ont changé et qu’il doit réduire ou augmenter son utilisation des ressources en conséquence. Lorsque vous décidez de la façon dont un jeu doit gérer l’état contraint, tenez compte du fait qu’un jeu ne sera contraint que s’il n’a pas le focus d’entrée. Par conséquent, un utilisateur ne peut pas interagir avec le jeu pendant qu’il est contraint. Pour cette raison, la plupart des jeux devraient mettre le jeu en pause (ou faire ce qui s’en rapproche le plus) pendant qu’ils sont contraints. Cependant, un jeu peut tout de même être visible pendant qu’il est contraint; il est donc important de continuer à afficher quelque chose pour que l’utilisateur puisse voir l’état du jeu. Il est également probable que l’utilisateur ramène bientôt le jeu au premier plan; maintenir les parties multijoueurs et les autres communications réseau offrira donc probablement une meilleure expérience à l’utilisateur. Au bout du compte, le seul objectif de la gestion de la contrainte est de maintenir l’exécution du jeu tout en s’adaptant au temps réduit du processeur et du GPU. La meilleure façon d’y parvenir dépend des besoins particuliers de votre jeu.

Lancement

Les jeux conçus avec le Microsoft Game Development Kit (GDK) sont de conception Win32, avec une boucle de messages Windows traditionnelle. Ainsi, lorsqu’ils sont lancés, le premier point d’entrée du code accessible au développeur est constitué des paramètres passés à WinMain. Le jeu pourrait aussi interroger les paramètres avec lesquels il a été lancé à l’aide de la fonction GetCommandLine. Contrairement aux ERA XBOX One ou aux applications UWP, les jeux conçus avec le Microsoft Game Development Kit (GDK) ne sont pas soumis à un délai d’expiration d’activation et n’ont pas de gestionnaire d’événement Activated. De plus, contrairement aux ERA XBOX One ou aux applications UWP, les jeux conçus avec le Microsoft Game Development Kit (GDK) ne gèrent pas les invitations à un jeu au moyen de paramètres d’activation ou de lancement. Les jeux conçus avec le Microsoft Game Development Kit (GDK) qui doivent gérer les invitations à un jeu doivent plutôt s’inscrire à ces événements à l’aide de XGameInviteRegisterForEvent. Lorsque le jeu effectue son inscription, il obtient alors toutes les invitations en attente disponibles.

Événements liés au cycle de vie

Ces événements ne sont pas réellement des événements du cycle de vie. Il s’agit d’événements liés aux causes et aux conditions des transitions d’état. Ils peuvent être utiles pour déterminer comment identifier ces événements et y répondre en conséquence.

Focus d’entrée

Pour savoir quand le jeu a le focus d’entrée, les jeux conçus avec le Microsoft Game Development Kit (GDK) peuvent écouter la notification de fenêtre WM_ACTIVATEAPP dans le rappel WindowProc. C’est la même chose que l’implémentation Win32 pour PC Windows, et la même documentation s’applique. Pour en savoir plus, consultez Message WM_ACTIVATEAPP. L’exemple de code suivant montre comment écouter cet événement.

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

Visibilité

Pour déterminer si la fenêtre du jeu est visible (de façon semblable au focus d’entrée), les jeux conçus avec le Microsoft Game Development Kit (GDK) peuvent écouter la notification de fenêtre WM_SHOWWINDOW dans le rappel WindowProc. Pour en savoir plus, consultez Message WM_SHOWWINDOW. L’exemple de code suivant montre comment écouter la notification de fenêtre WM_SHOWWINDOW dans le rappel 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;
    ...

Utilisation des délais d’expiration du GDK

Les développeurs d’ERA XBOX One et d’applications UWP travaillent avec divers délais d’expiration pour l’activation, la suspension et la détection des blocages. Les jeux conçus avec le Microsoft Game Development Kit (GDK) sont de conception Win32 et, pour la plupart, n’ont pas de notions comparables, sauf lorsqu’ils s’exécutent sur des consoles où la capacité de changer d’état de ressources est nécessaire pour garantir la plus grande disponibilité possible des ressources pour le jeu en cours d’exécution. Le tableau suivant compare les divers comportements entre les différentes plateformes.

Gestionnaire/délai d’expiration	Microsoft Game Development Kit (GDK)	ERA XBOX One	UWP
Gestionnaire d’activation	Sans objet	`CoreApplicationView:: Activated`	`CoreApplicationView::Activated`
Délai d’expiration d’activation	Sans objet	45 s	10 s
Gestionnaire de suspension	`RegisterAppStateChangeNotification`	`CoreApplication:: Suspending`	`CoreApplication:: Suspending`
Délai d’expiration de suspension	1 s	1 s	5 s
Gestionnaire de reprise	`RegisterAppStateChangeNotification`	`CoreApplication:: Resuming`	`CoreApplication:: Resuming`
Délai d’expiration de reprise	Sans objet	Sans objet	Sans objet
Gestionnaire de contrainte	`RegisterAppConstrainedChangeNotification`	`CoreApplication:: ResourceAvailabilityChanged`	Sans objet
Délai d’expiration de contrainte	Sans objet	Sans objet	Sans objet
Délai d’expiration de blocage	Sans objet	2 s	2 s

Quick Resume

Quick Resume est une nouvelle fonctionnalité de la récupération de juin 2020 sur les consoles XBOX Series. Elle permet aux utilisateurs de passer d’un jeu à l’autre plus rapidement qu’auparavant en gardant des jeux suspendus pendant qu’un autre jeu s’exécute. Sur tous les appareils de la famille XBOX One, et sur les consoles XBOX Series avant la récupération de juin, lorsqu’un jeu est en cours d’exécution (ou contraint ou suspendu) et que l’utilisateur sélectionne un nouveau jeu, le premier jeu est arrêté et le nouveau jeu est lancé. Sur les consoles XBOX Series dotées de la récupération de juin 2020 ou d’une version ultérieure, le premier jeu peut plutôt être suspendu, puis l’ensemble du Game OS et de sa mémoire peut être sauvegardé dans l’état suspendu. Lorsque l’utilisateur revient au jeu, le Game OS est restauré. Le jeu peut alors être repris. Le Game OS sauvegardé peut même être restauré après un redémarrage de la console. Du point de vue du jeu, c’est identique à une suspension/reprise ordinaire. Aucune étape ni aucun code supplémentaire n’est nécessaire. Si un jeu peut se suspendre et reprendre avec succès, il prend aussi entièrement en charge Quick Resume. Grâce à Quick Resume, il est plus facile pour un jeu de s’exécuter pendant des centaines d’heures au cours d’une même session de lancement. Les jeux peuvent rester suspendus pendant des jours, des semaines, voire des mois. Il est donc important de s’assurer que les renseignements d’état établis avant la suspension (en particulier les renseignements sur les utilisateurs) ne sont pas présumés exacts lors de la reprise. Par exemple, si votre jeu tire parti de relations sociales approfondies, de nouveaux amis pourraient avoir été ajoutés et d’autres retirés. Si vous utilisez les renseignements de présence des amis, il est peu probable que ce qu’ils faisaient la semaine dernière soit exactement ce qu’ils font lorsque le jeu est repris. Des problèmes semblables s’appliquent aux préférences d’accessibilité, aux privilèges et aux classements.

Assurez-vous d’interroger de nouveau les états qui peuvent facilement changer au fil du temps.

Outils et fonctionnalités de débogage

Cette section décrit certains des outils, journaux et fonctionnalités qui aident au débogage et aux tests du cycle de vie d’un jeu.

Outils de transition du cycle de vie

Pour le débogage et les tests, il est important de savoir dans quel état se trouve un jeu et de pouvoir faire passer un jeu d’un état à l’autre. Il existe quelques outils que vous pouvez utiliser pour interroger l’état actuel du cycle de vie et effectuer des transitions d’état. XBOX Manager, le XBOX Device Portal et l’outil en ligne de commande xbapp indiquent tous l’état actuel d’une application. Ils fournissent tous des commandes pour effectuer les diverses transitions. Par exemple, la capture d’écran suivante montre les menus State et Actions de XBOX Manager.

Capture d'écran qui montre les menus State et Actions de XBOX Manager

Pour accélérer les itérations et offrir de la souplesse pour les tests, si la commande « terminate » est utilisée sur un jeu non empaqueté, celui-ci passera directement à l’état Non exécuté plutôt que d’être d’abord suspendu. Pour arrêter un jeu de la façon dont il serait habituellement arrêté, suspendez-le simplement d’abord avec la commande suspend.

La transition de l’état en cours d’exécution à l’état suspendu peut aussi être déclenchée à l’aide de l’un des boutons du panneau avant d’un kit de développement. Le script Suspend_Title fourni avec le Microsoft Game Development Kit (GDK) peut être associé à un bouton du panneau avant à l’aide de XBOX Manager ou du XBOX Device Portal. Notez que la transition vers un état repris ne peut pas être déclenchée à partir d’un bouton du panneau avant. La reprise doit être effectuée à partir de l’interface de la console en sélectionnant la vignette du jeu dans l’Accueil ou dans Mes jeux et applications, ou à l’aide d’un autre outil comme xbApp, Visual Studio ou XBOX Manager.

Journalisation des transitions d’état dans xbWatson et Visual Studio

Savoir quand les transitions d’état se produisent est tout aussi important que de connaître l’état actuel du cycle de vie. Une journalisation abondante des transitions d’état du cycle de vie est affichée dans xbWatson et dans la fenêtre XBOX System Monitor de Visual Studio. Désormais, chaque fois qu’une transition d’état se produit, elle est journalisée avec des renseignements sur d’autres événements liés à l’application, comme les étapes du démarrage de l’application et les changements de focus dans l’ensemble du système. La capture d’écran suivante montre quand les transitions d’état se produisent à l’aide de xbWatson.

Capture d'écran qui montre quand les transitions d'état se produisent à l'aide de xbWatson

La nouvelle fonctionnalité de journalisation comprend aussi les erreurs et les échecs liés aux événements du cycle de vie. La consultation de ce journal peut vous aider à déterminer quand un problème survient, ou fournir des renseignements supplémentaires sur tout cas d’erreur. Si une erreur se produit et signale un HRESULT, vous pouvez trouver plus de renseignements à l’aide de l’outil en ligne de commande xberror. Dans le cas d’erreur montré dans la capture d’écran précédente, xberror indique que le titre a dépassé le délai d’expiration pendant son gestionnaire de suspension (E_GAME_SUSPEND_TITLE_TIMEOUT).

Arrêt sur délai d’expiration de suspension

Une nouvelle fonctionnalité du Microsoft Game Development Kit (GDK) de juin 2020 permet à Visual Studio de s’arrêter automatiquement s’il débogue un jeu conçu avec le Microsoft Game Development Kit (GDK) et que celui-ci ne parvient pas à se suspendre en raison du délai d’expiration d’une seconde. Ce paramètre est désactivé par défaut. Cependant, vous pouvez le modifier dans les propriétés de débogage du projet, comme le montre la capture d’écran suivante.

Vous pouvez aussi modifier ce paramètre pour un jeu installé à l’aide de la fenêtre XBOX Gaming Explorer, même si son projet n’est pas ouvert. Sélectionnez le jeu dans XBOX Gaming Explorer, puis modifiez le paramètre Break on Suspend Timeout dans la fenêtre d’outil Properties. Pour plus de détails, consultez XBOX Gaming Explorer. Cela peut être très utile pour déboguer les échecs de suspension, lorsqu’il pourrait y avoir un blocage ou lorsqu’une partie du processus de suspension prend plus de temps que prévu. Le débogueur y parvient en insérant un nouveau thread dans le processus du jeu avec une instruction INT3 pour provoquer un arrêt. Cela signifie que le débogueur s’arrêtera d’abord sur un thread apparemment vide, mais que les autres threads seront arrêtés à l’endroit où ils se trouvent au moment de l’expiration du délai d’une seconde. Pour en savoir plus sur le débogage des états du cycle de vie d’un jeu avec Visual Studio, consultez Débogage de projets XBOX à l’aide de Visual Studio.

Vidages automatiques lors des échecs de suspension

Chaque fois qu’un échec de suspension se produit, un vidage de plantage de diagnostic automatique est enregistré sur la console. Le vidage est aussi téléversé vers le portail des développeurs. Ces vidages sont enregistrés sur la console dans D:\LocalDumps\. Avec la mise à jour de juin 2020, xbWatson affiche aussi la liste des vidages disponibles sur la console. Il comporte également une option pour télécharger les vidages à partir du menu. On les appelle vidages de mémoire de mise au repos (quiesce memory dumps), car « quiesce » est un autre nom de la suspension. La capture d’écran suivante montre les vidages de mémoire de mise au repos disponibles sur la console.

Capture d'écran qui montre les vidages de mémoire de mise au repos disponibles sur la console

Des vidages de diagnostic sont aussi créés lorsque le rappel de suspension (PAPPSTATE_CHANGE_ROUTINE) aurait dû être appelé, mais qu’aucun gestionnaire de suspension n’est inscrit. Des vidages de diagnostic sont également créés si ID3D12CommandQueue::SuspendX n’a pas été appelée avant la sortie du gestionnaire de suspension.

Déclenchement manuel des transitions d’état

Vous pouvez déclencher manuellement chacune des transitions d’état en interagissant avec la console. Le tableau suivant énumère des façons de déclencher chacune des transitions d’état sans aucun outil (en supposant que le jeu se trouve dans un état de départ approprié pour la transition).

Transition	Action
Lancement (Launch)	Sélectionnez la vignette du jeu dans Accueil ou dans Mes jeux et applications.
Contrainte (Constrain)	Appuyez sur le bouton XBOX de la manette pour ouvrir le Guide.
Suspension (Suspend)	Éteignez la console lorsque le mode d’alimentation est réglé à Instant-on.
Arrêt (Terminate)	La vignette du jeu étant sélectionnée, appuyez sur le bouton Menu de la manette, puis sélectionnez Quitter.
Reprise (Resume)	Sélectionnez la vignette du jeu dans Accueil ou dans Mes jeux et applications. Pour éviter aussi la levée de contrainte, ouvrez le Guide pendant la transition.
Levée de contrainte (Unconstrain)	Appuyez sur le bouton XBOX de la manette pour fermer le Guide.

Annexe

Consultation des XR

Pour télécharger la liste des XR

Accédez à XBOX Developer Downloads.
Pour le type de fichier, sélectionnez Partner, Publishing, and Release Management Information.
Sélectionnez Confirm.
Pour le numéro de build/version, sélectionnez la version de XGD Partner Documentation qui correspond à la version que vous utilisez.
Sélectionnez Confirm. Le bouton Download Now apparaît et vous invite à télécharger la documentation.

Télémétrie de diagnostic pour les événements du cycle de vie

La plateforme de console envoie de la télémétrie pour les événements présentés dans le tableau suivant.

Événement	Description
Temps de lancement	Le temps écoulé entre l’appel de `CreateProcess` pour démarrer le jeu et le premier appel du jeu à present.
Temps de reprise	Le temps écoulé entre la reprise de la partition du jeu et l’appel suivant du jeu à present.

Diagrammes des ressources du processeur pour les consoles XBOX Series avec SMT activé

Pour en savoir plus sur le SMT, consultez Processeur et mémoire de la XBOX One par rapport à la XBOX Series X|S.

En cours d’exécution (Running)

Le diagramme suivant montre la correspondance entre les cœurs du processeur et les cœurs virtuels pour un jeu en cours d’exécution.

Diagramme qui montre la correspondance entre les cœurs du processeur et les cœurs virtuels pour un jeu en cours d'exécution

Contraint (Constrained)

Le diagramme suivant montre la correspondance entre les cœurs du processeur et les cœurs virtuels pour un jeu contraint.

Diagramme qui montre la correspondance entre les cœurs du processeur et les cœurs virtuels pour un jeu contraint

Last modified on October 6, 2026

⌘I

​Cycle de vie des jeux XBOX

​Introduction

​États du cycle de vie d’un jeu

​En cours d’exécution (Running)

​Contraint (Constrained)

​En cours de suspension (Suspending)

​Suspendu (Suspended)

​Non exécuté (Not Running)

​Transitions d’état du cycle de vie

​Transition de En cours d’exécution à Contraint (Constrain)

​Transition de Contraint à En cours de suspension (Suspend started)

​Transition de En cours de suspension à Suspendu (Suspend completed)

​Transition de Suspendu à Non exécuté (Terminate)

​Transition de Non exécuté à En cours d’exécution (Launch)

​Transition de Suspendu à Contraint (Resume)

​Transition de Contraint à En cours d’exécution (Unconstrain)

​Arrêt par le système Connected Storage

​Rappels d’événements du cycle de vie

​Réponse à la suspension et à la reprise

​Délai d’expiration de suspension

​Direct3D

​API XGameSave

​Utilisateurs et jumelage des utilisateurs et des manettes

​Autorisations et privilèges

​Réseau

​API asynchrones

​API du Gaming Runtime

​Audio

​Gestion des changements de temps pendant la suspension

​Réponse à la contrainte et à la levée de contrainte

​Lancement

​Événements liés au cycle de vie

​Focus d’entrée

​Visibilité

​Utilisation des délais d’expiration du GDK

​Quick Resume

​Outils et fonctionnalités de débogage

​Outils de transition du cycle de vie

​Journalisation des transitions d’état dans xbWatson et Visual Studio

​Arrêt sur délai d’expiration de suspension

​Vidages automatiques lors des échecs de suspension

​Déclenchement manuel des transitions d’état

​Annexe

​Consultation des XR

​Pour télécharger la liste des XR

​Télémétrie de diagnostic pour les événements du cycle de vie

​Diagrammes des ressources du processeur pour les consoles XBOX Series avec SMT activé

​En cours d’exécution (Running)

​Contraint (Constrained)

Cycle de vie des jeux XBOX

Introduction

États du cycle de vie d’un jeu

En cours d’exécution (Running)

Contraint (Constrained)

En cours de suspension (Suspending)

Suspendu (Suspended)

Non exécuté (Not Running)

Transitions d’état du cycle de vie

Transition de En cours d’exécution à Contraint (Constrain)

Transition de Contraint à En cours de suspension (Suspend started)

Transition de En cours de suspension à Suspendu (Suspend completed)

Transition de Suspendu à Non exécuté (Terminate)

Transition de Non exécuté à En cours d’exécution (Launch)

Transition de Suspendu à Contraint (Resume)

Transition de Contraint à En cours d’exécution (Unconstrain)

Arrêt par le système Connected Storage

Rappels d’événements du cycle de vie

Réponse à la suspension et à la reprise

Délai d’expiration de suspension

Direct3D

API XGameSave

Utilisateurs et jumelage des utilisateurs et des manettes

Autorisations et privilèges

Réseau

API asynchrones

API du Gaming Runtime

Audio

Gestion des changements de temps pendant la suspension

Réponse à la contrainte et à la levée de contrainte

Lancement

Événements liés au cycle de vie

Focus d’entrée

Visibilité

Utilisation des délais d’expiration du GDK

Quick Resume

Outils et fonctionnalités de débogage

Outils de transition du cycle de vie

Journalisation des transitions d’état dans xbWatson et Visual Studio

Arrêt sur délai d’expiration de suspension

Vidages automatiques lors des échecs de suspension

Déclenchement manuel des transitions d’état

Annexe

Consultation des XR

Pour télécharger la liste des XR

Télémétrie de diagnostic pour les événements du cycle de vie

Diagrammes des ressources du processeur pour les consoles XBOX Series avec SMT activé

En cours d’exécution (Running)

Contraint (Constrained)