Jogos:
tudo o resto,
mais o motor

1.1 O que se acumula

1.2 O que uma skill resolve, e o que não

1.3 A linha que este volume não atravessa

1.4 Delimitação

2.1 O problema, em concreto

2.2 A skill de referência de motor

---
name: unity-api
description: Referência da API da versão de Unity deste projeto, com as
  mudanças face a versões anteriores e as armadilhas conhecidas.
  LEIA references/API.md ANTES de escrever qualquer código de Unity
  — não presuma pela memória, mesmo que pareça uma linha só.
compatibility: Específica da versão indicada em references/VERSAO.md.
---

# API desta versão

## Versão em uso
Ver `references/VERSAO.md`. Se o projeto usar outra versão,
pare e avise — este ficheiro não se aplica.

## Antes de escrever
1. Confirmar a versão.
2. Ler a secção correspondente em `references/API.md`.
3. Se o que precisa não estiver lá, diga que não sabe em vez
   de escrever pela memória.

## Armadilhas conhecidas nesta versão
Ver `references/ARMADILHAS.md` — uma entrada por cada vez que
nos mordeu, com a data e o sintoma.

2.3 O ficheiro de armadilhas

É o que distingue uma skill útil de documentação copiada. Uma entrada por cada vez que a equipa foi mordida:

# Armadilhas — Unity, projeto X

## Instanciar dentro do ciclo de actualização — 2026-03
Sintoma: quebras de fotogramas de dois em dois segundos.
Causa: alocação por fotograma a disparar o colector de lixo.
Nunca instanciar em Update. Usar um conjunto pré-alocado.
Ver `Scripts/Pooling/`.

## Referência procurada por nome — 2026-05
Sintoma: funciona no editor, falha na compilação.
Causa: procura por nome depende da hierarquia da cena.
Nunca procurar por nome. Referência serializada, sempre.

## Coroutine em objecto desactivado — 2026-07
Sintoma: lógica que pára silenciosamente, sem erro.
Nunca assumir que continua. Verificar o estado antes.

Este ficheiro não se escreve de uma vez — cresce. E cada entrada representa horas que não se voltam a perder.

2.4 As skills oficiais da Unity

A Unity publica uma colecção oficial de skills para agentes de código — cerca de vinte e duas, focadas por tarefa: criar projeto, os três sistemas de interface, física e colisões, serviços multijogador, compras integradas, localização, otimização de áudio, de web e de texto, nós personalizados de shader, editor de sprites e a linha de comandos.

3.1 O orçamento

Um jogo a 60 fotogramas por segundo tem cerca de 16 milissegundos por fotograma para tudo: lógica, física, animação, som e desenho. A 30, tem 33. É um orçamento duro — ultrapassá-lo não torna o jogo mais lento, torna-o entrecortado, que é qualitativamente pior.

3.2 A skill de desempenho

# Regras de desempenho — verificar em cada alteração

## Nunca, no ciclo por fotograma
- Nunca alocar (nova lista, nova cadeia de texto, boxing).
- Nunca procurar objectos por nome ou por tipo.
- Nunca usar reflexão.
- Nunca concatenar texto para depuração — usar guarda de compilação.
- Nunca aceder a componentes por procura; guardar a referência.

## Sempre
- Conjuntos pré-alocados para tudo o que se cria e destrói.
- Estruturas de dados reutilizadas entre fotogramas.
- Trabalho pesado distribuído por vários fotogramas, ou fora do
  fio principal.

## Antes de considerar terminado
Correr `scripts/perfil.sh` numa cena representativa.
Reportar o pior fotograma, não a média.
Se o pior passar o orçamento, não está terminado.

3.3 O perfil por plataforma

O mesmo jogo tem orçamentos diferentes conforme onde corre, e a skill deve dizê-lo:

• Telemóvel — orçamento térmico além do de tempo: o dispositivo abranda ao aquecer. Um jogo que corre bem dois minutos pode ser injogável aos dez.
• Web — memória limitada, arranque lento, e o tamanho da transferência conta como experiência.
• Consola — orçamento fixo e conhecido, com requisitos de certificação.
• Realidade virtual — o mais duro: 90 fotogramas por segundo, e falhar não é desconforto visual, é enjoo.

Uma proibição que é conselho num alvo pode ser obrigatória noutro — e a skill tem de declarar para qual foi escrita, no campo compatibility.

4.1 O que codificar

# Recursos

## Nomenclatura
`<tipo>_<nome>_<variante>` em minúsculas, sem acentos, sem espaços.
  `tex_barril_madeira`  `mesh_barril_lod0`  `snd_porta_abrir`
Nunca `Barril_Final_v2_REAL.fbx`.

## Escala e orientação
1 unidade = 1 metro. Eixo Y para cima. Origem na base do objecto,
centrada em X e Z. Nunca exportar com transformação por aplicar.

## Texturas
Potências de dois. Máximo 2048 em objectos de cenário, 1024 em
adereços, 512 em pequenos. Nunca 4096 sem aprovação.

## Malhas
Orçamento de triângulos por categoria em `references/ORCAMENTOS.md`.
Níveis de detalhe obrigatórios acima de 5000 triângulos.

## Antes de integrar
Correr `scripts/validar-recurso.py`. Verifica nome, escala,
orientação, dimensão de textura, contagem de triângulos e
transformações por aplicar. Falha com a razão exacta.

4.2 Direcção de arte, e a família de recursos

Este é o ponto onde o volume IV entra no volume VI. Um jogo não precisa de recursos bonitos — precisa de recursos que pareçam do mesmo mundo:

• Paleta fechada, com a proibição de introduzir valores novos (volume IV, cap. 2).
• Densidade de textura consistente — píxeis por unidade. É o que mais denuncia recursos de origens diferentes.
• Vocabulário de formas. Se o mundo é feito de formas arredondadas, um adereço anguloso salta.
• Nível de detalhe coerente. Um objecto muito mais detalhado que os vizinhos lê-se como erro, não como qualidade.

4.3 A legibilidade é um requisito, não uma preferência

Em jogos, a cor tem uma função que não tem noutros meios: separar o que é jogável do que é cenário. Um objecto com que se interage tem de se distinguir de um que é decoração — e isso é uma regra verificável:

## Legibilidade de jogo
- Elementos interactivos: contraste mínimo de 3:1 contra o cenário
  imediatamente atrás, na iluminação real da cena.
- Perigo nunca depende só de matiz — sempre matiz + forma ou
  movimento (jogadores com deficiência de visão de cores).
- Testar cada cena em escala de cinzentos: a hierarquia do que é
  importante ainda se lê?

Correr `scripts/verificar-legibilidade.py` com capturas da cena.

É o teste de Cor, secção 5.8, caso 4, aplicado a jogabilidade em vez de a identidade — e aqui não é acessibilidade apenas, é jogabilidade.

5.1 O que codificar

5.2 A skill de gravação, que é a mais crítica

## Gravação — regras absolutas
- Número de versão no ficheiro, desde o primeiro dia.
- Nunca remover um campo. Marcar como obsoleto e ignorar.
- Nunca mudar o significado de um campo. Criar um novo.
- Toda a alteração de formato traz migração da versão anterior,
  e teste com um ficheiro real dessa versão.
- Nunca gravar por cima do único ficheiro: gravar noutro e trocar.

## Antes de qualquer alteração ao formato
Correr `scripts/testar-migracao.sh`, que carrega ficheiros de
todas as versões publicadas. Falha se alguma não carregar.

5.3 O limite: balancear

Uma skill pode estruturar o balanceamento — onde vivem os valores, que curvas se usam, como se documenta uma alteração. Não pode dizer se o número está certo, porque isso depende de como se sente a jogar.

6.1 O que é automatizável

6.2 O agente que joga

Um agente automático que percorre um nível — anda, salta, interage — não avalia diversão e detecta uma classe inteira de problemas:

• Sítios onde se fica preso — geometria mal fechada, colisões em falta.
• Percursos não previstos — o atalho que salta metade do nível.
• Estados impossíveis — a porta que fecha com o jogador do lado errado.
• Regressões — o nível que era completável na semana passada e já não é.

É o equivalente do webapp-testing do volume III, cap. 4, aplicado a jogo: não diz se está bom, diz se está partido — e é a distinção que torna a verificação automática útil sem prometer o que não pode dar.

6.3 A instrução que fecha o ciclo

## Antes de considerar terminado
1. `scripts/verificar.sh` — compila, testes, validador de recursos
2. `scripts/perfil.sh` na cena representativa
   → reportar o pior fotograma, não a média
3. `scripts/testar-migracao.sh` se tocou na gravação
4. `scripts/percorrer-nivel.sh` se tocou em geometria ou colisões
5. Capturar a cena e verificar legibilidade dos interactivos

Se qualquer passo falhar, corrigir e repetir.
Nenhum destes passos avalia se o jogo é bom. Isso é playtesting,
e é o que fica para as pessoas.

A última linha está lá de propósito: impede que a lista de verificação seja confundida com aprovação. Um nível que passa nos cinco passos pode ser aborrecido, e a skill diz isso em vez de o esconder.

7.1 O problema

Dez motores, cada um com dez tarefas — física, interface, animação, som, publicação — são cem skills possíveis. Instalar cem descrições em contexto permanente é impossível (volume II, cap. 8.4): a listagem estoura o orçamento, e as skills começam a desaparecer ou a perder descrição.

7.2 A solução: uma skill que escolhe skills

7.3 Como se escreve um roteador

---
name: gamedev
description: Ponto de entrada para desenvolvimento de jogos. Detecta o
  motor e a tarefa e indica que skills específicas carregar. Use em
  qualquer pedido sobre jogos, motores, física de jogo, interface de
  jogo, animação, som, níveis, ou publicação de jogos.
---

# Encaminhamento

## 1. Detectar o motor
Procure, por esta ordem: ficheiro de projeto do motor na raiz,
ficheiro de dependências, extensões de ficheiro dominantes.
Se não for claro, PERGUNTE. Nunca presuma o motor.

## 2. Detectar a tarefa
Física · interface · animação · som · nível · desempenho ·
publicação · dados · rede

## 3. Carregar
Leia `references/<motor>/<tarefa>.md`. Só esse ficheiro.
Se a combinação não existir, diga-o em vez de improvisar
com conhecimento de outro motor.

## Nunca
- Nunca aplicar um padrão de um motor a outro sem verificar.
  São modelos de execução diferentes, não dialectos.

7.4 O que verificar numa colecção grande

Antes de instalar setenta skills de terceiros (volume I, cap. 11):

• Estão fixadas a uma versão do motor? Uma skill sem versão declarada é uma armadilha (cap. 2.2).
• Há validação? Colecções sérias correm um validador sobre as próprias skills.
• Vêm da documentação primária ou de posts de blogue de origem incerta?
• Há roteador? Sem ele, a colecção não é instalável em conjunto.
• Que licença? Verificar antes de uso comercial.

8.1 Os seis

8.2 A quinta não tem correcção, e é importante admiti-lo

8.3 O que nunca delegar

• Saber se é divertido. Só com pessoas a jogar, e sobretudo a desistir (Game Design, cap. 12.2).
• A curva de dificuldade. Depende de como se sente falhar, e isso não está em nenhum número.
• O que se corta. A decisão mais difícil de um jogo é o que fica de fora, e exige saber o que o jogo é.
• A direcção de arte. Aplicá-la, sim; decidi-la, não (volume IV, cap. 1.1).
• O julgamento sobre representação — de pessoas, culturas, temas sensíveis. Exige contexto que não está em texto.

8.4 A revisão trimestral

10.1 O caminho de um recurso

Cada seta é um sítio onde a consistência se perde, e as duas últimas são as que uma skill resolve quase por completo — porque são deterministas.

10.2 As regras de exportação

# Exportação

## Sempre
- Aplicar todas as transformações antes de exportar.
- Congelar escala a 1. Rotação a zero.
- Origem na base, centrada em X e Z.
- Triangular na exportação, não no ficheiro de origem.
- Nomes das malhas iguais aos do objecto — sem sufixos automáticos.

## Nunca
- Nunca exportar com modificadores por aplicar.
- Nunca exportar câmaras, luzes ou objectos auxiliares.
- Nunca incluir histórico de construção.

## Verificar
`scripts/validar-export.py` — falha com a razão exacta e a linha.

10.3 Orçamentos por categoria

Um ficheiro de referência que a skill consulta, em vez de um número no corpo:

# Orçamentos — references/ORCAMENTOS.md

| Categoria | Triângulos | Textura | Níveis de detalhe |
| Personagem principal | 40 000 | 2048 | 3 |
| Personagem secundária | 12 000 | 1024 | 2 |
| Cenário grande | 8 000 | 2048 | 3 |
| Adereço | 2 000 | 512 | 1 |
| Adereço pequeno | 500 | 256 | 0 |

Estes números são deste projeto e desta plataforma alvo.
Ver `VERSAO.md` para a plataforma. Não aplicar a outro projeto.

A última nota é a que impede o erro mais comum ao reutilizar skills entre projetos: orçamentos são específicos da plataforma, e aplicá-los à cega é pior que não os ter.

10.4 O 3D em tempo real fora de jogos

Muito do mesmo se aplica a 3D na web, visualização e motion — com um orçamento diferente e frequentemente mais apertado: o tamanho da transferência conta como experiência, e o dispositivo é desconhecido.

• Compressão de malha e de textura como regra, não como otimização final.
• Orçamento total da cena em megabytes, além do de triângulos.
• Degradação declarada — o que se corta primeiro num dispositivo fraco.
• Verificar em ligação lenta, não só em rede local (Redes, cap. 7).

Ver 3D em Tempo Real e Computação Gráfica & Three.js.

11.1 As quatro

Cerca de cem linhas e dois scripts. As duas primeiras escrevem-se numa manhã e resolvem a classe de erro mais cara deste domínio.

11.2 O erro de começar

11.3 Como saber que resultou

• Menos correcções de API em revisão. O indicador mais directo.
• Menos quebras de fotograma novas. Mensurável pelo perfil.
• O validador de recursos devolve menos violações ao longo do trimestre.
• Mais tempo de playtesting por semana. É o indicador que interessa — e o único que mede o que este volume promete.

12.1 As sete regras

12.2 Catálogo: cinco fontes para jogos e 3D

12.3 O balanço dos seis volumes

12.4 Leituras a par

• A série completa: I · II · III · IV · V.
• Game Design — o playtesting que as skills libertam tempo para fazer.
• Unity e Blender 3D — o ofício.
• 3D em Tempo Real e Computação Gráfica & Three.js.
• O Futuro dos Jogos — para onde isto vai.