CommunityImagengithub.com

blender-gamepipe

Convierte activos de Blender (árboles, hierba, rocas, accesorios, edificios) y texturas PBR procesales en conjuntos de texturas/GLB verificados y listos para juegos, con LODs y compresión KTX2/meshopt, y demuestra que se renderizan en three.js. Incluye un runtime reutilizable de three.js (biomas de terreno, hierba con viento, LODs de árboles instanciados, cielo) y una herramienta de entrega de mundos.

¿Qué es blender-gamepipe?

blender-gamepipe es un pipeline determinista controlado por especificaciones que transforma activos de Blender en recursos listos para motores de juegos/web. Está diseñado para agentes de IA (como Claude Code, Cursor, Codex) que necesitan exportar, optimizar o validar activos de Blender. El pipeline sigue un ciclo cerrado: especificación -> lint -> construcción -> validación -> exportación -> inspección del GLB -> verificación en motor. El agente proporciona juicio (recetas, correcciones, dirección artística) mientras los scripts automatizan las compuertas de validación; nada se envía a menos que la compuerta lo apruebe. Incluye recetas para árboles, rocas, hierba, edificios y personajes, así como generadores procedimentales para estructuras complejas (como un castillo samurái, una casa de campo con techo de paja y una casa de té junto al agua). También proporciona un runtime completo de three.js con terreno por biomas, hierba animada por viento, bosques instanciados, cielo y efectos ambientales (día/noche, estaciones, clima). La herramienta `export_world.py` ensambla una carpeta de juego autocontenida. El sistema verifica la compresión KTX2/meshopt, asegura que las texturas sean correctas (sin horneados silenciosos, sin mapas de normales invertidos) y exige que el agente inspeccione visualmente los resultados, no solo los registros.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace blender-gamepipe?

Un bucle determinista alrededor de Blender: especificación -> lint -> construcción -> validación -> exportación -> inspeccionar el GLB -> verificación en el motor. El agente proporciona juicio (recetas, correcciones, dirección artística); los scripts proporcionan la compuerta. Nada se envía a menos que la compuerta diga pasar.

La única regla

Nunca afirmes que un activo está terminado basándote en tu propia lectura de un render o un registro. Terminado significa TODO:

  1. bin/gp build <spec> salió con 0 y out/<asset>/manifest.json dice "passed": true.
  2. Abriste una imagen de previsualización/QA y la observaste (los fallos silenciosos se ven bien en los registros: horneados en blanco, texturas volteadas, geometría que sobresale).
  3. La verificación en el motor tuvo éxito (los archivos cargan en three.js, las texturas llegan comprimidas, no hay errores en la consola, se ve correcto con la iluminación real). Si algún paso falló o se omitió, dilo claramente.

Inicio rápido

bin/gp test                                  # todo (necesita Blender; ~5 min)
bin/gp textures specs/biomes.json            # 11 conjuntos PBR repetibles (7 biomas + 4 materiales de construcción) + comprobaciones de costuras -> out/textures/
bin/gp generate generators/samurai_keep.py   # fortaleza procedimental -> fixtures/samurai_keep.blend (necesita primero las texturas)
bin/gp build specs/samurai_keep_01.json      # receta -> compuerta -> GLB -> inspección -> manifiesto -> previsualización   (-> out/<asset>/)
bin/gp build specs/grass_blades.json         # paquete de briznas listo para viento (sin necesidad de escena fuente)
bin/gp build specs/tree_maple_01.json        # árbol LOD0-3 incluyendo impostor
bin/gp lint my_script.py                     # detectar trampas de Blender ANTES de ejecutar código bpy
bin/gp glb out/<asset>/*.glb                 # inspeccionar archivos exportados sin Blender
bin/gp view                                  # visor de activo único: http://localhost:8765/viewer/?asset=<nombre>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ...   # ensamblar una carpeta de juego (rechaza activos fallidos)

Blender se detecta automáticamente en macOS; de lo contrario export BLENDER=/ruta/a/Blender.

Mapa del pipeline

necesidadherramientasalida
PBR de suelo/bioma/edificio repetible (13 conjuntos: 7 biomas, piedra, yeso, 2 maderas, teja, paja)gp textures (gp_texgen.py)<nombre>_albedo.jpg, _normal.png, _orm.png + hoja de contacto + informe de costuras
árbol principal -> LODs + impostorreceta tree<activo>_LOD0..3.glb (texturas propias)
roca/accesorio con material procesalreceta propLODs que comparten un conjunto PBR horneado
hierbareceta grassgrass_blades.glb (3 variantes x 2 LODs, 30 tris; uv.y = altura a lo largo de la brizna)
edificio (multimaterial, LODs creados)generators/{samurai_keep,minka,teahouse}.py (comparten gen_common.py) luego receta buildingUN GLB con LOD0-2, texturas compartidas
personaje esqueletizado y animadogenerators/samurai_unit.py (kit en generators/samurai/) luego receta characterLOD0-2 esqueletizado + nodos de armas en UN GLB, una animación por clip, clips.json; leer docs/character.md primero
motorruntime/*.js (módulos ES de three.js)biomas de terreno, hierba con viento, bosques instanciados, cielo, jugador
entregatools/export_world.pycarpeta de juego autocontenida

Flujo de trabajo

  1. Especificación (specs/*.json): nombre, tipo, recipe, source_blend, presupuestos, recipe_cfg, glb_expect, export. Copia un vecino.
  2. Lint cualquier bpy que escribas (bin/gp lint). Corrige cada error.
  3. Construye sin interfaz gráfica. Nunca hornees/renderices dentro de una sesión activa de Blender (ver Puntos de entrada).
  4. Lee el informe, no solo el código de salida: out/<asset>/*.report.json tiene códigos de hallazgos estables.
  5. Corrige y reconstruye. No aumentes un presupuesto para pasar a menos que el usuario haya aceptado.
  6. Observa: abre *.preview.png (y para generadores --render vistas de QA). Juzga silueta, materiales, escala.
  7. Verificación en el motor (abajo), luego reporta tris por LOD, tamaños, qué se verificó y qué no.

Puntos de entrada

  • Sin interfaz gráfica (por defecto): bin/gp build ... = blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>.
  • Blender en vivo vía MCP: gp_live.run_headless_from_live(spec) guarda una COPIA de la escena abierta y la ejecuta sin interfaz (hornear/renderizar en la sesión en vivo agota el tiempo y congela la interfaz). Los fragmentos execute_blender_code deben asignar result = {...} (un diccionario).

Verificación en el motor (three.js) - obligatorio

Activo único: bin/gp view, abre http://localhost:8765/viewer/?asset=<nombre>, espera >= 5 s (KTX2 se transcodifica en un worker), luego JSON.stringify({state: window.__state, report: window.report}). Espera tris == manifiesto, mapIsCompressed:true, corteza normalMap/aoMap/roughnessFromMap:true, hojas alphaTest:0.5, sin errores en la consola. Un mundo completo: usa runtime/ (ver runtime/index.js); construye el mundo conectando estos módulos (terreno + biomas, hierba, bosques, agua, cielo, post); tools/export_world.py ensambla la carpeta del juego. Mide el tiempo real de GPU con EXT_disjoint_timer_query_webgl2 (gl.finish() no hace nada en Metal); rAF se limita en pestañas en segundo plano/sin foco, por lo que los fps de un navegador incrustado son un límite inferior, no una medición.

Recetas (gamepipe/recipes/*.py) - contrato en recipes/__init__.py

META = {name, version, needs} + build(spec, out_dir) -> [especificaciones derivadas] (cada una: name,type,include_objects,budgets.max_tris,export). Las recetas crean NUEVOS objetos. Añade una: módulo + especificación + prueba (copia tests/test_recipes.py).

recetaentradanotas
treemalla de corteza + malla de hojas (una isla por hoja, primer vértice = base de la hoja)hornear albedo/normal/ORM, tarjetas de hojas en un atlas generado, LOD1-2 decimados, LOD3 impostor; leaf_palette: verde/otoño/sakura
propuna malla con material procesalLODs decimados, conjunto horneado compartido; los mapas de normales planos se omiten
grassninguna (generada)UV de la brizna: u a lo ancho, v = altura 0..1; Z arriba en Blender -> Y arriba en glTF, curvatura hacia -Z
buildingcolecciones de objetos LOD creados llamados <x>_LOD<n>_<Material>paso directo a la compuerta; lod_budgets imponen tris por LOD; UN GLB
characterun esqueleto + mallas LOD esqueletizadas + Acciones (construido por generators/samurai_unit.py)la compuerta añade códigos SKIN_* / RIG_BONE_BUDGET / ANIM_*; exporta pieles + una animación por Acción; escribe clips.json en el manifiesto. Ver docs/character.md

Generadores (generators/*.py) - para activos construidos desde código

samurai_keep.py: tenshu sobre una base ishigaki, ~23 m de alto. Método = geometría para silueta + PBR repetible con densidad de texel a escala mundial fija (Las UV son proyecciones planares en espacio mundial: piedra/yeso 3 m, madera 1.5 m, teja 1.6 m por repetición). Tris: LOD0 57k, LOD1 16k, LOD2 4.5k. Renderiza vistas de QA con --render out/_keep.png --no-save y MÍRALAS. Reglas ganadas con esfuerzo: las superficies de techo abiertas deben mirar hacia arriba; las paredes deben seguir la superficie del techo (no una caja) o sobresaldrán; inclina los sillares según el talud de la pared; solo UV en espacio mundial.

Edificios construidos hasta ahora (todos procedimentales, todos a través de la misma compuerta)

activoquétris LOD0/1/2notas
samurai_keep_01castillo fortaleza (tenshu) sobre base ishigaki, ~23 m57k / 16k / 4.5k5 materiales incl. remates dorados
minka_01casa de campo con techo de paja, techo a cuatro aguas, veranda shoji12k / 3.4k / 0.9kpaja = campo de altura irregular; las paredes se hunden 0.22 m debajo
teahouse_01casa de té junto al agua sobre 28 pilotes + embarcadero + linternas20k / 6.5k / 0.8korigen = superficie del agua, +Y = hacia la orilla; necesita origin_tolerance 3.6 (pilotes)
Cada generador: bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> mirar los renders de QA -> guardar fixture -> bin/gp build specs/<x>_01.json.

Runtime (runtime/*.js) - copiar en un juego vía export_world

assets.js (cargador GLB con meshopt+KTX2, matrices de textura de bioma) - terrain.js (splat de 7 biomas, antirrepetición, marco tangente, dosel lejano de otoño + línea de nieve) - grass.js + grass_clump.js (niveles fragmentados, viento GPU, pisoteo; clumps: true = matas altas de arrozal con espigas) - water.js + water_waves.js (modelo de olas GPU/CPU compartido, orilla horneada + espuma, absorción, cáusticas, reflejo planar, ondas; heightAt/normalAt/depthAt para objetos flotantes) - post.js (MSAA HDR -> bloom -> ACES -> gradación) - foliage.js/trees.js (cubos de LOD instanciados, balanceo, translucidez) - sky.js (gradiente de 3 paradas, halo solar, cúmulos + cirros iluminados) - look.js (archivos looks/*.json compartidos, incl. luz de relleno) - player.js - scatter.js - quality.js (resolución adaptativa) - noise.js - noisetex.js (una textura de ruido de 4 canales repetible) - día / noche, estaciones, clima: env_clock.js (astronomía solar + lunar), env_atmosphere.js (fotogramas clave por elevación solar de looks/atmosphere.json), env_seasons.js (estado de hierba / hoja / suelo / nieve + aplicadores), env_weather.js, env_sky.js, env_lighting.js, env_grade.js - vida: aquatic.js (juncos, nenúfares, restos flotantes, rocas de orilla), fauna.js (koi, patos, libélulas). El aspecto looks/golden_hour.json es un aspecto OTOÑAL de sol bajo (sol a 16 grados del oeste, cielo cálido, relleno frío, bloom + gradación). Autoría de color: los colores JSON de aspecto son lineales de escena (NO son sRGB); los tintes de hierba se crean como colores de visualización y se elevan al cuadrado en el sombreador.

Códigos del validador (corregir, no silenciar)

BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS (por encima del presupuesto) | UV_MISSING | MAT_PROCEDURAL (hornearlo) | TEX_BLANK (un horneado falló silenciosamente) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND (encaminar alfa vía Math Round -> MASK) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_* (problemas en el ARCHIVO exportado). Generador de texturas: NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG.

Trampas

Lee GOTCHAS.md antes de escribir código bpy o de sombreador. Lo más destacado: == no is en nodos; el horneado necesita un nodo de imagen activo y seleccionado; las imágenes de Blender son de abajo arriba (invertir en IO o cada mapa normal estará invertido); Los mapas ORM/normales deben ser PNG (el submuestreo de croma JPEG corrompe los canales de datos); el modo alfa de glTF proviene de un nodo Round; KTX2 se exporta dos veces a menos que se elimine; nunca confíes en los fps de una pestaña en segundo plano.

No cubierto (sé honesto)

Captura de movimiento / animación pulida a mano (los clips de la receta character son creados por código, ver docs/character.md), ríos/subacuático, transmisión de terreno/colisión más allá de colisionadores circulares, audio, física de cuerpo rígido (la física de superficie del agua para objetos flotantes SÍ está cubierta), precipitación (el estado climático lleva precip para ello). Los LOD inferiores de árboles reutilizan el mapa normal del LOD0. La rugosidad se deriva de la luminancia del albedo. El modelado procedimental no tiene fidelidad de escultura/escaneo manual. KTX2 verificado en un navegador/GPU (Apple M4 / Metal).

Skills relacionados