CommunityBildgithub.com

blender-gamepipe

Wandelt Blender-Assets (Bäume, Gras, Steine, Props, Gebäude) und prozedurale PBR-Texturen in verifizierte, spielbereite GLB/Textur-Sets mit LODs und KTX2/Meshopt-Kompression um und weist nach, dass sie in three.js rendern.

Was ist blender-gamepipe?

blender-gamepipe ist eine deterministische Pipeline für Blender, die Assets durch die Phasen Spezifikation → Linting → Build → Validierung → Export → GLB-Inspektion → Engine-Prüfung führt. Der Agent liefert Urteile (Rezepte, Korrekturen, künstlerische Leitung), die Skripte stellen sicher, dass nichts ausgeliefert wird, bevor nicht alle Prüfungen bestanden sind. Die Pipeline unterstützt die Erstellung von Bäumen mit LODs bis hin zu Impostoren, Felsen, Gras, mehrteiligen Gebäuden, Charakteren mit Skelettanimation und prozeduralen PBR-Texturen (13 Sets für Biome und Baumaterialien). Zur Laufzeit wird ein wiederverwendbares three.js-Modulsystem mitgeliefert, das Geländebiome, Windgras, instanziierte Baum-LODs, Himmel und Wasser umfasst. Der Workflow beginnt mit einer Spezifikationsdatei (JSON), gefolgt von Linting, Headless-Build in Blender, Validierung anhand von Budgets und Engine-Check im three.js-Viewer. Werkzeuge wie `bin/gp` und `python3 tools/export_world.py` ermöglichen die automatisierte Asset-Produktion und die Zusammenstellung eines spielfertigen Projektordners.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/RNT56/agent-skill-blender-export-three.js/tree/HEAD/skills/blender-gamepipe

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht blender-gamepipe?

Eine deterministische Schleife um Blender: Spezifikation → Linting → Build → Validierung → Export → GLB-Inspektion → Engine-Prüfung. Der Agent liefert Urteile (Rezepte, Korrekturen, künstlerische Leitung); die Skripte stellen das Tor. Nichts wird ausgeliefert, bevor das Tor nicht „Bestanden” sagt.

Die eine Regel

Behaupte niemals, ein Asset sei fertig, nur weil du einen Render oder ein Log gelesen hast. Fertig bedeutet ALLES:

  1. bin/gp build <spezifikation> wurde mit Exit-Code 0 beendet und out/<asset>/manifest.json sagt "passed": true.
  2. Du hast ein Vorschau-/QA-Bild geöffnet und hingesehen (stille Fehler sehen in Logs gut aus: leere Bakes, gespiegelte Texturen, durchstechende Geometrie).
  3. Die Engine-Prüfung war erfolgreich (die Dateien laden in three.js, Texturen kommen komprimiert an, keine Konsolenfehler, es sieht im tatsächlichen Licht richtig aus). Wenn ein Schritt fehlgeschlagen oder übersprungen wurde, sag das klar.

Schnellstart

bin/gp test                                  # alles (benötigt Blender; ~5 Min.)
bin/gp textures specs/biomes.json            # 11 nahtlose PBR-Sets (7 Biome + 4 Baumaterialien) + Naht-Prüfung -> out/textures/
bin/gp generate generators/samurai_keep.py   # prozedurale Burg -> fixtures/samurai_keep.blend (benötigt zuerst die Texturen)
bin/gp build specs/samurai_keep_01.json      # Rezept -> Tor -> GLB -> Inspektion -> Manifest -> Vorschau   (-> out/<asset>/)
bin/gp build specs/grass_blades.json         # windbereites Grashalm-Paket (keine Quell-Szene nötig)
bin/gp build specs/tree_maple_01.json        # Baum LOD0-3 inkl. Impostor
bin/gp lint my_script.py                     # Blender-Fallen erkennen, BEVOR bpy-Code ausgeführt wird
bin/gp glb out/<asset>/*.glb                 # exportierte Dateien ohne Blender inspizieren
bin/gp view                                  # Einzel-Asset-Viewer: http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ...   # Spielordner zusammenstellen (lehnt fehlgeschlagene Assets ab)

Blender wird auf macOS automatisch erkannt; ansonsten export BLENDER=/pfad/zu/Blender.

Pipeline-Übersicht

BedarfWerkzeugAusgabe
nahtloser Boden-/Biom-/Gebäude-PBR (13 Sets: 7 Biome, Stein, Putz, 2 Hölzer, Dachziegel, Stroh)gp textures (gp_texgen.py)<name>_albedo.jpg, _normal.png, _orm.png + Kontaktbogen + Nahtbericht
Hauptbaum -> LODs + ImpostorRezept tree<asset>_LOD0..3.glb (eigene Texturen)
Fels/Prop mit prozeduralem MaterialRezept propLODs teilen sich ein gebackenes PBR-Set
GrasRezept grassgrass_blades.glb (3 Varianten x 2 LODs, 30 Dreiecke; uv.y = Höhe entlang des Halms)
Gebäude (mehrere Materialien, selbst erstellte LODs)generators/{samurai_keep,minka,teahouse}.py (gemeinsam gen_common.py) dann Rezept buildingEIN GLB mit LOD0-2, Texturen gemeinsam genutzt
skelett-animierte Figurgenerators/samurai_unit.py (Bausatz in generators/samurai/) dann Rezept characterskelettierte LOD0-2 + Waffenknoten in EINEM GLB, eine Animation pro Clip, clips.json; zuerst docs/character.md lesen
Engineruntime/*.js (three.js ES-Module)Geländebiome, Windgras, instanziierte Wälder, Himmel, Spieler
Übergabetools/export_world.pyeigenständiger Spielordner

Arbeitsablauf

  1. Spezifikation (specs/*.json): Name, Typ, recipe, source_blend, Budgets, recipe_cfg, glb_expect, export. Kopiere einen Nachbarn.
  2. Linting für jedes bpy, das du schreibst (bin/gp lint). Behebe jeden error.
  3. Headless-Build. Backe/rendere niemals innerhalb einer live-Blender-Sitzung (siehe Einstiegspunkte).
  4. Lies den Bericht, nicht nur den Exit-Code: out/<asset>/*.report.json hat stabile Befund-codes.
  5. Behebe und baue neu. Erhöhe kein Budget ohne Zustimmung des Benutzers.
  6. Schau hin: Öffne *.preview.png (und bei Generatoren --render QA-Ansichten). Beurteile Silhouette, Materialien, Maßstab.
  7. Engine-Prüfung (unten), dann melde Dreiecke pro LOD, Größen, was verifiziert wurde und was nicht.

Einstiegspunkte

  • Headless (Standard): bin/gp build ... = blender -b <quelle.blend> -P gamepipe/gp_cli.py -- <spezifikation>.
  • Live-Blender via MCP: gp_live.run_headless_from_live(spezifikation) speichert eine KOPIE der offenen Szene und führt den Build headless aus (Bake/Render in der Live-Sitzung laufen aus und frieren die UI ein). Code-Snippets von execute_blender_code müssen result = {...} (ein Diktat) zuweisen.

Engine-Prüfung (three.js) - erforderlich

Einzel-Asset: bin/gp view, öffne http://localhost:8765/viewer/?asset=<name>, warte >= 5 s (KTX2 wird in einem Worker transkodiert), dann JSON.stringify({state: window.__state, report: window.report}). Erwarte tris == Manifest, mapIsCompressed:true, Rinde normalMap/aoMap/roughnessFromMap:true, Blätter alphaTest:0.5, keine Konsolenfehler. Eine ganze Welt: Verwende runtime/ (siehe runtime/index.js); baue die Welt durch Verdrahten dieser Module (Gelände + Biome, Gras, Wälder, Wasser, Himmel, Nachbearbeitung); tools/export_world.py erstellt den Spielordner. Messe die tatsächliche GPU-Zeit mit EXT_disjoint_timer_query_webgl2 (gl.finish() ist unter Metal ein No-op); rAF wird in Hintergrund-/nicht fokussierten Tabs gedrosselt, daher sind fps aus einem eingebetteten Browser eine untere Schranke, keine Messung.

Rezepte (gamepipe/recipes/*.py) - Vertrag in recipes/__init__.py

META = {name, version, needs} + build(spec, out_dir) -> [abgeleitete Spezifikationen] (jede: name,type,include_objects,budgets.max_tris,export). Rezepte erzeugen NEUE Objekte. Eines hinzufügen: Modul + Spezifikation + Test (kopiere tests/test_recipes.py).

RezeptEingabeAnmerkungen
treeRinden-Netz + Blatt-Netz (eine Insel pro Blatt, erster Vertex = Blattbasis)Backe albedo/normal/ORM, Blattkarten auf generiertem Atlas, LOD1-2 dezimiert, LOD3 Impostor; leaf_palette: grün/herbst/sakura
propein Netz mit prozeduralem Materialdezinierte LODs, gemeinsames gebackenes Set; flache Normal-Maps werden weggelassen
grasskeines (generiert)Halm-UV: u quer, v = Höhe 0..1; Blender Z-up -> glTF Y-up, biege in Richtung -Z
buildingSammlungen von selbst erstellten LOD-Objekten namens <x>_LOD<n>_<Material>Durchleitung zum Tor; lod_budgets erzwingen Dreiecke pro LOD; EIN GLB
characterein Armature + skelettierte LOD-Netze + Aktionen (erstellt durch generators/samurai_unit.py)Tor fügt SKIN_* / RIG_BONE_BUDGET / ANIM_*-Codes hinzu; exportiert Skins + eine Animation pro Aktion; schreibt clips.json ins Manifest. Siehe docs/character.md

Generatoren (generators/*.py) - für aus Code erstellte Assets

samurai_keep.py: Tenshu auf Ishigaki-Basis, ~23 m hoch. Methode = Geometrie für Silhouette + nahtloser PBR bei festgelegter Weltmaßstab-Texeldichte (UVs sind planare Projektionen im Weltraum: Stein/Putz 3 m, Holz 1,5 m, Ziegel 1,6 m pro Wiederholung). Dreiecke: LOD0 57k, LOD1 16k, LOD2 4,5k. Erstelle QA-Render-Ansichten mit --render out/_keep.png --no-save und SCHAU sie an. Hart erkämpfte Regeln: offene Dachflächen müssen nach oben zeigen; Wände müssen der Dachfläche folgen (nicht einer Box), sonst durchstoßen sie; Quadersteine um die Wandneigung kippen; nur Weltraum-UVs.

Bisher erstellte Gebäude (alle prozedural, alle durch dasselbe Tor)

AssetWasDreiecke LOD0/1/2Anmerkungen
samurai_keep_01Burg-Tenshu auf Ishigaki-Basis, ~23 m57k / 16k / 4,5k5 Materialien inkl. Goldabschlüsse
minka_01strohgedecktes Bauernhaus, Walmdach, Shoji-Veranda12k / 3,4k / 0,9kStroh = klumpiges Höhenfeld; Wände sinken 0,22 m darunter
teahouse_01Teehaus am Wasser auf 28 Stelzen + Steg + Laternen20k / 6,5k / 0,8kUrsprung = Wasseroberfläche, +Y = zum Ufer; benötigt origin_tolerance 3,6 (Stelzen)
Jeder Generator: bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> QA-Render anschauen -> Fixture speichern -> bin/gp build specs/<x>_01.json.

Laufzeit (runtime/*.js) - über export_world in ein Spiel kopieren

assets.js (GLB-Lader mit meshopt+KTX2, Biom-Textur-Arrays) - terrain.js (7-Biom-Splat, Anti-Tiling, Tangenten-Rahmen, entfernte Herbstkrone + Schneegrenze) - grass.js + grass_clump.js (gechunkte Stufen, GPU-Wind, Zertrampeln; clumps: true = hohe Reisfeld-Büschel mit Samenständen) - water.js + water_waves.js (gemeinsames GPU / CPU-Wellenmodell, eingebackene Uferlinie + Schaum, Absorption, Kaustiken, planare Reflexion, Kräuselung; heightAt/normalAt/depthAt für schwimmende Dinge) - post.js (MSAA HDR -> Bloom -> ACES -> Grading) - foliage.js/trees.js (instanziierte LOD-Buckets, Schwingen, Transluzenz) - sky.js (3-Stufen-Verlauf, Sonnenhof, beleuchtete Cumulus + Cirrus) - look.js (gemeinsame looks/*.json, inkl. Fülllicht) - player.js - scatter.js - quality.js (adaptive Auflösung) - noise.js - noisetex.js (eine nahtlose 4-Kanal-Rauschtextur) - Tag / Nacht, Jahreszeiten, Wetter: env_clock.js (Sonnen- + Mondastronomie), env_atmosphere.js (Keyframes nach Sonnenhöhe aus looks/atmosphere.json), env_seasons.js (Gras-/Blatt-/Boden-/Schneezustand + Anwender), env_weather.js, env_sky.js, env_lighting.js, env_grade.js - Leben: aquatic.js (Schilf, Seerosen, Treibgut, Ufersteine), fauna.js (Kois, Enten, Libellen). Der Look looks/golden_hour.json ist ein HERBSTLICHER Look mit niedrig stehender Sonne (Sonne 16 Grad von Westen, warmer Himmel, kühles Fülllicht, Bloom + Grading). Farbautorschaft: Look-JSON-Farben sind szenen-linear (sie sind NICHT sRGB); Gras-Tönungen werden als Anzeigefarben erstellt und im Shader quadriert.

Validator-Codes (beheben, nicht stummschalten)

BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS (über Budget) | UV_MISSING | MAT_PROCEDURAL (backen) | TEX_BLANK (ein Bake ist still fehlgeschlagen) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND (Alpha über Math Round -> MASK leiten) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_* (Probleme in der exportierten DATEI). Texturgenerator: NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG.

Fallstricke

Lies GOTCHAS.md, bevor du bpy- oder Shader-Code schreibst. Highlights: == nicht is bei Nodes; Bake benötigt einen aktiven+ausgewählten Image-Node; Blender-Bilder sind bottom-up (bei E/A umdrehen, sonst ist jede Normal-Map invertiert); ORM/Normal-Maps müssen PNG sein (JPEG-Chroma-Subsampling korrumpiert Datenkanäle); glTF-Alpha-Modus kommt von einem Round-Node; KTX2 wird zweimal exportiert, wenn nicht gestrippt; vertraue niemals fps aus einem Hintergrund-Tab.

Nicht abgedeckt (sei ehrlich)

Motion Capture / handpolierte Animation (die Clips des character-Rezepts sind per Code erstellt, siehe docs/character.md), Flüsse/Unterwasser, Gelände-Streaming/Kollision über Kreis-Collider hinaus, Audio, Starrkörperphysik (Wasseroberflächenphysik für schwimmende Dinge IST abgedeckt), Niederschlag (der Wetterzustand trägt precip dafür). Untere Baum-LODs verwenden die Normal-Map von LOD0 wieder. Rauheit wird aus der Albedo-Luminanz abgeleitet. Prozedurale Modellierung ist keine handmodellierte/gescannte Detailtreue. KTX2 verifiziert in einem Browser/GPU (Apple M4 / Metal).

Verwandte Skills