blender-gamepipe は何をしますか?
Blenderの周りをぐるっと一周する決定論的ループ:仕様 → リント → ビルド → 検証 → エクスポート → GLB検査 → エンジンチェック。 エージェントは判断(レシピ、修正、アートディレクション)を提供し、スクリプトはゲートを担当します。ゲートが合格と言わない限り、何も出荷しません。
唯一のルール
レンダリングやログを自分で読んだだけでアセットが完成したと主張してはいけません。 完成とは、以下のすべてが満たされた状態です。
bin/gp build <spec>が終了コード0で終了し、out/<asset>/manifest.jsonに"passed": trueと記載されていること。- プレビュー/QA画像を開いて実際に確認したこと(ログでは正常に見えても、ベイクの空白、テクスチャの反転、ジオメトリの突き抜けなどの静かな失敗があります)。
- エンジンチェックが成功したこと(ファイルがthree.jsで読み込まれ、テクスチャが圧縮されて到着し、コンソールエラーがなく、実際の照明で正しく見えること)。 いずれかのステップが失敗またはスキップされた場合は、その旨を明確に述べてください。
クイックスタート
bin/gp test # すべてをテスト(Blenderが必要;約5分)
bin/gp textures specs/biomes.json # 11個のタイル可能PBRセット(7バイオーム + 4建築素材)+ シームチェック -> out/textures/
bin/gp generate generators/samurai_keep.py # プロシージャルな城 -> fixtures/samurai_keep.blend(最初にテクスチャが必要)
bin/gp build specs/samurai_keep_01.json # レシピ -> ゲート -> GLB -> 検査 -> マニフェスト -> プレビュー (-> out/<asset>/)
bin/gp build specs/grass_blades.json # 風対応の草ブレードパック(ソースシーン不要)
bin/gp build specs/tree_maple_01.json # 木 LOD0-3(インプスター含む)
bin/gp lint my_script.py # bpyコードを実行する前にBlenderの罠をキャッチ
bin/gp glb out/<asset>/*.glb # Blenderを使わずにエクスポートファイルを検査
bin/gp view # 単一アセットビューア:http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ... # ゲームフォルダをアセンブル(失敗したアセットは拒否)
BlenderはmacOSでは自動検出されます。それ以外の場合は export BLENDER=/path/to/Blender を設定してください。
パイプラインマップ
| ニーズ | ツール | 出力 |
|---|---|---|
| タイル可能な地面/バイオーム/建築PBR(13セット:7バイオーム、石、漆喰、2種の木材、屋根瓦、茅葺) | gp textures (gp_texgen.py) | <name>_albedo.jpg, _normal.png, _orm.png + コンタクトシート + シームレポート |
| メインとなる木 -> LOD + インプスター | レシピ tree | <asset>_LOD0..3.glb(独自テクスチャ) |
| プロシージャルマテリアルの岩/小物 | レシピ prop | 1つのベイクされたPBRセットを共有するLOD |
| 草 | レシピ grass | grass_blades.glb(3バリエーション x 2 LOD、30トライアングル;uv.y = 草丈に沿った高さ) |
| 建物(マルチマテリアル、手動LOD) | generators/{samurai_keep,minka,teahouse}.py(共有 gen_common.py)その後レシピ building | 1つのGLBにLOD0-2を保持、テクスチャは共有 |
| スキニング、アニメーション付きキャラクター | generators/samurai_unit.py(generators/samurai/ 内のキット)その後レシピ character | スキニングLOD0-2 + 武器ノードを1つのGLBに、1アクションにつき1アニメーション、clips.json;最初に docs/character.md を読むこと |
| エンジン | runtime/*.js(three.js ESモジュール) | 地形バイオーム、風に揺れる草、インスタンス化された森、空、プレイヤー |
| 受け渡し | tools/export_world.py | 自己完結型のゲームフォルダ |
ワークフロー
- 仕様 (
specs/*.json):名前、タイプ、recipe、source_blend、予算、recipe_cfg、glb_expect、export。近隣のものをコピーしてください。 - 作成したすべてのbpyコードをリントする(
bin/gp lint)。すべてのerrorを修正してください。 - ヘッドレスでビルドする。ライブのBlenderセッション内でベイク/レンダリングを行わないでください(エントリポイントを参照)。
- 終了コードだけでなくレポートを読む:
out/<asset>/*.report.jsonには安定した検出codeが含まれています。 - 修正して再ビルドする。 ユーザーが同意しない限り、通過させるために予算を引き上げないでください。
- 確認する:
*.preview.png(ジェネレーターの場合は--renderQAビュー)を開く。シルエット、マテリアル、スケールを判断してください。 - エンジンチェック(下記)、その後LODごとのトライアングル数、サイズ、検証されたものとされなかったものを報告してください。
エントリポイント
- ヘッドレス(デフォルト):
bin/gp build ...=blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>。 - MCP経由のライブBlender:
gp_live.run_headless_from_live(spec)は開いているシーンのコピーを保存し、ヘッドレスで実行します(ライブセッション内でのベイク/レンダリングはタイムアウトし、UIをフリーズさせます)。execute_blender_codeスニペットはresult = {...}(辞書)を代入する必要があります。
エンジンチェック(three.js)- 必須
単一アセット:bin/gp view、http://localhost:8765/viewer/?asset=<name> を開き、>= 5 秒待機してから(KTX2がワーカー上でトランスコードされる)
JSON.stringify({state: window.__state, report: window.report}) を実行。tris がマニフェストと一致し、mapIsCompressed:true、樹皮 normalMap/aoMap/roughnessFromMap:true、葉 alphaTest:0.5、コンソールエラーがないことを期待します。
ワールド全体の場合は runtime/ を使用(runtime/index.js を参照);これらのモジュールを配線してワールドを構築します(地形 + バイオーム、草、森、水、空、ポストプロセス);tools/export_world.py がゲームフォルダをアセンブルします。
EXT_disjoint_timer_query_webgl2 で実際のGPU時間を測定します(gl.finish() はMetalではno-opです);rAFはバックグラウンド/フォーカスされていないタブではスロットルされるため、埋め込みブラウザからのfpsは下限値であり、測定値ではありません。
レシピ(gamepipe/recipes/*.py)- recipes/__init__.py の契約
META = {name, version, needs} + build(spec, out_dir) -> [derived specs](各:name,type,include_objects,budgets.max_tris,export)。レシピは新しいオブジェクトを作成します。追加するには:モジュール + 仕様 + テスト(tests/test_recipes.py をコピー)。
| レシピ | 入力 | 備考 |
|---|---|---|
tree | 樹皮メッシュ + 葉メッシュ(葉ごとに1つのアイランド、最初の頂点 = 葉の付け根) | アルベド/ノーマル/ORMをベイク、生成されたアトラス上の葉カード、LOD1-2は間引き、LOD3はインプスター;leaf_palette:緑/紅葉/桜 |
prop | プロシージャルマテリアルの1つのメッシュ | 間引きされたLOD、共有ベイクセット;フラットなノーマルマップは省略 |
grass | なし(生成) | ブレードUV:uは横方向、vは高さ 0..1;Blender Z-up -> glTF Y-up、-Z方向に曲がる |
building | <x>_LOD<n>_<Material> という名前のLODオブジェクトのコレクション | ゲートを通過;lod_budgets がLODごとのトライアングル数を強制;1つのGLB |
character | アーマチュア + スキニングLODメッシュ + アクション(generators/samurai_unit.py でビルド) | ゲートが SKIN_* / RIG_BONE_BUDGET / ANIM_* コードを追加;スキン + アクションごとに1つのアニメーションをエクスポート;clips.json をマニフェストに書き込む。docs/character.md を参照 |
ジェネレーター(generators/*.py)- コードからビルドされるアセット用
samurai_keep.py:石垣の上の天守、高さ約23m。手法 = シルエットのためのジオメトリ + 固定ワールドスケールテクセル密度のタイル可能PBR(UVはワールド空間平面投影:石/漆喰 3m、木 1.5m、瓦 1.6m/リピート)。トライアングル数:LOD0 57k、LOD1 16k、LOD2 4.5k。
--render out/_keep.png --no-save でQAビューをレンダリングし、実際に確認してください。苦労して得られたルール:開いた屋上面は上を向いている必要があります;壁は屋根に沿っている必要があります(箱ではない)、そうでないと突き抜けます;隅石は壁の傾斜に合わせて傾ける;ワールド空間UVのみ。
これまでにビルドされた建物(すべてプロシージャル、すべて同じゲートを通る)
| アセット | 説明 | トライアングル数 LOD0/1/2 | 備考 |
|---|---|---|---|
samurai_keep_01 | 石垣の上の城郭(天守)、約23m | 57k / 16k / 4.5k | 金の飾りを含む5マテリアル |
minka_01 | 茅葺き農家、寄棟屋根、障子の縁側 | 12k / 3.4k / 0.9k | 茅葺き = でこぼこのハイトフィールド;壁はその下に0.22m沈む |
teahouse_01 | 水辺の茶屋、28本の杭 + 桟橋 + 提灯 | 20k / 6.5k / 0.8k | 原点 = 水面、+Y = 岸に向かう;origin_tolerance 3.6が必要(杭) |
各ジェネレーター:bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> QAレンダリングを確認 -> フィクスチャを保存 -> bin/gp build specs/<x>_01.json。 |
ランタイム(runtime/*.js)- export_world でゲームにコピー
assets.js(meshopt+KTX2のGLBローダー、バイオームテクスチャ配列) - terrain.js(7バイオームスプラット、アンチタイリング、接空間、遠景の紅葉キャノピー + スノーライン) - grass.js + grass_clump.js(チャンク化された階層、GPU風、踏みつけ;clumps: true = 背の高い稲田のような株(種の穂付き)) - water.js + water_waves.js(共有GPU/CPU波モデル、ベイクされたbed shoreline + 泡、吸収、コースティクス、平面反射、さざ波;浮遊物用の heightAt/normalAt/depthAt) - post.js(MSAA HDR -> ブルーム -> ACES -> グレーディング) -
foliage.js/trees.js(インスタンス化LODバケット、揺れ、半透明) - sky.js(3段階グラデーション、太陽ハロー、照らされた積雲 + 巻雲) - look.js(共有 looks/*.json、フィルライトを含む) - player.js - scatter.js - quality.js(アダプティブ解像度) - noise.js - noisetex.js(1つのタイル可能4チャンネルノイズテクスチャ) - 昼/夜、季節、天候:env_clock.js(太陽+月の天文計算)、env_atmosphere.js(looks/atmosphere.json からの太陽高度によるキーフレーム)、env_seasons.js(草/葉/地面/雪の状態と適用器)、env_weather.js、env_sky.js、env_lighting.js、env_grade.js - 生命:aquatic.js(葦、睡蓮、浮きゴミ、岸の岩)、fauna.js(鯉、鴨、トンボ)。
looks/golden_hour.json ルックは秋の低い太陽のルックです(太陽が西から16度、暖かい空、冷たいフィル、ブルーム + グレーディング)。カラーオーサリング:ルックJSONの色はシーンリニアです(sRGBではありません);草の色合いはディスプレイカラーとして作成され、シェーダーで二乗されます。
バリデーターコード(修正してください、黙殺しないでください)
BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS(予算超過) | UV_MISSING | MAT_PROCEDURAL(ベイクしてください) | TEX_BLANK(ベイクが静かに失敗した) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND(Math Round -> MASK でアルファをルーティング) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_*(エクスポートされたファイルの問題)。テクスチャジェネレーター:NOT_TILEABLE、TEX_FLAT、ALBEDO_RANGE、NORMAL_TOO_STRONG。
注意点
bpyコードやシェーダーコードを書く前に GOTCHAS.md を読んでください。ハイライト:ノードでは is ではなく == を使用;ベイクにはアクティブで選択されたイメージノードが必要;Blenderの画像はボトムアップ(入出力時に反転しないとすべてのノーマルマップが反転する);ORM/ノーマルマップはPNGでなければならない(JPEGのクロマサブサンプリングがデータチャンネルを破壊する);glTFアルファモードはRoundノードから来る;KTX2は削除しない限り2回エクスポートされる;バックグラウンドタブからのfpsは信頼しないでください。
カバーされていないこと(正直に)
モーションキャプチャ / 手動調整アニメーション(character レシピのクリップはコードで作成されます。docs/character.md を参照)、川/水中、サークルコライダーを超える地形ストリーミング/衝突、オーディオ、リジッドボディ物理(浮遊物の水面物理はカバーされています)、降水(天候状態は precip を保持します)。低LODの木はLOD0のノーマルマップを再利用します。
ラフネスはアルベドの輝度から導出されます。プロシージャルモデリングは手彫り/スキャンの忠実度ではありません。KTX2は1つのブラウザ/GPU(Apple M4 / Metal)で検証されています。