BlockReel

O que BlockReel faz?

Você dirige e constrói animações curtas em blocos como código e as renderiza para MP4 quadro a quadro. Nenhum modelo de vídeo está envolvido: cada quadro vem de uma cena Three.js dirigida por um storyboard JSON.

O fluxo é A → E. Não pule para o storyboard (D) antes de ter um briefing e uma lista de cenas (A–C). A qualidade vem da preparação e de olhar seus próprios quadros (E), não de mais JSON.

0. Inicialização (primeiro uso)

export BLOCKREEL_HOME="${BLOCKREEL_HOME:-$HOME/blockreel}"
[ -d "$BLOCKREEL_HOME" ] || git clone https://github.com/ViniciusNoetzold/mine-blockreel-skill- "$BLOCKREEL_HOME"
cd "$BLOCKREEL_HOME" && npm install && pip install -r requirements.txt
python tools/vanilla.py fetch    # Texturas ORIGINAIS do jogo + texturas de mob/baú/steve/alex -> work/vanilla/ (cache local, ~45 KB)
python tools/vanilla.py sounds   # Efeitos sonoros ORIGINAIS do jogo -> work/vanilla/sounds/ (cache local, ~1 MB, sem música)

Pareça com o jogo por padrão. A menos que o usuário peça texturas próprias, os filmes usam as texturas originais do cache (o motor as pega automaticamente; "textures": "builtin" desativa para as originais CC0). Mobs: /work/vanilla/entity/zombie.png, creeper.png, pig.png, spider.png; skins padrão steve.png / alex.png. Estes arquivos são da Mojang: eles ficam em work/ na máquina do usuário e nunca são commitados ou distribuídos (docs/LEGAL.md). Requer Node 20+, Python 3.11+, ffmpeg e Chrome/Chromium (defina CHROME_PATH ou execute python -m playwright install chromium). Trabalhe em $BLOCKREEL_HOME/films/<nome>/ ou na pasta onde o usuário iniciou; nunca escreva dentro de core/.

1. Guias (leia quando chegar nessa etapa)

Arquivo	Leia para
docs/PREPRODUCTION.md	etapas A–C: briefing, regras de pesquisa, templates para brief.md / research.md / shotlist.md
DIRECTOR.md	história, ritmo, câmera, atuação, sequências de ação
TECHNIQUE.md	pipeline, unidades, desempenho, extensão do motor
docs/STORYBOARD.md	o esquema exato de story.json (a única fonte da verdade para campos)
docs/QA.md	etapa E: o checklist e tools/qa.py
styles/<estilo>/STYLE.md	a aparência do estilo escolhido
docs/SKINS.md, docs/BLOCK-ATLAS.md, docs/RESOURCE-PACKS.md, docs/MOBS.md	trabalho com ativos
docs/COVERAGE.md	o que o motor pode e não pode animar ainda: verifique antes de prometer uma cena

Gêneros (escolha um primeiro, como um estilo)

Para uma abertura, comece com python tools/opening.py "<CANAL>" --out films/<nome> (nome em blocos, explosão, órbita, logotipo fixo, sons do jogo e uma trilha original) e depois adapte o story.json gerado (bloco, skin, tempo, cenas extras).

Leia docs/GENRES.md: abertura (introdução de canal do YouTube, 5-12 s), curta cinematográfico (um filme épico ou dramático de 20-60 s, ex. examples/ e a produção "Farol Negro"), episódio de série (personagens falando, comédia ou aventura, 1-5 min, o formato dos grandes canais de animação Minecraft). Cada gênero fixa ritmo, gramática de câmera, som e o que entregar; a premissa pode ser sobre qualquer coisa que o usuário quiser.

A. Briefing (faça no máximo UMA pergunta curta)

Extraia da solicitação: premissa (uma frase), tom (comédia, terror, épico, saudável…), duração (padrão 30–60 s), personagens (quais skins), cenário, estilo (veja DIRECTOR.md §8). Se algo estiver faltando e existir um padrão sensato, escolha-o e diga quais padrões você escolheu. Faça uma pergunta apenas quando a resposta mudar todo o filme (ex.: "você tem skins para esses personagens?"). Salve o resultado em films/<nome>/brief.md (template em docs/PREPRODUCTION.md).

B. Pesquisa (web, registrada com links)

Use WebSearch / WebFetch. Escreva tudo em films/<nome>/research.md, cada afirmação com um link:

1. Linguagem de animação para o tom: ritmo, câmera, timing de comédia / pavor de terror / escala épica.
2. Animação de personagem com corpo rígido: antecipação, ultrapassagem, acompanhamento, substitutos de squash, quadros de impacto.
3. Referências de cenário: arquitetura em blocos, paletas de cores, pontos de referência para o cenário escolhido.
4. Fontes gratuitas de música e efeitos sonoros: liste a fonte, o nome da faixa e sua licença. Nunca baixe ou adicione áudio sem a permissão do usuário; o usuário fornece os arquivos que vão para story.json.

Em seguida, adicione uma seção "Princípios a aplicar": 5–10 marcadores em suas próprias palavras, cada um vinculado a uma cena ou regra neste filme. Nunca copie cenas, personagens ou falas de outro trabalho; extraia princípios. Mantenha cópias locais de qualquer vídeo de referência apenas em work/ (gitignorado); apenas suas conclusões escritas vão para o repositório.

C. Roteiro e lista de cenas

Escreva films/<nome>/shotlist.md usando a tabela em DIRECTOR.md §7 (adicione uma coluna de intenção: o que a cena faz o espectador sentir ou saber). Verifique-a contra o briefing: uma ideia, batidas claras (configuração → escalada → virada → recompensa), formato de energia (quieto → alto → quieto), durações de cena de acordo com o tom, cada linha curta.

D. Construção

1. Ativos.
   • O usuário envia uma skin → use ESSA skin, sem alterações, no filme (copie-a para a pasta do filme, referencie-a em story.json). Execute python core/skin.py validate skin.png primeiro; se for 64x32 legada, convert para um novo arquivo. Skins que você criar devem passar por validate (PNG RGBA 64x64, camada base totalmente opaca, slim/classic detectada) para que também possam ser enviadas ao jogo real (página de skin do Java/inicializador).
   • Skin fornecida como screenshot / imagem redimensionada → python core/skin.py snap in.png out.png --crop x0,y0,x1,y1, depois validate. Se linhas estiverem faltando, diga isso e peça a imagem completa.
   • Skin como uma imagem 3D renderizada de um personagem → não pode ser transformada em textura de forma confiável. Diga isso.
   • Skin para criar ou melhorar → execute a skill blockreel-skins (/blockreel:blockreel-skins): pesquisa, plano de paleta, pintura em camadas, python tools/turntable.py skin.png --out tt.png e pelo menos 2 rodadas de revisão. Texturas de blocos/itens ou um pacote de recursos → blockreel-textures (core/tilecheck.py, tools/pack_preview.py, core/pack.py). Use os resultados dentro do filme (caminhos de skin em story.json / pasta blocks).
   • Mobs: docs/MOBS.md (você precisa das texturas do usuário; rigs em forma de creeper, porco, aranha e um zumbi via rig de jogador).
   • Sem skin → python core/skin.py make ... ou os originais em core/builtin/skins/.
   • Folha de blocos/itens → python core/atlas.py slice|label|faces (veja docs/BLOCK-ATLAS.md). Rotule apenas o que puder identificar.
2. Storyboard. Barras de letterbox e a vinheta (cantos escurecidos) vêm do estilo (letterbox, vignette); para uma entrega em 2.37:1, corte as barras no final (ffmpeg -vf crop=iw:iw/2.37) para que os players não mostrem bordas pretas, e desligue a vinheta (styleOverride.vignette: false) se o usuário não a quiser. Escreva story.json a partir da lista de cenas (docs/STORYBOARD.md). Comece do examples/*/story.json mais próximo. Os deslocamentos de câmera são no espaço do mundo: coloque a câmera na frente do rosto que você quer ver.
3. Still de teste. python tools/render.py story.json --frame <t> --out check.png e OLHE a imagem (enquadramento primeiro, depois luz, depois atuação).
4. Pré-visualização. python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5.
5. Som (não opcional). Construa cada arquivo para o qual o bloco audio aponta: efeitos originais do jogo de work/vanilla/sounds/ (explosões, portas, baús, mobs, acertos, passos, chuva, trovão, fogo), sons inventados apenas onde o jogo não tem nenhum (whoosh, riser: a música do jogo tem outros detentores de direitos), uma trilha ORIGINAL que siga o formato de energia (python tools/score.py --out music.wav --duration 30 --sections calm:0:7,build:7:15,battle:15:23,silence:23:26,dawn:26:30), e vozes: primeiro as gravações do usuário; caso contrário tools/voice.py (offline apenas: vozes neurais Piper baixadas com python tools/voice.py fetch, ex. --voice piper:faber, ou as vozes Windows OneCore daniel/maria com pausas SSML e ênfase), com um preset de personagem (hero, villain, monster, child, narrator, radio). Ajuste cada linha dentro de sua cena: meça-a, depois ajuste --rate ou a duração da cena. Veja make_audio.py no estilo films/ em docs/GENRES.md. python tools/audio.py story.json --out mix.wav, ouça, depois renderize com áudio (ou multiplexe o mix no render silencioso).
6. Render final. python tools/render.py story.json --out film.mp4. GL por software é cerca de 1 s/quadro a 960x540: informe ao usuário quanto tempo um filme longo levará.

E. Revisão de qualidade (OBRIGATÓRIA antes da entrega)

python tools/qa.py films/<nome>/story.json --out films/<nome>/qa

Ele renderiza pelo menos 8 quadros espalhados (abertura, cada mudança de cena, close-ups, final), constrói uma folha de contato e executa verificações automáticas (câmera dentro de um bloco, ator fora do quadro, rosto virado para longe da câmera, legenda cortada, cena mais longa que o limite para seu tom). Em seguida, abra cada imagem de quadro e olhe para ela e julgue o que o script não pode: buracos na skin, sombras estranhas, pose estranha, história confusa, ritmo. Corrija, re-renderize, repita até ficar limpo. Registre o resultado em films/<nome>/qa.md (template em docs/QA.md): o que você verificou, o que encontrou, o que corrigiu e o que não pôde verificar. Só então entregue film.mp4 mais a pasta do projeto.

Regras

• Nunca copie ativos do jogo (texturas, sons, fontes) para o repositório ou a pasta do filme, a menos que o usuário os tenha fornecido e possua os direitos. Use os built-in originais caso contrário. Veja docs/LEGAL.md.
• Não afirme que um recurso funciona se você não o executou. Se uma etapa de render ou ativo falhar, diga o que falhou.
• Use os recursos reais do motor (listados em docs/STORYBOARD.md). Se a cena precisar de algo marcado como ausente em docs/COVERAGE.md (ferramentas seguradas, escadas e cercas, mais mobs, clipes de sneak/swim/ride...), diga isso de antemão e ofereça a coisa mais próxima que existe; não finja com campos JSON não suportados (eles são silenciosamente ignorados).
• Verifique proporções em close-ups, não apenas em planos abertos (ombros alinhados com o tronco, cabeça diretamente no corpo, rostos legíveis).
• Mantenha skins/texturas do usuário intactas; escreva arquivos derivados ao lado deles com um novo nome.
• Tudo em films/ e work/ é gitignorado. Exemplos que acompanham o repositório ficam em examples/.