godot-3d-materials

3D マテリアル

Godot の PBR マテリアルと StandardMaterial3D に関する専門的なガイダンスです。

絶対にしてはいけないこと

• 金属度／粗さ／AO テクスチャを個別に使用しないでください — ORM パッキング（オクルージョン／粗さ／金属度の各チャンネルを持つ 1 枚の RGB テクスチャ）を使用し、テクスチャスロットとメモリを節約してください。
• normal_enabled を有効にし忘れないでください — normal_enabled = true を設定しないと、法線マップは機能しません。設定漏れに気づきにくいことがよくあります。
• 切り抜きマテリアルに TRANSPARENCY_ALPHA を使用しないでください — 代わりに TRANSPARENCY_ALPHA_SCISSOR または TRANSPARENCY_ALPHA_HASH を使用してください。アルファブレンディングは負荷が高く、ソートの問題を引き起こします。
• metallic = 0.5 に設定しないでください — マテリアルは金属（1.0）か非金属（0.0）のどちらかです。錆や汚れの境界を除き、その中間値は物理的に正しくありません。
• HDR を有効にせず emission を使用しないでください — 1.0 を超える emission 値が機能するのは、Project Settings で HDR レンダリングが有効な場合のみです。
• 広い環境表面に透過マテリアルを使用しないでください — 透明なオブジェクトは、フラグメントの早期棄却に Z バッファーを利用できないため、大量のオーバードローが発生します。メッシュのごく一部だけが透明な場合は、メッシュを不透明な表面と透明な表面の 2 つに分割してください。
• パフォーマンスが低下しているときに、わずかに異なる StandardMaterial3D リソースを何百個も作成しないでください — Godot は、まったく同じ設定フラグ（チェックボックス）を共有するマテリアル間で基になるシェーダーを自動的に再利用し、GPU の状態変更を最小限に抑えます。マテリアル設定をまとめてください。
• オブジェクト同士をさらに離すだけで Z ファイティングを解決しようとしないでください — 距離が離れるほど浮動小数点の精度は低下します。ちらつくテクスチャを修正するには、Camera3D の Near 平面プロパティを大きくし、Far プロパティを小さくして、精度の範囲を圧縮してください。
• MeshInstance3D ごとに固有の Material リソースを使用しないでください — これによりドローコールのバッチ処理が妨げられます。単一の共有マテリアルを維持したままパラメーターを変えるには、「Instance Uniforms」を使用してください。
• 実行時に共有 Material .tres／サーフェスマテリアルを変更しないでください — パラメーターを調整する前に duplicate(true) を呼び出すか、Local To Scene を有効にしてから、固有のインスタンスを割り当ててください。フラッシュ／ディゾルブには、material_fx.gd の ensure_unique_override()／オーバーレイヘルパーを必ず使用してください。
• Cull Mask なしで、動的に動くアクターにデカールを使用しないでください — プレイヤーが歩いても、弾痕がプレイヤーの顔に貼り付いたままにならないようにしてください。キャラクターのレイヤーをマスクしてください。

---

利用可能なスクリプト

必須：対応するパターンを実装する前に、該当するスクリプトを読んでください。

ワークフロールーター（必須／読み込まないでください）

タスク	読み込むもの	読み込まないもの
StandardMaterial3D／ORM／透過	pbr_orm_packer.gd, transparency_sorting_fix.gd, material_batcher.gd, material_fx.gd	triplanar_world*.gdshader, vertex_wind_sway.gdshader
UV のない地形／崖	triplanar_world.gdshader または triplanar_world_projection.gdshader + pbr_material_builder.gd	葉でない限り、風の揺れ
葉の風揺れ	vertex_wind_sway.gdshader	岩／地形にも必要な場合を除き、トライプラナー
実行時のダメージ／ディゾルブ	必須 material_fx.gd	共有インポート済みマテリアルの編集
インスタンスの色／体力／テクスチャ配列のバリエーション	必須 instance_uniform_batching.gdshader	メッシュごとの固有の StandardMaterial3D のコピー、ボディのテクスチャ配列サンプル
HLOD／遠距離マテリアルの簡略化	material_batcher.gd（setup_lod_materials）	アルファブレンドによる距離フェード（Pixel Dither を使用）
有機物の SSS／リム／クリアコート	organic_material.gd, subsurface_scattering_setup.gd	Mobile／Compatibility での SSS の設定例

StandardMaterial3D のアルベド／ORM／透過のみを扱う場合：トライプラナー、風、テクスチャ配列の各シェーダーは読み込まないでください。

material_fx.gd

実行時 FX には必須です。ensure_unique_override()／オーバーレイフラッシュ／シザー・ディゾルブを使用してください。共有 .tres マテリアルをトゥイーンしないでください。

pbr_material_builder.gd

ORM テクスチャとトライプラナー マッピングを使用した、実行時の PBR マテリアル作成です。

organic_material.gd

有機的な表面（皮膚、葉）のための、サブサーフェス散乱とリムライティングの設定です。リアルなキャラクターや植生のマテリアルに使用します。

triplanar_world.gdshader

UV マッピングなしで地形に適用する、トライプラナー投影シェーダーです。表面法線に基づいてテクスチャをブレンドします。崖、洞窟、プロシージャルな地形に使用します。

pbr_orm_packer.gd

高機能な PBR リソースユーティリティです。アンビエントオクルージョン、ラフネス、メタリックを 1 枚の ORM テクスチャにまとめ、VRAM とドローコールを最適化します。

vertex_wind_sway.gdshader

GPU 駆動による高パフォーマンスな葉のアニメーションです。頂点のワールド座標と頂点カラーのウェイトペイントを使用して、スケルトンなしで風をシミュレートします。

triplanar_world_projection.gdshader

UV を使わない環境マッピングです。X／Y／Z 軸に沿ってテクスチャを投影し、複雑な岩や地形に有機的なブレンドを施します。

subsurface_scattering_setup.gd

リアルな有機マテリアルの設定です。Forward+ レンダリング向けに、Skin Mode、Transmittance、深度散乱の設定を扱います。

instance_uniform_batching.gdshader

高速バッチ処理のためのアーキテクチャパターンです。インスタンスユニフォームを通じて個別の色や体力状態を維持しながら、10,000 個のメッシュで 1 つのマテリアルを共有できます。

decal_placer_expert.gd

衝撃エフェクト向けの、カリングマスクとライフサイクル管理を備えた動的な 3D デカールシステムです。

transparency_sorting_fix.gd

アルファハッシュと深度プリパスの手法を使用して、描画アーティファクトを解決します。

shader_state_manager.gd

複数のエンティティでシェーダーベースの視覚状態（Frozen、Burned）を切り替えるための、シンプルなパターンです。

depth_precision_fix.gd

大規模なワールドで発生する Z ファイティングやテクスチャのちらつきを解消する、カメラ側の修正です。

material_batcher.gd

環境メッシュを最適化された状態固定バッチで描画するための、グローバルオーバーライドシステムです。

---

StandardMaterial3D チェックリスト（スクリプト優先）

1. AO／ラフネス／メタリックをまとめる → pbr_orm_packer.gd は必須です。orm_texture を設定してください（3 枚の個別マップは使用しないでください）。
2. normal_texture を割り当てる前に normal_enabled を有効にしてください（有効にしない場合、何も起こりません）。
3. 下のマトリクスから透明度を選択してください。カットアウトにドキュメント既定の ALPHA を使用しないでください。
4. 有機的な皮膚／葉 → organic_material.gd + subsurface_scattering_setup.gd（実際の SSS は Forward+ のみ）。
5. 実行時のフラッシュ／ディゾルブ → 最初に material_fx.gd の ensure_unique_override() を呼び出すことが必須です。
6. 共有メッシュの色調／バリエーション → instance_uniform_batching.gdshader を使用してください。インスタンスごとに固有の .tres を作成しないでください。
7. 遠距離 LOD の簡略化／ピクセルディザーフェード → material_batcher.gd の setup_lod_materials() を使用してください。
8. SSS／クリアコート／異方性を有効にする前に、Forward+ と Mobile の機能マトリクスを確認してください。

Forward+ と Mobile（マテリアル機能）

機能	Forward+	Mobile / Compatibility	理由
サブサーフェス・スキャタリング / スキンモード	完全対応	制限あり / 多くの場合利用不可	SSS には Forward+ のライティング経路が必要です。Mobile ではリムライトとトランスミッタンスのベイクで代用します
クリアコート	対応	多くの場合、削除または近似	スペキュラローブの追加にはコストがかかります。遠距離の LOD と Mobile では削除します
異方性	対応	オフを推奨	フローマップと異方性 BRDF は、モバイルのフラグメント予算を消費します
アルファハッシュ / ピクセルディザーフェード	対応	アルファスキッサーまたは不透明ディザーを推奨	ハッシュノイズとオーバードローはタイル GPU に負荷をかけます
インスタンスユニフォーム（バッチング）	対応	対応（こちらを推奨）	マテリアルを 1 つに保ち、リソース固有化によるドローの分割を避けられます

---

透明度モード

選択マトリックス

モード	用途	パフォーマンス	ソートの問題
ALPHA_SCISSOR	葉、金網フェンス	高速	なし
ALPHA_HASH	ディザーフェード、LOD 遷移	高速	ノイズあり
ALPHA	ガラス、水、godot-particles	低速	あり（描画順）

アルファスキッサー（カットアウト）

# For leaves, grass, fences
mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_SCISSOR
mat.alpha_scissor_threshold = 0.5  # Pixels < 0.5 alpha = discarded
mat.albedo_texture = load("res://leaf.png")  # Must  have alpha channel

# Enable backface culling for performance
mat.cull_mode = BaseMaterial3D.CULL_BACK

アルファハッシュ（ディザリング）

# For smooth fade-outs without sorting issues
mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA_HASH
mat.alpha_hash_scale = 1.0  # Dither pattern scale

# Animate fade
var tween := create_tween()
tween.tween_property(mat, "albedo_color:a", 0.0, 1.0)

アルファブレンド（完全な透明度）

# For glass, water (expensive)
mat.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
mat.blend_mode = BaseMaterial3D.BLEND_MODE_MIX

# Disable depth writing for correct blending
mat.depth_draw_mode = BaseMaterial3D.DEPTH_DRAW_DISABLED
mat.cull_mode = BaseMaterial3D.CULL_DISABLED  # Show both sides

---

テクスチャチャンネルのパッキング

R=AO / G=Roughness / B=Metallic のパッキングには、必ず pbr_orm_packer.gd を使用してください。ここにパッキング方法を直接記述しないでください。カスタムのチャンネル再マッピングは、インポート済みのアトラスが ORM レイアウトとすでに一致しない場合に限ります。

---

シェーダーの変換

ShaderMaterial に変換する場合

• カスタムエフェクトが必要な場合（ディゾルブ、頂点変位）
• StandardMaterial3D の制限に達した場合
• シェーダーを最適化する場合（未使用の機能を削除）

変換ワークフロー

# 1. Create StandardMaterial3D with all settings
var std_mat := StandardMaterial3D.new()
std_mat.albedo_color = Color.RED
std_mat.metallic = 1.0
std_mat.roughness = 0.2

# 2. Convert to ShaderMaterial
var shader_mat := ShaderMaterial.new()
shader_mat.shader = load("res://custom_shader.gdshader")

# 3. Transfer parameters manually
shader_mat.set_shader_parameter("albedo", std_mat.albedo_color)
shader_mat.set_shader_parameter("metallic", std_mat.metallic)
shader_mat.set_shader_parameter("roughness", std_mat.roughness)

---

マテリアルバリアント（Godot 4.0+）

効率的なマテリアルの再利用

# Base material (shared)
var base_red_metal := StandardMaterial3D.new()
base_red_metal.albedo_color = Color.RED
base_red_metal.metallic = 1.0

# Variant 1: Rough
var rough_variant := base_red_metal.duplicate()
rough_variant.roughness = 0.8

# Variant 2: Smooth
var smooth_variant := base_red_metal.duplicate()
smooth_variant.roughness = 0.1

# Note: Use resource_local_to_scene for per-instance tweaks

---

パフォーマンスの最適化

マテリアルのバッチング

# ✅ GOOD: Reuse materials across meshes
const SHARED_STONE := preload("res://materials/stone.tres")

func _ready() -> void:
    for wall in get_tree().get_nodes_in_group("stone_walls"):
        wall.material_override = SHARED_STONE
    # All walls batched in single draw call

# ❌ BAD: Unique material per mesh
func _ready() -> void:
    for wall in get_tree().get_nodes_in_group("stone_walls"):
        var mat := StandardMaterial3D.new()  # New material!
        mat.albedo_color = Color(0.5, 0.5, 0.5)
        wall.material_override = mat
    # Each wall is separate draw call

テクスチャアトラス

# Combine multiple materials into one texture atlas
# Then use UV offsets to select regions

# material_atlas.gd
extends StandardMaterial3D

func set_atlas_region(tile_x: int, tile_y: int, tiles_per_row: int) -> void:
    var tile_size := 1.0 / tiles_per_row
    uv1_offset = Vector3(tile_x * tile_size, tile_y * tile_size, 0)
    uv1_scale = Vector3(tile_size, tile_size, 1)

---

エッジケース

法線マップが機能しない

# Problem: Forgot to enable
mat.normal_enabled = true  # REQUIRED

# Problem: Wrong texture import settings
# In Import tab: Texture → Normal Map = true

モデルにテクスチャの継ぎ目ができる

# Problem: Mipmaps causing seams
# Solution: Disable mipmaps for tightly-packed UVs
# Import → Mipmaps → Generate = false

マテリアルが平坦に見える

# Problem: Missing normal map or roughness variation
# Solution: Add normal map + roughness texture

mat.normal_enabled = true
mat.normal_texture = load("res://normal.png")
mat.roughness_texture = load("res://roughness.png")

---

エキスパート向けテクニックと最適化

1. ピクセルディザーを使用した LOD 遷移

Hierarchical Level of Detail（HLOD）または Visibility Ranges を使用して、遠距離でオブジェクトをフェードアウトする場合、標準のアルファブレンドでは透明な境界が重なり、パフォーマンスが大幅に低下します。代わりに、マテリアルの Distance Fade モードを Pixel Dither に設定してください。知覚的に滑らかなフェードを実現しながら、高性能な不透明描画パイプライン内で処理できます。

2. ステンシルバッファ（Godot 4.5+）

StandardMaterial3D でステンシルバッファを直接使用します。基本的なエフェクトのためにカスタムシェーダーを書くことなく、壁の後ろに隠れたオブジェクトの輪郭や X 線エフェクトを簡単に描画できます。

3. AR シャドウオーバーレイシェーダー

AR ゲームを開発している場合、現実世界のカメラ映像に仮想の影を表示したいことがあります。標準的なブレンドの代わりに、空間シェーダーで Godot 組み込みの shadow_to_opacity レンダーモードを使用します。

shader_type spatial;
// shadow_to_opacity makes the material invisible when lit, 
// but opaque (dark) when it receives a shadow from another 3D object.
render_mode blend_mix, depth_draw_opaque, cull_back, shadow_to_opacity;

void fragment() {
    // The surface color is black; opacity will be driven by incoming shadows
    ALBEDO = vec3(0.0, 0.0, 0.0);
}

---

エキスパートパターン：マテリアル・テクスチャ配列（インスタンスバリエーション）

インスタンスごとの色／体力およびテクスチャ配列インデックスのバリアントには、必ず instance_uniform_batching.gdshader を使用してください。GeometryInstance3D.set_instance_shader_parameter で texture_index を設定し、樹木や群衆のバリアントごとに固有のマテリアルを作成しないでください。

---

エキスパートパターン：ディゾルブシェーダーの統合（アルファスキッサー）

アルファスキッサーを使用すると、ディゾルブのパフォーマンスを高められます（影を維持し、アルファソートを回避します）。オーバーライドを先に複製する material_fx.gd の dissolve_scissor() を必ず使用してください。

---

エキスパートパターン：マテリアル LOD システム（HLOD）

メッシュ LOD は自動ですが、マテリアルのシェーディングは自動ではありません。可視範囲に応じた切り替え、遠距離のマテリアルからの機能削除、アルファブレンドではなくピクセルディザーによる距離フェードには、material_batcher.gd の setup_lod_materials() を必ず使用してください。

専門家の知見（理由 — 本文に記載）

• ORM パッキング — 理由：マップが3つに分かれていると、サンプラー枠が3倍になり、バッチ処理が妨げられます。1つのRGBテクスチャに AO／ラフネス／メタリックをまとめます（pbr_orm_packer.gd）。
• メタリック値 0.5 — 理由：PBR における金属の値は 0 または 1 です。中間値を使うのは、汚れや錆への遷移に限られ、デフォルトの塗装には使いません。
• 共有マテリアルの変更 — 理由：共有 .tres を変更すると、すべてのインスタンスに影響します。実行時の FX を適用する前に duplicate(true) を使うか、Local To Scene を有効にしてください（material_fx.gd）。
• ピクセルディザの LOD フェード — 理由：アルファブレンドによる距離フェードでは、フラグメントが透明描画パイプラインに残ります。ディザなら不透明のままです（material_batcher.gd）。

詳細レシピ（必要に応じて）

トピック	リファレンス／スクリプト
金属／誘電体プリセット／SSS／クリアコート	pbr-workflows.md

リファレンス

段階的開示：特定の API を調べる場合にのみ公式ドキュメントへのリンクを開いてください。 関連スキルは、作業を別の専門領域に振り分ける際に読み込み、スキル全体を事前に読み込まないでください。

公式ドキュメント

• Standard Material 3D と ORM Material 3D — StandardMaterial3D のアルベド／メタリック／ラフネス、ORM パッキング、透明モード、機能フラグを解説する PBR の主要チュートリアルです。
• BaseMaterial3D — 透明度の列挙型、テクスチャチャンネル、カリング／深度描画、距離フェード、サブサーフェススキャタリング制御の共通 API です。
• StandardMaterial3D — このスキルのビルダー、FX ヘルパー、プリセットで使用する具体的なマテリアルクラスです。
• ORMMaterial3D — オクルージョン／ラフネス／メタリックがすでに1つの RGB テクスチャにまとまっている場合に使う、専用の ORM パック済みマテリアルの経路です。
• デカールの使用 — 専用マテリアルを増やさずに弾痕やディテールを表現するための、プロジェクターデカール、カリングマスク、パフォーマンス上の制限を解説します。
• 画像のインポート — PBR マップをカラー データとして扱わないための、正しいノーマルマップとチャンネルのインポート設定を解説します。
• 可視性範囲（HLOD） — 簡略化した遠景用マテリアルやピクセルディザの距離フェードと組み合わせる、距離による切り替え／フェードモードを解説します。
• Spatial シェーダー — StandardMaterial3D では不十分な場合に使う、トライプラナー、風による揺れ、instance uniform、shadow_to_opacity の組み込み機能を解説します。
• 初めての3Dシェーダー — StandardMaterial3D の設定を編集可能な spatial ShaderMaterial に変換する方法を解説します。
• GeometryInstance3D — 共有マテリアルのバッチ処理に使う set_instance_shader_parameter、マテリアルのオーバーレイ／オーバーライド、可視性範囲のプロパティを解説します。
• GPU の最適化 — ORM パッキングや専用マテリアルの回避につながる、オーバードロー、透明描画のコスト、バッチ処理の指針を解説します。

関連スキル

前提条件

• godot-project-foundations — 再利用可能な .tres マテリアルやテクスチャセットを作成する前に必要な、ノード、リソース、インポートの基本事項です。
• godot-resource-data-patterns — マテリアル／テクスチャのリソース、複製と共有の使い分け、ドローコールのバッチ処理を維持するデータ駆動型プリセットについて説明します。
• godot-shaders-basics — StandardMaterial3D を変換したり、トライプレーナー／インスタンスユニフォームシェーダーを作成したりする前に必要な、シェーディング言語と ShaderMaterial の基礎です。

関連項目

• godot-3d-lighting — シーン内で PBR マテリアルや発光マテリアルが実際にどう見えるかを左右する、発光エネルギー、HDR、GI、AreaLight3D の相互作用について説明します。
• godot-3d-world-building — 大規模なレベルジオメトリ全体に、共有環境マテリアル、デカール、トライプレーナー投影を適用する方法を説明します。
• godot-camera-systems — マテリアルだけでは解決できない Z ファイティング／深度精度の問題を解消する、Camera3D のニア／ファー設定とフレーミングの選択について説明します。
• godot-particles — マテリアルの透明度設定（スキザー／ハッシュとブレンド）に合わせる必要がある、パーティクルの描画モードとアルファ処理について説明します。
• godot-performance-optimization — 個別マテリアルと共有マテリアルを拡張する際の、ドローコールのバッチ処理、MultiMesh、GPU 予算について説明します。
• godot-debugging-profiling — マテリアル変更後に透明度やマテリアル状態のリグレッションを検証するための、GPU／オーバードローのプロファイラーについて説明します。

下流／利用するスキル

• godot-genre-open-world — 大規模なワールドでは、このスキルで扱う HLOD の可視範囲、ディザリングによる距離フェード、共有マテリアルのバッチ処理パターンを利用します。
• godot-procedural-generation — プロシージャルメッシュや地形では、UV がない場合や不安定な場合に、トライプレーナー／ワールド投影マテリアルが一般的に必要です。
• godot-adapt-2d-to-3d — 平面のアートを 3D に移行するには、ここで扱う PBR マップの設定、法線のインポート、透明度モードの選択が必要です。

マスター

• godot-master — スキル横断での発見を支援するライブラリルーター兼ミラーリングされたモジュールエントリです。