よつばゲームズ
ノード一覧に戻る

サーフェース書き出し

surface_export

サーフェースを、ゲームエンジン用のPNGテクスチャセット(見た目・法線・高さ・くぼみ・発光・ざらつき)として書き出します。

確認済み
解説あり

入力ポート

名前型説明
サーフェース
surface
Surface
必須
テクスチャセットとして書き出すサーフェースです。

出力ポート

名前型説明
プレビュー
preview
Image
書き出すサーフェースの見た目画像です。
警告
warnings
Text
省略マップ、世代混在の追加、セット全体のスキップに関する警告です。

パラメータ

名前型既定値範囲説明・選択肢
保存先(ベース)
path
FilePath
——

基準になる.pngパスです。ファイル名にマップごとのサフィックスが付きます(例: brick.png → brick_n.png)。

保存モード
save_mode
Enum
Disabled—

ファイルを保存するか、既存ファイルを上書きするかです。

  • 無効Disabled
  • 不足マップを追加CreateIfMissing
    既存ファイルを保持し、不足マップだけ追加します。異なる生成時点のマップが混在する可能性があります。
  • セットが無い時のみCreateSetIfMissing
    対象ファイルが1つも存在しない時だけ、マップセット全体を書き込みます。
  • 上書きOverwrite
命名規約
naming
Enum
Suffix—

マップセットのファイル命名規約です。

  • 短縮形Suffix
    base.png / base_n.png / base_h.png / base_ao.png / base_e.png / base_r.png
  • UnityUnity
    base_Albedo / base_Normal / base_Height / base_Occlusion / base_Emission / base_Roughness
  • GodotGodot
    base_albedo / base_normal / base_height / base_ao / base_emission / base_roughness
法線のY軸規約
normal_convention
Enum
OpenGL—

書き出し先エンジンのノーマルマップ規約です。内部はOpenGL規約で保持しているため、DirectXを選ぶとGチャンネルを反転します。

  • OpenGL (Godot等)OpenGL
    Gチャンネルが上向き(+Y)です。Godot や Blender で使われます。
  • DirectX (Unity等)DirectX
    Gチャンネルが下向き(-Y)です。Unity や Unreal で使われます。
拡大倍率
scale
Int
11–16

全マップに適用する整数倍の最近傍拡大です。

見た目を書き出す
export_albedo
Bool
true—

見た目の画像を書き出します。

法線を書き出す
export_normal
Bool
true—

法線マップがあれば書き出します。

高さを書き出す
export_height
Bool
true—

高さマップがあれば書き出します。

くぼみを書き出す
export_ao
Bool
true—

くぼみマップがあれば書き出します。

発光を書き出す
export_emission
Bool
true—

発光マップがあれば書き出します。

ざらつきを書き出す
export_roughness
Bool
true—

ざらつきマップがあれば書き出します。

概要

Surface をゲームエンジン用のPNGテクスチャセット(albedo/normal/height等)として 一括書き出しするノードです。HD-2D系の表現をエンジン側で行うための出口で、 命名規約(Godot/Unity等)と法線のY軸規約を選べます。

  • 副作用: あり(has_side_effects: true、ファイル書き込み)

使い方のポイント

  • エンジン別の定番設定: Godot(StandardMaterial3D)→ naming=Godot / normal=OpenGL、 Unity(Lit)→ naming=Unity / normal=DirectX(下の使用例参照)
  • 書き出し系共通の作法: 組み立て中は save_mode = Disabled、出すときだけ Overwrite
  • CreateIfMissingは不足mapだけを既存setへ追加する互換モードで、既存mapと今回追加した mapの世代が混在する場合は警告する。set全体を新規時だけ作るなら CreateSetIfMissingを選ぶ
  • ドット絵をエンジンで大きく表示するなら整数倍拡大(scale)もここで指定できる
  • 「PixPipeline内でライティングまで完成させてPNG1枚」なら surface_light_preview → batch_export。エンジン側でライトを当てるならこのノード、と出口を使い分ける

よくある失敗

  • エンジンで法線が凹んで見える: 法線のY軸規約の不一致。OpenGL/DirectXを エンジンに合わせる(内部保持はOpenGL、DirectX選択時のみG反転)
  • ファイルが出ない: save_mode が Disabled のまま(他のExport系と同じ)
  • 選んだマップの一部が出ない: 入力Surfaceにそのmapデータがありません。warningsと内部結果 _omitted_mapsで省略されたmap IDを確認してください

技術詳細

  • 内部のノーマルマップは OpenGL 規約(+Y up)で保持しており、DirectX 選択時のみ flip_normal_map_y()(pxn-core)で G チャンネルを反転する
  • 拡大は scale_image_nearest()(pxn-core)による最近傍補間
  • 有効でも入力Surfaceに存在しないマップはneutral画像を生成せず明示的に省略し、warningsと _omitted_maps: List<Text>へ安定IDを返す。_written_maps: List<Text>は今回実際に書いたmapだけを返し、 unchanged / already-existsは既存の_effect_outcomeで区別する

使用例

  • 画像からサーフェース → サーフェース書き出し で、HD-2D 系エンジンのマテリアルに読み込めるマップセットを作る
  • Godot の StandardMaterial3D へは naming=Godot / normal=OpenGL、Unity の Lit へは naming=Unity / normal=DirectX

関連ノード

  • solid_render / model_render / image_to_surface — 書き出すSurfaceの供給源
  • surface_light_preview + batch_export — アプリ内でライティング済みPNGを出す別ルート
  • model_gltf_export — メッシュごと持ち込むならこちら
  • tiled_tileset_export — タイルセット形式での出力

関連ノード

ソリッドレンダリングsolid_renderサーフェース光プレビューsurface_light_previewモデルGLB書き出しmodel_gltf_exportTiledタイルセットJSON断片tiled_tileset_export
ノード一覧に戻る
サーフェース書き出し — PixPipeline ノード解説