# Armadilhas conhecidas Cada item: **sintoma → causa → correção → onde está tratado**. Observadas na implementação da prova de conceito com Godot 4.7.2 / FFmpeg 7.1.1 / pnpm 11.22 (16/11/2026). Registro formal em `doc/TEST_RESULT.md`: itens 1–5, 7, 13–15, 17 e 18; itens 30–33 estão em `voice/README.md` ("GPU e CPU"); itens 57–61 estão em `clipper/README.md` ("Armadilhas já resolvidas"); itens 74–76, 87–90 e 103–108 também estão lá e o 78 na seção "Limitações" do editor; itens 79, 81–84 e 92–95 estão em `doc/FACE_BAKEOFF.md` (o 93 também em "Variáveis" de `clipper/README.md`) (o 80, no comentário de `clipper/requirements.txt`); itens 118–128 (publicação) seguem `doc/publicacao/` e o código; itens 129–132 foram informados em 17/11/2026 e conferidos no código (`doc_main.gd`, `doc/godot/cenas.md`) e no banco (`agent_runs` 5, 7 e 8); itens 62–67, 77, 85–86, 91, 99–102, 109–112 e as ampliações do 52, do 44, 77, 86 e 87 foram informados em 16–17/11/2026 (não estão em `doc/TEST_RESULT.md`); os demais vieram de erros de compilação ou instalação durante a implementação. Ao descobrir uma nova, registre aqui via `cenaforge-skill-updater`. Os números são estáveis (outros textos os citam): item novo entra na seção do assunto com o próximo número livre. ## Render (Godot Movie Maker) 1. **Primeiro quadro diferente** (azulado, sombra diagonal errada). Causa: sombras e radiância do céu ainda não prontas no 1º quadro. Correção: 3 quadros de aquecimento em t = 0, descartados com `-start_number 3`. Onde: `--warmup-frames` em `main.gd`; `render.ts` passa `-start_number`. 2. **`delta` não é 1/fps** mesmo com `--fixed-fps` (0,025; 0,0333; 0,0417…). Correção: tempo da cena = contador de quadros / fps. Nunca use `delta` em render. Onde: `_process_render` em `main.gd`. 3. **Resolução do filme travada na inicialização.** `--resolution` e `content_scale_size` em runtime não mudam o arquivo; janela de 1080×1920 não cabe numa tela de 1080 px. Correção: `godot/override.cfg` temporário com o viewport do perfil e janela menor (stretch `viewport`, aspect `keep`). A cena aborta (código 3) se o viewport ≠ config. Onde: `render.ts` escreve/remove o arquivo; checagem em `main.gd`. Consequência: render manual sem o lançador só sai em 540×960. 4. **`--write-movie` relativo grava em `godot/`, e falha em silêncio.** Com a pasta inexistente, nenhum PNG é gravado e a Godot sai com código 0 dizendo "Done recording". Correção: caminho absoluto; o lançador confere os PNGs; `main.gd` aborta se a pasta não existe. Lição: log de sucesso não prova nada — confira arquivos. 5. **Quantidade de quadros.** Chamar `quit()` no `_process` do último quadro ainda grava esse quadro: total de PNGs = aquecimento + fps × duração, índices contínuos a partir de 0, padrão `frame%08d.png`, mais `frame.wav` (silencioso, descartado). 6. **Modo `--headless` não renderiza 3D válido.** Use só para validação, testes e preparação de assets. O render abre uma janela e precisa de backend gráfico. 7. **Custo do render é a codificação PNG** (~105 ms/quadro em 540×960, ~404 ms em 1080×1920), não a GPU. Não prometa tempo sem medir. 110. **Cena do documentário (`doc2d`/`doc3d`) reprovada como "quadro preto" ou "moto não termina no ponto".** Causa: as checagens do lançador eram da rua — o fundo escuro do documentário (#0d0d10) tem luma ≈ 13, abaixo do piso 20 (`MIN_AVERAGE_LUMA`), e não há moto. Correção: com `kind` `doc2d` ou `doc3d`, `render.ts` pula a checagem da moto e usa `MIN_AVERAGE_LUMA_DOC2D` = 4. Fundo novo mais escuro que isso → ajuste o piso, não desligue a checagem. 129. **Render de cena `doc3d` não termina e enche a pasta de PNGs** (17/11/2026: 39 mil quadros, "apply em Nil" em laço). Causa: `template.gd` com erro de compilação; o protocolo seguia sem a cena. Correção: `doc_main.gd` carrega o script na validação e, se `can_instantiate()` falha, sai com `SCENE_SCRIPT_INVALID` (código 2, `EXIT_INVALID_CONFIG`); os `Parse Error` com a linha ficam no `render.log` do run. No render, cena sem `setup`/`apply` também sai com `SCENE_SCRIPT_INVALID`. Se um render antigo travar assim: encerre a Godot **e** o lançador e apague `output/.render.lock`. Erros de GDScript mais comuns: itens 9 e 130. ## GDScript (Godot 4.7) e TypeScript do lançador 8. **`class_name` depende do cache do editor.** O projeto roda sem importação prévia; use `const X := preload(...)`. 9. **`var x := dicionario.campo + 1.0`** não compila (tipo não inferível a partir de Variant). Idem `var x := dict.get("k")`, `var p := nodes[i]` e retorno de método de kit chamado por variável tipada como `Node3D`. Declare o tipo (`var x: float = ...`) ou use `=`. 10. **Comparar valor não-objeto com `null`**: prefira `typeof(v) == TYPE_NIL`. 11. **`quit()` é adiado para o fim do quadro**: depois de chamar, marque um sinalizador (`_halted`) para o `_process` seguinte não rodar com estado incompleto. 12. **Dentro de comentário de bloco TypeScript, `*/`** (ex.: `godot-*/`) encerra o comentário. 130. **"shadows a native class"**: constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`, `Environment`) não compila. Use outro nome (`SkyRig` em `godot/library/castaways/template.gd`). Guia: "Testar" em `doc/godot/cenas.md`. ## Composição visual 13. Título longo quebra linha: o rótulo cresce para cima (alinhado embaixo) para não invadir as opções. Reserve ~18% inferior livre para a interface da plataforma. 14. No fim do plano, câmera baixa (~1,1 m) com leve inclinação para baixo põe o entregador na metade superior e mantém o horizonte; câmera alta deixa o texto cobrindo o personagem. 15. Borda do plano do morro vira linha reta no céu: a cumeeira de volumes irregulares resolve. 16. Câmera lateral perto dos postes (x = meia pista + 0,5 m): mantenha ≥ 1 m de folga no offset. 17. Rodas: a ~4 m/s giram ~26°/quadro; acima de 30°/quadro a simetria de 60° dos raios pode causar efeito estroboscópico. 111. **Espuma do mar desenhada por elipse não acompanha a costa** (anel regular em volta de uma ilha irregular). Causa: a elipse no shader do mar ignora o contorno real do terreno. Correção: removida; a cor turquesa perto da costa já marca a transição. Espuma futura precisa seguir a altura do terreno, não uma forma fixa. Onde: `_build_ocean` em `godot/library/island/template.gd`. ## Ferramentas 18. **`pnpm doctor`** é comando nativo do pnpm 11 → use `pnpm run doctor`. 19. **pnpm 11 bloqueia scripts de instalação** não aprovados (erro `ERR_PNPM_IGNORED_BUILDS`). O `esbuild` está recusado em `pnpm-workspace.yaml` (`allowBuilds: esbuild: false`) e funciona assim. 20. **pnpm repassa o `--`** para o script; o parser do lançador ignora um `--` solto. 21. Executável principal da Godot (não o `_console.exe`) escreve stdout em pipe normalmente; use-o para poder encerrar a árvore com `taskkill /T`. 44. **Heredoc ou `node -e "..."` no Bash do agente quebra com barra invertida e aspas** (`\\` vira `\`; escapes como `\b` de regex se perdem; às vezes o script inteiro falha). Em 17/11/2026 um `node -e` com regex quebrou o build do painel duas vezes. Texto com barra invertida (caminhos Windows, `package.json`, regex) ou script com aspas aninhadas: edite com Edit/Write, ou grave o script num arquivo (scratchpad) com Write e execute o arquivo, nunca inline. ## Painel 22. **Portas:** o CenaForge usa a faixa **4500–4599** (painel = 4500). A 3100 já é de outro aplicativo nesta máquina. `EADDRINUSE` = porta ocupada: escolha outra da faixa, nunca encerre o processo alheio. 23. **Node não executa `.cmd`/`.bat` sem shell** (ex.: `pnpm.cmd`). O painel chama o lançador como `node node_modules/tsx/dist/cli.mjs scripts/cli.ts render …` e procura só `.exe`. 24. **Next.js 16.4** vem com `cacheComponents` ligado; o painel desliga (dados sempre dinâmicos) e chama `connection()` antes de ler o SQLite. `params` de página/rota é `Promise`. 25. **Script `.ts` dentro de `panel/`** roda como CommonJS (sem `"type": "module"`): para `await` no topo, use `.mts`. 26. **`claude -p` reclama de stdin** se a entrada não for fechada: o painel usa `stdio: ["ignore", …]`. 27. **Codex fora de repositório Git** recusa rodar sem `--skip-git-repo-check`. `codex exec resume` não aceita `--sandbox` nem `-C`: use `-c sandbox_mode="workspace-write"` e o cwd do processo. 28. **Shims do npm no Windows** (`codex`, `codex.cmd`, `codex.ps1`): o sem extensão é script de shell e o `.cmd` exige shell. O painel (`agents.ts`) e o juiz do Clipador (`clipper/app/judge.py`) executam `node /bin/codex.js`. 29. **Ruído das CLIs no stderr.** Codex: configuração pessoal do usuário (`~/.codex/config.toml`, servidor MCP fora do ar) e "Codex is ignoring N unrecognized configuration setting"; Claude Code: `[claude-code:unrecognized_model]` para id fora da lista interna dele (ex.: `claude-fable-5-2`), mas o modelo roda normalmente. O painel filtra esses padrões (`STDERR_NOISE` em `panel/src/lib/agents.ts`); os avisos de configuração do Codex chegam como item `error`, exibidos como nota. 42. **Ícone some no menu recolhido:** SVG dentro de flex encolhe a 0 px ao lado de texto `nowrap`. Correção: `shrink-0` nos ícones (`panel/src/components/icons.tsx`). 43. **Grade na barra lateral cresce até a largura do texto.** Correção: `flex-col` + `min-w-0` (`panel/src/components/sidebar-nav.tsx`). 48. **Nó do `@xyflow/react` 13 não responde a clique** sem `onNodeClick` no canvas. Correção: o clique sobe até o nó e é tratado no `onNodeClick` (`components/story-flow.tsx`). 49. **Foco dentro do canvas rola o contêiner** e desalinha a árvore. Correção: `onScrollCapture` desfaz a rolagem e `setCenter` traz o nó focado para a vista (`story-flow.tsx`). 50. **Grade sem `grid-cols-1` estoura no celular** (colunas implícitas crescem até o conteúdo). Correção: declarar `grid-cols-1` na base e as colunas extras só nos breakpoints. 51. **Mudança de esquema não aparece no painel em dev** (ex.: v4 → criar história documental falha no CHECK de `stories.kind`). Causa: a conexão do SQLite fica em `globalThis.__cenaforgeDb` (`panel/src/lib/db.ts`) e a migração só rodava ao abrir o banco. Hoje a marca `checkedThisModule` faz a 1ª chamada de `db()` depois da recarga do código migrar o banco aberto (item 138); se o `db.ts` não foi recarregado, faça uma requisição ao painel ou peça ao usuário que reinicie o `pnpm panel` (é dele: não reinicie você). Conferir: `PRAGMA user_version` do `data/cenaforge.db` = `MIGRATIONS.length`. 52. **`tsx` com `await` no topo** exige arquivo `.mts`, e o import de módulo local precisa de URL `file:///` (caminho Windows cru com `C:\` ou `f:/` não é URL e falha no loader ESM). Node puro não resolve import `.ts` sem extensão: rode pelo tsx da raiz, `node node_modules/tsx/dist/cli.mjs