CommunityImagegithub.com

blender-gamepipe

Transformez des actifs Blender (arbres, herbe, rochers, accessoires, bâtiments) et textures PBR procédurales en ensembles GLB/textures prêts pour le jeu, avec LOD et compression KTX2/meshopt, et vérifiez leur rendu dans three.js. Inclut un runtime three.js réutilisable (biomes de terrain, herbe avec vent, LOD d'arbres en instanciation, ciel) et un outil de transfert de monde.

Qu'est-ce que blender-gamepipe ?

blender-gamepipe est un pipeline automatisé en boucle fermée qui garantit que les actifs 3D créés dans Blender sont correctement exportés, validés et rendus dans un moteur de jeu web (three.js). Il part d'une spécification (spec JSON) qui décrit l'actif, puis exécute les étapes : linting du script Blender, build (baking, génération des niveaux de détail (LOD), export GLB avec compression KTX2/meshopt), validation (taille, nombre de triangles, textures, etc.), inspection du GLB, et enfin vérification moteur dans three.js. Le pipeline est déterministe : rien n'est considéré comme terminé tant que toutes les vérifications automatisées et visuelles ne sont pas passées. Il supporte plusieurs recettes de build : arbres (avec imposteur LOD3), herbe, accessoires, bâtiments multi-matériaux et personnages animés. Il inclut également des générateurs procéduraux (samurai_keep, minka, teahouse) et un runtime three.js complet (terrain à 7 biomes, herbe avec vent, forêts instanciées, eau, ciel, post-processing). L'outil web de visualisation et le script d'export de monde facilitent l'intégration dans un projet de jeu. Les plates-formes principales sont Blender (côté création et script) et three.js (côté rendu). Le pipeline fonctionne en mode headless ou via une interface MCP (dépannage en direct).

Compatible avec~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 Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. bin/gp build <spec> a retourné 0 et out/<asset>/manifest.json mentionne "passed": true.
  2. 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).
  3. 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

besoinoutilsortie
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 + imposteurrecette tree<asset>_LOD0..3.glb (propres textures)
rocher/accessoire avec matériau procéduralrecette propLOD partageant un ensemble PBR cuit
herberecette grassgrass_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 buildingUN SEUL GLB contenant LOD0-2, textures partagées
personnage animé avec squelettegenerators/samurai_unit.py (kit dans generators/samurai/) puis recette characterLOD0-2 avec squelette + nœuds d'armes dans UN SEUL GLB, une animation par clip, clips.json ; lisez d'abord docs/character.md
moteurruntime/*.js (modules ES three.js)biomes de terrain, herbe avec vent, forêts instanciées, ciel, joueur
transferttools/export_world.pydossier de jeu autonome

Flux de travail

  1. Spécification (specs/*.json) : nom, type, recipe, source_blend, budgets, recipe_cfg, glb_expect, export. Copiez un voisin.
  2. Lintez tout code bpy que vous écrivez (bin/gp lint). Corrigez chaque error.
  3. Build en mode headless. Ne faites jamais de bake/rendu dans une session Blender en cours (voir Points d'entrée).
  4. Lisez le rapport, pas seulement le code de sortie : out/<asset>/*.report.json contient des codes de constatation stables (code).
  5. Corrigez et reconstruisez. N'augmentez pas un budget pour passer sans l'accord de l'utilisateur.
  6. Regardez : ouvrez *.preview.png (et pour les générateurs les vues QA --render). Jugez la silhouette, les matériaux, l'échelle.
  7. 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 snippets execute_blender_code doivent assigner result = {...} (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).

recetteentréenotes
treemaillage 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
propun maillage avec matériau procéduralLOD décimés, ensemble cuit partagé ; les cartes normales plates sont omises
grassaucun (généré)UV de la brindille : u en largeur, v = hauteur 0..1 ; Z-up de Blender -> Y-up glTF, courbure vers -Z
buildingcollections 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
characterune 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)

actifquoitriangles LOD0/1/2notes
samurai_keep_01donjon (tenshu) sur socle ishigaki, ~23 m57k / 16k / 4,5k5 matériaux dont les pinacles dorés
minka_01ferme au toit de chaume, toit en croupe, véranda shoji12k / 3,4k / 0,9kchaume = champ de hauteur bosselé ; les murs s'enfoncent de 0,22 m en dessous
teahouse_01maison de thé au bord de l'eau sur 28 pilotis + jetée + lanternes20k / 6,5k / 0,8korigine = 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).

Skills associés