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:
bin/gp build <spezifikation>wurde mit Exit-Code 0 beendet undout/<asset>/manifest.jsonsagt"passed": true.- Du hast ein Vorschau-/QA-Bild geöffnet und hingesehen (stille Fehler sehen in Logs gut aus: leere Bakes, gespiegelte Texturen, durchstechende Geometrie).
- 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
| Bedarf | Werkzeug | Ausgabe |
|---|---|---|
| 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 + Impostor | Rezept tree | <asset>_LOD0..3.glb (eigene Texturen) |
| Fels/Prop mit prozeduralem Material | Rezept prop | LODs teilen sich ein gebackenes PBR-Set |
| Gras | Rezept grass | grass_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 building | EIN GLB mit LOD0-2, Texturen gemeinsam genutzt |
| skelett-animierte Figur | generators/samurai_unit.py (Bausatz in generators/samurai/) dann Rezept character | skelettierte LOD0-2 + Waffenknoten in EINEM GLB, eine Animation pro Clip, clips.json; zuerst docs/character.md lesen |
| Engine | runtime/*.js (three.js ES-Module) | Geländebiome, Windgras, instanziierte Wälder, Himmel, Spieler |
| Übergabe | tools/export_world.py | eigenständiger Spielordner |
Arbeitsablauf
- Spezifikation (
specs/*.json): Name, Typ,recipe,source_blend, Budgets,recipe_cfg,glb_expect,export. Kopiere einen Nachbarn. - Linting für jedes bpy, das du schreibst (
bin/gp lint). Behebe jedenerror. - Headless-Build. Backe/rendere niemals innerhalb einer live-Blender-Sitzung (siehe Einstiegspunkte).
- Lies den Bericht, nicht nur den Exit-Code:
out/<asset>/*.report.jsonhat stabile Befund-codes. - Behebe und baue neu. Erhöhe kein Budget ohne Zustimmung des Benutzers.
- Schau hin: Öffne
*.preview.png(und bei Generatoren--renderQA-Ansichten). Beurteile Silhouette, Materialien, Maßstab. - 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 vonexecute_blender_codemüssenresult = {...}(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).
| Rezept | Eingabe | Anmerkungen |
|---|---|---|
tree | Rinden-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 |
prop | ein Netz mit prozeduralem Material | dezinierte LODs, gemeinsames gebackenes Set; flache Normal-Maps werden weggelassen |
grass | keines (generiert) | Halm-UV: u quer, v = Höhe 0..1; Blender Z-up -> glTF Y-up, biege in Richtung -Z |
building | Sammlungen von selbst erstellten LOD-Objekten namens <x>_LOD<n>_<Material> | Durchleitung zum Tor; lod_budgets erzwingen Dreiecke pro LOD; EIN GLB |
character | ein 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)
| Asset | Was | Dreiecke LOD0/1/2 | Anmerkungen |
|---|---|---|---|
samurai_keep_01 | Burg-Tenshu auf Ishigaki-Basis, ~23 m | 57k / 16k / 4,5k | 5 Materialien inkl. Goldabschlüsse |
minka_01 | strohgedecktes Bauernhaus, Walmdach, Shoji-Veranda | 12k / 3,4k / 0,9k | Stroh = klumpiges Höhenfeld; Wände sinken 0,22 m darunter |
teahouse_01 | Teehaus am Wasser auf 28 Stelzen + Steg + Laternen | 20k / 6,5k / 0,8k | Ursprung = 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).