ViniciusNoetzold/blockreel

¿Qué hace blockreel?

Diriges y construyes animaciones cortas en estilo bloque como código, luego las renderizas a MP4 fotograma a fotograma. No hay ningún modelo de video involucrado: cada fotograma proviene de una escena de Three.js controlada por un storyboard JSON.

El flujo es A → E. No saltes al storyboard (D) antes de tener un briefing y una lista de tomas (A–C). La calidad viene de la preparación y de mirar tus propios fotogramas (E), no de más JSON.

0. Inicialización (primer 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 ORIGINALES del juego + mobs/cofre/steve/alex -> work/vanilla/ (caché local, ~45 KB)
python tools/vanilla.py sounds   # Efectos de sonido ORIGINALES del juego -> work/vanilla/sounds/ (caché local, ~1 MB, sin música)

Se ve como el juego por defecto. A menos que el usuario pida sus propias texturas, las películas usan las texturas originales de la caché (el motor las selecciona automáticamente; "textures": "builtin" opta por las originales CC0). Mobs: /work/vanilla/entity/zombie.png, creeper.png, pig.png, spider.png; skins por defecto steve.png / alex.png. Estos archivos son de Mojang: permanecen en work/ en la máquina del usuario y nunca se confirman ni se envían (docs/LEGAL.md). Requiere Node 20+, Python 3.11+, ffmpeg y Chrome/Chromium (configura CHROME_PATH, o ejecuta python -m playwright install chromium). Trabaja en $BLOCKREEL_HOME/films/<nombre>/ o en la carpeta donde el usuario inició; nunca escribas dentro de core/.

1. Guías (léelas cuando llegues a ese paso)

Archivo	Léelo para
docs/PREPRODUCTION.md	pasos A–C: briefing, reglas de investigación, plantillas para brief.md / research.md / shotlist.md
DIRECTOR.md	historia, ritmo, cámara, actuación, secuencias de acción
TECHNIQUE.md	pipeline, unidades, rendimiento, extender el motor
docs/STORYBOARD.md	el esquema exacto de story.json (la única fuente de verdad para los campos)
docs/QA.md	paso E: la lista de verificación y tools/qa.py
styles/<estilo>/STYLE.md	el aspecto del estilo elegido
docs/SKINS.md, docs/BLOCK-ATLAS.md, docs/RESOURCE-PACKS.md, docs/MOBS.md	trabajo con assets
docs/COVERAGE.md	lo que el motor puede y no puede animar todavía: verifícalo antes de prometer una escena

Géneros (elige uno primero, como un estilo)

Para una apertura, comienza desde python tools/opening.py "<CANAL>" --out films/<nombre> (nombre en bloques, explosión, órbita, logotipo sostenido, sonidos del juego y una partitura original) y luego adapta el story.json generado (bloque, skin, tiempo, tomas adicionales).

Lee docs/GENRES.md: apertura (intro de canal de YouTube, 5-12 s), corto cinematográfico (una película épica o dramática de 20-60 s, ej. examples/ y la producción "Farol Negro"), episodio de serie (personajes hablando, comedia o aventura, 1-5 min, el formato de los grandes canales de animación de Minecraft). Cada género fija el ritmo, la gramática de cámara, el sonido y lo que hay que entregar; la premisa puede ser sobre cualquier cosa que el usuario quiera.

A. Briefing (pregunta como máximo UNA pregunta corta)

Extrae de la solicitud: premisa (una frase), tono (comedia, terror, épico, conmovedor…), duración (por defecto 30–60 s), personajes (qué skins), escenario, estilo (ver DIRECTOR.md §8). Si falta algo y existe un valor predeterminado razonable, elígelo y di qué valores predeterminados elegiste. Pregunta solo cuando la respuesta cambie toda la película (ej. "¿tienes skins para estos personajes?"). Guarda el resultado en films/<nombre>/brief.md (plantilla en docs/PREPRODUCTION.md).

B. Investigación (web, registrada con enlaces)

Usa WebSearch / WebFetch. Escribe todo en films/<nombre>/research.md, cada afirmación con un enlace:

1. Lenguaje de animación para el tono: ritmo, cámara, sincronización cómica / terror / escala épica.
2. Animación de personajes con cuerpo rígido: anticipación, exceso, seguimiento, sustitutos de squash, fotogramas de impacto.
3. Referencias del escenario: arquitectura de bloques, paletas de colores, puntos de referencia para el escenario elegido.
4. Fuentes de música y efectos de sonido gratuitas: enumera la fuente, el nombre de la pista y su licencia. Nunca descargues ni agregues audio sin el permiso del usuario; el usuario proporciona los archivos que van en story.json.

Luego agrega una sección "Principios a aplicar": de 5 a 10 viñetas con tus propias palabras, cada una vinculada a una toma o regla de esta película. Nunca copies escenas, personajes o líneas de otro trabajo; extrae principios. Mantén copias locales de cualquier video de referencia solo en work/ (gitignorado); solo tus conclusiones escritas van en el repositorio.

C. Guion y lista de tomas

Escribe films/<nombre>/shotlist.md usando la tabla de DIRECTOR.md §7 (agrega una columna de intención: qué hace sentir o saber la toma al espectador). Verifícalo contra el briefing: una idea, ritmos claros (planteamiento → escalada → giro → desenlace), forma de la energía (tranquilo → alto → tranquilo), duración de las tomas según el tono, cada línea corta.

D. Construcción

1. Assets.
   • El usuario envía un skin → usa ESE skin, sin cambios, en la película (cópialo en la carpeta de la película, referéncialo en story.json). python core/skin.py validate skin.png primero; si es legacy 64x32, convert a un nuevo archivo. Los skins que crees deben pasar validate (PNG RGBA 64x64, capa base completamente opaca, slim/classic detectado) para que también se puedan subir al juego real (página de skin de Java/launcher).
   • Skin dado como captura de pantalla / imagen escalada → python core/skin.py snap in.png out.png --crop x0,y0,x1,y1, luego validate. Si faltan filas, dilo y pide la imagen completa.
   • Skin como imagen 3D renderizada de un personaje → no se puede convertir en una textura de manera confiable. Dilo claramente.
   • Skin a crear o mejorar → ejecuta la habilidad blockreel-skins (/blockreel:blockreel-skins): investigación, plan de paleta, pintura por capas, python tools/turntable.py skin.png --out tt.png y al menos 2 rondas de revisión. Texturas de bloques/objetos o un pack de recursos → blockreel-textures (core/tilecheck.py, tools/pack_preview.py, core/pack.py). Usa los resultados dentro de la película (rutas de skin en story.json / carpeta blocks).
   • Mobs: docs/MOBS.md (necesitas las texturas del usuario; rigs con forma de creeper, cerdo, araña y un zombie mediante el rig de jugador).
   • Sin skin → python core/skin.py make ... o los originales en core/builtin/skins/.
   • Lámina de bloques/objetos → python core/atlas.py slice|label|faces (ver docs/BLOCK-ATLAS.md). Etiqueta solo lo que puedas identificar.
2. Storyboard. Las barras de letterbox y la viñeta (esquinas oscurecidas) provienen del estilo (letterbox, vignette); para una entrega en 2.37:1 recorta las barras al final (ffmpeg -vf crop=iw:iw/2.37) para que los reproductores no muestren barras negras, y desactiva la viñeta (styleOverride.vignette: false) si el usuario no la quiere. Escribe story.json a partir de la lista de tomas (docs/STORYBOARD.md). Comienza desde el examples/*/story.json más cercano. Los desplazamientos de cámara son en espacio mundial: coloca la cámara frente a la cara que quieres ver.
3. Fotogramas de prueba. python tools/render.py story.json --frame <t> --out check.png y MIRA la imagen (primero el encuadre, luego la luz, luego la actuación).
4. Vista previa. python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5.
5. Sonido (no opcional). Construye cada archivo al que apunte el bloque audio: efectos originales del juego desde work/vanilla/sounds/ (explosiones, puertas, cofres, mobs, golpes, pasos, lluvia, truenos, fuego), sonidos inventados solo donde el juego no tenga ninguno (whoosh, riser: la música del juego tiene otros titulares de derechos), una partitura ORIGINAL que siga la forma de la energía (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), y voces: primero las grabaciones del usuario; de lo contrario tools/voice.py (solo sin conexión: voces neuronales Piper obtenidas con python tools/voice.py fetch, ej. --voice piper:faber, o las voces de Windows OneCore daniel/maria con pausas y énfasis SSML), con un preset de personaje (hero, villain, monster, child, narrator, radio). Ajusta cada línea dentro de su toma: mídela, luego ajusta --rate o la duración de la toma. Consulta el estilo films/-make_audio.py en docs/GENRES.md. python tools/audio.py story.json --out mix.wav, escucha, luego renderiza con audio (o multiplexa la mezcla en el renderizado silencioso).
6. Renderizado final. python tools/render.py story.json --out film.mp4. Software GL es aproximadamente 1 s/fotograma a 960x540: informa al usuario cuánto tiempo llevará una película larga.

E. Revisión de calidad (OBLIGATORIA antes de la entrega)

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

Renderiza al menos 8 fotogramas distribuidos (apertura, cada cambio de toma, primeros planos, final), construye una hoja de contactos y ejecuta comprobaciones automáticas (cámara dentro de un bloque, actor fuera de cuadro, cara mirando lejos de la cámara, subtítulo recortado, toma más larga que el límite para su tono). Luego abre cada imagen de fotograma y mírala y juzga lo que el script no puede: agujeros en el skin, sombras extrañas, pose incómoda, historia poco clara, ritmo. Corrige, vuelve a renderizar, repite hasta que esté limpio. Registra el resultado en films/<nombre>/qa.md (plantilla en docs/QA.md): qué comprobaste, qué encontraste, qué corregiste, y qué no pudiste verificar. Solo entonces entrega film.mp4 junto con la carpeta del proyecto.

Reglas

• Nunca copies assets del juego (texturas, sonidos, fuentes) en el repositorio o la carpeta de la película a menos que el usuario los haya proporcionado y los posea. Usa los incorporados originales en caso contrario. Consulta docs/LEGAL.md.
• No afirmes que una característica funciona si no la ejecutaste. Si un paso de renderizado o asset falla, di qué falló.
• Usa las características reales del motor (listadas en docs/STORYBOARD.md). Si la escena necesita algo marcado como faltante en docs/COVERAGE.md (herramientas sostenidas, escaleras y vallas, más mobs, clips de agacharse/nadar/montar...), dilo de inmediato y ofrece lo más cercano que exista; no lo finjas con campos JSON no soportados (se ignoran silenciosamente).
• Verifica las proporciones en primeros planos, no solo en tomas amplias (hombros alineados con el torso, cabeza directamente sobre el cuerpo, caras legibles).
• Mantén los skins/texturas del usuario intactos; escribe archivos derivados junto a ellos con un nombre nuevo.
• Todo lo que esté en films/ y work/ está en gitignore. Los ejemplos que se envían con el repositorio viven en examples/.