huayuehua15-netizen/unity-gameplay-dev

Unity Gameplay Development Skill (First-Person / Unity 6 / URP)

Path Convention (Read this first): All scripts/, references/, assets/ paths in this file are relative to the directory containing this SKILL.md. Before executing any script, navigate to that directory. Installation paths vary by host: Claude Code plugin places it under the plugin directory; Cursor/Codex installs it via install.ps1 to <Project>/skills/game-dev/<SkillName>/. If unsure, use glob to find the absolute path of this SKILL.md, then call scripts with absolute paths. Running python scripts/xxx.py directly from the project root will cause file-not-found.

Overview

This skill turns GDD specifications and 3D assets into playable game features: use MCP to create/modify scripts, attach components, configure animations and UI, enter Play mode to verify, run tests, and build the project. Default tech stack: Unity 6 (6000.x LTS, compatible with 6000.3), URP, UGUI, new Input System, Cinemachine 3 (optional), standalone game, no networking.

Boundaries

• Does: Gameplay logic, controllers, interaction, UI, inventory/dialogue/save, AI, audio, tests, builds, and performance profiling.
• Does not: 3D asset creation/import/materials (handled by the unity-blender-mcp skill); multiplayer networking (Netcode); hand-written shaders (only provides selection suggestions for effects).
• The target project uses first-person; third-person/top-down views reuse the same architecture (state machine, input, interaction, UI remain unchanged), only the controller and camera branches differ (see references/02).
• 2D Projects: The architecture layers (state machine/event bus/save/inventory/UI stack) can be reused, but character control, physics, navigation, and performance budgets must be replaced – see references/11-2d-gameplay.md. Do not use the 3D CharacterController + NavMesh for 2D.

Prerequisites

• Unity 6000.x (6000.0 LTS is supported until October 2026, then upgrade to 6000.3 LTS; code is compatible with both).
• Required packages: com.unity.inputsystem (new Input System), com.unity.ugui (UGUI), com.unity.ai.navigation (NavMesh baking), com.unity.test-framework (tests, scaffold auto-writes with --tests); optional: com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• Package installation: use MCP manage_packages, or let the scaffold auto-write the manifest (Input System / UGUI / test framework, versions resolved based on editor built-in and the fallback table); after installation, set Project Settings → Active Input Handling to Both (the scaffold writes activeInputHandler: 2).
• Version confirmation: check ProjectSettings/ProjectVersion.txt in the project; when unsure about APIs, use unity_docs / unity_reflect – never write unfamiliar APIs from memory.

Standard Workflow (From GDD to Playable Feature)

Flow A: New Project / New Project from Scratch

1. Confirm Version & Render Pipeline: Use manage_editor to read the editor version; determine if the project is URP or Built-in (materials and post-processing differ).
2. Run the Scaffold: Execute python scripts/new_gameplay.py --out "<Project>/Assets/Game" --namespace <GameName> to generate framework code, asmdef, test assemblies, and automatically add Input System dependencies; open Unity once to let packages download, then run the scaffold again to backfill asmdef GUIDs.
   • ⚠️ First build errors like CS0234/CS0246 (missing UnityEngine.InputSystem) are expected – not a scaffold failure: the new project hasn't downloaded the package yet, so InputSystem's asmdef GUID is unavailable. Open Unity once to let packages download → re-run the scaffold → GUIDs backfilled → second build compiles with zero errors.
   • Tested on Unity 6000.0.84f1: after re-running, compilation is error-free, InventoryTests 3/3 pass.
3. Set Up Scene Bootstrap Objects: Follow references/01 to create the startup scene (GameManager, AudioManager, UIManager, EventSystem, Canvas) using manage_gameobject / manage_components.
4. Implement Features in Order: Input → First-Person Controller → Interaction → HUD → Specific Gameplay Systems → AI → Audio/VFX (see "Feature Development Order" below).
5. Validate Feature by Feature: After completing each feature, manually test in Play mode and write EditMode/PlayMode tests (see the verification loop in references/00).
6. Navigation/Baking/Build: NavMesh baking, scene inclusion in Build, shipping checklist – see references/08, references/09.

Flow B: Individual Feature Development (Most Common)

Read the corresponding GDD page (character/interaction/system/dialogue/animation specs) → List scripts and components to modify → Select a template or create a new one → Follow the MCP edit loop → Implement → Play verify → Add tests → Update feature completion definition.

Flow C: Troubleshooting & Optimization

For compilation/runtime errors, check references/10; for frame drops/stuttering, follow the Profiler flow in references/08; for MCP operation failures, follow the fallback plan in references/00.

MCP Edit Loop (Follow for Every Code Change)

1. refresh_unity to sync disk first; read_console to confirm no errors at the starting point.
2. Create script: create_script; modify script: prefer script_apply_edits (structured method-level editing); use apply_text_edits only for small changes; after editing, run validate_script.
3. refresh_unity to trigger compilation → read_console to check build results (fix any CS errors immediately – do not continue with errors).
4. Attach components / wire references: manage_components / manage_gameobject; for animation: manage_animation; for UI: manage_gameobject (use manage_ui only for UI Toolkit).
5. Enter Play mode to verify: manage_editor to switch playmode, read_console to check runtime exceptions; confirm view/feel by reading Transform state via find_gameobjects; if necessary, use execute_code to capture Game View screenshots.
6. Merge multiple non-conflicting operations into batch_execute; save the scene via manage_scene before finishing each feature.

Feature Development Order (After Scaffolding)

1. Input InputReader (already generated by scaffold) → Attach to Player in scene, WASD/mouse functional
2. First-Person PlayerLook + FirstPersonController (walk, run, jump, crouch, land)
   - For 2D projects: use PlatformerController2D (auto-generated with --dimension 2d, 3D-specific files not generated)
3. Interaction Interactor + Door/Pickup (crosshair UI wired through)
4. HUD + Menu Panel Stack (UIManager, ESC pause)
5. Gameplay Systems: Health / Inventory / Dialogue (based on GDD trade-offs)
6. Save System (integrate completed systems into ISaveable)
7. Enemy AI: NavMesh baking + EnemyAI + Perception
8. Audio AudioManager + Mixer; VFX (particles/muzzle/hit)
9. Performance Profiler frame locking; Build package (references/08, 09)

Scaffold & Templates

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests: do not generate test assemblies
#   --editor-data "Editor/Data path": parse Input System version (if omitted, use version fallback table)

Template list (assets/templates/). Note: templates contain {{NS}} namespace placeholders — if you manually copy them, replace first, or directly run new_gameplay.py to auto-generate; otherwise they will not compile:

Module	File	Purpose
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	Singleton, state machine, event bus, game flow (menu/game/pause/loading)
Input	InputReader	Wraps new Input System in code, supports keyboard+mouse+controller
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D: CharacterController movement, mouse view, run/jump/crouch. 2D: Rigidbody2D platform jumping (includes coyote time / jump buffer / variable jump height)
Interaction	InteractableBase / Interactor / PickupItem	Crosshair interaction, pickup example
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	Health, inventory, JSON save, linear dialogue, object pool, audio
AI	EnemyAI / EnemyPerception	NavMesh patrol/chase/attack state machine + cone vision perception
UI	UIPanel / UIManager / HUDController	Panel stack, HUD health bar/prompts/subtitles
Tests	InventoryTests (+ asmdef)	Inventory logic test example, can be run via run_tests

Reference Document Index (Load on Demand)

• references/00-mcp-code-workflow.md: Mapping of 47 MCP tools to gameplay tasks, edit loop, Play verification, testing, fallback without MCP
• references/01-architecture.md: Directory structure, asmdef, naming conventions, data-driven, reference/event/singleton usage boundaries, ScriptableObject
• references/02-input-and-fp-controller.md: Input System implementation, Player prefab hierarchy, first-person movement/view parameter tables, third-person/top-down branches
• references/03-interaction-animation.md: Interaction layer, Animator state machine/Blend Tree/root motion, animation events, Humanoid integration
• references/04-ui-ugui.md: Canvas/EventSystem setup, panel stack, HUD, pause, input switching
• references/05-gameplay-systems.md: Usage and extension specifications for health/inventory/dialogue/save/object pool, data definitions
• references/06-ai-navigation.md: NavMesh baking, enemy configuration, patrol points, perception tuning, state extension
• references/07-audio-vfx.md: AudioMixer groups, audio pool, music crossfade, particle/VFX Graph selection
• references/08-performance.md: 60fps budget, Profiler/Frame Debugger flow, common hot spots
• references/09-build-release.md: Build settings, scene list, Steam/Deck checks, save compatibility
• references/10-troubleshooting.md: Common error reference for compilation/null references/execution order/input/navigation/UI
• references/11-2d-gameplay.md: Read this first for 2D projects. 2D package installation, Sprite import, Physics2D and layer matrix, 2D platform jumping (coyote time/jump buffer), Tilemap and Composite collision, pixel-perfect camera, 2D budget based on overdraw and batches (the triangle budget table is meaningless for 2D).

2D Project Note: The C# templates in this skill default to 3D first-person (CharacterController, NavMesh). For 2D, reuse dimension-independent parts (EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager), but rewrite controller, navigation, physics, and performance budgets according to references/11.

Hard Rules

• Values come from GDD: Move speed, jump, damage, hit frames, view distance must be exposed in Inspector and match the GDD page; if GDD doesn't specify, mark as 【To Be Confirmed】 – never make up numbers.
• Every step must be verifiable: After code changes, compilation must have zero errors, and Play mode must be tested; for feel-related features (movement/view/attack), you must capture Transform/state evidence, not just say "it should work."
• No fake compilation: If validate_script or read_console doesn't pass, the task is not complete; if verification is impossible in the current environment, state that clearly – do not fabricate results.
• Data and logic separation: Tweakable values use SerializeField/ScriptableObject; presentation layers subscribe to events, do not hardcode them into system classes.
• Naming conventions: Class PascalCase; filename matches the main class name; scenes/prefabs Level_01_, PF_Player; constants contain no Chinese; even CS warnings in Console must be fixed.
• Small commits: One feature per commit; save/backup the scene before making changes; for dangerous operations (delete, batch modify components), first list the affected objects.

Definition of Done (DoD)

• Implemented logic matches GDD page, values are traceable (industry defaults annotated)
• Compilation zero errors and zero warnings (proof via read_console screenshot/log)
• Play mode test passed: input, state transitions, interaction, feedback all reproducible
• Testable logic has unit tests (run_tests green)
• All relevant references/components/hierarchy are fully configured (prefab can be dragged into an empty scene and work, no manual temporary wiring needed)
• New save fields have version handling; new scenes added to Build
• Performance has no new hot spots (target 60fps, for mobile/Deck see 08)