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:
bin/gp build <spec>retornou 0 eout/<asset>/manifest.jsondiz"passed": true.- Você abriu uma imagem de pré-visualização/QA e olhou (falhas silenciosas parecem boas nos logs: bakes vazios, texturas invertidas, geometria trespassando).
- 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
| necessidade | ferramenta | saí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 + impostor | receita tree | <asset>_LOD0..3.glb (texturas próprias) |
| rocha/adereço com material procedural | receita prop | LODs compartilhando um conjunto PBR cozido |
| grama | receita grass | grass_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 building | UM GLB contendo LOD0-2, texturas compartilhadas |
| personagem esqueletado e animado | generators/samurai_unit.py (kit em generators/samurai/) depois receita character | LOD0-2 esqueletados + nós de arma em UM GLB, uma animação por clipe, clips.json; leia docs/character.md primeiro |
| motor | runtime/*.js (módulos ES three.js) | biomas de terreno, grama com vento, florestas instanciadas, céu, jogador |
| exportação | tools/export_world.py | pasta de jogo autossuficiente |
Fluxo de trabalho
- Especificação (
specs/*.json): nome, tipo,recipe,source_blend, orçamentos,recipe_cfg,glb_expect,export. Copie um vizinho. - Lint em qualquer bpy que você escrever (
bin/gp lint). Corrija todoerror. - Construa em modo headless. Nunca faça bake/render dentro de uma sessão Blender ao vivo (ver Pontos de entrada).
- Leia o relatório, não apenas o código de saída:
out/<asset>/*.report.jsontem códigos de achado estáveiscode. - Corrija e reconstrua. Não aumente um orçamento para passar a menos que o usuário tenha concordado.
- Olhe: abra
*.preview.png(e para geradores,--rendervistas de QA). Julgue silhueta, materiais, escala. - 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). Snippetsexecute_blender_codedevem atribuirresult = {...}(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).
| receita | entrada | notas |
|---|---|---|
tree | malha 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 |
prop | uma malha com material procedural | LODs decimados, conjunto cozido compartilhado; mapas normais planos são omitidos |
grass | nenhuma (gerada) | UV da lâmina: u na largura, v = altura 0..1; Blender Z-up -> glTF Y-up, dobra em direção a -Z |
building | coleçõ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 |
character | uma 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)
| asset | o que | tris LOD0/1/2 | notas |
|---|---|---|---|
samurai_keep_01 | castelo (tenshu) sobre base ishigaki, ~23 m | 57k / 16k / 4.5k | 5 materiais incl. remates dourados |
minka_01 | casa de fazenda com colmo, telhado de quatro águas, varanda shoji | 12k / 3.4k / 0.9k | colmo = campo de altura irregular; paredes afundam 0.22 m sob ele |
teahouse_01 | casa de chá à beira d'água sobre 28 palafitas + cais + lanternas | 20k / 6.5k / 0.8k | origem = 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).