huayuehua15-netizen/unity-gameplay-dev

Habilidade de Desenvolvimento de Jogabilidade Unity (Primeira Pessoa / Unity 6 / URP)

Convenção de caminho (leia esta linha primeiro): Todos os caminhos scripts/, references/, assets/ neste arquivo são relativos ao diretório onde este SKILL.md está localizado. Antes de executar scripts, encontre esse diretório. A localização de instalação varia conforme o host: no plugin Claude Code, fica no diretório de plugins; no Cursor/Codex, o install.ps1 coloca em <projeto>/skills/game-dev/<nome-da-skill>/. Em caso de dúvida, use glob para obter o caminho absoluto deste SKILL.md e chame os scripts com o caminho absoluto. Se você tentar executar python scripts/xxx.py diretamente na raiz do projeto, ocorrerá file-not-found.

Visão Geral

Esta skill transforma especificações GDD e ativos 3D em funcionalidades de jogo jogáveis: usando MCP para criar/modificar scripts, anexar componentes, configurar animações e UI, entrar no Play Mode para verificar, executar testes e criar builds no Unity. Pilha tecnológica padrão: Unity 6 (6000.x LTS, compatível com 6000.3), URP, UGUI, novo Input System, Cinemachine 3 (opcional), single-player, sem multiplayer.

Limites

• Faz: Lógica de jogabilidade, controladores, interação, UI, inventário/diálogo/salvamento, IA, áudio, testes, build e identificação de gargalos de performance.
• Não faz: Criação/importação de ativos 3D/materiais (delegado à skill unity-blender-mcp); multiplayer (Netcode); shaders escritos à mão (apenas recomendações de seleção para efeitos especiais).
• O projeto alvo usa primeira pessoa; terceira pessoa/vista superior usam a mesma arquitetura (máquina de estados, input, interação, UI permanecem), apenas o controlador e a câmera diferem, veja references/02.
• Projetos 2D: A camada de arquitetura (máquina de estados/barramento de eventos/salvamento/inventário/pilha de UI) é reutilizável, mas o controle do personagem, física, navegação e orçamento de performance devem ser alterados, veja references/11-2d-gameplay.md. Não use CharacterController + NavMesh do 3D para 2D.

Ambiente Pré-requisito

• Unity 6000.x (6000.0 LTS suportado até outubro de 2026, depois atualize para 6000.3 LTS; o código é compatível com ambos).
• Pacotes obrigatórios: com.unity.inputsystem (novo Input System), com.unity.ugui (UGUI), com.unity.ai.navigation (hornerização NavMesh), com.unity.test-framework (testes, o scaffolding os adiciona automaticamente com --tests); opcionais: com.unity.cinemachine, URP com.unity.render-pipelines.universal.
• Instalação de pacotes via MCP manage_packages, ou o scaffolding escreve automaticamente o manifest (Input System / UGUI / test framework, resolvendo versões com base na tabela de fallback integrada ao editor e versão principal); após instalação, vá em Project Settings → Active Input Handling e defina como Both (o scaffolding escreve activeInputHandler: 2).
• Verificação de versão: ProjectSettings/ProjectVersion.txt no projeto; em caso de dúvida sobre APIs, use unity_docs / unity_reflect; é proibido escrever APIs não familiares de memória.

Fluxo de Trabalho Padrão (Do GDD à Funcionalidade Jogável)

Fluxo A: Novo Projeto / Configuração do Zero

1. Confirme a versão e a pipeline: manage_editor lê a versão do editor; veja se o projeto é URP ou Built-in (materiais e pós-processamento diferem).
2. Execute o scaffolding: python scripts/new_gameplay.py --out "<projeto>/Assets/Game" --namespace <nome-do-jogo>, gera código do framework, asmdef, assembly de teste e adiciona automaticamente a dependência do Input System; abra o Unity uma vez para baixar os pacotes e depois execute o scaffolding novamente para preencher os GUIDs do asmdef.
   • ⚠️ Erros de compilação CS0234/CS0246 (não encontra UnityEngine.InputSystem) na primeira compilação são esperados, não significa que o scaffolding quebrou: o projeto novo ainda não baixou os pacotes, então não consegue ler o GUID do asmdef do InputSystem. Abra o Unity uma vez para baixar os pacotes → execute o scaffolding novamente → GUIDs preenchidos → compilação sem erros.
   • Testado no Unity 6000.0.84f1: após reexecutar, compilação zero erros, InventoryTests 3/3 aprovados.
3. Crie objetos guia de cena: Siga references/01 para criar a cena inicial (GameManager, AudioManager, UIManager, EventSystem, Canvas), usando manage_gameobject / manage_components.
4. Implemente na ordem das funcionalidades: Input → Controlador de Primeira Pessoa → Interação → HUD → Sistemas Específicos de Jogabilidade → IA → Áudio/VFX (veja a ordem abaixo em "Ordem de Desenvolvimento de Funcionalidades").
5. Valide cada funcionalidade: Ao concluir cada funcionalidade, teste manualmente no Play Mode e escreva testes EditMode/PlayMode, veja o ciclo de validação em references/00.
6. Navegação/Hornerização/Build: Hornerização NavMesh, inclusão de cenas no Build, lista de verificação pré-build, veja references/08, references/09.

Fluxo B: Desenvolvimento de Funcionalidade Única (Mais Comum)

Leia a página correspondente do GDD (especificações de personagem/interação/sistema/diálogo/animação) → Liste os scripts e componentes a serem alterados → Escolha um template ou crie um novo → Siga o ciclo de edição MCP para implementar → Valide no Play Mode → Adicione testes → Atualize a definição de conclusão da funcionalidade.

Fluxo C: Depuração e Otimização

Para erros de compilação/execução, consulte references/10; para quedas de FPS/travamentos, siga o fluxo do Profiler em references/08; para falhas de operação MCP, siga o plano de contingência em references/00.

Ciclo de Edição MCP (Siga Sempre ao Modificar Código)

1. refresh_unity sincroniza o disco primeiro; read_console confirma que não há erros iniciais.
2. Crie script: create_script; modifique script: priorize script_apply_edits (edição estruturada no nível do método), use apply_text_edits apenas para pequenas alterações; após modificar, execute validate_script.
3. refresh_unity aciona a compilação → read_console verifica o resultado da compilação (corrija erros CS imediatamente, não prossiga com erros).
4. Anexe componentes/configure referências: manage_components / manage_gameobject; animações use manage_animation; UI use manage_gameobject (use manage_ui apenas para UI Toolkit).
5. Entre no Play Mode para validar: manage_editor alterna para playmode, read_console verifica exceções em tempo de execução; para sensação de visão/controle, use find_gameobjects para ler o estado do Transform e confirme, se necessário, execute_code para capturar a visualização do Game View.
6. Mescle múltiplas operações não conflitantes em batch_execute; salve a cena com manage_scene ao final de cada funcionalidade.

Ordem de Desenvolvimento de Funcionalidades (Após o Scaffolding)

1. Input InputReader (já gerado pelo scaffolding) → Anexe ao Player na cena, mova com WASD/mouse
2. Controle de Primeira Pessoa PlayerLook + FirstPersonController (andar, correr, pular, agachar, aterrissar)
   - Projetos 2D: Use `PlatformerController2D` (gerado automaticamente com `--dimension 2d`, arquivos específicos 3D não serão gerados)
3. Interação Interactor + Porta/Item Coletável (conecte a UI de mira)
4. HUD + Pilha de Painéis de Menu (UIManager, ESC pausa)
5. Sistemas de Jogabilidade: Health/Inventário/Diálogo (conforme escolha do GDD)
6. SaveSystem (conecte os sistemas existentes à interface ISaveable)
7. IA Inimiga: Hornerização NavMesh + EnemyAI + Percepção
8. AudioManager + Mixer de Áudio; VFX (partículas/boca da arma/acerto)
9. Performance: use Profiler para estabilizar quadros; crie build (references/08, 09)

Scaffolding e Templates

python scripts/new_gameplay.py --out "D:/MyProject/Assets/Game" --namespace MyGame
#   --no-tests: não gera assembly de teste
#   --editor-data "caminho do Editor/Data": resolve a versão do Input System (se não informado, usa tabela de fallback de versão)

Lista de templates (assets/templates/). Nota: os templates contêm o placeholder de namespace {{NS}}; substitua ao copiar manualmente, ou execute new_gameplay.py para gerar automaticamente caso contrário, não compilará:

Módulo	Arquivo	Uso
Core	PersistentSingleton / StateMachine / EventBus / GameManager / GameEvents	Singleton, máquina de estados, barramento de eventos, fluxo do jogo (menu/jogo/pausa/carregamento)
Input	InputReader	Encapsulamento codificado do novo Input System, teclado+mouse e controle
Player	FirstPersonController / PlayerLook / PlatformerController2D	3D: CharacterController movimento, visão do mouse, correr/pular/agachar. 2D: Rigidbody2D pulo de plataforma (com coyote time / jump buffer / altura de pulo variável)
Interaction	InteractableBase / Interactor / PickupItem	Interação com mira, exemplo de coleta
Systems	Health / Inventory / SaveSystem / DialogueRunner / ObjectPool / AudioManager	Vida, inventário, salvamento JSON, diálogo linear, pool de objetos, áudio
AI	EnemyAI / EnemyPerception	Máquina de estados NavMesh patrulha/persegue/ataca + percepção de cone de visão
UI	UIPanel / UIManager / HUDController	Pilha de painéis, HUD barra de vida/dicas/legendas
Tests	InventoryTests (+ asmdef)	Exemplo de teste de lógica de inventário, executável com run_tests

Índice de Documentos de Referência (Carregar Sob Demanda)

• references/00-mcp-code-workflow.md: Mapeamento das 47 ferramentas MCP para tarefas de jogabilidade, ciclo de edição, validação no Play Mode, testes, plano de contingência sem MCP
• references/01-architecture.md: Estrutura de diretórios, asmdef, convenções de nomenclatura, direcionamento a dados, limites de uso de referência/evento/singleton, ScriptableObject
• references/02-input-and-fp-controller.md: Implementação do Input System, hierarquia do prefab Player, tabela de parâmetros de movimento/visão de primeira pessoa, ramificações terceira pessoa/vista superior
• references/03-interaction-animation.md: Camada de interação, máquina de estados Animator/Blend Tree/movimento root, eventos de animação, integração Humanoid
• references/04-ui-ugui.md: Configuração de Canvas/EventSystem, pilha de painéis, HUD, pausa, alternância de input
• references/05-gameplay-systems.md: Padrões de uso e extensão para vida/inventário/diálogo/salvamento/pool de objetos, definição de dados
• references/06-ai-navigation.md: Hornerização NavMesh, configuração de inimigos, pontos de patrulha, ajuste de parâmetros de percepção, extensão de estados
• references/07-audio-vfx.md: Agrupamento AudioMixer, pool de áudio, fade de música, seleção de partículas/VFX Graph
• references/08-performance.md: Orçamento para 60fps, fluxo do Profiler/Frame Debugger, hotspots comuns
• references/09-build-release.md: Configurações de build, lista de cenas, verificação para Steam/Deck, compatibilidade de salvamentos
• references/10-troubleshooting.md: Tabela de erros comuns: compilação/referência nula/ordem de execução/input/navegação/UI
• references/11-2d-gameplay.md: Leia este documento primeiro ao trabalhar em projetos 2D. Instalação de pacotes 2D, importação de Sprite, Physics2D e matriz de camadas, pulo de plataforma 2D (coyote time/jump buffer), Tilemap e colisão Composite, câmera pixel-perfect, orçamento 2D baseado em overdraw e Batch (tabela de orçamento de triângulos não se aplica a 2D).

Atenção para Projetos 2D: Os templates C# desta skill são padrão para 3D primeira pessoa (CharacterController, NavMesh). Para 2D, reutilize as partes independentes de dimensão (EventBus, StateMachine, Inventory, SaveSystem, Health, ObjectPool, UIManager, AudioManager), e reescreva controlador, navegação, física e orçamento de performance conforme references/11.

Regras de Ferro

• Valores vêm do GDD: Velocidade de movimento, pulo, dano, frames de acerto, distância de visão devem ser expostos no Inspector e consistentes com a página do GDD; se o GDD não especificar, marque como 【A Confirmar】, é proibido inventar números.
• Cada passo deve ser verificável: Após modificar o código, compilação sem erros, teste real no Play Mode; funcionalidades de sensação (movimento/visão/ataque) devem capturar evidências de Transform/estado, não pode apenas dizer "deve funcionar".
• Proibido fingir compilação: Se validate_script ou read_console não passarem, não está concluído; se não for possível verificar no ambiente atual, declare explicitamente, não invente resultados.
• Separação de dados e lógica: Valores ajustáveis devem usar SerializeField/ScriptableObject; a camada de apresentação assina eventos, não escreva na classe do sistema.
• Convenções de nomenclatura: Classes em PascalCase; nome do arquivo igual ao nome da classe principal; cenas/prefabs Level_01_, PF_Player; constantes sem chinês; avisos CS no Console também devem ser corrigidos.
• Commits pequenos e frequentes: Uma funcionalidade por commit; salve/faça backup da cena antes de modificar; operações perigosas (excluir, modificar componentes em lote) devem primeiro listar os objetos afetados.

Definição de Conclusão (DoD)

• Lógica implementada consistente com a página do GDD, valores rastreáveis (valores padrão do setor já anotados)
• Compilação sem erros e sem avisos (com captura de tela/leitura do read_console como prova)
• Teste real no Play Mode aprovado: input, alternância de estados, interação e feedback reproduzíveis
• Lógica testável unitariamente tem testes (run_tests verde)
• Referências/componentes/estrutura de hierarquia configurados completamente (prefab arrastado para cena vazia funciona, sem dependência de conexões manuais temporárias)
• Novos campos de salvamento já tratados com número de versão; novas cenas já incluídas no Build
• Performance sem novos hotspots (objetivo 60fps, para celular/Deck veja 08)