3D機能

PixPipeline の3D機能には、目的の違う2本のレーンがあります。

Solid は計算式で形を持つため、穴あけや融合に強い一方、ゲーム向けの整理された三角形には なりません。Model は三角形を正本にするため GLB に向きますが、ブーリアンは行いません。 Model では部品をめり込ませて重ねるのが正常な作り方です。

Isometric — IsoWorld が正本

アイソメ制作では IsoWorld がユーザー向けの正本です。推奨経路は IsoBlock / IsoItemBuilder -> IsoAssemble -> IsoPlace -> IsoWorldCompose -> IsoWorldToScene です。IsoScene は描画直前の内部 IR で、既存プロジェクトとの 互換性と高度な調整のために公開ノードを維持しています。

• Standard: iso_block, iso_item_builder, iso_assemble, iso_place, iso_world_compose, iso_world_to_scene
• Advanced: iso_surface, iso_extrude, sprite_stack, iso_scene_compose, iso_scene_render, iso_scene_to_surface_geometry

新しいグラフは World 系から組み、Scene 系を直接つなぐのは内部 IR の構造が必要な場合に 限ります。Advanced ノードはパレットで折りたたまれますが、検索では通常どおり見つかります。

Solid — 3D素体システム

• パラメトリックな基本形(ボックス/球/円柱/円錐/トーラス/階段/坂)を Solid カテゴリの ノードで作り、変換・合体(なめらか融合対応)・くり抜き・交差で組み合わせる
• パスから押し出し/回転体を作るノードもある
• 3Dビュー(Solid 3D ステージ)で角度を確認しながら編集できる
• Solid は3Dモデルとして書き出せません。GLBが必要ならModelを使います

Model — ゲーム用メッシュ組み立て

• model_box / model_cylinder / model_cone / model_wedge などで部品を作る
• model_transform で移動・回転・非uniform拡縮・pivotを設定し、model_group で同じ GLBへまとめる。部品同士の面を縫い合わせたり、内部面を削除したりはしない
• model_extrude / model_revolve で閉じたベジェパスを押し出し・回転体へ変換できる
• Model 3D ステージではパーツを選び、ギズモの操作を生成元ノードへ書き戻せる。 頂点・面・UVの手編集はできない
• model_gltf_export は自己完結した .glb を保存する。Animation Frames を2以上にすると、 stable PartIdごとの剛体TRSをglTF animationとしてベイクする

2D画像からPBRテクスチャを作る

pbr_material は通常のImageを、base color / tangent normal / roughness / metallic / AO / emissionへ明示的に割り当てます。base colorとemissionはsRGB、その他はlinearです。 normalにはタンジェント空間のOpenGLまたはDirectX規約を指定します。Surfaceのビュー空間normalを そのまま接続することはできません。

各モデル生成ノードの Texture Layout を model_texture_layout へ接続すると、UVガイド、 領域マスク、推奨解像度を2D画像として使えます。最近傍サンプリング時も境界がにじまないよう、 texture_layout_dilate でgutterへ端色を延長してからPBR素材へ束ねます。

再編集用素材として保存する

完成品を書き出す前のModelとSolidは、専用のネイティブ素材として別プロジェクトから再利用できます。

• model_asset_save / model_asset_load
  • .pxmodelへModel階層、stable PartId、メッシュ、ピボット、PBR画像をまとめて保存・読込する
  • 既定フォルダはuser_data/library/models。設定の「Model素材ライブラリ」から変更できる
• solid_asset_save / solid_asset_load
  • .pxsolidへSDFツリーをそのまま保存・読込する。ポリゴン変換は行わない
  • 既定フォルダはuser_data/library/solids。設定の「Solid素材ライブラリ」から変更できる

どちらの保存ノードも初期状態では書込無効です。保存時だけCreateIfMissingまたはOverwriteを 選びます。アトミック保存と読戻し検証を行い、アニメーションの複数フレーム評価中は途中フレームを 保存しません。

Solid Render — 3D→ドット絵化

• solid_render が立体を1ピクセル=1レイのオルソグラフィックレンダリングで Surface(法線・高さ・深度・素材ID付きの多層画像)に変換する
• 2:1アイソメなどの角度プリセットがあり、pixels_per_unit でドット密度を決める

同梱サンプル workflows/solid_turntable_phase10.ppl は、タイムソースでソリッドを回しながら ソリッドレンダリング → アニメーションレンダー で回転スプライトを作る最小構成です。

model_render も同じパラメータ語彙でModelをSurfaceへ変換します。アニメーションや8方向素材では frame_mode = FixedCanvas を使い、全フレームの大きさと中心を固定してください。

Surface とライティング

• Surface は albedo(色)のほかに normal / height / AO / emission / roughness の サブマップを持つ「ドット絵用のGバッファ」
• ライティング系ノードで陰影段数・OKLCH調整・パレットスナップを制御し、 ドット絵らしい段階的な陰影に落とし込む
• ライティング定義は user_data/definitions/lighting/ に保存でき、素材間で共有できる

手描き絵の3D化

• height_from_image — シルエットや明るさから高さマップを推定する
• かんたん陰影 (Quick Shade) — 1ノードでドット絵に光と影をつける入門ノード

書き出し

• surface_export — Surface をゲームエンジン用のPNGテクスチャセットとして一括書き出しする (命名規約・normalのY軸規約・整数倍拡大に対応)
• model_gltf_export — Modelをテクスチャ込みのGLBとして書き出す。通常は Save Mode = Disabled のまま編集し、保存先を確認してから CreateIfMissing または Overwrite にする
  • 保存済みプロジェクトではexports/models、未保存プロジェクトでは設定の 「3Dモデル書き出し」フォルダが保存ダイアログの初期位置になる

詳しい手順は workflows/model-asset-basics.md と workflows/model-chest-animation.md を参照してください。