Files
CenaForge/doc/godot/cenas.md
T
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 16:35:09 -03:00

161 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Guia: construir cenas no Godot para os vídeos (biblioteca de cenas)
Para **qualquer agente** (Codex ou Claude pela CLI do painel) que precise de uma cena que ainda
não existe: um campo de futebol, um estádio, o Pelé batendo um pênalti, uma cidade, um planeta.
A cena construída fica guardada na **biblioteca** e serve para todos os vídeos depois.
## Onde fica
```
godot/library/<id>/
template.gd a cena (obrigatório)
manifest.json nome, descrição, parâmetros e palavras-chave (obrigatório)
*.gd peças reaproveitáveis (ex.: field.gd com a função que monta o campo)
assets/ modelos .glb, texturas, sons que a cena usa (opcional)
```
- `<id>`: minúsculas, números e `-` (ex.: `soccer-field`, `penalty-kick`). É o nome usado no JSON.
- **Leia `doc/godot/api.md`** (gerado: assinaturas das peças e cenas) em vez de abrir os .gd
inteiros de outras cenas. Depois de criar ou mudar peça ou cena, rode
`python .claude/skills/cenaforge/scripts/godot_api.py` para atualizar o resumo.
- Antes de criar, **liste `godot/library/`** e leia os manifestos: se já existe algo parecido,
reaproveite ou estenda. Uma cena pode usar peças de outra:
`const Field := preload("res://library/soccer-field/field.gd")`.
- Não mexa em `godot/scripts/`, `scripts/` nem `panel/`: a cena nova não precisa disso.
## Contrato do `template.gd`
```gdscript
extends Node3D # (ou Node2D para cena 2D)
## Monta a cena uma vez. cfg.params = parâmetros do manifest; cfg.video.duration = segundos.
func setup(cfg: Dictionary, viewport_size: Vector2) -> void: ...
## Estado no instante t (segundos). Chamada a cada quadro, em qualquer ordem de t.
func apply(t: float) -> void: ...
## Texto curto do estado atual (posição da câmera etc.), para conferir determinismo.
func state_signature() -> String: ...
```
Regras que não se negociam:
1. **Determinismo:** a imagem depende só de `(params, t)`. Nada de `TIME`, `randf()` sem semente,
`_process(delta)` nem física em tempo real. Use `RandomNumberGenerator` com `seed` fixo e
passe `t` para shaders por `uniform` (veja o mar da ilha).
2. **A cena dura o que a narração dura** (`cfg.video.duration`, de 2 a ~20 s). Anime em
proporção da duração (`p = t / duração`) para funcionar com qualquer tamanho.
3. **Vertical 9:16** (1080x1920; a prévia é 540x960). Componha para tela em pé. O terço de
baixo (y > 70%) recebe a legenda, e o alto (y < 18%), o texto na tela. Deixe o assunto
principal no meio.
4. **Câmera própria:** crie a `Camera3D`, marque `current = true` e posicione em `apply(t)`.
Movimento suave (ease in/out), nada de corte seco dentro da cena.
5. **Luz e céu próprios** (WorldEnvironment + DirectionalLight3D). O render é `mobile`, com MSAA 2x.
Tonemap ACES e névoa leve deixam tudo mais bonito.
6. **Parâmetro `variant`** (inteiro): o botão "Gerar de novo" do painel soma 1. Use para mudar
ângulo, sentido da câmera, hora do dia ou paleta, mantendo a cena reconhecível.
7. **Sem texto dentro da cena 3D** (o painel põe o texto na tela e a legenda por cima).
## `manifest.json`
```json
{
"id": "soccer-field",
"kind": "doc3d",
"label": "Campo de futebol",
"description": "Estádio com gramado listrado, traves, arquibancada e torcida; câmera de transmissão.",
"keywords": ["campo", "futebol", "gol", "estádio", "gramado", "pênalti"],
"params": [
{ "name": "shot", "label": "Tomada", "type": "select", "default": "broadcast", "options": [
{ "value": "broadcast", "label": "Câmera de TV", "keywords": ["jogo", "partida"] },
{ "value": "goal", "label": "Atrás do gol", "keywords": ["gol", "pênalti", "goleiro"] }
] },
{ "name": "night", "label": "Jogo à noite", "type": "bool", "default": false },
{ "name": "team_color", "label": "Cor do time", "type": "text", "default": "#ffffff" }
],
"createdBy": "<agente>",
"createdAt": "AAAA-MM-DD"
}
```
- `keywords`: palavras que, na coluna "Imagem" do roteiro, fazem o modo automático escolher
esta cena. Seja específico (para uma cena de futebol, não use "verde").
- `params[].type`: `select` (com `options`), `bool`, `number` ou `text`. Cada opção de `select`
pode ter `keywords` próprias: o automático escolhe a opção pelo texto do roteiro.
- O painel monta o formulário da cena a partir daqui.
## Testar: renderize e OLHE os quadros
1. Crie um JSON de teste em `data/tmp/<id>-teste.json`:
```json
{ "id": "teste-<id>", "kind": "doc3d", "template": "<id>",
"video": { "width": 1080, "height": 1920, "fps": 30, "durationSeconds": 5 },
"params": { "shot": "broadcast", "variant": 0 } }
```
2. Rode `python .claude/skills/cenaforge/scripts/frame_check.py --config data/tmp/<id>-teste.json`.
Ele chama `pnpm render ... --profile preview`, mostra só o fim do log se falhar e devolve ~10
linhas: status, tempo e, por quadro, luz, contraste, movimento e enquadramento, marcando
ESCURO, ESTOURADO, CHAPADO, PARADO ou FORA. Para conferir um render que já existe:
`frame_check.py output/runs/<run>` (ou `--last`).
- `CONFIG_INVALID`: o erro diz o campo.
- `SCENE_SCRIPT_INVALID`: o `template.gd` (ou algo que ele carrega) não compila. A validação
reprova antes de renderizar e os `Parse Error` com a linha ficam no `render.log` da pasta do run.
Os dois erros mais comuns:
- `var x := dict.get("k")`, `var p := nodes[i]` ou uma variável de tipo `Node3D` com método do
kit: o tipo não pode ser inferido. Declare o tipo (`var x: Vector3 = ...`) ou use `=`.
- Constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`, `Environment`):
"shadows a native class". Use outro nome (`SkyRig`).
3. **Abra UMA imagem por render**, a que o `frame_check.py` indicar: `inspect/contact-sheet.png`
(480 px de altura) ou o quadro marcado. Não abra quadros soltos em resolução cheia, não abra
imagens em lote e não gere imagens próprias de QA: cada imagem fica no histórico e é reenviada
a cada turno (na cena dos náufragos, ~100 imagens = 6,8 milhões de tokens de entrada). Confira
com olho crítico:
- [ ] o assunto está claro e no meio da tela vertical;
- [ ] nada cortado nas bordas e nada sem sentido (objeto flutuando, buraco, emenda no horizonte);
- [ ] cores com contraste (nada lavado ou estourado) e luz coerente;
- [ ] movimento suave entre o primeiro e o último quadro;
- [ ] cada `select` e `variant` 0, 1 e 2 dão resultados diferentes e bons.
4. Corrija e renderize de novo **até ficar bom**. Uma cena só vai para a biblioteca quando
passar nessa lista. Depois apague os JSONs de teste.
## Personagens e animação (ex.: o Pelé batendo o pênalti)
- Sem modelo pronto, monte o personagem com formas simples (cápsulas e cilindros: tronco,
cabeça, braços, coxas, canelas) em `Node3D` articulados. Anime as juntas por tempo, com
curvas suaves: corrida, apoio, chute, comemoração.
- Movimento crível: o pé de apoio planta antes do chute, o corpo inclina e o braço contrário
balança. A bola sai no instante do contato, com trajetória (parábola) e giro.
- Com modelo `.glb` (feito por você ou obtido na internet), coloque em `library/<id>/assets/` e
carregue em tempo de execução, porque o render não passa pelo importador do editor:
`var doc := GLTFDocument.new(); var st := GLTFState.new(); doc.append_from_file(ProjectSettings.globalize_path("res://library/<id>/assets/x.glb"), st); add_child(doc.generate_scene(st))`.
- **Peças prontas em `godot/kits/`** (use antes de modelar do zero):
`person.gd` é uma pessoa articulada com poses idle, walk, run, swim, sit, wave, kneel, lie e exhausted;
roupa, pele, cabelo, altura e colete são opções; `blend` faz a transição entre poses.
`boat.gd` é uma lancha de pesca com balanço e afundamento.
- Pessoa real: estilizada e respeitosa (sem caricatura ofensiva). Use a roupa e as cores da época.
## Reaproveitar uma cena dentro de outra (ex.: náufrago NA ilha)
Para pôr um personagem, barco ou ação dentro de um cenário que já existe, use a cena existente
como cenário em vez de refazer:
```gdscript
const Island := preload("res://library/island/template.gd")
var island := Island.new()
add_child(island)
# embedded: a ilha não cria câmera (a sua cena cria); céu, mar e luz continuam vindo dela.
island.setup({"params": {"time": "night", "embedded": true}, "video": cfg.video}, viewport_size)
# em apply(t): island.apply(t) (anima o mar e o farol)
var y := island.ground_at(x, z) # altura da malha desenhada: o personagem pisa aqui
var farol := island.lighthouse_position()
```
O nível do mar é y = 0. A ilha tem cerca de 160 × 84 m, com o centro em (0, 0, 0), e o costão
fica onde `height_at` passa de 0. A hora vai em `time`: "day", "sunset" ou "night".
## Exemplo completo
`godot/library/island/` é a referência. Ela mostra terreno por ruído com semente, mata em
`MultiMesh`, mar por shader com `uniform scene_time`, céu e névoa, quatro tomadas de câmera e
`variant`. Copie a estrutura, não o conteúdo.