Cycle de vie d’un jeu 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 Microsoft Game Development Kit (GDK) passent par différents é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 attendue par les utilisateurs. Cela garantit également que les jeux obtiennent le maximum de ressources de la console lorsque les utilisateurs y jouent. Pour y parvenir, cependant, les jeux 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 d’un jeu permettent aux utilisateurs de basculer rapidement et efficacement entre les jeux, le shell XBOX et d’autres applications. Ce processus nécessite 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 quittent votre jeu ou y reviennent. Cette rubrique explique les différents aspects de la gestion du cycle de vie de votre jeu et décrit les outils disponibles pour les prendre en charge. Si vous connaissez la gestion de la durée de vie des processus (PLM, process lifetime management) des applications XBOX One Software Development Kit ou de la plateforme Windows universelle (UWP), ces informations vous seront familières. Notez qu’il existe des différences et des améliorations clés pour les applications GDK. Cette rubrique commence par :

Une présentation des différents états du cycle de vie.
Les transitions entre ces états.
Les rappels qui leur sont associés.

Ensuite, cette rubrique explique les exigences relatives à la bonne gestion de ces transitions pour satisfaire aux XBOX Requirements (XR) et aborde les cas d’utilisation courants que la plupart des jeux doivent prendre en compte. Enfin, cette rubrique présente les outils et 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 Microsoft Game Development Kit (GDK) installé sur une console XBOX se trouve toujours dans l’un des cinq états possibles suivants.

Running (en cours d’exécution)
Constrained (contraint)
Suspending (en cours de suspension)
Suspended (suspendu)
Not Running (pas en cours d’exécution)

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.

Running

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

Six cœurs de processeur physiques (core0-core5), plus 50 à 90 pour cent du cœur de processeur core6 sur les appareils de la famille XBOX One, et 100 pour cent du cœur de processeur 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 plus d’informations, consultez Configuration de la mémoire du titre.

Pour mieux illustrer les changements de ressources processeur entre l’état Running et l’état Constrained, considérez le diagramme suivant qui montre l’état des cœurs de processeur lorsqu’un jeu est dans l’état Running.

Diagramme montrant l'état des cœurs de processeur lorsque le jeu est dans l'état Running

Les consoles XBOX Series peuvent activer le multithreading simultané (SMT), ce qui modifie légèrement le diagramme. Pour plus d’informations sur le SMT, consultez XBOX One vs. XBOX Series X|S CPU and memory ainsi que l’annexe pour des diagrammes détaillant les cœurs de processeur avec le SMT.

Constrained

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

Quatre cœurs de processeur physiques. Les threads sont regroupés selon le schéma suivant.
- Les threads sur core0 et core1 ne sont pas affectés.
- Les threads sur core2 et core3 sont répartis par tranches de temps sur un seul cœur de processeur physique.
- Les threads sur core4, core5 et core6 sont répartis par tranches de temps sur un seul cœur de processeur physique.
Environ 45 pour cent du GPU.
La même mémoire disponible que dans l’état Running. Notez que le fait d’être contraint ne modifie pas la quantité de mémoire disponible pour le jeu.

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

Illustration montrant l'état des cœurs de processeur lorsqu'un jeu est dans l'état Constrained

Suspending

Lorsqu’un jeu s’exécute dans l’état d’exécution Suspending, il s’exécute avec les mêmes ressources que dans l’état Constrained, à ceci près que cet état indique que la console a commencé le processus de transition du jeu vers l’état Suspended. Suspending est un état transitoire. Par conséquent, selon la fréquence à laquelle vous interrogez l’état d’exécution, l’état d’exécution Suspending peut être difficile à observer.

Suspended

Lorsqu’un jeu est dans l’état d’exécution Suspended, il est toujours résident 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 reste intact jusqu’à ce qu’une autre transition d’état se produise.

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 des ressources de la console. Notez que certains outils (tels que xbapp query) peuvent signaler cet état d’exécution comme l’état d’exécution du 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 d’elles. Certaines interactions de l’utilisateur avec la console peuvent provoquer plusieurs de ces événements successivement, 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 ne montre que les transitions sans erreur. Notez qu’un jeu peut toujours passer de n’importe quel état à l’état Not Running à la suite d’un plantage.

Transition de Running à Constrained (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 (par exemple le sélecteur de compte).
Un utilisateur revient à l’accueil.
Le jeu perd le focus.

Transition de Constrained à Suspending (début de la suspension)

Lorsqu’un jeu est en cours de suspension, il passe d’abord à l’état Suspending. Tous les rappels inscrits avec RegisterAppStateChangeNotification se déclenchent. Le jeu reste dans l’état Suspending 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 placée en veille connectée (Connected Standby).
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 lors du lancement d’un nouveau jeu.

Cette transition est parfois appelée quiesce.

Transition de Suspending à Suspended (fin de la suspension)

Cette transition se produit automatiquement lorsqu’un jeu dans l’état Suspending 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 Suspended à Not Running (Terminate)

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

Lorsque l’utilisateur choisit de quitter le jeu depuis l’accueil.
Lorsque la console s’éteint (sans passer en veille connectée).
Lors de la dernière étape de l’arrêt d’un jeu, par exemple lors du lancement d’un nouveau jeu.
Lorsque les données de sauvegarde du jeu ne sont pas synchronisées avec le cloud. Pour plus de détails, consultez Arrêt par le système Connected Storage.

Transition de Not Running à Running (Launch)

Cette transition d’état représente le chargement du jeu et son exécution au sein du 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 le shell et le système XBOX.

Transition de Suspended à Constrained (Resume)

Cette transition d’état est le plus souvent suivie d’un événement Unconstrain. Elle représente la reprise de l’exécution des threads du jeu, et la transition commence par des rappels vers tous les gestionnaires de RegisterAppStateChangeNotification. Un jeu est repris lorsqu’il se trouvait auparavant dans l’état Suspended et qu’il est ramené au premier plan (généralement par les mêmes interactions que celles qui lanceraient le jeu s’il avait été dans l’état Not Running).

Transition de Constrained à Running (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 totalité de l’état Running. Cette transition est également associée à un rappel vers 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 courantes avec la console, comme le lancement d’un autre jeu ou l’extinction de la console, il passe tout de même d’abord à l’état Suspended avant l’arrêt. Cela garantit que le jeu en cours d’exécution a la possibilité d’enregistrer son état avant d’être arrêté. Cependant, si un jeu plante ou ne parvient pas à se suspendre, il passe directement à l’état Not Running.

Arrêt par le système Connected Storage

Si les données de sauvegarde locales du jeu ne sont pas synchronisées avec le cloud, le système Connected Storage arrêtera le jeu lors de sa prochaine suspension. Cela lui permet de synchroniser les dernières données de sauvegarde lorsque le jeu est relancé. 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 peut se produire si vous lancez un jeu alors que la console n’est pas connectée au réseau XBOX (également appelé XBOX Live), puis que vous vous reconnectez pendant son exécution. Cela peut également 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é initié par le système après une suspension réussie. La valeur -2138890207 est un HRESULT, CS_E_TERMINATEDTITLE_NOLOCK, indiquant 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 également comment les jeux déterminent quand ces transitions se produisent, et comment ils y répondent ensuite. Pour les jeux Microsoft Game Development Kit (GDK), il existe deux événements auxquels vous pouvez vous inscrire pour recevoir des informations sur les changements d’état. Cela est illustré dans 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 plus d’informations, consultez RegisterAppStateChangeNotification.

La notification de changement de contrainte est propre aux consoles XBOX et ne dispose actuellement pas de page de référence d’API. L’API est très similaire, avec simplement le remplacement de « State » par « Constrained » dans le nom et les paramètres.

Le PVOID Context peut être n’importe quoi ; il est transmis à la fonction Routine lorsqu’elle est appelée. Vous pouvez conserver Registration pour vous désinscrire de ces événements avec UnregisterAppStateChangeNotification et UnregisterAppConstrainedChangeNotification. Routine, transmise 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 manière asynchrone sur des threads distincts du pool de threads. Cela peut se produire à tout moment au cours d’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 Suspending et a démarré le délai d’expiration de la suspension. Routine est appelée avec la valeur booléenne false lors de la reprise du jeu de l’état Suspended vers l’état Running. Pour RegisterAppConstrainedChangeNotification, Routine est appelée avec la valeur booléenne true lorsque la console place le jeu dans l’état Constrained. Routine est appelée avec la valeur booléenne false lors de la levée de contrainte du jeu, de l’état Constrained vers l’état Running. Pour un exemple montrant comment configurer et gérer ces événements et garantir qu’ils sont traités sur le thread principal à un point cohérent de l’image d’un jeu, consultez l’exemple de code dans le Guide de portage du Microsoft Game Development Kit pour XBOX One. Vous pouvez également 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 des exemples depuis XBOX Developer Downloads. Lors de l’examen de minidumps de blocage de quiesce, vous pouvez vous retrouver dans la situation assez 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 optimization). Pour contourner ce problème, encapsulez simplement votre rappel dans :

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

Les jeux Microsoft Game Development Kit (GDK) exécutés sur un PC Windows ne sont pas suspendus. Sur PC Windows, ces jeux peuvent toujours 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 effectuer quelques opérations lors de sa suspension afin d’offrir une expérience transparente aux utilisateurs qui quittent le jeu ou y reviennent, et de garantir que le jeu satisfait aux XR.

Délai d’expiration de la suspension

Pour mener à bien 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 manière 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 Suspended. Si le jeu ne revient pas des routines de suspension dans un délai d’une seconde, ou si aucun rappel n’est inscrit, le jeu est arrêté et passe à l’état Not Running (ce qui constitue un échec de XR-001). Ce processus garantit que la console peut basculer rapidement entre les jeux tout en s’assurant que le jeu est prêt pour la suspension 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 depuis son thread de rendu. Cela garantit que l’état du GPU est enregistré 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, provoquant 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 (là encore, un échec de XR-001). Pour plus d’informations, consultez Direct3D support for suspend and resume.

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 Suspended, il peut passer à l’état Not Running sans aucun temps d’exécution supplémentaire. Cela signifie que pendant cette seconde de suspension, le jeu doit enregistrer toutes les données utilisateur non enregistrées avant d’entrer dans l’état Suspended. Les API XGameSave sont conçues pour prendre en charge l’enregistrement dans ce délai limité. L’API XGameSave utilise de la RAM en dehors 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: User State stipule que les titres ne doivent pas provoquer de perte involontaire de données utilisateur, ce qui inclut 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 inclut l’enregistrement des données utilisateur. Il est également judicieux d’enregistrer plus souvent que lors de la seule suspension. Cela garantit que le jeu n’a pas à préparer une sauvegarde volumineuse pendant le délai d’expiration, et qu’un événement comme une panne de courant n’entraîne pas de perte importante de données utilisateur. Pour plus d’informations, 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 permet à 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 manière de procéder, consultez XGameSaveSubmitUpdateAsync. Avant de reprendre le jeu, le système d’exploitation vérifie si la sauvegarde du jeu 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 est arrêté puis relancé afin de le ramener dans un état cohérent. Si l’appareil est hors ligne au moment de la vérification, le jeu est tout de même autorisé à se lancer. Lors de la reprise, les jeux doivent toujours essayer de réacquérir leur fournisseur de sauvegarde en appelant XGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync. La réinitialisation du fournisseur garantit que les dernières données de sauvegarde sont disponibles.

Utilisateurs et association utilisateur-manette

XR-112: Establishing a User and Controller During Initial Activation and Resume stipule que lorsqu’un titre est repris, il doit valider l’association 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 aux informations sur l’état des utilisateurs ou des manettes antérieures à la suspension, et de rétablir l’état des utilisateurs et des manettes lors de la reprise. Vous devez conserver XUserHandle au cours d’un cycle de suspension/reprise, car c’est ainsi que le jeu reçoit les mises à jour de l’état des utilisateurs. De plus, les rappels inscrits avec XUserRegisterForChangeEvent et XUserRegisterForDeviceAssociationChanged se déclenchent pendant une reprise pour informer le jeu des changements d’état survenus. Pour plus d’informations sur la gestion des utilisateurs et des appareils, consultez User identity and XUser et Users and Input Devices. Pour un exemple de la façon dont les jeux peuvent gérer cela, 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 comment ils peuvent communiquer avec les autres. Lorsqu’un jeu est repris, il doit revérifier toutes les autorisations ou tous les privilèges avant d’activer ou de désactiver les fonctionnalités associées, afin que le comportement du jeu reflète l’état actuel des paramètres de l’utilisateur. XR-015: Managing Player Communication détaille les autorisations relatives à la communication textuelle et vocale. XR-045: XBOX Live and Account Privileges détaille les privilèges permettant d’autoriser ou d’empêcher les actions liées aux XBOX services.

Mise en 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é affectées. Pour obtenir des conseils sur la gestion de cette situation, consultez Introduction aux API de mise en réseau. Pour des détails propres aux XBOX services, consultez Getting started with XBOX services APIs. Pour plus d’informations sur les sessions multijoueur, consultez Multiplayer Session advanced topics.

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 doivent é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 de disposer d’une gestion des erreurs permettant de traiter cette éventualité correctement. Si un appel échoue de cette manière, la meilleure solution consiste généralement à simplement réessayer une fois le jeu repris.

API 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 Gaming Runtime sont appelées sur d’autres threads pendant que le runtime est suspendu, elles échouent avec E_GAMERUNTIME_SUSPENDED. Cela peut se produire, par exemple, si une API asynchrone est appelée peu de temps avant la fin du gestionnaire de suspension. Le rappel peut se déclencher après la suspension du runtime, mais avant que le jeu ne cesse de planifier des threads. Dans la mesure du possible, évitez d’effectuer des appels Gaming Runtime susceptibles de s’exécuter pendant cette fenêtre où le Gaming Runtime est suspendu. Lorsque cela ne peut être évité, 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, en revanche, ce client continue de fonctionner normalement lors de la suspension et de la reprise. Il est également recommandé (bien que non obligatoire) d’arrêter tous les flux audio lors de la suspension et de les redémarrer lors de la reprise. Lors de la reprise, les flux audio du jeu sont également invalidés et doivent ê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 plus d’informations, consultez Comparison of XBOX One Software Development Kit and Microsoft Game Development Kit audio API.

Tenter de réinitialiser les flux audio avant le début de l’exécution du gestionnaire de reprise peut entraîner un comportement indéfini.

Gestion des changements d’heure pendant la suspension

Pendant que le jeu est suspendu, beaucoup de choses peuvent se produire. La seule certitude est que le temps continue de s’écouler pendant que le jeu est suspendu. Les jeux doivent en tenir compte et s’assurer que, lors du calcul de métriques telles que le temps passé à jouer, ils n’incluent pas involontairement le temps écoulé pendant la suspension du jeu. À partir du GDK de juin 2021, lorsque le jeu est suspendu, le compteur d’horodatage (TSC, time stamp counter) est gelé et ne progresse pas tant que le jeu n’est pas repris. De plus, le TSC n’inclut pas le temps écoulé pendant la suspension. Cela signifie que les jeux peuvent s’appuyer sur les éléments suivants pour indiquer 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) continue d’avancer. Cela signifie que si le jeu appelle GetSystemTime ou GetLocalTime, il constatera que le temps a progressé.

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

Contrairement à la notification de suspension, pour laquelle le jeu doit effectuer des actions spécifiques et la console attend le retour de la routine, 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 Constrained ou vers l’état Running 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. Pour décider de la manière dont un jeu doit gérer la contrainte, tenez compte du fait qu’un jeu n’est 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. C’est pourquoi la plupart des jeux devraient mettre le jeu en pause (ou faire ce qui s’en rapproche le plus) lorsqu’ils sont contraints. Cependant, un jeu peut rester visible pendant qu’il est contraint ; il est donc important de continuer à afficher quelque chose afin que l’utilisateur puisse voir l’état du jeu. Il est également probable que l’utilisateur ramène rapidement le jeu au premier plan ; maintenir les parties multijoueur et les autres communications réseau offrira donc probablement une meilleure expérience à l’utilisateur. En définitive, le seul objectif de la gestion de la contrainte est de maintenir l’exécution du jeu tout en s’adaptant à la réduction du temps processeur et GPU. La meilleure façon d’y parvenir dépend des besoins propres à votre jeu.

Lancement

Les jeux Microsoft Game Development Kit (GDK) sont conçus en 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 transmis à WinMain. Le jeu peut également interroger les paramètres avec lesquels il a été lancé à l’aide de la fonction GetCommandLine. Contrairement aux ERA XBOX One ou aux UWP, les jeux 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 UWP, les jeux Microsoft Game Development Kit (GDK) ne gèrent pas les invitations à un jeu par le biais de paramètres d’activation ou de lancement. Les jeux 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 reçoit 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. Ce sont des événements liés aux causes et aux conditions des transitions d’état. Ils peuvent être utiles pour 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 Microsoft Game Development Kit (GDK) peuvent écouter la notification de fenêtre WM_ACTIVATEAPP dans le rappel WindowProc. Il s’agit de la même implémentation que sur PC Windows en Win32, et la même documentation s’applique. Pour plus d’informations, 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 manière similaire au focus d’entrée), les jeux Microsoft Game Development Kit (GDK) peuvent écouter la notification de fenêtre WM_SHOWWINDOW dans le rappel WindowProc. Pour plus d’informations, 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 ERA XBOX One et UWP travaillent avec divers délais d’expiration pour l’activation, la suspension et la détection des blocages. Les jeux Microsoft Game Development Kit (GDK) sont conçus en Win32 et, pour la plupart, n’ont pas de notions comparables, sauf lors de l’exécution sur des consoles où la possibilité de modifier les états des ressources est nécessaire pour garantir la plus grande disponibilité de ressources possible au jeu en cours d’exécution. Le tableau suivant compare les différents comportements selon les plateformes.

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

Quick Resume

Quick Resume est une nouvelle fonctionnalité de la recovery de juin 2020 sur les consoles XBOX Series. Elle permet aux utilisateurs de basculer entre les jeux plus rapidement qu’auparavant en maintenant 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 antérieures à la recovery 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 disposant de la recovery de juin 2020 ou ultérieure, le premier jeu peut au contraire être suspendu, puis l’ensemble du Game OS et sa mémoire peuvent être enregistrés dans l’état suspendu. Lorsque l’utilisateur revient au jeu, le Game OS est restauré. Le jeu peut alors être repris. Le Game OS enregistré 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 normale. Aucune étape ni aucun code supplémentaire n’est nécessaire. Si un jeu peut se suspendre et reprendre correctement, il prend également entièrement en charge Quick Resume. Grâce à Quick Resume, il est plus facile pour un jeu de rester en cours d’exécution 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 informations d’état établies avant la suspension (en particulier les informations sur les utilisateurs) ne sont pas considérées comme toujours vraies lors de la reprise. Par exemple, si votre jeu exploite des relations sociales approfondies, de nouveaux amis ont pu être ajoutés et d’autres supprimés. Si vous utilisez les informations de présence des amis, il est peu probable que ce qu’ils faisaient la semaine dernière soit exactement ce qu’ils font au moment où le jeu est repris. Des problèmes similaires concernent les préférences d’accessibilité, les privilèges et les classements.

Veillez à interroger de nouveau les états susceptibles de changer facilement au fil du temps.

Outils et fonctionnalités de débogage

Cette section décrit certains des outils, journaux et fonctionnalités qui facilitent le débogage et le test 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 permettant d’effectuer les différentes transitions. Par exemple, la capture d’écran suivante montre les menus State et Actions de XBOX Manager.

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

Pour accélérer les itérations et offrir de la flexibilité pour les tests, si la commande ‘terminate’ est utilisée sur un jeu non empaqueté, celui-ci passe directement à l’état Not Running au lieu d’être d’abord suspendu. Pour arrêter un jeu de la manière dont il le serait habituellement, suspendez-le d’abord avec la commande suspend.

La transition de l’état en cours d’exécution à l’état suspendu peut également être déclenchée à l’aide de l’un des boutons du panneau avant d’un devkit. 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 depuis un bouton du panneau avant. La reprise doit être effectuée depuis le shell 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 tel que 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 prise en charge importante de la journalisation des transitions d’état du cycle de vie est présentée dans xbWatson et dans la fenêtre XBOX System Monitor de Visual Studio. Désormais, chaque transition d’état est journalisée avec des informations sur d’autres événements liés à l’application, tels que 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 montrant quand les transitions d'état se produisent, à l'aide de xbWatson

La nouvelle fonctionnalité de journalisation inclut également les erreurs et les échecs des événements du cycle de vie. Consulter ce journal peut vous aider à identifier quand un problème survient, ou fournir des informations supplémentaires sur tout cas d’erreur. Si une erreur se produit et signale un HRESULT, vous pouvez obtenir plus d’informations à l’aide de l’outil en ligne de commande xberror. Dans le cas d’erreur illustré 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épassement du délai 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 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. Vous pouvez toutefois le modifier dans les propriétés de débogage du projet, comme illustré dans la capture d’écran suivante.

Vous pouvez également 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 Outil Properties. Pour plus de détails, consultez XBOX Gaming Explorer. Cela peut être très utile pour déboguer les échecs de suspension, en cas de blocage ou lorsqu’une partie du processus de suspension prend plus de temps que prévu. Le débogueur procède 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 initialement sur un thread apparemment vide, mais que les autres threads seront arrêtés à l’endroit où ils se trouvaient lors de l’expiration du délai d’une seconde. Pour plus d’informations 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 en cas d’échec de suspension

Chaque fois qu’un échec de suspension se produit, un vidage de plantage de diagnostic est automatiquement enregistré sur la console. Le vidage est également chargé sur le portail des développeurs. Ces vidages sont enregistrés sur la console dans D:\LocalDumps\. Avec la mise à jour de juin 2020, xbWatson répertorie également les vidages disponibles sur la console. Il propose aussi une option permettant de télécharger les vidages depuis le menu. Ils sont appelés vidages mémoire de quiesce, car quiesce est un autre nom de la suspension. La capture d’écran suivante montre les vidages mémoire de quiesce disponibles sur la console.

Capture d'écran montrant les vidages mémoire de quiesce disponibles sur la console

Des vidages de diagnostic sont également 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 aussi créés si ID3D12CommandQueue::SuspendX n’a pas été appelé avant de quitter le 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 répertorie les moyens 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
Launch	Sélectionnez la vignette du jeu dans Accueil ou Mes jeux et applications.
Constrain	Appuyez sur le bouton XBOX de la manette pour ouvrir le Guide.
Suspend	Éteignez la console lorsque le mode d’alimentation est réglé sur Instant-on.
Terminate	Avec la vignette du jeu sélectionnée, appuyez sur le bouton Menu de la manette, puis sélectionnez Quitter.
Resume	Sélectionnez la vignette du jeu dans Accueil ou Mes jeux et applications. Pour éviter également la levée de contrainte, ouvrez le Guide pendant la transition.
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 la XGD Partner Documentation qui correspond à la version que vous utilisez.
Sélectionnez Confirm. Le bouton Download Now apparaît, vous invitant à télécharger la documentation.

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

La plateforme console envoie des données de 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 de présentation (present) effectué par le jeu.
Temps de reprise	Le temps écoulé entre la reprise de la partition du jeu et la présentation suivante effectuée par le jeu.

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

Pour plus d’informations sur le SMT, consultez XBOX One vs. XBOX Series X|S CPU and memory.

Running

Le diagramme suivant montre la correspondance entre les cœurs de processeur et les cœurs virtuels pour un jeu dans l’état Running.

Constrained

Le diagramme suivant montre la correspondance entre les cœurs de processeur et les cœurs virtuels pour un jeu dans l’état Constrained.

​Cycle de vie d’un jeu XBOX

​Introduction

​États du cycle de vie d’un jeu

​Running

​Constrained

​Suspending

​Suspended

​Not Running

​Transitions d’état du cycle de vie

​Transition de Running à Constrained (Constrain)

​Transition de Constrained à Suspending (début de la suspension)

​Transition de Suspending à Suspended (fin de la suspension)

​Transition de Suspended à Not Running (Terminate)

​Transition de Not Running à Running (Launch)

​Transition de Suspended à Constrained (Resume)

​Transition de Constrained à Running (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 la suspension

​Direct3D

​API XGameSave

​Utilisateurs et association utilisateur-manette

​Autorisations et privilèges

​Mise en réseau

​API asynchrones

​API Gaming Runtime

​Audio

​Gestion des changements d’heure 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épassement du délai de suspension

​Vidages automatiques en cas d’échec 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 processeur pour les consoles XBOX Series avec le SMT activé

​Running

​Constrained

Cycle de vie d’un jeu XBOX

Introduction

États du cycle de vie d’un jeu

Running

Constrained

Suspending

Suspended

Not Running

Transitions d’état du cycle de vie

Transition de Running à Constrained (Constrain)

Transition de Constrained à Suspending (début de la suspension)

Transition de Suspending à Suspended (fin de la suspension)

Transition de Suspended à Not Running (Terminate)

Transition de Not Running à Running (Launch)

Transition de Suspended à Constrained (Resume)

Transition de Constrained à Running (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 la suspension

Direct3D

API XGameSave

Utilisateurs et association utilisateur-manette

Autorisations et privilèges

Mise en réseau

API asynchrones

API Gaming Runtime

Audio

Gestion des changements d’heure 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épassement du délai de suspension

Vidages automatiques en cas d’échec 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 processeur pour les consoles XBOX Series avec le SMT activé

Running

Constrained