Passer au contenu principal

​
Dossiers de superposition

En général, le SKU Tools 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é Dossiers de superposition (Overlay Folders) 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 Tools.

​
Utilisations typiques des dossiers de superposition

Les dossiers de superposition sont bien adaptés aux scénarios dans lesquels 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 d’origine du jeu. Prenons les exemples suivants.
  • Abigail teste une version empaquetée de son titre sur son kit 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 son kit 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ésolu le bogue. Cela accélère considérablement ses itérations. Auparavant, elle devait réempaqueter l’intégralité du titre et redéployer le package sur la console avant de pouvoir tester ce type de correctif.
  • Felix gère un laboratoire de tests de jeu dans lequel les kits de développement sont configurés pour exécuter à la demande divers jeux, via le réseau de son studio, à partir de builds de fichiers libres stockés sur un serveur de build centralisé (à l’aide du modèle de déploiement Exécuter à partir d’un PC). L’un des testeurs découvre un bogue grave. Un développeur fournit une .dll privée à Felix, qui la configure dans un dossier de superposition sur l’une des machines du laboratoire. Avec la .dll privée superposée, le jeu s’exécute désormais sans problème. Felix a pu tester le correctif localement sur un kit 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 d’apporter des modifications rapides et itératives à un titre, même lorsque le package d’origine utilisé pour installer le titre n’est pas disponible ou ne peut pas être modifié.

​
Concepts des dossiers de superposition

À l’aide d’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, y compris sous forme de fichiers libres sur un lecteur local ou quelque part sur le réseau. Voici les concepts fondamentaux à comprendre pour utiliser correctement les dossiers de superposition :
  • Set : associe le nom complet du package de votre jeu au chemin d’un dossier dans lequel vos fichiers de superposition seront stockés. Une fois défini, le nom complet du package et le chemin forment essentiellement une paire clé-valeur qui persiste lors des redémarrages du kit de développement.
  • Get : récupère le chemin du dossier de superposition actuellement associé à un nom complet de package spécifique.
  • List : répertorie toutes les paires nom complet de package (PFN)/chemin de dossier de superposition inscrites sur le kit de développement.
  • Clear : vous pouvez effacer (opération également appelée réinitialisation) le dossier de superposition d’un nom complet de package spécifique, 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.
Prenons 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 bloc 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 blocs diffusés en continu vers la console après l’installation du bloc de lancement. installlazily.dll est l’un des binaires qui peuvent être diffusés vers la console après le lancement du jeu. Une développeuse, Eugenia, a corrigé quelques bogues dans le build empaqueté de MyGame de la nuit dernière et souhaite qu’Omar teste les correctifs. Il peut facilement se préparer à tester les correctifs, sans même demander à Eugenia de réempaqueter 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 son kit 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 bloc de lancement à partir du build empaqueté 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 bloc de lancement du package). Lorsque l’installation en continu a progressé jusqu’à l’installation du bloc contenant installlazily.dll, le jeu est informé que le bloc est disponible et il charge installlazily.dll. C’est la version d’installlazily.dll du dossier de superposition qui est 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

Le kit de développement effectue beaucoup de travail de manière transparente pour le compte du développeur afin de rendre les dossiers de superposition faciles à utiliser. Bien que ce fonctionnement soit transparent, certains aspects doivent être compris pour tirer le meilleur parti 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 le build empaqueté de la nuit dernière. Il aurait tout aussi bien pu décider d’installer le package en premier. 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 sont 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 ultérieurs 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 actuellement pas pris en charge.

​
Choix des outils de développement

Dans l’exemple précédent, Omar a créé un répertoire sur le kit 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 pu choisir d’utiliser d’autres outils.
  • Outils distants du GDK (par exemple, xbdir et xbcp)
  • Outils graphiques 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 en ligne de commande. La configuration des dossiers de superposition est également prise en charge par les outils suivants :
  • XBOX Manager
  • XBOX Device Portal
  • Developer Home (Dev Home)
  • API XBOX Tools Framework

​
Fonctionnement et diagnostic transparents

​
Indicateur visuel

Il est facile de définir un dossier de superposition puis de l’oublier. Une fois qu’un dossier de superposition est 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 indiqués.

​
Configuration des dossiers de superposition

​
Configuration d’un dossier de superposition en ligne de commande

Comme indiqué dans la section précédente de cette rubrique, le dossier de superposition d’un nom complet de package spécifié 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 recherche E:\Overlay dans le System OS et ne le trouve pas. Cela est dû à la manière 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, suivez les conseils ci-dessous.
  • Vous pouvez partager le dossier de superposition via 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 via xbcred add FQDN_PC_NAME\shared_overlay FQDN\USER_NAME PASSWORD
    • REMARQUE : utilisez le nom de domaine complet (FQDN) chaque fois que vous faites référence à ce chemin afin d’éviter les problèmes de résolution de noms.
  • Vous pouvez utiliser Run-from-PC via XBTPLink, avec xbtp:\FQDN\Q:\overlay
    • Exemple : xbapp.exe overlayfolder bo5-dev_1.0.0.0_neutral__ht1qfjb0gaftw Q:\overlay
    • REMARQUE : vous devez 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 était nécessaire d’utiliser xbtp:\FQDN_PC_NAME\ pour construire le chemin xbtp vers le dossier de superposition. Ce n’est plus nécessaire : spécifiez simplement le chemin du dossier réseau.
  • Vous pouvez utiliser D:\ dans le System OS, en copiant le ou les fichiers via 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 n° 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 première ou la deuxième option.

​
Impact des dossiers de superposition sur les performances

Les dossiers de superposition ajoutent un léger coût à chaque ouverture de fichier. Ce coût est bien moindre si la superposition est configurée pour un emplacement du System OS (option n° 3 de la section précédente). En effet, chaque ouverture d’un fichier du titre sur G:\ déclenche 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 concerné dispose ou non d’une superposition. Si le dossier de superposition se trouve sur le PC de développement, l’impact sur les performances doit être considéré comme comparable à celui de l’exécution d’un titre via Run From PC. À chaque lecture de fichier, le dossier de superposition est vérifié pour déterminer s’il contient un fichier qui doit être lu à la place et, si c’est le cas, ce fichier est transféré du PC de développement vers le kit de développement. Il est recommandé d’utiliser un dossier de superposition dans le System Scratch du kit de développement pour éviter ce coût lors de l’utilisation de dossiers de superposition pour les déploiements de dossiers et les 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 est donc nécessaire pour appliquer une nouvelle superposition. Pour préparer cela à l’avance, vous pouvez définir un dossier vide comme superposition pour votre titre et y ajouter des fichiers ultérieurement. Ce dossier de superposition vide entraîne tout de même la légère surcharge de performances décrite dans la section précédente.

​
Utilisation des dossiers de superposition avec les installations de packages limitées au bloc de lancement

Les dossiers de superposition prennent en charge la superposition de fichiers sur une installation de package limitée au bloc de lancement, dans laquelle seule une partie du package est installée. Dans ce scénario, xbapp install doit être exécuté avec l’indicateur /W. /W est nécessaire pour toute installation dans laquelle le package peut demander des blocs supplémentaires une fois la commande ‘xbapp install’ initiale terminée. Dans ce cas, les blocs qui suivent le bloc de lancement seront demandés au lancement du titre.

​
Considérations relatives à la 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 exécuté sur le PC de développement autorise uniquement la console à récupérer des fichiers à partir des dossiers locaux qui ont été 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 tous les scénarios où le dossier de superposition se trouve en dehors du kit de développement.

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

Lorsque vous accédez à un dossier de superposition situé sur un partage réseau, vous devez vous assurer que des informations d’identification d’utilisateur disposant de l’autorisation d’accéder au partage réseau sont inscrites sur le kit de développement. Pour ce faire, vous pouvez utiliser la commande xbCred ou les fonctionnalités équivalentes de XBOX Manager et XBOX Device Portal.

​
Voir aussi

Dernière modification le 6 octobre 2026