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>
This commit is contained in:
2026-11-17 16:35:09 -03:00
co-authored by Claude Opus 5.5
commit 84f30bbc2d
484 changed files with 74826 additions and 0 deletions
+129
View File
@@ -0,0 +1,129 @@
# API das peças e cenas do Godot (gerado)
Gerado por `python .claude/skills/cenaforge/scripts/godot_api.py`. Não edite à mão: rode de novo
quando uma peça ou cena mudar. Use estas funções sem abrir os .gd inteiros.
## Peças (`godot/kits/`, use com `preload("res://kits/<arquivo>.gd")`)
### `godot/kits/boat.gd`
> Peça reaproveitável: lancha de pesca (~8 m) low-poly, com balanço e afundamento.
> const Boat := preload("res://kits/boat.gd")
> var b := Boat.new()
> b.build({"hull": "#f2f0ea", "stripe": "#1f5fa8", "cabin": "#e9e6df", "lights": true})
> add_child(b)
> # em apply(t):
> b.float_on(t, 1.0) # balanço no mar (intensidade 0 = calmo, 1 = normal, 2 = agitado)
> b.sink(0.6) # 0 = flutuando; 1 = quase submerso (popa afunda primeiro, adernado)
> Origem no centro do casco na linha d'água (y = 0 é o nível do mar), proa em -Z.
- `build(opts: Dictionary = {}) -> void`
- `deck() -> Node3D`: Corpo do barco (balança e afunda): pessoas e objetos a bordo entram como filhos dele, com o pé em y = DECK_Y; popa em +Z (z de 0,8 a 3,4 livre atrás da cabine).
- `float_on(t: float, intensity := 1.0) -> void`: Balanço determinístico no mar (sobe/desce, arfagem e jogo).
- `sink(amount: float) -> void`: 0 = flutuando; 1 = quase submerso. Chame antes de float_on no mesmo quadro.
### `godot/kits/person.gd`
> Peça reaproveitável: pessoa estilizada (low-poly) com juntas e animações por tempo.
> const Person := preload("res://kits/person.gd")
> var p := Person.new()
> p.build({"shirt": "#2f6fb3", "pants": "#3a3a3a", "skin": "#c68e6a", "hair": "#2b1d14", "height": 1.75})
> # opções: "sleeveless": true (regata, braço de fora), "shorts": true (bermuda), "vest", "shoes"
> add_child(p)
> # em apply(t):
> p.pose("walk", t) # parado | andar | correr | nadar | sentar | acenar | ajoelhar | deitar
> p.blend("walk", "run", t, 0.3) # mistura duas poses (0 = a primeira, 1 = a segunda)
> Origem nos pés (y = 0 é o chão), frente em -Z. Tudo depende só de t: determinístico.
> Poses: "idle", "walk", "run", "swim", "sit", "wave", "kneel", "lie", "exhausted".
- `build(opts: Dictionary = {}) -> void`
- `pose(action: String, t: float, amount := 1.0) -> void`: Aplica uma pose no instante t (segundos). Ver lista no topo.
- `blend(a: String, b: String, t: float, k: float) -> void`: Mistura duas poses (k de 0 a 1), por exemplo "walk" → "kneel" quando o personagem chega.
## Cenas da biblioteca (`godot/library/<id>/`)
### `castaways`
**Náufragos no costão** (doc3d): Reconstituição estilizada: quatro pescadores, pesqueiro e lancha civil na ilha. Chegada, naufrágio, nado, espera, resgate, embarque e partida. Elenilson mantém regata cinza e bermuda escura; roupas e gestos são ilustrativos.
- param `moment` (select: arrival, sinking, swimming, waiting, rescue, boarding, departure; padrão 'arrival')
- param `camera` (select: medium, close, wide; padrão 'medium')
- param `variant` (number; padrão 0)
`godot/library/castaways/actor.gd`
> Mantém o kit e suas roupas; flexão das poses voltada para a frente local (-Z).
`godot/library/castaways/cast.gd`
> Elenco e barcos da reconstituição dos náufragos (opções de res://kits/person.gd e boat.gd).
> Elenilson: regata cinza e bermuda escura (convenção visual do roteiro, igual em todo o vídeo).
> Os companheiros usam cores discretas e diferentes entre si, nenhuma cinza.
`godot/library/castaways/shore.gd`
> Ilha reutilizada com uma pequena laje de costão para encenação, sem precisão topográfica.
> A malha e ground_at compartilham as mesmas alturas; a ilha original não é modificada.
- `prepare_coast(center: Vector3, sea: Vector3) -> void`
- `height_at(x: float, z: float) -> float`
`godot/library/castaways/sky.gd`
> Céu, sol (ou lua), névoa e cor do mar por hora do dia, com mistura entre duas horas
> (a espera no costão passa da noite para o dia). Usa o ShaderMaterial do mar da ilha.
> const SkyRig := preload("res://library/castaways/sky.gd")
> var sky := SkyRig.new(); add_child(sky)
> sky.build(island.ocean_material(), direção_horizontal_do_sol)
> sky.set_preset("dawn") # "dawn" | "day" | "dusk" | "night"
> sky.blend_presets("night", "dawn", k)
- `build(ocean: ShaderMaterial, sun_dir: Vector3) -> void`
- `set_preset(preset: String) -> void`
- `blend_presets(a_name: String, b_name: String, k: float) -> void`
`godot/library/castaways/template.gd`
> Cena 3D do documentário: os náufragos da Ilha das Cobras (reconstituição do caso de 2019).
> Elenilson (regata cinza, bermuda escura) e três companheiros, do naufrágio do pesqueiro ao
> resgate pela lancha de mergulho, no costão da ilha da biblioteca (res://library/island).
> Tudo depende só de (params, t): poses e barcos animados por tempo, sem física nem relógio.
> Modelo "castaways": params
> moment: "arrival" | "sinking" | "swimming" | "waiting" | "rescue" | "boarding" | "departure"
> camera: "medium" (padrão) | "close" (mais perto do Elenilson) | "wide" (mais aberto)
> variant: inteiro; muda o ângulo da câmera (lado, altura e ponto de vista)
> Tom sóbrio: sem cobra, sem helicóptero, sem navio militar; a lancha do resgate é civil.
- `setup(cfg: Dictionary, viewport_size: Vector2) -> void`
- `apply(t: float) -> void`
- `state_signature() -> String`
`godot/library/castaways/verify.gd`
> Verificação local: Godot --headless --path godot --script res://library/castaways/verify.gd
> Compara todos os nós articulados ao buscar tempos em ordens diferentes.
### `island`
**Ilha costeira** (doc3d): Ilha alongada com mata densa, costão de pedra e farol listrado num mar animado. Sobrevoo, chegada pelo mar, perto do farol ou rasante; de dia, entardecer ou noite. Outras cenas podem usá-la como cenário (params embedded: true, environment: false, sea_detail: true; métodos ground_at(x, z), sea_height(x, z, t), set_sea_state, set_sea_focus, rock_list e lighthouse_position()).
- param `shot` (select: orbit, approach, lighthouse, lowpass; padrão 'orbit')
- param `time` (select: day, sunset, night; padrão 'day')
- param `lighthouse` (bool; padrão True)
`godot/library/island/template.gd`
> Cena 3D do documentário: uma ilha costeira estilizada (terreno por ruído, mata densa,
> costão de pedra, farol) num mar animado por shader. Tudo depende só de (configuração, t):
> sementes fixas, o mar recebe o tempo de cena por uniform (não usa TIME), então o render
> é determinístico.
> Modelo "island": params
> shot: "orbit" (sobrevoo em volta) | "approach" (chega do mar) | "lighthouse" (perto do
> farol) | "lowpass" (rasante sobre a água) — padrão "orbit"
> time: "day" | "sunset" — padrão "day"
> lighthouse: true/false — padrão true
> variant: inteiro; muda ângulo inicial, sentido da câmera e (ímpar) a hora do dia
> Como cenário de outra cena (params embedded: true; environment: false se a outra cena faz
> céu e luz; sea_detail: true para tomadas rente à água): height_at / ground_at / ground_normal
> (terreno), sea_height(x, z, t) e set_sea_state(escala) (mar), set_sea_focus(x, z) (centro da
> malha fina do mar), rock_list() (pedras do costão) e lighthouse_position().
- `lighthouse_position() -> Vector3`: Para outras cenas da biblioteca: posição do farol (pé da torre) e altura do terreno.
- `ground_at(x: float, z: float) -> float`: Altura da superfície do terreno COMO DESENHADA (interpola os triângulos da malha, não o ruído): use para apoiar pés, joelhos e pedras sem flutuar nem afundar na rocha.
- `ground_normal(x: float, z: float) -> Vector3`: Normal do terreno desenhado em (x, z).
- `rock_list() -> Array`: Pedras do costão: lista de [centro (Vector3), raio horizontal].
- `sea_height(x: float, z: float, t: float) -> float`: Altura da água em (x, z) no instante t (as mesmas ondas do shader).
- `set_sea_state(scale: float) -> void`: Mar mais calmo (< 1) ou agitado (> 1). Padrão 1.
- `set_sea_focus(x: float, z: float) -> void`: Com params.sea_detail = true, o mar é uma malha radial fina no centro; mova o centro para perto da câmera a cada quadro (as ondas usam coordenada do mundo, então não "andam").
- `ocean_material() -> ShaderMaterial`
- `setup(cfg: Dictionary, viewport_size: Vector2) -> void`
- `apply(t: float) -> void`
- `state_signature() -> String`
- `height_at(x: float, z: float) -> float`: Altura do terreno (y = 0 é o nível do mar). A ilha é alongada, com uma crista central alta, encostas íngremes e costão de pedra que cai direto no mar.
+160
View File
@@ -0,0 +1,160 @@
# 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.