ViniciusNoetzold/blockreel

Was macht blockreel?

Du inszenierst und baust kurze Block-Animationen als Code und renderst sie dann Frame für Frame als MP4. Es wird kein Videomodell verwendet: Jeder Frame stammt von einer Three.js-Szene, die von einem JSON-Storyboard gesteuert wird.

Der Ablauf ist A → E. Springe nicht zum Storyboard (D), bevor du ein Briefing und eine Shot-Liste (A–C) hast. Qualität entsteht durch Vorbereitung und durch das Betrachten deiner eigenen Frames (E), nicht durch mehr JSON.

0. Bootstrap (erste Verwendung)

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    # ORIGINELLE Spieltexturen + Mob/Truhe/Steve/Alex-Texturen -> work/vanilla/ (lokaler Cache, ~45 KB)
python tools/vanilla.py sounds   # ORIGINELLE Spiel-Soundeffekte -> work/vanilla/sounds/ (lokaler Cache, ~1 MB, keine Musik)

Sieht standardmäßig wie das Spiel aus. Sofern der Benutzer nicht nach eigenen Texturen verlangt, verwenden Filme die originalen Texturen aus dem Cache (die Engine erkennt sie automatisch; "textures": "builtin" deaktiviert sie zugunsten der CC0-Originale). Mobs: /work/vanilla/entity/zombie.png, creeper.png, pig.png, spider.png; Standardskins steve.png / alex.png. Diese Dateien gehören Mojang: Sie verbleiben auf dem Rechner des Benutzers in work/ und werden niemals committet oder ausgeliefert (docs/LEGAL.md). Erfordert Node 20+, Python 3.11+, ffmpeg und Chrome/Chromium (CHROME_PATH setzen oder python -m playwright install chromium ausführen). Arbeite in $BLOCKREEL_HOME/films/<name>/ oder in dem Ordner, in dem der Benutzer gestartet ist; schreibe niemals in core/.

1. Guides (lesen, wenn du diesen Schritt erreichst)

Datei	Lesen für
docs/PREPRODUCTION.md	Schritte A–C: Briefing, Rechercheregeln, Vorlagen für brief.md / research.md / shotlist.md
DIRECTOR.md	Geschichte, Rhythmus, Kamera, Schauspiel, Actionszenen
TECHNIQUE.md	Pipeline, Einheiten, Performance, Erweiterung der Engine
docs/STORYBOARD.md	Das exakte story.json-Schema (die einzige Quelle der Wahrheit für Felder)
docs/QA.md	Schritt E: Die Checkliste und tools/qa.py
styles/<style>/STYLE.md	Den Look des gewählten Stils
docs/SKINS.md, docs/BLOCK-ATLAS.md, docs/RESOURCE-PACKS.md, docs/MOBS.md	Asset-Arbeit
docs/COVERAGE.md	Was die Engine bereits animieren kann und was nicht: Überprüfe es, bevor du eine Szene versprichst

Genres (wähle zuerst eines aus, wie einen Stil)

Für ein Opening starte mit python tools/opening.py "<CHANNEL>" --out films/<name> (Name in Blöcken, Blast, Orbit, Logo-Haltepunkt, Spiel-Sounds und eine originelle Filmmusik) und passe dann das generierte story.json an (Block, Skin, Timing, zusätzliche Shots).

Lies docs/GENRES.md: Opening (YouTube-Kanal-Intro, 5-12 s), Kinokurzfilm (ein epischer oder dramatischer 20-60 s Film, z. B. examples/ und die Produktion „Farol Negro“), Serienepisode (sprechende Charaktere, Comedy oder Abenteuer, 1-5 min, das Format der großen Minecraft-Animationskanäle). Jedes Genre definiert Tempo, Kameragrammatik, Sound und was ausgeliefert wird; die Prämisse kann sich auf alles beziehen, was der Benutzer möchte.

A. Briefing (höchstens EINE kurze Frage stellen)

Extrahiere aus der Anfrage: Prämisse (ein Satz), Ton (Comedy, Horror, episch, herzerwärmend…), Länge (Standard 30–60 s), Charaktere (welche Skins), Schauplatz, Stil (siehe DIRECTOR.md §8). Fehlt etwas und es gibt eine sinnvolle Voreinstellung, wähle sie und nenne welche Voreinstellungen du gewählt hast. Stelle nur eine Frage, wenn die Antwort den gesamten Film verändert (z. B. „Hast du Skins für diese Charaktere?“). Speichere das Ergebnis in films/<name>/brief.md (Vorlage in docs/PREPRODUCTION.md).

B. Recherche (Web, mit Links dokumentiert)

Verwende WebSearch / WebFetch. Schreibe alles in films/<name>/research.md, jede Behauptung mit einem Link:

1. Animationssprache für den Ton: Tempo, Kamera, Comedy-Timing / Horror-Beklommenheit / epische Größe.
2. Starrkörper-Charakteranimation: Antizipation, Überschießen, Durchschwingen, Quetschersatz, Impact-Frames.
3. Schauplatz-Referenzen: Blockarchitektur, Farbpaletten, Wahrzeichen für den gewählten Schauplatz.
4. Kostenlose Musik- und Soundeffekt-Quellen: Liste die Quelle, den Tracknamen und seine Lizenz auf. Lade niemals Audio herunter oder füge es ohne Erlaubnis des Benutzers hinzu; der Benutzer liefert die Dateien, die in story.json eingehen.

Füge dann einen Abschnitt „Anzuwendende Prinzipien“ hinzu: 5–10 Punkte in eigenen Worten, die jeweils mit einem Shot oder einer Regel in diesem Film verknüpft sind. Kopiere niemals Szenen, Charaktere oder Zeilen aus fremden Werken; extrahiere Prinzipien. Behalte lokale Kopien von Referenzvideos nur in work/ (gitignoriert); nur deine schriftlichen Schlussfolgerungen kommen in das Repository.

C. Drehbuch und Shot-Liste

Schreibe films/<name>/shotlist.md unter Verwendung der Tabelle aus DIRECTOR.md §7 (füge eine Absichts-Spalte hinzu: was der Shot den Zuschauer fühlen oder wissen lassen soll). Überprüfe sie gegen das Briefing: eine Idee, klare Beats (Aufbau → Steigerung → Wendung → Auflösung), Energieform (leise → laut → leise), Shotlängen entsprechend dem Ton, jede Zeile kurz.

D. Bauen

1. Assets.
   • Der Benutzer sendet einen Skin → verwende DIESEN Skin, unverändert, im Film (kopiere ihn in den Filmordner, referenziere ihn in story.json). Führe zuerst python core/skin.py validate skin.png aus; falls Legacy 64x32, convert zu einer neuen Datei. Skins, die du erstellst, müssen die validate-Prüfung bestehen (64x64 RGBA PNG, Basisschicht vollständig deckend, slim/classic erkannt), damit sie auch in das echte Spiel hochgeladen werden können (Java-Skin-Seite/Launcher).
   • Skin als Screenshot / skaliertes Bild gegeben → python core/skin.py snap in.png out.png --crop x0,y0,x1,y1, dann validate. Wenn Zeilen fehlen, sage dies und bitte um das vollständige Bild.
   • Skin als gerendertes 3D-Bild eines Charakters → kann nicht zuverlässig in eine Textur umgewandelt werden. Sage dies.
   • Skin zu erstellen oder zu verbessern → führe die blockreel-skins-Fähigkeit aus (/blockreel:blockreel-skins): Recherche, Farbplan, schichtweises Malen, python tools/turntable.py skin.png --out tt.png und mindestens 2 durchgesehene Runden. Block-/Gegenstandstexturen oder ein Resource Pack → blockreel-textures (core/tilecheck.py, tools/pack_preview.py, core/pack.py). Verwende die Ergebnisse innerhalb des Films (story.json-Skin-Pfade / blocks-Ordner).
   • Mobs: docs/MOBS.md (du benötigst die Texturen des Benutzers; Creeper-, Schwein-, Spinnen-förmige Rigs und einen Zombie über das Spieler-Rig).
   • Kein Skin → python core/skin.py make ... oder die Originale in core/builtin/skins/.
   • Blöcke/Gegenstände als Blatt → python core/atlas.py slice|label|faces (siehe docs/BLOCK-ATLAS.md). Beschrifte nur, was du identifizieren kannst.
2. Storyboard. Letterbox-Balken und die Vignette (abgedunkelte Ecken) stammen aus dem Stil (letterbox, vignette); für eine 2.37:1-Lieferung schneide die Balken am Ende weg (ffmpeg -vf crop=iw:iw/2.37), damit Player keine schwarzen Balken anzeigen, und deaktiviere die Vignette (styleOverride.vignette: false), wenn der Benutzer sie nicht wünscht. Schreibe story.json aus der Shot-Liste (docs/STORYBOARD.md). Beginne mit dem nächstgelegenen examples/*/story.json. Kamera-Offsets sind weltraumbezogen: platziere die Kamera vor dem Gesicht, das du sehen möchtest.
3. Test-Stills. python tools/render.py story.json --frame <t> --out check.png und SCHAU DIR das Bild an (zuerst Bildausschnitt, dann Licht, dann Schauspiel).
4. Vorschau. python tools/render.py story.json --out preview.mp4 --fps 12 --scale 0.5.
5. Sound (nicht optional). Baue jede Datei, auf die der audio-Block verweist: originale Spiel-Effekte aus work/vanilla/sounds/ (Explosionen, Türen, Truhen, Mobs, Treffer, Schritte, Regen, Donner, Feuer), nur erfundene Sounds, wo das Spiel keine hat (Whoosch, Risers: Die Musik des Spiels hat andere Rechteinhaber), eine ORIGINELLE Filmmusik, die der Energieform folgt (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), und Sprachausgabe: zuerst die Aufnahmen des Benutzers; andernfalls tools/voice.py (nur offline: Piper-Neuralstimmen, bezogen mit python tools/voice.py fetch, z. B. --voice piper:faber, oder die Windows-OneCore-Stimmen daniel/maria mit SSML-Pausen und Betonung), mit einem Charakter-Preset (hero, villain, monster, child, narrator, radio). Passe jede Zeile in ihren Shot ein: miss sie, dann passe --rate oder die Shotlänge an. Siehe films/-artiges make_audio.py in docs/GENRES.md. python tools/audio.py story.json --out mix.wav, höre zu, dann rendere mit Audio (oder mische den Mix in den stummen Render).
6. Finaler Render. python tools/render.py story.json --out film.mp4. Software-GL liegt bei etwa 1 s/Frame bei 960x540: teile dem Benutzer mit, wie lange ein langer Film dauern wird.

E. Qualitätsprüfung (VERPFLICHTEND vor der Auslieferung)

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

Es rendert mindestens 8 verteilte Frames (Eröffnung, jeder Shot-Wechsel, Nahaufnahmen, Ende), erstellt ein Kontaktblatt und führt automatische Prüfungen durch (Kamera innerhalb eines Blocks, Schauspieler außerhalb des Bildes, Gesicht von der Kamera abgewandt, Untertitel abgeschnitten, Shot länger als das Limit für seinen Ton). Dann öffne jedes Frame-Bild und schaue es dir an und beurteile, was das Skript nicht kann: Skin-Löcher, seltsame Schatten, unbeholfene Pose, unklare Geschichte, Tempo. Korrigiere, rendere erneut, wiederhole bis sauber. Dokumentiere das Ergebnis in films/<name>/qa.md (Vorlage in docs/QA.md): was du überprüft hast, was du gefunden hast, was du korrigiert hast und was du nicht verifizieren konntest. Erst dann liefere film.mp4 plus den Projektordner aus.

Regeln

• Kopiere niemals Spiel-Assets (Texturen, Sounds, Schriftarten) in das Repository oder den Filmordner, es sei denn, der Benutzer hat sie geliefert und besitzt sie. Verwende andernfalls die originalen Built-ins. Siehe docs/LEGAL.md.
• Behaupte nicht, dass eine Funktion funktioniert, wenn du sie nicht ausgeführt hast. Wenn ein Render- oder Asset-Schritt fehlschlägt, sage, was fehlgeschlagen ist.
• Verwende die echten Funktionen der Engine (aufgelistet in docs/STORYBOARD.md). Wenn die Szene etwas benötigt, das in docs/COVERAGE.md als fehlend markiert ist (gehaltene Werkzeuge, Treppen und Zäune, weitere Mobs, Sneak/Swim/Ride-Clips...), sage dies gleich zu Beginn und biete das Nächstliegende an, das existiert; täusche es nicht mit nicht unterstützten JSON-Feldern vor (sie werden still ignoriert).
• Überprüfe Proportionen in Nahaufnahmen, nicht nur in Totalen (Schultern bündig mit dem Oberkörper, Kopf direkt auf dem Körper, Gesichter lesbar).
• Lasse Benutzer-Skins/-Texturen unberührt; schreibe abgeleitete Dateien daneben mit einem neuen Namen.
• Alles unter films/ und work/ ist gitignoriert. Beispiele, die mit dem Repository ausgeliefert werden, befinden sich in examples/.