Que fait blender-gamepipe ?
Une boucle déterministe autour de Blender : spécification -> lint -> build -> valide -> exporte -> inspecte le GLB -> vérification moteur. L'agent fournit le jugement (recettes, corrections, direction artistique) ; les scripts fournissent la passerelle. Rien ne part tant que la passerelle n'a pas donné son feu vert.
La règle unique
Ne prétendez jamais qu'un actif est terminé en vous basant uniquement sur votre lecture d'un rendu ou d'un log. Terminé signifie TOUT ceci :
bin/gp build <spec>a retourné 0 etout/<asset>/manifest.jsonmentionne"passed": true.- Vous avez ouvert une image de prévisualisation/QA et regardé (les échecs silencieux semblent corrects dans les logs : bakes vides, textures inversées, géométrie qui perce).
- La vérification moteur a réussi (les fichiers se chargent dans three.js, les textures arrivent compressées, aucune erreur dans la console, tout a l'air correct sous l'éclairage réel). Si une étape a échoué ou a été sautée, dites-le clairement.
Démarrage rapide
bin/gp test # tout (nécessite Blender ; ~5 min)
bin/gp textures specs/biomes.json # 11 ensembles PBR tuilables (7 biomes + 4 matériaux de construction) + contrôles de jointures -> out/textures/
bin/gp generate generators/samurai_keep.py # donjon procédural -> fixtures/samurai_keep.blend (nécessite d'abord les textures)
bin/gp build specs/samurai_keep_01.json # recette -> passerelle -> GLB -> inspection -> manifeste -> prévisualisation (-> out/<asset>/)
bin/gp build specs/grass_blades.json # ensemble de brins d'herbe prêts pour le vent (pas de scène source nécessaire)
bin/gp build specs/tree_maple_01.json # arbre LOD0-3 incluant l'imposteur
bin/gp lint my_script.py # détecter les pièges Blender AVANT d'exécuter du code bpy
bin/gp glb out/<asset>/*.glb # inspecter les fichiers exportés sans Blender
bin/gp view # visualiseur mono-actif : http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ... # assembler un dossier de jeu (refuse les actifs ayant échoué)
Blender est détecté automatiquement sur macOS ; sinon définissez export BLENDER=/chemin/vers/Blender.
Carte du pipeline
| besoin | outil | sortie |
|---|---|---|
| sol/biome/bâtiment PBR tuilable (13 ensembles : 7 biomes, pierre, plâtre, 2 bois, tuile, chaume) | gp textures (gp_texgen.py) | <name>_albedo.jpg, _normal.png, _orm.png + planche contact + rapport de jointure |
| arbre héros -> LOD + imposteur | recette tree | <asset>_LOD0..3.glb (propres textures) |
| rocher/accessoire avec matériau procédural | recette prop | LOD partageant un ensemble PBR cuit |
| herbe | recette grass | grass_blades.glb (3 variantes x 2 LOD, 30 triangles ; uv.y = hauteur le long du brin) |
| bâtiment (multi-matériaux, LOD authorisés) | generators/{samurai_keep,minka,teahouse}.py (gen_common.py partagé) puis recette building | UN SEUL GLB contenant LOD0-2, textures partagées |
| personnage animé avec squelette | generators/samurai_unit.py (kit dans generators/samurai/) puis recette character | LOD0-2 avec squelette + nœuds d'armes dans UN SEUL GLB, une animation par clip, clips.json ; lisez d'abord docs/character.md |
| moteur | runtime/*.js (modules ES three.js) | biomes de terrain, herbe avec vent, forêts instanciées, ciel, joueur |
| transfert | tools/export_world.py | dossier de jeu autonome |
Flux de travail
- Spécification (
specs/*.json) : nom, type,recipe,source_blend, budgets,recipe_cfg,glb_expect,export. Copiez un voisin. - Lintez tout code bpy que vous écrivez (
bin/gp lint). Corrigez chaqueerror. - Build en mode headless. Ne faites jamais de bake/rendu dans une session Blender en cours (voir Points d'entrée).
- Lisez le rapport, pas seulement le code de sortie :
out/<asset>/*.report.jsoncontient des codes de constatation stables (code). - Corrigez et reconstruisez. N'augmentez pas un budget pour passer sans l'accord de l'utilisateur.
- Regardez : ouvrez
*.preview.png(et pour les générateurs les vues QA--render). Jugez la silhouette, les matériaux, l'échelle. - Vérification moteur (ci-dessous), puis rapportez les triangles par LOD, les tailles, ce qui a été vérifié et ce qui ne l'a pas été.
Points d'entrée
- Headless (par défaut) :
bin/gp build ...=blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>. - Blender en cours via MCP :
gp_live.run_headless_from_live(spec)enregistre une COPIE de la scène ouverte et exécute headless (bake/rendu dans la session en cours expirent et figent l'interface). Les snippetsexecute_blender_codedoivent assignerresult = {...}(un dictionnaire).
Vérification moteur (three.js) - obligatoire
Actif unique : bin/gp view, ouvrez http://localhost:8765/viewer/?asset=<name>, attendez >= 5 s (le transcodage KTX2 s'effectue dans un worker), puis
JSON.stringify({state: window.__state, report: window.report}). Attendez-vous à ce que tris == manifeste, mapIsCompressed:true, normalMap/aoMap/roughnessFromMap:true pour l'écorce, alphaTest:0.5 pour les feuilles, aucune erreur console.
Un monde entier : utilisez runtime/ (voir runtime/index.js) ; construisez le monde en câblant ces modules (terrain + biomes, herbe, forêts, eau, ciel, post) ; tools/export_world.py assemble le dossier de jeu.
Mesurez le temps GPU réel avec EXT_disjoint_timer_query_webgl2 (gl.finish() est sans effet sur Metal) ; rAF est limité dans les onglets en arrière-plan/non focalisés, donc les fps d'un navigateur intégré sont une borne inférieure, pas une mesure.
Recettes (gamepipe/recipes/*.py) - contrat dans recipes/__init__.py
META = {name, version, needs} + build(spec, out_dir) -> [specs dérivées] (chacune : name,type,include_objects,budgets.max_tris,export). Les recettes créent de NOUVEAUX objets. Ajoutez-en une : module + spec + test (copiez tests/test_recipes.py).
| recette | entrée | notes |
|---|---|---|
tree | maillage d'écorce + maillage de feuilles (une île par feuille, premier sommet = base de la feuille) | bake albedo/normal/ORM, cartes de feuilles sur un atlas généré, LOD1-2 décimés, LOD3 imposteur ; leaf_palette : vert/automne/sakura |
prop | un maillage avec matériau procédural | LOD décimés, ensemble cuit partagé ; les cartes normales plates sont omises |
grass | aucun (généré) | UV de la brindille : u en largeur, v = hauteur 0..1 ; Z-up de Blender -> Y-up glTF, courbure vers -Z |
building | collections d'objets LOD authorisés nommés <x>_LOD<n>_<Material> | passage direct à la passerelle ; lod_budgets imposent les triangles par LOD ; UN SEUL GLB |
character | une armature + maillages LOD avec peau + Actions (construit par generators/samurai_unit.py) | la passerelle ajoute des codes SKIN_* / RIG_BONE_BUDGET / ANIM_* ; exporte les skins + une animation par Action ; écrit clips.json dans le manifeste. Voir docs/character.md |
Générateurs (generators/*.py) - pour les actifs construits par code
samurai_keep.py : tenshu sur un socle ishigaki, ~23 m de haut. Méthode = géométrie pour la silhouette + PBR tuilable à densité de texel à échelle fixe
(les UV sont des projections planes dans l'espace monde : pierre/plâtre 3 m, bois 1,5 m, tuile 1,6 m par répétition). Triangles : LOD0 57k, LOD1 16k, LOD2 4,5k.
Rendus QA avec --render out/_keep.png --no-save et REGARDEZ-les. Règlements durement acquis : les surfaces de toit ouvertes doivent être orientées vers le haut ; les murs doivent suivre la surface du toit (pas une boîte) sinon ils traversent ; inclinez les pierres d'angle avec le fruit du mur ; UV dans l'espace monde uniquement.
Bâtiments construits jusqu'à présent (tous procéduraux, tous via la même passerelle)
| actif | quoi | triangles LOD0/1/2 | notes |
|---|---|---|---|
samurai_keep_01 | donjon (tenshu) sur socle ishigaki, ~23 m | 57k / 16k / 4,5k | 5 matériaux dont les pinacles dorés |
minka_01 | ferme au toit de chaume, toit en croupe, véranda shoji | 12k / 3,4k / 0,9k | chaume = champ de hauteur bosselé ; les murs s'enfoncent de 0,22 m en dessous |
teahouse_01 | maison de thé au bord de l'eau sur 28 pilotis + jetée + lanternes | 20k / 6,5k / 0,8k | origine = surface de l'eau, +Y = vers la rive ; nécessite origin_tolerance 3,6 (pilotis) |
Chaque générateur : bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> regardez les rendus QA -> enregistrez le fixture -> bin/gp build specs/<x>_01.json. |
Runtime (runtime/*.js) - copiez-le dans un jeu via export_world
assets.js (chargeur GLB avec meshopt+KTX2, tableaux de textures de biomes) - terrain.js (splat 7 biomes, anti-répétition, cadre tangentiel, canopée d'automne lointaine + ligne de neige) - grass.js + grass_clump.js (niveaux par morceaux, vent GPU, piétinement ; clumps: true = hautes touffes de riz avec épis) - water.js + water_waves.js (modèle d'ondes GPU/CPU partagé, rivage cuit avec fond + écume, absorption, caustiques, réflexion planaire, ondulations ; heightAt/normalAt/depthAt pour les objets flottants) - post.js (MSAA HDR -> bloom -> ACES -> étalonnage) -
foliage.js/trees.js (seaux d'instanciation LOD, balancement, translucidité) - sky.js (dégradé 3 arrêts, halo solaire, cumulus et cirrus éclairés) - look.js (looks partagés looks/*.json, incluant la lumière de remplissage) - player.js - scatter.js - quality.js (résolution adaptative) - noise.js - noisetex.js (une texture de bruit 4 canaux tuilable) - jour / nuit, saisons, météo : env_clock.js (astronomie solaire + lunaire), env_atmosphere.js (images clés par élévation du soleil depuis looks/atmosphere.json), env_seasons.js (état des herbes / feuilles / sol / neige + applicateurs), env_weather.js, env_sky.js, env_lighting.js, env_grade.js - vie : aquatic.js (roseaux, nénuphars, débris flottants, rochers de rivage), fauna.js (koïs, canards, libellules).
Le look looks/golden_hour.json est un look D'AUTOMNE à faible soleil (soleil à 16 degrés de l'ouest, ciel chaud, remplissage froid, bloom + étalonnage). Création des couleurs : les couleurs des looks JSON sont scène-linéaires (elles ne sont PAS sRGB) ; les teintes de l'herbe sont authorisées comme couleurs d'affichage et mises au carré dans le shader.
Codes de validation (corrigez, ne mettez pas en sourdine)
BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS (hors budget) | UV_MISSING | MAT_PROCEDURAL (cuisez-le) | TEX_BLANK (un bake a échoué silencieusement) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND (acheminez l'alpha via Math Round -> MASK) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_* (problèmes dans le FICHIER exporté). Générateur de textures : NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG.
Pièges
Lisez GOTCHAS.md avant d'écrire du code bpy ou de shader. Points saillants : == pas is sur les nœuds ; le bake nécessite un nœud d'image actif et sélectionné ; les images Blender sont bas en haut (inversez à l'IO ou toute normale inversée) ; les cartes ORM/normales doivent être en PNG (le sous-échantillonnage chroma du JPEG corrompt les canaux de données) ; le mode alpha glTF provient d'un nœud Round ; KTX2 est exporté deux fois sauf s'il est retiré ; ne faites jamais confiance aux fps d'un onglet en arrière-plan.
Non couvert (soyez honnête)
Capture de mouvement / animation peaufinée à la main (les clips de la recette character sont authorisés par code, voir docs/character.md), rivières/sous-marin, streaming/collision de terrain au-delà des colliders sphériques, audio, physique de corps rigides (la physique de surface de l'eau pour les objets flottants EST couverte), précipitations (l'état météorologique transporte precip pour cela). Les LOD inférieurs des arbres réutilisent la normale de LOD0.
La rugosité est dérivée de la luminance de l'albedo. La modélisation procédurale n'a pas la fidélité de la sculpture manuelle/numérisation. KTX2 vérifié dans un seul navigateur/GPU (Apple M4 / Metal).