Passer au contenu principal

​
Dossiers de superposition

En général, le SKU Outils vous permet de mettre à niveau les outils du GDK sans avoir à mettre à niveau les autres composants du GDK (par exemple, les en-têtes, les bibliothèques et le Game OS). La fonctionnalité des dossiers de superposition est une exception, car elle dépend de la prise en charge du Game OS, qui est publié dans le cadre du GDK, mais pas du SKU Outils.

​
Utilisations typiques des dossiers de superposition

Les dossiers de superposition conviennent bien aux scénarios où un développeur de jeux souhaite mettre à jour localement un seul fichier, ou quelques fichiers, d’un titre tout en laissant intact le stockage sous-jacent des fichiers originaux du jeu. Prenons les exemples suivants.
  • Abigail teste une version empaquetée de son titre sur sa trousse de développement XBOX One ERA. Elle rencontre un bogue dans le titre et en connaît la cause. Elle corrige rapidement le code fautif localement sur son PC de développement. Sur sa trousse de développement, elle crée un dossier de superposition associé au package de son titre. Elle copie l’exécutable contenant son correctif dans le dossier de superposition, lance le titre et peut immédiatement vérifier que le correctif a réglé le bogue. Cela accélère considérablement ses itérations. Auparavant, elle devait recréer le package de tout le titre et le redéployer sur la console avant de pouvoir tester ce genre de correctif.
  • Felix gère un laboratoire de tests de jeu où des trousses de développement sont configurées pour exécuter divers jeux à la demande, sur le réseau de son studio, à partir de builds de fichiers libres stockées sur un serveur de build centralisé (selon le modèle de déploiement Exécuter à partir d’un PC). L’un des testeurs découvre un bogue grave. Un développeur fournit un fichier .dll privé à Felix, qui le configure dans un dossier de superposition sur l’une des machines du laboratoire. Avec le fichier .dll privé en superposition, le jeu s’exécute maintenant sans problème. Felix a pu tester le correctif localement sur une trousse de développement sans avoir à modifier la version du jeu partagée sur le réseau, ce qui réduit le risque de perturber les autres testeurs.
Les dossiers de superposition sont conçus pour permettre des modifications rapides et itératives d’un titre, même lorsque le package original utilisé pour installer le titre n’est pas disponible ou ne peut pas être modifié.

​
Concepts des dossiers de superposition

Grâce à un dossier de superposition, un développeur peut superposer ou remplacer la version d’un fichier d’un jeu par une autre version stockée ailleurs, notamment en tant que fichier libre sur un lecteur local ou quelque part sur le réseau. Voici les concepts de base que vous devez comprendre pour bien utiliser les dossiers de superposition :
  • Définir (Set) : Associe le nom complet du package de votre jeu au chemin d’un dossier où vos fichiers de superposition seront stockés. Une fois définis, le nom complet du package et le chemin forment essentiellement une paire clé-valeur qui persiste lors des redémarrages de la trousse de développement.
  • Obtenir (Get) : Récupère le chemin du dossier de superposition actuellement associé à un nom complet de package précis.
  • Lister (List) : Liste toutes les paires nom complet de package (PFN)/chemin de dossier de superposition inscrites sur la trousse de développement.
  • Effacer (Clear) : Vous pouvez effacer (aussi appelé réinitialiser) le dossier de superposition d’un nom complet de package précis ou de tous les noms complets de package. Cela supprime simplement tout chemin de dossier de superposition précédemment associé au nom complet du package.
Utilisons un exemple pour illustrer ces concepts. Omar teste un jeu appelé MyGame. L’exécutable principal du jeu est MyGame.exe, et il est installé dans le cadre du segment de lancement du jeu. D’autres parties du jeu peuvent être chargées pendant l’exécution du jeu; elles se trouvent donc dans des segments diffusés vers la console après l’installation du segment de lancement. installlazily.dll est un binaire qui peut être diffusé vers la console après le lancement du jeu. Une développeuse, Eugenia, a corrigé quelques bogues dans la build empaquetée de MyGame de la nuit dernière et aimerait qu’Omar teste les correctifs. Il peut facilement se préparer à tester les correctifs, sans même demander à Eugenia de recréer le package de MyGame, en utilisant un dossier de superposition comme suit.
  1. Omar utilise l’invite de commandes du GDK pour créer un nouveau dossier sur le lecteur de travail système de sa trousse de développement XBOX.
  2. Il copie ensuite les binaires corrigés dans le dossier de superposition nouvellement créé.
  3. Ensuite, Omar définit son dossier comme dossier de superposition pour son jeu.
  4. Enfin, il installe le segment de lancement de la build de package de la nuit dernière.
  5. Il est maintenant prêt à tester. Il lance son jeu comme d’habitude.
Au lancement du jeu, c’est le fichier game.exe du dossier de superposition qui est chargé (et non le fichier game.exe copié sur la console dans le cadre du segment de lancement du package). Lorsque l’installation en continu a progressé jusqu’à ce que le segment contenant installlazily.dll soit installé, le jeu est avisé que le segment est disponible, et il charge installlazily.dll. C’est la version de installlazily.dll du dossier de superposition qui sera chargée. Ainsi, les binaires corrigés du dossier de superposition permettent au package non modifié de s’exécuter correctement, et Omar signale que les problèmes sont résolus.

​
Implications de conception

La trousse de développement effectue beaucoup de travail de manière transparente pour le développeur afin de rendre les dossiers de superposition faciles à utiliser. Même si ce travail est transparent, il y a certains aspects que vous devez comprendre pour tirer le maximum des dossiers de superposition.

​
Flux de travail flexible

Dans l’exemple précédent, Omar a décidé de configurer d’abord le dossier de superposition, puis d’installer la build empaquetée de la nuit dernière. Il aurait tout aussi bien pu décider d’installer d’abord le package. Tant que le dossier contenant les fichiers de superposition existe et est accessible, que le dossier de superposition a été défini pour associer le nom complet du package du jeu au chemin du dossier de superposition et que le jeu est installé/inscrit au moment où le développeur tente de le lancer, les fichiers du dossier de superposition seront utilisés pour exécuter le jeu. L’ordre de ces opérations est laissé au choix du développeur.
  • Le jeu n’a pas besoin d’être installé/inscrit au moment où le dossier de superposition est défini.
  • Le répertoire référencé dans le chemin du dossier de superposition n’a pas besoin d’exister ni d’être accessible lorsque le dossier de superposition est défini.
  • Les nouveaux fichiers et répertoires ajoutés au dossier de superposition, y compris pendant l’exécution du jeu, sont utilisés lors des appels FileOpen subséquents pendant l’exécution du jeu.
  • La désinstallation/réinstallation du jeu après la définition de la superposition n’entraîne aucun effet secondaire.
Le remplacement du fichier MicrosoftGame.config de votre titre dans un dossier de superposition n’est pas pris en charge actuellement.

​
Choix des outils de développement

Dans l’exemple précédent, Omar a créé un répertoire sur la trousse de développement XBOX et y a copié des fichiers à l’aide de l’invite de commandes du GDK (c’est-à-dire avec mkdir et copy). Il aurait plutôt pu choisir d’utiliser d’autres outils.
  • Outils à distance du GDK (par exemple, xbdir et xbcp)
  • Outils graphiques de Windows (par exemple, l’Explorateur de fichiers)
  • Commandes de l’interpréteur Bash
  • Outils tiers
De même, Omar a défini son dossier de superposition à l’aide de xbapp sur la ligne de commande. La configuration des dossiers de superposition est aussi prise en charge au moyen des outils suivants :
  • XBOX Manager
  • XBOX Device Portal
  • Developer Home (Dev Home)
  • API XBOX Tools Framework

​
Fonctionnement transparent et diagnostic

​
Indicateur visuel

Il est facile de « définir et oublier » un dossier de superposition. Une fois un dossier de superposition défini, les fichiers et répertoires qu’il contient peuvent être ajoutés, mis à jour ou supprimés sans modifier le paramètre du dossier de superposition. C’est pourquoi nous fournissons des repères visuels dans les outils graphiques pour rappeler de manière proactive aux développeurs qu’ils ont défini un dossier de superposition pour un titre.

​
Sortie de débogage

Lorsqu’un jeu est activé et qu’un dossier de superposition est défini pour le nom complet de son package, une sortie de débogage est écrite pour indiquer qu’une superposition a été trouvée, et les fichiers chargés à partir du dossier de superposition sont également affichés.

​
Configuration des dossiers de superposition

​
Configuration d’un dossier de superposition à partir de la ligne de commande

Comme le montre la section précédente de cette rubrique, le dossier de superposition d’un nom complet de package donné peut être récupéré, défini, mis à jour et réinitialisé à l’aide de la commande xbApp overlayfolder.

​
Configuration d’un dossier de superposition à partir de XBOX Manager

XBOX Manager permet d’afficher, d’ajouter et de supprimer le chemin du dossier de superposition d’un nom complet de package. Pour plus d’informations, consultez Gestion des applications et des fichiers (XBOX Manager).

​
Configuration d’un dossier de superposition à partir de XBOX Device Portal

XBOX Device Portal permet d’afficher, d’ajouter et de supprimer le chemin du dossier de superposition d’un nom complet de package. Pour plus d’informations, consultez Gestion des dossiers de superposition (XBOX Device Portal).

​
Configuration d’un dossier de superposition à partir de Dev Home

Dev Home permet d’afficher, d’ajouter et de supprimer le chemin du dossier de superposition d’un nom complet de package. Pour plus d’informations, consultez Gestion des dossiers de superposition (Dev Home).

​
Configuration d’un dossier de superposition à l’aide de l’API XBOX Tools Framework (XTF)

XTF permet d’interroger, d’ajouter et d’effacer le chemin du dossier de superposition d’un nom complet de package. Pour plus d’informations, consultez API Xtf supplémentaires.

​
Configuration des chemins relatifs à la console

Les chemins des dossiers de superposition sont interprétés du point de vue de la console. Si vous spécifiez E:\Overlay, la console cherchera E:\Overlay dans le système d’exploitation système (System OS) et ne le trouvera pas. Cela est dû à la façon dont les superpositions sont traitées : ce sont le System OS et le Title OS, et non les outils du PC, qui sont responsables du traitement des superpositions. Pour configurer correctement votre dossier de superposition, veuillez suivre les directives ci-dessous.
  • Vous pouvez partager le dossier de superposition par SMB, puis utiliser le chemin \FQDN_PC_NAME\shared_overlay :
    • Exemple : xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw \FQDN_PC_NAME\shared_overlay
    • REMARQUE : La console aura besoin d’informations d’identification pour le partage SMB, au moyen de xbcred add FQDN_PC_NAME\shared_overlay FQDN\USER_NAME PASSWORD
    • REMARQUE : Utilisez le nom de domaine complet (FQDN) partout où vous faites référence à ce chemin afin d’éviter les problèmes de résolution de noms.
  • Vous pouvez utiliser Exécuter à partir d’un PC par XBTPLink, avec xbtp:\FQDN\Q:\overlay
    • Exemple : xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw Q:\overlay
    • REMARQUE : Vous devrez vous assurer que XbtpLinkSvc.exe est démarré et que le pare-feu autorise les connexions sur le port TCP 4201.
    • REMARQUE : Dans les versions du GDK antérieures à octobre 2021, il fallait utiliser xbtp:\FQDN_PC_NAME\ pour construire le chemin xbtp vers le dossier de superposition; ce n’est plus nécessaire, il suffit de spécifier le chemin du dossier réseau.
  • Vous pouvez utiliser le lecteur D:\ du System OS, en copiant le ou les fichiers au moyen de xbcp : xbcp Q:\overlay\mygame.exe xd:\overlay\
    • Exemple : xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw xD:\overlay
    • REMARQUE : Dans ce cas, vous utiliserez xD:\overlay comme dossier de superposition.
Pour un petit nombre de fichiers, le dossier local du System OS (option 3) est probablement le meilleur choix. Il permet à la console d’utiliser la superposition sans dépendre de votre PC. Si vous devez remplacer un plus grand nombre de fichiers, il peut être plus simple d’utiliser la 1re ou la 2e option.

​
Incidence des dossiers de superposition sur les performances

Les dossiers de superposition ajoutent un faible coût à chaque ouverture de fichier. Ce coût est beaucoup moins élevé si la superposition est configurée pour un emplacement du System OS (option 3 de la section précédente). En effet, chaque ouverture de fichier du titre sur G:\ effectue d’abord une recherche dans le System OS pour vérifier si le dossier de superposition contient le chemin. Ce coût s’applique, que le fichier en question ait une superposition ou non. Si le dossier de superposition se trouve sur le PC de développement, l’incidence sur les performances devrait être considérée comme comparable à l’exécution d’un titre au moyen d’Exécuter à partir d’un PC. À chaque lecture de fichier, le dossier de superposition sera vérifié pour déterminer s’il contient un fichier qui doit être lu à la place et, le cas échéant, celui-ci sera transféré du PC de développement vers la trousse de développement. Il est recommandé d’utiliser un dossier de superposition dans le System Scratch de la trousse de développement pour éviter ce coût lorsque vous utilisez des dossiers de superposition pour des déploiements de dossiers et des installations de packages.

​
Configuration des superpositions pendant l’exécution du titre

Les dossiers de superposition sont appliqués au moment du mappage des volumes; un redémarrage du titre sera donc nécessaire pour appliquer une nouvelle superposition. Pour configurer cela à l’avance afin que votre titre y ait accès, vous pouvez définir un dossier vide comme superposition de votre titre et y ajouter des fichiers plus tard. Ce dossier de superposition vide entraînera tout de même une légère surcharge de performances, comme décrit dans la section ci-dessus.

​
Utilisation des dossiers de superposition avec les installations de packages par segment de lancement

Les dossiers de superposition prennent en charge la superposition de fichiers sur une installation de package par segment de lancement, où seule une partie du package est installée. Dans ce scénario, xbapp install doit être exécuté avec l’indicateur /W. L’indicateur /W est nécessaire pour toute installation où le package pourrait demander des segments supplémentaires après la fin de la commande « xbapp install » initiale. Dans ce cas, les segments suivant le segment de lancement seront demandés au lancement du titre.

​
Considérations de sécurité

​
Accès aux dossiers de superposition

Lorsqu’un dossier de superposition est configuré sur le PC du développeur, il est nécessaire d’accorder explicitement à la console l’autorisation d’accéder au dossier sur le PC du développeur. Le service XRFS qui s’exécute sur le PC de développement permet uniquement à la console de récupérer des fichiers dans les dossiers locaux ajoutés à sa liste d’accès. Un dossier de superposition est ajouté à la liste d’accès XRFS à l’aide d’une ligne de commande comme suit.
La définition d’une liste d’autorisation est requise dans tout scénario où le dossier de superposition ne se trouve pas sur la trousse de développement.

​
Accès aux dossiers de superposition sur des partages réseau

Lors de l’accès à un dossier de superposition situé sur un partage réseau, il est nécessaire de s’assurer que des informations d’identification d’utilisateur autorisées à accéder au partage réseau sont inscrites sur la trousse de développement. Vous pouvez le faire à l’aide de la commande xbCred ou des fonctionnalités équivalentes de XBOX Manager et de XBOX Device Portal.

​
Voir aussi

Dernière modification le 6 octobre 2026