CommunityImagemgithub.com

blender-gamepipe

Transforme assets do Blender (árvores, grama, rochas, adereços, edifícios) e texturas PBR procedurais em conjuntos de textura/GLB verificados e prontos para jogos, com LODs e compressão KTX2/meshopt, e comprove que eles renderizam no three.js. Inclui um runtime reutilizável three.js (biomas de terreno, grama com vento, LODs de árvores com instâncias, céu) e uma ferramenta de exportação de mundo.

O que é blender-gamepipe?

blender-gamepipe é um pipeline determinístico que transforma assets do Blender em ativos verificados e prontos para jogos/web. Ele cobre todo o ciclo: especificação, lint, construção, validação, exportação, inspeção do GLB e verificação no motor gráfico. O pipeline gera LODs, texturas PBR, compressão KTX2/meshopt e inclui um runtime three.js completo com terreno procedural, grama com vento, florestas instanciadas, água e céu. É ideal para desenvolvedores que precisam exportar assets do Blender para motores de jogo ou web com garantia de qualidade, suportando desde árvores heroicas e grama até edifícios complexos e personagens esqueletados. A ferramenta também oferece geradores procedurais (como samurai_keep, minka, teahouse) e uma ferramenta de exportação de mundo que monta uma pasta de jogo autossuficiente a partir dos ativos verificados.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que blender-gamepipe faz?

Um loop determinístico em torno do Blender: especificação -> lint -> construção -> validação -> exportação -> inspeção do GLB -> verificação no motor. O agente fornece julgamento (receitas, correções, direção artística); os scripts fornecem o portão. Nada é enviado a menos que o portão aprove.

A única regra

Nunca afirme que um asset está pronto apenas lendo um render ou um log. Pronto significa TODOS os seguintes:

  1. bin/gp build <spec> retornou 0 e out/<asset>/manifest.json diz "passed": true.
  2. Você abriu uma imagem de pré-visualização/QA e olhou (falhas silenciosas parecem boas nos logs: bakes vazios, texturas invertidas, geometria trespassando).
  3. A verificação no motor foi bem-sucedida (os arquivos carregam no three.js, as texturas chegam comprimidas, sem erros no console, parece correto na iluminação real). Se alguma etapa falhou ou foi pulada, diga isso claramente.

Início rápido

bin/gp test                                  # tudo (precisa de Blender; ~5 min)
bin/gp textures specs/biomes.json            # 11 conjuntos tileáveis PBR (7 biomas + 4 materiais de construção) + verificações de emenda -> out/textures/
bin/gp generate generators/samurai_keep.py   # keep procedural -> fixtures/samurai_keep.blend (precisa das texturas primeiro)
bin/gp build specs/samurai_keep_01.json      # receita -> portão -> GLB -> inspeção -> manifest -> pré-visualização   (-> out/<asset>/)
bin/gp build specs/grass_blades.json         # pacote de lâminas prontas para vento (sem cena de origem necessária)
bin/gp build specs/tree_maple_01.json        # árvore LOD0-3 incluindo impostor
bin/gp lint my_script.py                     # detecta armadilhas do Blender ANTES de executar código bpy
bin/gp glb out/<asset>/*.glb                 # inspeciona arquivos exportados sem Blender
bin/gp view                                  # visualizador de asset único: http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ...   # monta uma pasta de jogo (recusa assets falhos)

O Blender é detectado automaticamente no macOS; caso contrário, use export BLENDER=/path/to/Blender.

Mapa do pipeline

necessidadeferramentasaída
PBR tileável de chão/bioma/edifício (13 conjuntos: 7 biomas, pedra, gesso, 2 madeiras, telhado, colmo)gp textures (gp_texgen.py)<name>_albedo.jpg, _normal.png, _orm.png + folha de contato + relatório de emenda
árvore heroica -> LODs + impostorreceita tree<asset>_LOD0..3.glb (texturas próprias)
rocha/adereço com material proceduralreceita propLODs compartilhando um conjunto PBR cozido
gramareceita grassgrass_blades.glb (3 variantes x 2 LODs, 30 tris; uv.y = altura ao longo da lâmina)
edifício (multi-material, LODs autorais)generators/{samurai_keep,minka,teahouse}.py (gen_common.py compartilhado) depois receita buildingUM GLB contendo LOD0-2, texturas compartilhadas
personagem esqueletado e animadogenerators/samurai_unit.py (kit em generators/samurai/) depois receita characterLOD0-2 esqueletados + nós de arma em UM GLB, uma animação por clipe, clips.json; leia docs/character.md primeiro
motorruntime/*.js (módulos ES three.js)biomas de terreno, grama com vento, florestas instanciadas, céu, jogador
exportaçãotools/export_world.pypasta de jogo autossuficiente

Fluxo de trabalho

  1. Especificação (specs/*.json): nome, tipo, recipe, source_blend, orçamentos, recipe_cfg, glb_expect, export. Copie um vizinho.
  2. Lint em qualquer bpy que você escrever (bin/gp lint). Corrija todo error.
  3. Construa em modo headless. Nunca faça bake/render dentro de uma sessão Blender ao vivo (ver Pontos de entrada).
  4. Leia o relatório, não apenas o código de saída: out/<asset>/*.report.json tem códigos de achado estáveis code.
  5. Corrija e reconstrua. Não aumente um orçamento para passar a menos que o usuário tenha concordado.
  6. Olhe: abra *.preview.png (e para geradores, --render vistas de QA). Julgue silhueta, materiais, escala.
  7. Verificação no motor (abaixo), depois reporte tris por LOD, tamanhos, o que foi verificado e o que não foi.

Pontos de entrada

  • Headless (padrão): bin/gp build ... = blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>.
  • Blender ao vivo via MCP: gp_live.run_headless_from_live(spec) salva uma CÓPIA da cena aberta e executa headless (bake/render na sessão ao vivo causam timeout e congelam a UI). Snippets execute_blender_code devem atribuir result = {...} (um dicionário).

Verificação no motor (three.js) - obrigatória

Asset único: bin/gp view, abra http://localhost:8765/viewer/?asset=<name>, aguarde >= 5 s (KTX2 transcodifica em um worker), então JSON.stringify({state: window.__state, report: window.report}). Espere tris == manifest, mapIsCompressed:true, casca normalMap/aoMap/roughnessFromMap:true, folhas alphaTest:0.5, sem erros no console. Um mundo inteiro: use runtime/ (veja runtime/index.js); construa o mundo conectando esses módulos (terreno + biomas, grama, florestas, água, céu, pós); tools/export_world.py monta a pasta de jogo. Meça o tempo real de GPU com EXT_disjoint_timer_query_webgl2 (gl.finish() é um no-op no Metal); rAF é limitado em abas em segundo plano/sem foco, então fps de um navegador embutido é um limite inferior, não uma medição.

Receitas (gamepipe/recipes/*.py) - contrato em recipes/__init__.py

META = {name, version, needs} + build(spec, out_dir) -> [specs derivadas] (cada: name,type,include_objects,budgets.max_tris,export). Receitas criam NOVOS objetos. Adicione uma: módulo + spec + teste (copie tests/test_recipes.py).

receitaentradanotas
treemalha de casca + malha de folhas (uma ilha por folha, primeiro vértice = base da folha)bake albedo/normal/ORM, cartões de folhas em um atlas gerado, LOD1-2 decimados, LOD3 impostor; leaf_palette: verde/outono/sakura
propuma malha com material proceduralLODs decimados, conjunto cozido compartilhado; mapas normais planos são omitidos
grassnenhuma (gerada)UV da lâmina: u na largura, v = altura 0..1; Blender Z-up -> glTF Y-up, dobra em direção a -Z
buildingcoleções de objetos LOD autorais nomeados <x>_LOD<n>_<Material>passagem direta para o portão; lod_budgets impõem tris por LOD; UM GLB
characteruma armadura + malhas LOD esqueletadas + Actions (construído por generators/samurai_unit.py)portão adiciona códigos SKIN_* / RIG_BONE_BUDGET / ANIM_*; exporta peles + uma animação por Action; escreve clips.json no manifest. Veja docs/character.md

Geradores (generators/*.py) - para assets construídos a partir de código

samurai_keep.py: tenshu sobre uma base ishigaki, ~23 m de altura. Método = geometria para silhueta + PBR tileável com densidade de texel em escala mundial fixa (UVs são projeções planares em espaço mundial: pedra/gesso 3 m, madeira 1.5 m, telha 1.6 m por repetição). Tris: LOD0 57k, LOD1 16k, LOD2 4.5k. Renderize vistas de QA com --render out/_keep.png --no-save e OLHE para elas. Regras duramente conquistadas: superfícies de telhado abertas devem estar viradas para cima; paredes devem seguir a superfície do telhado (não uma caixa) ou trespassam; incline quoins pela inclinação da parede; UVs em espaço mundial apenas.

Edifícios construídos até agora (todos processurais, todos através do mesmo portão)

asseto quetris LOD0/1/2notas
samurai_keep_01castelo (tenshu) sobre base ishigaki, ~23 m57k / 16k / 4.5k5 materiais incl. remates dourados
minka_01casa de fazenda com colmo, telhado de quatro águas, varanda shoji12k / 3.4k / 0.9kcolmo = campo de altura irregular; paredes afundam 0.22 m sob ele
teahouse_01casa de chá à beira d'água sobre 28 palafitas + cais + lanternas20k / 6.5k / 0.8korigem = superfície da água, +Y = em direção à costa; precisa de origin_tolerance 3.6 (palafitas)
Cada gerador: bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> olhe para os renders de QA -> salve o fixture -> bin/gp build specs/<x>_01.json.

Runtime (runtime/*.js) - copie para um jogo via export_world

assets.js (carregador GLB com meshopt+KTX2, arrays de textura de bioma) - terrain.js (splat de 7 biomas, anti-tiling, quadro tangente, dossel outonal distante + linha de neve) - grass.js + grass_clump.js (níveis em blocos, vento GPU, pisoteio; clumps: true = touceiras altas de arroz com cabeças de sementes) - water.js + water_waves.js (modelo de onda GPU/CPU compartilhado, linha costeira cozida + espuma, absorção, causticas, reflexão planar, ondulações; heightAt/normalAt/depthAt para objetos flutuantes) - post.js (MSAA HDR -> bloom -> ACES -> grade) - foliage.js/trees.js (baldes de LOD instanciados, balanço, translucidez) - sky.js (gradiente de 3 paradas, halo solar, cúmulos e cirros iluminados) - look.js (looks compartilhados looks/*.json, incl. luz de preenchimento) - player.js - scatter.js - quality.js (resolução adaptativa) - noise.js - noisetex.js (uma textura de ruído tileável de 4 canais) - dia / noite, estações, clima: env_clock.js (astronomia solar + lunar), env_atmosphere.js (quadros-chave por elevação solar de looks/atmosphere.json), env_seasons.js (estado de grama / folha / chão / neve + aplicadores), env_weather.js, env_sky.js, env_lighting.js, env_grade.js - vida: aquatic.js (juncos, lírios, detritos, rochas costeiras), fauna.js (carpas, patos, libélulas). O look looks/golden_hour.json é um look outonal de sol baixo (sol 16 graus do oeste, céu quente, preenchimento frio, bloom + grade). Criação de cores: cores dos looks JSON são lineares de cena (NÃO são sRGB); tons de grama são criados como cores de exibição e elevados ao quadrado no shader.

Códigos do validador (corrija, não silencie)

BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIAIS (acima do orçamento) | UV_MISSING | MAT_PROCEDURAL (faça o bake) | TEX_BLANK (um bake falhou silenciosamente) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND (roteie alfa via Math Round -> MASK) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_* (problemas no arquivo exportado). Gerador de textura: NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG.

Pegadinhas

Leia GOTCHAS.md antes de escrever código bpy ou shader. Destaques: == não is em nós; bake precisa de um nó de imagem ativo+selecionado; imagens do Blender são de baixo para cima (inverta na IO ou todo mapa normal será invertido); mapas ORM/normal devem ser PNG (subamostragem de croma JPEG corrompe canais de dados); o modo alfa do glTF vem de um nó Round; KTX2 é exportado duas vezes a menos que seja removido; nunca confie em fps de uma aba em segundo plano.

Não coberto (seja honesto)

Captura de movimento / animação polida à mão (os clipes da receita character são autorais por código, veja docs/character.md), rios/submerso, streaming de terreno/colisão além de colisores circulares, áudio, física de corpo rígido (a física de superfície de água para objetos flutuantes ESTÁ coberta), precipitação (o estado climático carrega precip para isso). LODs inferiores de árvores reutilizam o mapa normal do LOD0. A rugosidade é derivada da luminância do albedo. Modelagem procedural não tem fidelidade de escultura/escaneamento manual. KTX2 verificado em um navegador/GPU (Apple M4 / Metal).

Habilidades Relacionadas