huayuehua15-netizen/unity-gameplay-dev

Habilidad de Desarrollo de Juego en Unity (Primera Persona / Unity 6 / URP)

Convención de rutas (lee esto primero): Todos los scripts/, references/, assets/ son relativos al directorio donde se encuentra este SKILL.md. Ejecuta los scripts después de localizar ese directorio. La ubicación de instalación varía según el host: el plugin de Claude Code está en el directorio de plugins; Cursor/Codex lo instalan mediante install.ps1 en <proyecto>/skills/game-dev/<nombre-habilidad>/. Si no estás seguro, usa glob para encontrar la ruta absoluta de este SKILL.md y llama a los scripts con esa ruta absoluta. Si ejecutas python scripts/xxx.py directamente desde la raíz del proyecto, obtendrás un error 'file-not-found'.

Resumen

Esta habilidad convierte las especificaciones GDD y los assets 3D en funcionalidades de juego jugables: usando MCP para crear/modificar scripts, asignar componentes, configurar animaciones y UI, entrar en modo Play para verificar, ejecutar tests y generar builds. Pila tecnológica por defecto: Unity 6 (6000.x LTS, compatible con 6000.3), URP, UGUI, nuevo Input System, Cinemachine 3 (opcional), para un jugador, sin multijugador.

Límites

• Hace: lógica de juego, controladores, interacción, UI, inventario/diálogo/guardado, IA, audio, tests, compilación y localización de rendimiento.
• No hace: creación/importación de assets 3D / materiales (se lo deja a la habilidad unity-blender-mcp); multijugador (Netcode); shaders escritos a mano (solo da recomendaciones de selección para efectos).
• El proyecto objetivo usa primera persona; tercera persona / vista cenital reutilizan la misma arquitectura (máquina de estados, entrada, interacción, UI sin cambios), solo difieren en el controlador y la cámara, ver references/02.
• Proyectos 2D: la capa de arquitectura (máquina de estados/bus de eventos/guardado/inventario/pila UI) se puede usar igual, pero el control del personaje, física, navegación y presupuesto de rendimiento deben cambiarse, ver references/11-2d-gameplay.md. No uses CharacterController + NavMesh de 3D para 2D.

Entorno previo

• Unity 6000.x (6000.0 LTS con soporte hasta octubre de 2026, luego se debe actualizar a 6000.3 LTS; el código es compatible con ambos).
• Paquetes obligatorios: com.unity.inputsystem (nuevo Input System), com.unity.ugui (UGUI), com.unity.ai.navigation (para hornear NavMesh), com.unity.test-framework (tests, el scaffolding los añade automáticamente con --tests); opcionales: com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• Instalación de paquetes mediante MCP manage_packages, o el scaffolding escribe automáticamente el manifest (Input System / UGUI / framework de tests, resolviendo la versión según la versión interna del editor y la tabla de retroceso de la rama principal); después de la instalación, en Project Settings → Active Input Handling poner en Both (el scaffolding escribe activeInputHandler: 2).
• Confirmación de versión: ProjectSettings/ProjectVersion.txt en el proyecto; si no estás seguro de una API, usa unity_docs / unity_reflect. Prohibido escribir APIs que no conozcas de memoria.

Flujo de trabajo estándar (de GDD a funcionalidad jugable)

Flujo A: Nuevo proyecto / construcción desde cero

1. Confirmar versión y pipeline: manage_editor lee la versión del editor; ¿el proyecto es URP o Built-in? (los materiales y los postprocesos son diferentes).
2. Ejecutar scaffolding: python scripts/new_gameplay.py --out "<proyecto>/Assets/Game" --namespace <nombre-del-juego>, genera el código base, asmdef, ensamblado de tests, y añade automáticamente las dependencias de Input System; abre Unity una vez para que los paquetes se descarguen y luego vuelve a ejecutar para rellenar los GUIDs de asmdef.
   • ⚠️ En la primera compilación, los errores CS0234/CS0246 (no encuentra UnityEngine.InputSystem) son esperados, no es que el scaffolding esté roto: el proyecto nuevo aún no ha descargado los paquetes, por lo que no puede leer los GUIDs de asmdef de InputSystem. Abre Unity una vez para que los paquetes se descarguen → vuelve a ejecutar el scaffolding → los GUIDs se rellenan → la siguiente compilación es sin errores.
   • Probado en Unity 6000.0.84f1: después de volver a ejecutar, la compilación es sin errores, InventoryTests 3/3 pasan.
3. Crear objetos guía de la escena: siguiendo references/01 construir la escena de inicio (GameManager, AudioManager, UIManager, EventSystem, Canvas), usando manage_gameobject / manage_components.
4. Implementar por orden de funcionalidad: entrada → controlador de primera persona → interacción → HUD → sistemas de juego específicos → IA → audio/VFX (el orden se detalla en "Orden de desarrollo de funcionalidades").
5. Validar cada funcionalidad: al completar cada funcionalidad, prueba manualmente en modo Play + escribe tests EditMode/PlayMode, ver el bucle de validación en references/00.
6. Navegación / horneado / compilación: hornear NavMesh, incluir escenas en Build, lista antes de empaquetar, ver references/08, references/09.

Flujo B: Desarrollo de una funcionalidad individual (el caso más común)

Lee la página correspondiente del GDD (personaje/interacción/sistema/diálogo/especificaciones de animación) → lista los scripts y componentes a modificar → selecciona una plantilla o crea una nueva → sigue el bucle de edición MCP para implementar → verifica en modo Play → añade tests → actualiza la definición de funcionalidad completada.

Flujo C: Depuración y optimización

Para errores de compilación/ejecución consulta references/10; para caídas de frames / ralentizaciones sigue el flujo de Profiler en references/08; si falla una operación MCP, sigue el plan de contingencia en references/00.

Bucle de edición MCP (cumplir cada vez que se modifica código)

1. refresh_unity para sincronizar el disco; read_console para confirmar que no hay errores de partida.
2. Crear script: create_script; modificar script: priorizar script_apply_edits (edición estructurada a nivel de método), solo usar apply_text_edits para cambios pequeños; después de modificar, validate_script.
3. refresh_unity para disparar la compilación → read_console para ver el resultado de la compilación (si hay errores CS, corregirlos inmediatamente, no continuar con errores).
4. Asignar componentes/referencias: manage_components / manage_gameobject; animaciones usar manage_animation; UI usar manage_gameobject (solo UI Toolkit usa manage_ui).
5. Entrar en modo Play para verificar: manage_editor para cambiar a playmode, read_console para buscar excepciones en tiempo de ejecución; para la sensación de la cámara/controles, usar find_gameobjects para leer el estado de Transform y confirmar, si es necesario execute_code para capturar la Game View.
6. Múltiples operaciones no conflictivas se pueden combinar en batch_execute; antes de terminar cada funcionalidad, manage_scene para guardar.

Orden de desarrollo de funcionalidades (después del scaffolding)

1. Entrada InputReader (ya generado por scaffolding) → asignar al Player en la escena, que WASD/ratón se muevan
2. Control de primera persona PlayerLook + FirstPersonController (caminar, correr, saltar, agacharse, aterrizar)
   - Para proyectos 2D, usar `PlatformerController2D` (generado automáticamente al usar `--dimension 2d`; los archivos específicos de 3D no se generan)
3. Interacción Interactor + puerta/objeto recogible (conectar la UI de la mira)
4. HUD + pila de paneles de menú (UIManager, ESC para pausar)
5. Sistemas de juego: Health/Inventario/Diálogo (según lo que decida el GDD)
6. Guardado SaveSystem (conectar los sistemas ya implementados a ISaveable)
7. IA enemiga: hornear NavMesh + EnemyAI + Percepción
8. Audio AudioManager + mezclador; VFX (partículas/efectos de boca/impacto)
9. Rendimiento Profiler para fijar framerate; generar build (references/08, 09)

Scaffolding y plantillas

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests: no generar ensamblado de tests
#   --editor-data "Ruta de Editor/Data": para resolver la versión de Input System (si no se pasa, se usa la tabla de retroceso de versiones)

Lista de plantillas (assets/templates/). Nota: las plantillas contienen el marcador de posición {{NS}} para el namespace; si las copias manualmente, reemplázalo primero; o simplemente ejecuta new_gameplay.py para que lo genere automáticamente; de lo contrario no compilarán:

Módulo	Archivo	Uso
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	Singleton, máquina de estados, bus de eventos, flujo del juego (menú/juego/pausa/carga)
Input	InputReader	Encapsulación code-based del nuevo Input System, teclado+ratón y mando
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D: movimiento con CharacterController, cámara con ratón, correr/saltar/agacharse. 2D: salto de plataformas con Rigidbody2D (incluye coyote time / jump buffer / altura de salto variable)
Interaction	InteractableBase / Interactor / PickupItem	Interacción con mira, ejemplo de recogida
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	Vida, inventario, guardado JSON, diálogo lineal, pool de objetos, audio
AI	EnemyAI / EnemyPerception	Máquina de estados de patrulla/persecución/ataque en NavMesh + percepción con cono de visión
UI	UIPanel / UIManager / HUDController	Pila de paneles, HUD (barra de vida/indicadores/subtítulos)
Tests	InventoryTests (+ asmdef)	Ejemplo de prueba de lógica de inventario, se puede ejecutar con run_tests

Índice de documentos de referencia (cargar según necesidad)

• references/00-mcp-code-workflow.md: Mapeo de las 47 herramientas MCP a tareas de juego, bucle de edición, verificación en Play, tests, contingencia sin MCP
• references/01-architecture.md: Estructura de directorios, asmdef, convenciones de nombres, arquitectura guiada por datos, límites de uso de referencias/eventos/singletons, ScriptableObject
• references/02-input-and-fp-controller.md: Implementación de Input System, jerarquía del prefab Player, tabla de parámetros de movimiento y cámara en primera persona, variantes para tercera persona/vista cenital
• references/03-interaction-animation.md: Capa de interacción, máquina de estados Animator/Blend Tree/root motion, eventos de animación, integración con Humanoid
• references/04-ui-ugui.md: Configuración de Canvas/EventSystem, pila de paneles, HUD, pausa, cambio de entrada
• references/05-gameplay-systems.md: Normas de uso y extensión de vida/inventario/diálogo/guardado/pool de objetos, definiciones de datos
• references/06-ai-navigation.md: Horneado de NavMesh, configuración de enemigos, puntos de patrulla, ajuste de percepción, extensión de estados
• references/07-audio-vfx.md: Agrupación en AudioMixer, pool de audio, fundido de música, selección de partículas/VFX Graph
• references/08-performance.md: Presupuesto de 60fps, flujo de Profiler/Frame Debugger, cuellos de botella comunes
• references/09-build-release.md: Configuración de build, lista de escenas, comprobaciones para Steam/Deck, compatibilidad de guardado
• references/10-troubleshooting.md: Referencia de errores comunes de compilación/referencia nula/orden de ejecución/entrada/navegación/UI
• references/11-2d-gameplay.md: Lee esto primero si haces un proyecto 2D. Instalación de paquetes 2D, importación de Sprites, Physics2D y matriz de capas, salto en plataformas 2D (coyote time/jump buffer), Tilemap y Composite Collider, cámara Pixel Perfect, presupuesto 2D basado en overdraw y batches (la tabla de presupuesto de triángulos no tiene sentido para 2D).

Nota para proyectos 2D: Las plantillas C# de esta habilidad son por defecto para 3D en primera persona (CharacterController, NavMesh). Para 2D, reutiliza las partes independientes de la dimensión (EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager), y reescribe el controlador, navegación, física y presupuesto de rendimiento según references/11.

Reglas de hierro

• Los valores numéricos provienen del GDD: velocidad de movimiento, salto, daño, frames de detección, distancia de visión deben exponerse en el Inspector y coincidir con la página correspondiente del GDD; si el GDD no lo especifica, márcalo como 【Por confirmar】. Prohibido inventar números.
• Cada paso debe ser verificable: después de modificar el código, compilación sin errores, prueba en modo Play; para aspectos de sensación (movimiento/cámara/ataque) se debe poder registrar evidencia de Transform/estado, no basta con decir "debería funcionar".
• Prohibido fingir la compilación: si validate_script o read_console no pasan, la tarea no está completa; si no se puede verificar en este entorno, decláralo explícitamente, no fabriques resultados.
• Separación de datos y lógica: los valores ajustables deben ser SerializeField/ScriptableObject; la capa de presentación se suscribe a eventos, no se escribe dentro de las clases de sistema.
• Convenciones de nombres: clases en PascalCase; nombre de archivo igual al nombre de la clase principal; escenas/prefabs Level_01_, PF_Player; constantes sin caracteres chinos; incluso las advertencias CS en la consola deben corregirse.
• Commits pequeños: una funcionalidad un commit; antes de modificar, guardar/copiar la escena; para operaciones peligrosas (eliminar, modificar componentes en lote), primero lista los objetos afectados.

Definición de funcionalidad completada (DoD)

• La lógica implementada coincide con la página correspondiente del GDD, los valores numéricos son trazables (los valores por defecto de la industria están marcados)
• Compilación sin errores ni advertencias (con captura de read_console como prueba)
• Modo Play probado: entrada, cambio de estados, interacción, feedback se pueden reproducir
• La lógica que se puede probar unitariamente tiene tests (run_tests en verde)
• Las referencias/componentes/configuración de jerarquía están completos (el prefab se puede arrastrar a una escena vacía y funciona, no depende de conexiones manuales temporales)
• Los nuevos campos de guardado ya tienen número de versión; las nuevas escenas ya están incluidas en Build
• El rendimiento no tiene nuevos cuellos de botella (objetivo 60fps, para móvil/Deck ver 08)