ViniciusNoetzold/blockreel

Que fait blockreel ?

Vous dirigez et construisez de courtes animations en blocs sous forme de code, puis les rendez en MP4 image par image. Aucun modèle vidéo n'est impliqué : chaque image provient d'une scène Three.js pilotée par un storyboard JSON.

Le flux est A → E. Ne sautez pas au storyboard (D) avant d'avoir un brief et une liste de plans (A–C). La qualité vient de la préparation et de l'observation de vos propres images (E), pas de davantage de JSON.

0. Amorçage (première utilisation)

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    # Textures ORIGINALES du jeu + textures mob/coffre/steve/alex -> work/vanilla/ (cache local, ~45 Ko)
python tools/vanilla.py sounds   # Effets sonores ORIGINAUX du jeu -> work/vanilla/sounds/ (cache local, ~1 Mo, pas de musique)

Ressemblez au jeu par défaut. Sauf si l'utilisateur demande ses propres textures, les films utilisent les textures originales du cache (le moteur les récupère automatiquement ; "textures": "builtin" opte pour les originaux CC0). Mobs : /work/vanilla/entity/zombie.png, creeper.png, pig.png, spider.png ; skins par défaut steve.png / alex.png. Ces fichiers appartiennent à Mojang : ils restent dans work/ sur la machine de l'utilisateur et ne sont jamais commités ou distribués (docs/LEGAL.md). Nécessite Node 20+, Python 3.11+, ffmpeg et Chrome/Chromium (définissez CHROME_PATH, ou exécutez python -m playwright install chromium). Travaillez dans $BLOCKREEL_HOME/films/<name>/ ou dans le dossier où l'utilisateur a démarré ; n'écrivez jamais dans core/.

1. Guides (à lire lorsque vous atteignez cette étape)

Fichier	À lire pour
docs/PREPRODUCTION.md	étapes A–C : brief, règles de recherche, modèles pour brief.md / research.md / shotlist.md
DIRECTOR.md	histoire, rythme, caméra, jeu d'acteur, séquences d'action
TECHNIQUE.md	pipeline, unités, performances, extension du moteur
docs/STORYBOARD.md	le schéma exact de story.json (la seule source de vérité pour les champs)
docs/QA.md	étape E : la checklist et tools/qa.py
styles/<style>/STYLE.md	l'apparence du style choisi
docs/SKINS.md, docs/BLOCK-ATLAS.md, docs/RESOURCE-PACKS.md, docs/MOBS.md	travail sur les assets
docs/COVERAGE.md	ce que le moteur peut et ne peut pas encore animer : vérifiez-le avant de promettre une scène

Genres (choisissez-en d'abord un, comme un style)

Pour une ouverture, partez de python tools/opening.py "<CHAÎNE>" --out films/<name> (nom en blocs, explosion, orbite, maintien du logo, sons du jeu et musique originale) puis adaptez le story.json généré (bloc, skin, timing, plans supplémentaires).

Lisez docs/GENRES.md : ouverture (intro de chaîne YouTube, 5-12 s), court métrage cinématographique (film épique ou dramatique de 20-60 s, p. ex. examples/ et la production "Farol Negro"), épisode de série (personnages qui parlent, comédie ou aventure, 1-5 min, le format des grandes chaînes d'animation Minecraft). Chaque genre fixe le rythme, la grammaire de la caméra, le son et ce qu'il faut livrer ; le postulat peut porter sur n'importe quoi, selon le souhait de l'utilisateur.

A. Brief (posez au plus UNE question courte)

Extrayez de la demande : postulat (une phrase), ton (comédie, horreur, épique, réconfortant…), durée (par défaut 30–60 s), personnages (quels skins), cadre, style (voir DIRECTOR.md §8). Si quelque chose manque et qu'une valeur par défaut raisonnable existe, choisissez-la et dites quelles valeurs par défaut vous avez choisies. Ne posez une question que lorsque la réponse change tout le film (p. ex. "avez-vous des skins pour ces personnages ?"). Enregistrez le résultat dans films/<name>/brief.md (modèle dans docs/PREPRODUCTION.md).

B. Recherche (web, enregistrée avec liens)

Utilisez WebSearch / WebFetch. Écrivez tout dans films/<name>/research.md, chaque affirmation avec un lien :

1. Langage d'animation pour le ton : rythme, caméra, timing comique / horreur angoissante / échelle épique.
2. Animation de personnages rigides : anticipation, dépassement, suivi, substituts d'écrasement, images d'impact.
3. Références de décor : architecture en blocs, palettes de couleurs, points de repère pour le cadre choisi.
4. Sources de musique et d'effets sonores libres de droits : listez la source, le nom du morceau et sa licence. Ne téléchargez ni n'ajoutez jamais de son sans la permission de l'utilisateur ; l'utilisateur fournit les fichiers qui vont dans story.json.

Ajoutez ensuite une section "Principes à appliquer" : 5 à 10 puces dans vos propres mots, chacune liée à un plan ou une règle de ce film. Ne copiez jamais les scènes, personnages ou répliques d'une autre œuvre ; extrayez des principes. Conservez des copies locales de toute vidéo de référence uniquement dans work/ (gitignoré) ; seules vos conclusions écrites vont dans le dépôt.

C. Script et liste de plans

Écrivez films/<name>/shotlist.md en utilisant le tableau dans DIRECTOR.md §7 (ajoutez une colonne intention : ce que le plan fait ressentir ou savoir au spectateur). Vérifiez-le par rapport au brief : une idée, des rythmes clairs (installation → escalade → tournant → conclusion), forme d'énergie (calme → fort → calme), longueurs de plans selon le ton, chaque réplique courte.

D. Construction

1. Assets.
   • L'utilisateur envoie un skin → utilisez CE skin, inchangé, dans le film (copiez-le dans le dossier du film, référencez-le dans story.json). python core/skin.py validate skin.png d'abord ; si héritage 64x32, convert vers un nouveau fichier. Les skins que vous créez doivent passer validate (PNG 64x64 RGBA, couche de base entièrement opaque, slim/classic détecté) afin de pouvoir aussi être téléversés vers le vrai jeu (page de skin Java/lanceur).
   • Skin donné sous forme de capture d'écran / image redimensionnée → python core/skin.py snap in.png out.png --crop x0,y0,x1,y1, puis validate. Si des rangées manquent, dites-le et demandez l'image complète.
   • Skin sous forme d'image 3D rendue d'un personnage → ne peut pas être transformé en texture fiablement. Dites-le.
   • Skin à créer ou améliorer → exécutez la compétence blockreel-skins (/blockreel:blockreel-skins) : recherche, plan de palette, peinture en couches, python tools/turntable.py skin.png --out tt.png et au moins 2 passages examinés. Textures de blocs/objets ou pack de ressources → blockreel-textures (core/tilecheck.py, tools/pack_preview.py, core/pack.py). Utilisez les résultats dans le film (chemins de skin dans story.json / dossier blocks).
   • Mobs : docs/MOBS.md (vous avez besoin des textures de l'utilisateur ; squelettes en forme de creeper, cochon, araignée et un zombie via le squelette de joueur).
   • Pas de skin → python core/skin.py make ... ou les originaux dans core/builtin/skins/.
   • Planche de blocs/objets → python core/atlas.py slice|label|faces (voir docs/BLOCK-ATLAS.md). Étiquetez uniquement ce que vous pouvez identifier.
2. Storyboard. Les barres letterbox et la vignette (coins assombris) proviennent du style (letterbox, vignette) ; pour un recadrage 2.37:1, coupez les barres à la fin (ffmpeg -vf crop=iw:iw/2.37) afin que les lecteurs n'affichent pas de barres noires, et désactivez la vignette (styleOverride.vignette: false) si l'utilisateur ne la souhaite pas. Écrivez story.json à partir de la liste de plans (docs/STORYBOARD.md). Commencez par le examples/*/story.json le plus proche. Les décalages de caméra sont dans l'espace monde : placez la caméra devant le visage que vous voulez voir.
3. Images de test. python tools/render.py story.json --frame <t> --out check.png et REGARDEZ l'image (cadrage d'abord, puis lumière, puis jeu d'acteur).
4. Aperçu. python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5.
5. Son (non optionnel). Construisez chaque fichier pointé par le bloc audio : effets originaux du jeu depuis work/vanilla/sounds/ (explosions, portes, coffres, mobs, coups, pas, pluie, tonnerre, feu), sons fabriqués uniquement là où le jeu n'en a pas (whoosh, riser : la musique du jeu a d'autres ayants droit), une musique ORIGINALE qui suit la forme d'énergie (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), et des voix : les enregistrements de l'utilisateur d'abord ; sinon tools/voice.py (hors ligne uniquement : voix neurales Piper récupérées avec python tools/voice.py fetch, p. ex. --voice piper:faber, ou les voix Windows OneCore daniel/maria avec pauses SSML et emphase), avec un préréglage de personnage (hero, villain, monster, child, narrator, radio). Adaptez chaque réplique à l'intérieur de son plan : mesurez-la, puis ajustez --rate ou la durée du plan. Voir films/-style make_audio.py dans docs/GENRES.md. python tools/audio.py story.json --out mix.wav, écoutez, puis effectuez le rendu avec l'audio (ou muxez le mix dans le rendu silencieux).
6. Rendu final. python tools/render.py story.json --out film.mp4. Le rendu logiciel GL est d'environ 1 s/image à 960x540 : dites à l'utilisateur combien de temps prendra un long film.

E. Revue de qualité (OBLIGATOIRE avant la livraison)

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

Il rend au moins 8 images réparties (ouverture, chaque changement de plan, gros plans, fin), construit une planche contact, et exécute les vérifications automatiques (caméra à l'intérieur d'un bloc, acteur hors cadre, visage tourné loin de la caméra, sous-titre coupé, plan plus long que la limite pour son ton). Ensuite ouvrez chaque image et regardez-la et jugez ce que le script ne peut pas : trous dans le skin, ombres bizarres, pose maladroite, histoire floue, rythme. Corrigez, re-rendez, répétez jusqu'à ce que ce soit propre. Enregistrez le résultat dans films/<name>/qa.md (modèle dans docs/QA.md) : ce que vous avez vérifié, ce que vous avez trouvé, ce que vous avez corrigé, et ce que vous n'avez pas pu vérifier. Ce n'est qu'après cela que vous livrez film.mp4 plus le dossier du projet.

Règles

• Ne copiez jamais les assets du jeu (textures, sons, polices) dans le dépôt ou le dossier du film, sauf si l'utilisateur les a fournis et en possède les droits. Utilisez sinon les originaux intégrés. Voir docs/LEGAL.md.
• Ne prétendez pas qu'une fonctionnalité fonctionne si vous ne l'avez pas exécutée. Si une étape de rendu ou d'asset échoue, dites ce qui a échoué.
• Utilisez les vraies fonctionnalités du moteur (listées dans docs/STORYBOARD.md). Si la scène nécessite quelque chose marqué comme manquant dans docs/COVERAGE.md (outils tenus, escaliers et clôtures, plus de mobs, clips sneak/ nage/monte...), dites-le d'emblée et proposez la chose la plus proche qui existe ; ne le simulez pas avec des champs JSON non supportés (ils sont ignorés silencieusement).
• Vérifiez les proportions dans les gros plans, pas seulement les plans larges (épaules alignées avec le torse, tête directement sur le corps, visages lisibles).
• Laissez les skins/textures de l'utilisateur intacts ; écrivez les fichiers dérivés à côté d'eux avec un nouveau nom.
• Tout ce qui se trouve sous films/ et work/ est gitignoré. Les exemples livrés avec le dépôt se trouvent dans examples/.