3d-essentials

Name: 3d-essentials
Author: jame581

github.com/jame581開発889180 回インストール4 日前に更新

リポジトリ

3d-essentials について

Godot 4.3+で3D開発を学ぶ開発者向けのスキルです。シーン構成、マテリアル、ライティング、環境効果に加え、レンダラー選択や最適化をGDScriptとC#の例で解説します。

主な機能

013D座標系と主要ノード
02マテリアル設定と透明モード
03ライティング、影、ベイクモード
04環境効果とグローバルイルミネーション
05フォグとデカール
06LOD、カリング、MultiMeshによる最適化

活用シーン

01基本的なライティングを備えたGodot 3Dシーンの構築
02マテリアル、フォグ、ポストプロセスの設定
03プロジェクト要件に応じたレンダラー選択
04多数のメッシュを含むシーンの最適化

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jame581/godotprompter --skill 3d-essentials

インストール後、Claude Code で/3d-essentialsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

common-pitfalls.md

decals.md

environment-and-post.md

fog-recipes.md

global-illumination.md

godot-4.7-additions.md

lod-and-culling.md

materials-and-lighting-recipes.md

renderer-comparison.md

詳細

Godot 4.3+ の3D基礎

すべての例は、非推奨 API を使用せず、Godot 4.3+ を対象としています。まず GDScript を示し、続いて C# を示します。

関連スキル： レンダラーの選択、ライティング戦略、AA と解像度スケーリングについては rendering-pipeline、CharacterBody3D の移動については player-controller、3D コリジョンシェイプとレイキャスティングについては physics-system、Camera3D の追従とトランジションについては camera-system、空間シェーダーとポストプロセスについては shader-basics、3D のパフォーマンス調整については godot-optimization、AnimationTree と3Dアニメーションのブレンドについては animation-system を参照してください。

1. 3D座標系と主要ノード

座標系

Godot はメートル法の単位（1単位 = 1メートル）を使う右手座標系を採用しています。

軸	方向	色
X	右	赤
Y	上	緑
Z	画面の外（+Z は視聴者側）	青

カメラとライトは、デフォルトで -Z 方向を向きます。キャラクターが「前を向く」場合、-Z 方向を向きます。

主要な3Dノード

ノード	用途
`Node3D`	基本のトランスフォームノード — 位置、回転、スケール
`MeshInstance3D`	マテリアルを使ってメッシュを表示します
`Camera3D`	3Dのレンダリングに必要 — 透視投影または正投影
`DirectionalLight3D`	太陽／月 — 平行光線を放つ、最も軽量なライト
`OmniLight3D`	点光源 — 全方向に光を放ちます
`SpotLight3D`	円錐状の光 — 懐中電灯、スポットライト
`WorldEnvironment`	スカイ、フォグ、トーンマッピング、ポストプロセス
`Decal`	サーフェスに投影するテクスチャ
`GPUParticles3D`	GPU 駆動のパーティクルエフェクト
`CSGBox3D` など	コンストラクティブソリッドジオメトリ — プロトタイピング
`GridMap`	3Dタイルベースのレベル構築

Godot 4.7+： GridMap は空間クエリ用に内部オクタントを公開します（cell_octant_size、get_used_octants()、get_octants_in_bounds() など）。これにより、すべてのセルを走査する代わりに、作業範囲をリージョンに絞り込めます。CSGShape3D には、自動的な面のスムージングを行う autosmooth／smoothing_angle が追加されます。メソッド一覧と仕様の全容については、references/godot-4.7-additions.md を参照してください。

最小限の3Dシーン

World (Node3D)
├── Camera3D
├── DirectionalLight3D
├── WorldEnvironment
├── MeshInstance3D (floor)
└── MeshInstance3D (player model)

2. マテリアル

StandardMaterial3D と ShaderMaterial

マテリアル	用途	備考
`StandardMaterial3D`	ほとんどの3Dオブジェクト — PBR ワークフロー	コード不要。インスペクターで設定
`ORMMaterial3D`	ORM テクスチャをパックした Standard と同様のマテリアル	オクルージョン＋ラフネス＋メタリックを1つのテクスチャに格納
`ShaderMaterial`	トゥーン、水、ディゾルブなどのカスタムエフェクト	空間シェーダーコードが必要

StandardMaterial3D の主要プロパティ

PBR の基本要素：albedo_color／albedo_texture（ベースカラー）、metallic（0 は誘電体 → 1 は金属）、roughness（0 は鏡面 → 1 はマット）、normal_enabled と組み合わせる normal_texture（サーフェスのディテール）、ao_texture（アンビエントオクルージョン）。自己発光には emission と emission_energy_multiplier を追加し、視差には heightmap_texture を、マテリアルのアクセントには rim／clearcoat を使います。

透明度モード

通常の Alpha（低速で、影なし）よりも、Alpha Scissor（高速で、影付きの切り抜き）または Alpha Hash（ディザリング。髪などに適しています）を優先してください。Depth Pre-Pass は、透明なエッジを持つほぼ不透明なメッシュに適しています。

比較表については、references/materials-and-lighting-recipes.md を参照してください。

コードからのマテリアル設定とマテリアルのインスタンス化

実行時に StandardMaterial3D を作成して mesh.material_override に割り当て、Tween で発光フラッシュを制御します。.duplicate() を使ってインスタンスごとのコピーを作成すれば、1つのメッシュのマテリアルを変更しても、ほかのメッシュに影響しません。

基本的なマテリアル設定、発光フラッシュ、インスタンスごとの複製、動的な OmniLight3D の爆発エフェクトを含む GDScript と C# のレシピ全体については、references/materials-and-lighting-recipes.md を参照してください。

3. ライティング

ライトの種類の比較

ライト	形状	シャドウ	コスト	最大表示数
`DirectionalLight3D`	平行光線	PSSM	最も低コスト	8（Forward+）
`OmniLight3D`	球体	キューブ／デュアルパラボロイド	中程度	512（クラスター化）*
`SpotLight3D`	円錐	単一テクスチャ	低コスト	512（クラスター化）*
`AreaLight3D`（4.7+）	長方形	PCSS ソフトシャドウ	最も高コスト	—

*Forward+ では、512 個のクラスター化要素スロットをオムニライト、スポットライト、デカール、リフレクションプローブで共有します。

ライトのプロパティ

主な設定項目：light_color、light_energy（HDR — 1 より大きい値も有効です）、shadow_enabled（パフォーマンスへの影響が大きい項目です）、directional_shadow_mode、directional_shadow_max_distance（値を小さくするとシャドウが鮮明になります）。

プロパティの一覧と、GDScript および C# による太陽の設定例については、references/materials-and-lighting-recipes.md を参照してください。

AreaLight3D（Godot 4.7+）

AreaLight3D はノードの -Z 方向に長方形の面から光を放ちます（ネオン管、スクリーン、ソフトボックスパネルなど）。light_size によって PCSS ソフトシャドウを生成します。モバイルのサポートは限定的で、Compatibility ではエリアライトのシャドウを生成できません。また、Forward+ では可視のエリアライトを 1 つ追加するごとに、レンダリングされるすべてのオブジェクトのクラスター化ライティングコストが増加するため、シネマティック用途やハイエンド環境に限定してください。

プロパティの一覧と、GDScript および C# による設定手順については、references/materials-and-lighting-recipes.md を参照してください。

動的ポイントライト

実行時に OmniLight3D を生成し、トゥイーンでエネルギーを変化させ、完了時にキューから解放します。爆発、マズルフラッシュ、魔法のエフェクトなどによく使われます。

GDScript および C# による完全な手順については、references/materials-and-lighting-recipes.md を参照してください。

シャドウの設定とベイクモード

シャドウアクネ対策には shadow_bias よりも shadow_normal_bias を優先してください。directional_shadow_max_distance は必要最小限に設定してください（一般的には 50～100 m）。ベイクモード：Disabled（完全なリアルタイム処理。GI では無視されます）、Static（完全にベイクされ、実行時コストはありません）、Dynamic（デフォルト。間接光はライトマップにベイクされ、直接光はリアルタイムで処理されます）。

シャドウ調整の一覧とベイクモードの一覧については、references/materials-and-lighting-recipes.md を参照してください。

4. 環境とポストプロセス

Environment リソースを保持する WorldEnvironment ノードを通じて、空の背景、トーンマッピング、グロー、SSR、SSAO／SSIL／SDFGI、被写界深度などのグローバルなレンダリング設定を行います。Environment リソースでトーンマップを選択します（Linear、Reinhard、Filmic、ACES、または Godot 4.4 以降の AgX）。Forward+ では SSAO、SSIL、SSR、SDFGI が有効になります。Mobile レンダラーではこれらが省略され、Compatibility では SSAO のみを利用できます（4.6 以降）。

セットアップ手順の詳細（空のオプション、トーンマップモード、すべてのポストプロセスエフェクト、4.6 以降のグローブレンドとデフォルト設定の変更、AgX の tonemap_agx_white／tonemap_agx_contrast コントロール、4.6 以降の SSR 品質向上）については、references/environment-and-post.md を参照してください。

Godot 4.7 以降： display/window/hdr/request_hdr_output は HDR ディスプレイ出力を要求します（起動時に読み取られます。実行時には Window.hdr_output_requested を切り替えてください）。⚠️ rendering/reflections/sky_reflections/roughness_layers のデフォルト値は、4.6.0～4.6.1 での 7 から再び 8 になります。詳細は references/environment-and-post.md を参照してください。

5. グローバルイルミネーション

GI には、品質とコストのバランスが異なる 5 つの選択肢があります。なし（環境光のみ）→ ReflectionProbe（局所的）→ LightmapGI（最高品質、ベイク済み）→ VoxelGI（小規模〜中規模の動的シーン）→ SDFGI（大規模なオープンワールド）です。VoxelGI と SDFGI には Forward+ が必要です。LightmapGI は 3 つすべてのレンダラーで利用できますが、ベイクできるのは Forward+ または Mobile のエディターのみです。以下の 4.5+ のサブセクションは、すべての GI 方式に適用されます。

方式の比較表、ReflectionProbe のシーンとコードのレシピ、LightmapGI のベイクワークフロー、SDFGI の設定については、references/global-illumination.md を参照してください。

スペキュラーオクルージョンとベンド法線マップ（Godot 4.5+）

4.5 以降では、すべてのレンダラーで、各ピクセルに届く環境光に応じて間接スペキュラーが減光されます。デフォルトで有効になっており、再ベイクは不要です。rendering/reflections/specular_occlusion/enabled で全体的に無効化するか、シェーダーごとに render_mode specular_occlusion_disabled で無効化できます。StandardMaterial3D の ベンド法線 スロットには、ベイク済みのベンド法線マップを設定すると、主役となるアセットの間接光を改善できます。

それぞれが効果を発揮する場面とベンド法線の設定については、references/global-illumination.md を参照してください。

6. フォグ

フォグには 3 つのレイヤーがあります。WorldEnvironment.environment で設定する深度／高さフォグ（低コストで、すべてのレンダラーに対応）、ボリューメトリックフォグ（Forward+ のみ。深度を通したゴッドレイに対応）、そして局所的なフォグ効果（屋内の部屋、穴、雰囲気を演出するボリューム）に使う FogVolume ノードです。

深度／高さフォグの設定、ボリューメトリックフォグのパラメーターとパフォーマンスに関する注意点、FogVolume の配置について、GDScript と C# の完全なレシピは references/fog-recipes.md を参照してください。

⚠️ Godot 4.7 での変更： 新しいプロジェクト設定 rendering/environment/fog/use_legacy_blending（デフォルトは false）を使うと、Godot 4.5 以前のボリューメトリックフォグのブレンディングが復元されます（GH-119414。4.6 ブランチにも適用）。ブレンディング自体は 4.6 で変更され、より物理的に正確になったため、4.5 で調整したフォグはアップグレード後に明るく見えます（GH-112494）。以前の見た目を正確に再現するには、この設定を有効にしてください。有効にしない場合は、フォグの密度またはライトの Volumetric Fog Energy を下げてください。

7. デカール

Decal ノードは、バウンディングボックス内にあるあらゆるサーフェスにテクスチャを投影します。弾痕、血しぶき、地面のディテール、看板などに使えます。Forward+ と Mobile はデカールを描画しますが、Compatibility は対応していません。パフォーマンスはオーバードローとデカール数に応じて変化します。

シーンの設定、実行時に生成するレシピ（GDScript + C#）、レンダラーごとのデカール上限については、references/decals.md を参照してください。

8. 最適化 — LOD、カリング、MultiMesh

最適化には 4 つのツールがあります。自動メッシュ LOD（インポート時または MeshInstance3D ごとに設定）、段階的な切り替えに使う手動の VisibilityRange、OccluderInstance3D を使ったオクルージョンカリング、そして 1 回のドローコールで同一メッシュを数千個描画する MultiMeshInstance3D です。

各ツールの設定レシピと、実行時に MultiMesh を生成する例については、references/lod-and-culling.md を参照してください。

9. レンダラーの比較

見た目を作り込む前に、レンダラーを選んでください。Forward+（デスクトップのデフォルト）だけが SDFGI とボリューメトリックフォグに対応しています。Mobile はタイルベース GPU でのパフォーマンスを優先し、これらの機能を省いています。Compatibility（GLES3 クラス）は、高度なライティング機能の大部分に対応していません。SDFGI を前提としたアドバイスは、ほかの 2 つのレンダラーでは気づかないうちに機能しません。

機能のレンダラー別一覧表と選択のガイダンスについては、references/renderer-comparison.md を参照してください。

10. よくある落とし穴

黒いシーン、環境光がないと暗くなるオブジェクト、シャドウアクネとピーター・パンニング、影のちらつき、平坦なマテリアル、見えないデカール、透明度のソートによるアーティファクト、SDFGI の光漏れ、表示されないボリューメトリックフォグ、見えない MultiMesh インスタンスについて、症状 → 原因 → 対処法をまとめたクイックテーブルです。

完全な一覧表は references/common-pitfalls.md を参照してください。

11. 実装チェックリスト

Markdown 対応

ログインしてコメント

基本情報

作者: jame581
リポジトリ: jame581/godotprompter
カテゴリ: 開発
インストール数: 180
GitHub スター: 889

問題を報告