Unity 玩法开发（第一人称 / Unity 6 / URP）

Compétence de Développement de Gameplay Unity (Première Personne / Unity 6 / URP)

Convention de Chemin (lisez ceci d'abord) : Tous les chemins scripts/, references/, assets/ dans ce fichier sont relatifs au répertoire contenant ce SKILL.md. Avant d'exécuter un script, localisez ce répertoire. Le chemin d'installation varie selon l'hôte : Claude Code installe le plugin dans son répertoire de plugins ; Cursor/Codex utilisent install.ps1 pour le placer dans <projet>/skills/game-dev/<nom_compétence>/. En cas de doute, utilisez glob pour trouver le chemin absolu de ce SKILL.md, puis appelez les scripts avec ce chemin absolu. Exécuter python scripts/xxx.py depuis la racine du projet échouera avec une erreur fichier non trouvé.

Aperçu

Cette compétence transforme les spécifications GDD et les assets 3D en fonctionnalités de jeu jouables : créer/modifier des scripts, attacher des composants, configurer des animations et de l'UI, entrer en mode Play pour valider, exécuter des tests et générer une build dans Unity via MCP. Stack technique par défaut : Unity 6 (6000.x LTS, compatible avec 6000.3), URP, UGUI, nouveau Input System, Cinemachine 3 (optionnel), jeu solo, sans multijoueur.

Périmètre

• Fait : Logique de gameplay, contrôleurs, interaction, UI, inventaire/dialogue/sauvegarde, IA, audio, tests, build et identification des problèmes de performance.
• Ne fait pas : Création/import d'assets 3D / matières (confié à la compétence unity-blender-mcp) ; multijoueur (Netcode) ; écriture manuelle de Shaders (seulement des suggestions de sélection d'effets).
• Le projet cible utilise la première personne ; pour la troisième personne / vue de dessus, on utilise la même architecture (machine d'états, entrée, interaction, UI inchangés), seuls le contrôleur et la caméra diffèrent, voir references/02.
• Projet 2D : La couche d'architecture (machine d'états / bus d'événements / sauvegarde / inventaire / pile d'UI) est réutilisable, mais le contrôle du personnage, la physique, la navigation et le budget de performance doivent être changés, voir references/11-2d-gameplay.md. N'utilisez pas CharacterController + NavMesh 3D pour la 2D.

Prérequis Environnement

• Unity 6000.x (6000.0 LTS supporté jusqu'en octobre 2026, puis mise à jour vers 6000.3 LTS ; le code est compatible avec les deux).
• Paquets obligatoires : com.unity.inputsystem (nouveau Input System), com.unity.ugui (UGUI), com.unity.ai.navigation (baking NavMesh), com.unity.test-framework (tests, le script de génération les ajoute automatiquement avec --tests) ; optionnels : com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• Installer les paquets via MCP manage_packages, ou le script de génération écrit automatiquement le manifest (Input System / UGUI / test framework, version résolue via la table de régression du versionnage interne de l'éditeur) ; après installation, Project Settings → Active Input Handling doit être réglé sur Both (le script de génération écrit activeInputHandler: 2).
• Vérification de version : ProjectSettings/ProjectVersion.txt dans le projet ; en cas de doute sur l'API, utilisez unity_docs / unity_reflect, il est interdit d'écrire des API non familières de mémoire.

Flux de Travail Standard (du GDD à la Fonctionnalité Jouable)

Procédure A : Nouveau Projet / Nouveau Projet à Partir de Zéro

1. Confirmer la version et le pipeline : manage_editor pour lire la version de l'éditeur ; projet URP ou Built-in (matériaux et post-processing différents).
2. Exécuter le script de génération : python scripts/new_gameplay.py --out "<projet>/Assets/Game" --namespace <nom_du_jeu>, génère le code du framework, l'asmdef, l'assembly de test, et ajoute automatiquement la dépendance Input System ; ouvrez Unity une fois pour que les paquets se téléchargent, puis réexécutez-le pour remplir les GUID asmdef.
   • ⚠️ Les premières erreurs de compilation CS0234/CS0246 (UnityEngine.InputSystem introuvable) sont attendues, ce n'est pas un problème du générateur : le nouveau projet n'a pas encore téléchargé les paquets et ne trouve pas le GUID asmdef d'InputSystem. Ouvrez Unity une fois → les paquets se téléchargent → réexécutez le générateur → les GUID sont remplis → compilation zéro erreur.
   • Testé sur Unity 6000.0.84f1 : après réexécution, compilation zéro erreur, InventoryTests 3/3 réussis.
3. Mettre en place les objets guides de scène : Suivez references/01 pour créer la scène de démarrage (GameManager, AudioManager, UIManager, EventSystem, Canvas), en utilisant manage_gameobject / manage_components.
4. Implémenter dans l'ordre fonctionnel : Entrée → Contrôleur première personne → Interaction → HUD → Systèmes de gameplay spécifiques → IA → Audio/VFX (ordre détaillé ci-dessous dans « Ordre de développement des fonctionnalités »).
5. Valider fonction par fonction : Après chaque fonction, test manuel en mode Play + écrire des tests EditMode/PlayMode, voir le cycle de validation dans references/00.
6. Navigation/Baking/Build : Baking NavMesh, ajout des scènes à la Build, liste de vérification avant build, voir references/08, references/09.

Procédure B : Développement d'une Fonction Individuelle (le plus courant)

Lire la page GDD correspondante (spécifications personnage/interaction/système/dialogue/animation) → Lister les scripts et composants à modifier → Choisir un template ou créer → Suivre le cycle d'édition MCP pour implémenter → Valider en mode Play → Ajouter des tests → Mettre à jour la définition de fonctionnalité terminée (DoD).

Procédure C : Dépannage et Optimisation

Erreurs de compilation/runtime → voir references/10 ; chutes de fps/lag → suivre la procédure Profiler dans references/08 ; échec d'opération MCP → suivre le plan de secours dans references/00.

Cycle d'Édition MCP (à respecter à chaque modification de code)

1. refresh_unity pour synchroniser d'abord le disque ; read_console pour confirmer qu'il n'y a pas d'erreur initiale.
2. Créer un script : create_script ; Modifier un script : privilégier script_apply_edits (édition structurée au niveau méthode), utiliser apply_text_edits uniquement pour les petites modifications ; après modification, validate_script.
3. refresh_unity déclenche la compilation → read_console pour voir le résultat de la compilation (corriger immédiatement toute erreur CS, ne pas continuer avec des erreurs).
4. Attacher composants/références : manage_components / manage_gameobject ; animation avec manage_animation ; UI avec manage_gameobject (UI Toolkit uniquement manage_ui).
5. Valider en mode Play : manage_editor pour passer en playmode, read_console pour vérifier les exceptions runtime ; perspective/ressenti avec find_gameobjects pour lire l'état Transform, si nécessaire execute_code pour prendre une capture d'écran de la Game View.
6. Regrouper les opérations non conflictuelles dans batch_execute ; sauvegarder la scène avec manage_scene à la fin de chaque fonctionnalité.

Ordre de Développement des Fonctionnalités (après le script de génération)

1. Entrée InputReader (généré par le script) → Attacher au Player dans la scène, WASD/souris le fait bouger
2. Première personne PlayerLook + FirstPersonController (marcher, courir, sauter, s'accroupir, atterrir)
   - Projet 2D : utiliser `PlatformerController2D` (généré automatiquement avec `--dimension 2d`, les fichiers 3D dédiés ne sont pas générés)
3. Interaction Interactor + Porte/Objet ramassable (UI de visée connectée)
4. HUD + Pile de panneaux de menu (UIManager, ESC pour pause)
5. Systèmes de gameplay : Health/Inventaire/Dialogue (selon le GDD)
6. Sauvegarde SaveSystem (intégrer les systèmes existants avec ISaveable)
7. IA ennemie : Baking NavMesh + EnemyAI + Perception
8. Audio AudioManager + Mixeur ; VFX (particules, bouche de canon, impacts)
9. Performance Profiler pour fixer le framerate ; Build de l'application (references/08, 09)

Script de Génération et Templates

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests : ne pas générer d'assembly de test
#   --editor-data "Chemin Editor/Data" : analyser la version d'Input System (si non fourni, utilise la table de régression)

Liste des templates (dans assets/templates/). Attention : les templates contiennent le placeholder de namespace {{NS}} ; si vous les copiez manuellement, remplacez-les d'abord, ou mieux, exécutez new_gameplay.py pour générer automatiquement, sinon ils ne compileront pas :

Module	Fichier	Usage
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	Singleton, machine d'états, bus d'événements, flux de jeu (menu/jeu/pause/chargement)
Input	InputReader	Encapsulation codée du nouveau Input System, clavier+souris+manette
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D : CharacterController déplacement, vue souris, courir/sauter/s'accroupir. 2D : Saut de plateforme Rigidbody2D (avec coyote time / jump buffer / hauteur de saut variable)
Interaction	InteractableBase / Interactor / PickupItem	Interaction au viseur, exemple de ramassage
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	Vie, inventaire, sauvegarde JSON, dialogue linéaire, pool d'objets, audio
IA	EnemyAI / EnemyPerception	Machine d'états patrouille/poursuite/attaque NavMesh + perception cône visuel
UI	UIPanel / UIManager / HUDController	Pile de panneaux, HUD barre de vie/infos/sous-titres
Tests	InventoryTests (+ asmdef)	Exemple de test logique d'inventaire, exécutable avec run_tests

Index des Documents de Référence (chargement à la demande)

• references/00-mcp-code-workflow.md : 47 outils MCP mappés aux tâches de gameplay, cycle d'édition, validation Play, tests, secours sans MCP
• references/01-architecture.md : Structure de répertoires, asmdef, conventions de nommage, pilotage par les données, limites d'utilisation des références/événements/singletons, ScriptableObject
• references/02-input-and-fp-controller.md : Mise en œuvre d'Input System, hiérarchie du prefab Player, table des paramètres de mouvement et de vue première personne, branches troisième personne/vue de dessus
• references/03-interaction-animation.md : Couche d'interaction, machine d'états Animator/Blend Tree/animation racine, événements d'animation, interface Humanoid
• references/04-ui-ugui.md : Mise en place Canvas/EventSystem, pile de panneaux, HUD, pause, changement d'entrée
• references/05-gameplay-systems.md : Normes d'utilisation et d'extension de la vie/inventaire/dialogue/sauvegarde/pool d'objets, définitions de données
• references/06-ai-navigation.md : Baking NavMesh, configuration des ennemis, points de patrouille, réglage des paramètres de perception, extension d'états
• references/07-audio-vfx.md : Groupes AudioMixer, pool audio, fondu musical, sélection particules/VFX Graph
• references/08-performance.md : Budget 60fps, procédure Profiler/Frame Debugger, points chauds courants
• references/09-build-release.md : Paramètres de build, liste des scènes, vérification Steam/Deck, compatibilité des sauvegardes
• references/10-troubleshooting.md : Tableau des erreurs courantes compilation/référence nulle/ordre d'exécution/entrée/navigation/UI
• references/11-2d-gameplay.md : À lire en premier pour un projet 2D. Installation des paquets 2D, import de sprites, Physics2D et matrices de couches, saut de plateforme 2D (coyote time/jump buffer), Tilemap et collision Composite, caméra pixel perfect, budget 2D basé sur l'overdraw et le nombre de Batch (le tableau du budget triangles n'a pas de sens pour la 2D).

Attention Projet 2D : Les templates C# de cette compétence sont par défaut en 3D première personne (CharacterController, NavMesh). Pour la 2D, réutilisez les parties indépendantes de la dimension (EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager), et réécrivez le contrôleur, la navigation, la physique et le budget de performance selon references/11.

Règles d'Or

• Les valeurs numériques viennent du GDD : Vitesse de déplacement, saut, dégâts, frames d'impact, distance de vision doivent être exposés dans l'Inspector et cohérents avec la page GDD ; si le GDD ne les définit pas, marquez 【À CONFIRMER】, il est interdit d'inventer des valeurs.
• Chaque étape doit être vérifiable : Après modification du code, compilation zéro erreur, test en mode Play ; pour les aspects de ressenti (déplacement/vue/interaction), il faut capturer des preuves d'état Transform, pas seulement dire « ça devrait marcher ».
• Interdiction de simuler la compilation : Si validate_script ou read_console n'est pas passé, la tâche n'est pas considérée comme terminée ; en cas d'impossibilité de vérification dans l'environnement actuel, déclarez-le clairement, ne fabriquez pas de résultat.
• Séparation des données et de la logique : Les valeurs ajustables utilisent SerializeField/ScriptableObject ; la couche de présentation s'abonne aux événements, ne les écrit pas dans les classes système.
• Conventions de nommage : Classes en PascalCase ; nom de fichier identique au nom de la classe principale ; scènes/prefabs Level_01_, PF_Player ; constantes sans caractères chinois ; les avertissements CS dans la Console doivent aussi être corrigés.
• Étapes petites et fréquentes : Une fonctionnalité, un commit ; sauvegarder/dupliquer la scène avant toute modification ; pour les opérations risquées (suppression, modification en masse de composants), lister d'abord les objets impactés.

Définition de Fonctionnalité Terminée (DoD)

• La logique implémentée est cohérente avec la page GDD, les valeurs sont traçables (les valeurs par défaut de l'industrie sont annotées)
• Compilation zéro erreur zéro avertissement (read_console capture/lecture comme preuve)
• Test en mode Play réussi : entrée, changement d'état, interaction, feedback reproductibles
• La logique testable unitairement a des tests (run_tests vert)
• Les références/composants/configurations de hiérarchie associés sont complets (le prefab fonctionne quand déposé dans une scène vide, sans nécessité de connexions manuelles temporaires)
• Les nouveaux champs de sauvegarde gèrent le numéro de version ; les nouvelles scènes sont ajoutées à la Build
• Aucun nouveau point chaud de performance (objectif 60fps, mobile/Steam Deck voir 08)