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

8.9 KiB
Raw Blame History

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

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

{
  "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:
    { "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:

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.