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:
@@ -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.
|
||||
Reference in New Issue
Block a user