Utiliser le GDK avec Unity

​

Vue d’ensemble

Cet article explique comment bien démarrer avec Unity lorsque vous intégrez des composants du Microsoft Game Development Kit (GDK) dans votre projet. Il présente les différents types de packages Unity, vous montre comment les configurer et décrit les fonctionnalités incluses dans chaque package. Les derniers packages Microsoft GDK pour Unity, codéveloppés par Microsoft et Unity, offrent la possibilité de cibler Windows x64 ainsi que les consoles XBOX Series X|S et XBOX One avec la même configuration et la même base de code.

​

Prérequis

Pour utiliser les packages du GDK pour Unity, vous avez besoin des prérequis suivants :

• Unity Editor version 2021.3 ou ultérieure
• Visual Studio 2019 (16.9) ou version ultérieure
• Windows SDK (22000 ou version ultérieure)
• Windows 10 (1809 ou version ultérieure) ou Windows 11
• GDK d’octobre 2023 Update 4 ou version ultérieure
• Licence Unity valide si vous ciblez les consoles XBOX

Pour plus d’informations sur la configuration requise des packages, consultez le document sur la configuration requise et l’installation de Unity.

​

Packages du GDK pour Unity

Unity distribue plusieurs packages du GDK. Chaque package ajoute des fonctionnalités spécifiques à votre projet et à l’Unity Editor. Vous trouverez les packages GDK pour Unity et plus de détails sur le portail de téléchargement de Unity. Vous devez faire partie d’un programme de développeurs XBOX, comme ID@XBOX, pour accéder aux packages GDK pour console XBOX. Demandez l’accès au site Unity XBOX Discussions à votre représentant Microsoft. Les packages nécessaires pour commencer le développement PC sont disponibles publiquement sur Microsoft GDK Package Releases. Voici la liste complète des packages.

• Package Microsoft GDK API pour Unity (PC et console)
• Package Microsoft GDK Tools pour Unity (PC et console)
• Package Microsoft GDK Tools for XBOX pour Unity (console uniquement)
• Package GXDK Input System pour Unity (console uniquement)
• Package Game Core Render Pipeline pour Unity (console uniquement)

Le package Microsoft GDK API pour Unity fournit des wrappers C# pour les API natives qui s’exécutent sur PC, XBOX Series X|S et XBOX One. Le package donne accès aux services réseau XBOX, notamment les succès, les sauvegardes dans le cloud et les classements. Le package Microsoft GDK Tools pour Unity fournit l’intégration nécessaire aux workflows de développement dans Unity pour créer un fichier Microsoft Game Configuration et empaqueter votre jeu PC avec le GDK en vue de sa soumission au Microsoft Store. Le package Microsoft GDK Tools for XBOX pour Unity étend le package GDK Tools avec une intégration des workflows de développement pour les consoles XBOX Series X|S et XBOX One, notamment l’empaquetage de votre jeu GDK pour console en vue de sa soumission au Microsoft Store. Le package GXDK Input System pour Unity fournit des fonctionnalités propres à la console au système d’entrée Unity (Input System) lorsque vous ciblez les consoles XBOX Series X|S ou XBOX One. Le package Game Core Render Pipeline pour Unity fournit des fonctionnalités propres à la console pour utiliser les Scriptable Render Pipelines (SRP) de Unity, comme l’Universal Render Pipeline (URP) ou le High Definition Render Pipeline (HDRP), sur les consoles XBOX Series X|S ou XBOX One.

​

Modules complémentaires de l’Unity Editor pour console

Installez les modules complémentaires de l’éditeur fournis par Unity. Ils activent les profils de build et les paramètres de projet nécessaires pour configurer, générer, déployer et lancer votre jeu sur les consoles XBOX Series X|S et XBOX One directement dans l’Unity Editor. Ces modules complémentaires sont des programmes d’installation .exe qui ajoutent des fonctionnalités à chaque éditeur. Vous devez les installer sur chaque machine qui utilise l’Unity Editor pour débloquer ces fonctionnalités. Une fois les modules complémentaires installés, la version associée de l’Unity Editor dans l’onglet Installs de l’Unity Hub les répertorie comme fonctionnalités prises en charge. Tous les projets utilisant cette version de l’Unity Editor peuvent alors activer les paramètres de projet et les profils de build GDK pour XBOX Series X|S et XBOX One. La capture d’écran suivante montre la version Unity 6 de l’Unity Editor avec les deux modules complémentaires installés. Figure 1. Version Unity 6 de l’Unity Editor avec les deux modules complémentaires installés.

​

Compatibilité des packages, des modules complémentaires, du GDK et du moteur

Obtenez les packages Microsoft GDK API et Tools pour Unity depuis le Unity Registry via le Package Manager de l’Unity Editor. La version affichée correspond à la version active de l’Unity Editor lorsque vous utilisez Unity 2021.3.47f1, 2022.3.55f1, 6000.0.31f1 ou une version ultérieure. Pour plus de détails sur la compatibilité entre le GDK et les versions du moteur pour chaque version du package GDK API pour Unity, consultez la documentation sur Microsoft GDK Package Releases. Ces packages prennent en charge le GDK obtenu depuis GitHub et le GDK obtenu depuis le portail XBOX Developer Downloads. Obtenez le package Microsoft GDK Tools for XBOX pour Unity via un lien de téléchargement direct sur le site Unity XBOX Discussions. Ce package est compatible avec les versions 2021.3.45f1, 2022.3.49f1, 6000.0.22f1 ou ultérieures de l’Unity Editor. Pour plus d’informations sur la configuration requise de ce package, consultez ce billet du forum Unity XBOX. Ce package est pris en charge uniquement avec le GDK téléchargé depuis le portail XBOX Developer Downloads. Ce package apparaît dans l’Unity Editor uniquement lorsque vous installez les modules complémentaires XBOX Series X|S et XBOX One pour l’Unity Editor. Obtenez le package GXDK Input System pour Unity via un lien de téléchargement direct sur le site Unity XBOX Discussions. Pour plus d’informations sur la configuration requise de ce package, consultez ce billet Unity XBOX Discussions. Ce package est pris en charge uniquement avec le GDK téléchargé depuis le portail XBOX Developer Downloads. Ce package nécessite que les modules complémentaires XBOX Series X|S et XBOX One pour l’Unity Editor soient installés pour apparaître dans l’Unity Editor. Obtenez le package Game Core Render Pipeline pour Unity via un lien de téléchargement direct sur le site Unity XBOX Discussions. Pour plus d’informations sur la configuration requise de ce package, consultez ce billet Unity XBOX Discussions. Ce package est pris en charge uniquement avec le GDK téléchargé depuis le portail XBOX Developer Downloads. Ce package nécessite que les modules complémentaires XBOX Series X|S et XBOX One pour l’Unity Editor soient installés pour apparaître dans l’Unity Editor. Obtenez les modules complémentaires XBOX Series X|S et XBOX One pour l’Unity Editor via un lien de téléchargement direct sur le site Unity XBOX Discussions. Pour plus d’informations sur la configuration requise de ces modules complémentaires, consultez ce billet Unity XBOX Discussions. Ces modules complémentaires sont pris en charge uniquement avec le GDK téléchargé depuis le portail XBOX Developer Downloads.

​

Intégrer les packages à votre projet

Pour bien démarrer avec les packages Microsoft GDK API et Tools pour Unity, procédez comme suit.

1. Sélectionnez le bouton Start, puis sélectionnez Package Manager.
2. Sélectionnez l’option Unity Registry dans la colonne de droite.
3. Dans la zone Search, entrez gdk, puis attendez que la liste soit actualisée.
4. Sélectionnez le package Microsoft GDK API, puis sélectionnez Install.
5. Une fois l’installation terminée, sélectionnez le package Microsoft GDK Tools, puis sélectionnez Install.
6. Fermez le Package Manager une fois les deux packages installés.

Voici un aperçu de la recherche des packages dans le Unity Registry dans Unity 6. Figure 2. Aperçu de la recherche des packages dans le Unity Registry dans Unity 6. Les packages propres à la console XBOX s’obtiennent depuis le portail de téléchargement Unity XBOX Discussions. Ajoutez ces packages localement au projet.

1. Sélectionnez le bouton Start, puis sélectionnez Package Manager.
2. Sélectionnez +, puis sélectionnez Add package from tarball.
3. Accédez au package téléchargé portant l’extension .tgz.
4. Sélectionnez-le, puis installez-le dans votre projet.

Figure 3. Packages installés localement dans un projet dans Unity 6. Les packages Unity sont associés à votre projet Unity. Lorsque vous créez un nouveau projet Unity, vous devez récupérer et réinstaller ces packages pour ce projet. Si vous ouvrez un projet Unity qui inclut déjà ces packages, vous n’avez pas besoin de les télécharger à nouveau depuis le registre pour utiliser leurs fonctionnalités.

​

Configurer votre projet pour qu’il prenne en charge le GDK

Cette section couvre l’intégration initiale de votre projet pour qu’il prenne en charge le GDK.

​

Créer une ressource de paramètres GDK

Une fois les packages Microsoft GDK API et Tools pour Unity installés dans votre projet, vous disposez d’options de menu supplémentaires. L’une d’elles est un ensemble de ressources propres au GDK, que vous utilisez pour générer une ressource GDK Settings. Cette étape ajoute à vos paramètres de projet (Project Settings) des paramètres propres au GDK qui vous permettent de configurer votre produit GDK directement dans Unity. Pour plus d’informations sur la gestion de vos paramètres GDK dans Unity, consultez GDK Settings. Exemple de création d’une ressource GDK Settings dans Unity 6. Figure 4. Création d’une ressource GDK Settings dans Unity 6. Si vous installez le package GDK Tools for XBOX et les modules complémentaires XBOX, les paramètres GDK comportent plusieurs onglets, un pour chaque plateforme. Vous pouvez créer à partir de ceux-ci des paramètres et des fichiers .config propres à chaque plateforme. Votre projet peut contenir plusieurs ressources GDK Settings, mais une seule ressource peut être active à la fois. L’exemple suivant montre la création de paramètres GDK pour XBOX Series X|S et XBOX One dans Unity 6. Figure 5. Création de paramètres GDK pour XBOX Series X|S et XBOX One dans Unity 6.

​

Créer une ressource Microsoft Game Config

Après avoir créé votre ressource GDK Settings, ajoutez une ressource Microsoft Game Config à votre projet. Cette étape génère les fichiers nécessaires pour configurer votre projet afin qu’il fonctionne avec les fonctionnalités et capacités propres au GDK. Pour plus d’informations sur la gestion de votre fichier Microsoft Game Configuration dans Unity, consultez Microsoft Game Configuration file. L’exemple suivant montre la création d’une ressource Microsoft Game Config dans Unity 6. Figure 6. Création d’une ressource Microsoft Game Config dans Unity 6.

​

Associer votre Microsoft Game Config à votre ressource GDK

Après avoir créé votre Microsoft Game Config, ouvrez les GDK Project Settings et associez votre Microsoft Game Config au projet. Cette étape garantit que le fichier .config est utilisé pour cette plateforme lors des étapes de génération et d’empaquetage. L’exemple suivant montre l’association de votre Microsoft Game Config dans Unity 6. Figure 7. Association de votre Microsoft Game Config dans Unity 6.

​

Modifier votre ressource Microsoft Game Config

Le package GDK Tools s’intègre à l’Unity Editor, ce qui vous permet d’afficher et de mettre à jour la ressource Microsoft Game Config directement dans Unity. Lorsque vous sélectionnez cette ressource dans la fenêtre Project, ses paramètres GDK configurables apparaissent dans l’Inspector. Pour plus d’informations sur la gestion de votre fichier Microsoft Game Config dans Unity, consultez Microsoft Game Configuration file. L’exemple suivant montre la modification de votre fichier Microsoft Game Config dans Unity 6 : Figure 8. Modification de votre Microsoft Game Config dans Unity 6.

​

Associer votre jeu GDK à votre produit Microsoft Partner Center

Dans le cadre de l’intégration du package GDK Tools, le Microsoft Game Config Editor vous permet d’utiliser un Assistant intégré pour associer votre jeu GDK à votre produit Partner Center. Connectez-vous avec un compte Microsoft autorisé à accéder au produit Partner Center auquel vous souhaitez associer votre jeu GDK. Une fois votre projet correctement associé à Partner Center, l’Assistant indique les valeurs qu’il mappe automatiquement depuis Partner Center vers la ressource Microsoft Game Config de votre projet. Pour plus d’informations sur la création de votre produit dans Partner Center et l’accès aux fonctionnalités des XBOX services, consultez Setting up an app or game at Partner Center, for Managed Partners. L’exemple suivant montre le démarrage de l’Assistant Store Association dans Unity 6. Figure 9. Démarrage de l’Assistant Store Association dans Unity 6.

​

Utiliser les wrappers C# pour accéder aux API

Le package Microsoft GDK API pour Unity fournit un ensemble de wrappers C# pour les API natives du GDK. Utilisez ces wrappers pour accéder directement aux API du GDK dans votre projet Unity. Pour plus d’informations sur l’accès aux API du GDK, consultez Utilisation des wrappers C# pour les API du GDK dans votre projet Unity. L’exemple suivant montre les wrappers C# du package Microsoft GDK API pour Unity dans la fenêtre Packages. Figure 10. Wrappers C# du package Microsoft GDK API pour Unity dans la fenêtre Packages.

​

Utilisation de Visual Studio et Unity

Visual Studio propose une charge de travail Jeux, dans le cadre de Visual Studio Installer, pour une intégration directe avec Unity. Pour plus d’informations sur l’extension Visual Studio Tools pour Unity, consultez Démarrage rapide : configurer Visual Studio pour le développement multiplateforme avec Unity.

​

Utilisation des exemples

Trois ensembles d’exemples Unity sont disponibles comme référence de code lorsque vous générez votre projet.

​

Exemples du Unity Registry

Le premier ensemble d’exemples est fourni avec le package Microsoft GDK API pour Unity. Après avoir téléchargé le package, ces exemples se trouvent dans l’onglet Samples de l’entrée Microsoft GDK API dans le Unity Registry. Cette image montre où les exemples apparaissent dans l’Unity Editor. Figure 11. Onglet Samples de l’entrée Microsoft GDK API dans le Unity Registry après le téléchargement. Ces exemples illustrent des interactions de base avec des systèmes comme les succès, les sauvegardes dans le cloud, les sauvegardes de jeu, le comportement du magasin dans le jeu, les classements, la connexion, le synthétiseur vocal et le comportement des utilisateurs. Pour plus d’informations sur ces exemples, consultez Samples overview.

​

Exemples Unity du GDK

En plus des exemples fournis par le Unity Registry, le téléchargement du GDK inclut un ensemble d’exemples. Ils illustrent une utilisation plus avancée des API et sont les suivants.

• UnityAchievements : illustre l’utilisation des API XblAchievement pour interroger et mettre à jour la progression des succès.
• UnityInGameStore : une expérience complète de magasin dans le jeu que vous pouvez configurer pour qu’elle s’exécute comme n’importe quel jeu. Il illustre la plupart des API XStore pour interroger les offres du catalogue, les droits des utilisateurs et les produits sous licence.
• UnityLeaderboardsTitleManaged : illustre l’utilisation des classements gérés par le titre pour mettre à jour et interroger les statistiques des utilisateurs, et pour interroger les classements sociaux et globaux.
• UnitySimpleMPSD : un exemple de session multijoueur de base qui utilise les API Multiplayer Session Directory (MPSD) et SmartMatch pour la gestion des sessions et le matchmaking.
• UnityRumble : un jeu multijoueur simple qui utilise Multiplayer Manager (MPM) et Microsoft Azure PlayFab Party pour créer et rejoindre des sessions multijoueurs, effectuer le matchmaking et les quitter. Il met à jour l’état de session, partage les données de jeu et communique par chat.
• UnityRumblePlayFabMultiplayer : semblable à UnityRumble, mais utilise Microsoft Azure PlayFab Multiplayer pour la gestion des sessions et le matchmaking au lieu de MPM.
• UnitySimpleHttpCall : illustre l’utilisation des appels HTTP réseau XBOX pour envoyer et recevoir des messages sous forme de chaîne ou de tableau d’octets.
• UnitySimpleWebSockets : illustre l’utilisation des Web Sockets HTTP Client pour envoyer et recevoir des messages binaires ou de type chaîne vers un point de terminaison Web Socket préconfiguré.
• UnitySimplePLM : un exemple de base qui montre comment détecter les événements de gestion de la durée de vie des processus (PLM) et y répondre.
• UnityAssetWorkflow (XBOX uniquement) : illustre l’utilisation des ressources de la console XBOX et des API d’outillage pour faciliter l’itération rapide sur les ressources du jeu.

Vous pouvez consulter et obtenir ces exemples sur le GitHub XBOX GDK Samples. En plus de ces exemples, trois exemples privés (UnityRumble, UnityRumblePlayFabMultiplayer et UnityAssetWorkflow) sont disponibles sur le portail XBOX Developer Downloads. Voici un exemple du nom de l’exemple dans la liste des builds sous le type de fichier GDK du portail de téléchargement. Figure 12. Nom de l’exemple dans la liste des builds sous le type de fichier GDK du portail de téléchargement.

​

Exemple Unity HandheldBestPractices

L’exemple Unity HandheldBestPractices fournit des bonnes pratiques et des exemples de code C# managé que vous pouvez intégrer à vos jeux Unity lorsque vous générez pour des appareils portables Windows, comme le ROG XBOX Ally. Vous pouvez obtenir cet exemple sur le site GitHub Unity Handheld Best Practices Sample.

​

Générer et empaqueter votre projet

Cette section décrit comment générer et empaqueter votre projet dans Unity.

​

Paramètres de localisation et d’empaquetage

Dans le cadre de vos paramètres GDK pour la plateforme Windows, indiquez si Unity génère les éléments visuels du shell, inclut les ressources localisées et crée un package pendant le processus de génération. Vous n’avez pas besoin de configurer de paramètres Build Profiles spécifiques pour l’empaquetage Windows. Pour plus d’informations sur les paramètres d’empaquetage, consultez Package creation settings and encryption methods. L’image suivante montre un exemple de définition de ces valeurs de paramètres GDK dans Unity 6. Figure 13. Définition des valeurs des paramètres GDK dans Unity 6. Pour la console, votre projet inclut le package Microsoft GDK Tools for XBOX. Définissez Shell Visuals Mode sur Copy Only. Ce paramètre garantit que les images du Microsoft Store sont copiées dans le dossier de build avant l’empaquetage, afin que vous n’ayez pas à les copier vous-même. Pour définir la méthode de chiffrement du package pour la console, sélectionnez Project Settings > Player > Publisher Settings. Les cibles XBOX incluent un paramètre Package Encryption. Utilisez l’option Development lorsque vous générez un package que vous souhaitez charger de manière indépendante (sideload) pour des tests locaux (avec Build and Deploy ou xbapp install). Utilisez Submission pour les packages que vous chargez dans Partner Center puis installez depuis le Microsoft Store. Unity configure la génération des packages pour console dans la page Build Profiles. Remplacez la plateforme cible par XBOX One ou XBOX Series, selon l’appareil pour lequel vous prévoyez de générer. Pour créer un package local que vous pouvez charger de manière indépendante, définissez Build Type sur Development player. Pour produire un package à charger dans Partner Center, définissez Build Type sur Master player. Définissez ensuite Deploy Method sur Package. Pour un package console chargeable de manière indépendante et généré avec le chiffrement Development, vous pouvez utiliser l’option Build and Run pour le déployer sur votre console. Cette option crée un build sous forme de dossier libre (loose), exécute makepkg.exe avec une signature de test, puis installe et lance le package sur votre kit de développement par défaut. Un package généré avec le chiffrement Submission ne peut pas être chargé de manière indépendante. Il doit être chargé dans Partner Center, puis installé depuis le Microsoft Store.

​

Profils de build

Chaque plateforme cible possède son propre profil de build. Windows lit le fichier GDK Settings et génère un package MSIXVC dans le dossier MSIXVC à la fin de la génération, si les paramètres GDK Windows spécifient un package. Pour plus d’informations sur les profils de build, consultez Build an application with the Microsoft GDK API package. Pour les plateformes console, vous spécifiez les paramètres de déploiement, y compris l’empaquetage, dans les paramètres de build propres à la plateforme. Ces paramètres incluent également des options supplémentaires de génération, de déploiement et de débogage. À la fin de la génération, le répertoire de sortie contient un package XVC dans un dossier XVC. Cet exemple montre les profils de build de chaque plateforme dans Unity 6. Figure 14. Affichage des profils de build de chaque plateforme dans Unity 6.

​

Tester votre projet en Play Mode

Pour garantir le bon fonctionnement des projets basés sur le GDK en Play Mode, vous devez suivre des étapes et considérations supplémentaires. Pour plus d’informations sur les étapes nécessaires pour utiliser correctement le Play Mode, consultez Test your project in Play mode.

​

Tester votre jeu à distance avec XBOX PC Remote Tools

Les XBOX PC Remote Tools vous permettent de déployer et de lancer votre build Windows sur un appareil cible distant directement depuis l’Unity Editor, sans générer de projet Visual Studio. Installez XBOX PC Toolbox sur votre machine de développement et sur l’appareil cible, puis associez-les. Vous pouvez ensuite sélectionner XBOX PC Remote Tools dans la liste déroulante Build and Run on de votre profil de build Windows. Unity génère, déploie et exécute alors votre jeu sur l’appareil associé, ce qui permet une itération plus rapide lorsque vous testez des builds sur du matériel représentatif. Pour les étapes de configuration et plus d’informations, consultez Deploy a Windows application with the XBOX PC Remote Tools.

​

Informations supplémentaires

​

Utilisation de PlayFab avec Unity

Pour plus d’informations sur l’utilisation de PlayFab, qui inclut une intégration directe et des packages pour travailler dans Unity, consultez le SDK Unity3D (C#) pour PlayFab.

​

Détection des appareils portables Windows

Depuis juillet 2025, Unity permet de détecter si un appareil est un appareil portable Windows. Cette fonctionnalité a été ajoutée à SystemInfo.deviceType dans le moteur Unity et incluse dans les versions suivantes.

• Unity 6000.2.0b10
• Unity 6000.1.12f1
• Unity 6000.0.54f1

​

Obtenir de l’aide

Pour obtenir de l’aide sur tout problème, consultez Unity XBOX Discussions. Si vous ne faites pas partie du programme XBOX Developers et que vous utilisez les packages publics pour le développement Windows, utilisez Unity Windows Discussions. Si vous avez besoin d’aide concernant des articles propres au GDK qui ne sont pas spécifiques à l’intégration Unity, publiez votre demande sur les forums XBOX GDK.

​

Problèmes connus

Pour obtenir la liste des problèmes connus liés au package GDK API pour Unity, consultez GDK API package for Unity: Issues and limitations. Pour obtenir la liste des problèmes connus liés au package GDK Tools pour Unity, consultez Microsoft GDK Tools package: Issues and limitations.

​

Utilisation de versions antérieures de Unity

Les packages Microsoft GDK API et Tools prennent en charge Unity 2021.3 et les versions ultérieures de l’Unity Editor. Utilisez une version prise en charge pour bénéficier d’outils intégrés, de la prise en charge complète des fonctionnalités et de capacités fiables de génération et d’exécution sur toutes les plateformes. Si vous utilisez une version antérieure de Unity, vous pouvez référencer les wrappers C# fournis dans le package GDK API pour créer vos propres interfaces propres au projet avec les API natives du GDK. Vous pouvez également utiliser l’Unity Editor pour créer le fichier MicrosoftGame.config, configurer la localisation, configurer les éléments visuels du shell et empaqueter votre jeu. Ces processus sont manuels et n’offrent pas d’intégration directe à l’Unity Editor. Si vous ne pouvez pas mettre à niveau votre version de l’Unity Editor et avez besoin de plus de conseils sur les options disponibles, contactez votre représentant Microsoft.

​

Packages dépréciés

Microsoft ne distribue plus le GDK Unity Package (PC Only) sur GitHub. Ce package est déprécié. Les développeurs Unity utilisent désormais les packages Microsoft GDK API et Tools pour Unity. Si vous avez des questions sur le GDK Unity Package (PC Only), contactez votre représentant Microsoft. Si vous utilisez l’ancien GDK Unity Package (PC Only) et avez besoin des étapes de migration, consultez le guide de mise à niveau. Pour plus d’informations sur les packages fournis par Unity qui sont désormais dépréciés, consultez les forums Unity XBOX.