shader-basics

Godot 4.3+ のシェーダー

すべての例は、非推奨 API を使わずに Godot 4.3+ を対象としています。

関連スキル： animation-system はヒット時のフラッシュなどシェーダー駆動のエフェクトに、godot-optimization はシェーダーのパフォーマンスに関する考慮事項に、camera-system はポストプロセスのカメラエフェクトに、2d-essentials は 2D ライティング、ピクセルアート用シェーダー、CanvasTexture の法線マップに、3d-essentials は空間シェーダーと環境マテリアルに、particles-vfx はカスタムパーティクルシェーダーに、tween-animation は実行時のシェーダーパラメーターのアニメーション化に役立ちます。

---

1. 基本概念

シェーダーの種類

シェーダーの種類	適用対象	用途
canvas_item	2D ノード（Sprite2D、Control など）	2D エフェクト — アウトライン、ディゾルブ、色の置き換え
spatial	3D メッシュ（MeshInstance3D）	3D マテリアル — 水、地形、トゥーンシェーディング
particles	GPUParticles2D/3D	カスタムパーティクルの挙動
sky	WorldEnvironment	プロシージャルな空の描画
fog	FogVolume	ボリュメトリックフォグエフェクト

Shader と ShaderMaterial の違い

Shader (.gdshader)        → The code (GLSL-like language)
ShaderMaterial            → Instance of a shader with specific uniform values
CanvasItemMaterial / StandardMaterial3D → Built-in materials (no code needed)

複数のノードで同じ Shader を共有しながら、異なる uniform 値を持つ個別の ShaderMaterial インスタンスを使用できます（例：同じディゾルブシェーダーを使い、敵ごとにディゾルブの進行度を変える）。

シェーダーの作成

1. ノード（例：Sprite2D）を選択します
2. インスペクター → Material → New ShaderMaterial を選択します
3. ShaderMaterial → Shader → New Shader を選択します
4. 組み込みエディターで .gdshader ファイルを編集します

または、FileSystem ドックで .gdshader ファイルを直接作成します。

---

2. Godot シェーダー言語の基本

Godot は、Godot 固有の拡張を加えた GLSL ES 3.0 に似た言語を使用します。

最小限の Canvas Item シェーダー

shader_type canvas_item;

void fragment() {
    // COLOR is the output pixel color
    // TEXTURE is the sprite's texture
    // UV is the texture coordinate (0,0 top-left to 1,1 bottom-right)
    vec4 tex = texture(TEXTURE, UV);
    COLOR = tex;
}

最小限の Spatial シェーダー

shader_type spatial;

void fragment() {
    // ALBEDO is the base color (vec3)
    ALBEDO = vec3(0.8, 0.2, 0.2);
}

組み込み変数（canvas_item）

変数	型	説明
UV	vec2	テクスチャ座標
COLOR	vec4	出力色（fragment() 内で設定します）
TEXTURE	sampler2D	ノードのテクスチャ
VERTEX	vec2	頂点位置（vertex() 内）
TIME	float	経過時間（秒）
SCREEN_UV	vec2	スクリーン空間の UV（スクリーンエフェクト用）

SCREEN_TEXTURE は Godot 4.0 で削除されました。スクリーンを読み取るには、uniform を宣言します：uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap;

組み込み変数（spatial）

変数	型	説明
ALBEDO	vec3	表面の基本色
METALLIC	float	金属度（0.0–1.0）
ROUGHNESS	float	粗さ（0.0–1.0）
NORMAL	vec3	表面の法線（法線マッピング用）
EMISSION	vec3	発光色
ALPHA	float	透明度（これに値を設定すると、マテリアルは透明パスに移動します）
VERTEX	vec3	頂点位置（vertex() 内）

Uniform（シェーダーパラメーター）

Uniform を使うと、シェーダーの値をインスペクターやコードから操作できます。

shader_type canvas_item;

uniform float speed : hint_range(0.0, 10.0, 0.1) = 1.0;
uniform vec4 tint_color : source_color = vec4(1.0, 1.0, 1.0, 1.0);
uniform sampler2D noise_texture : filter_linear_mipmap;

void fragment() {
    vec4 tex = texture(TEXTURE, UV);
    COLOR = tex * tint_color;
}

よく使う Uniform ヒント

ヒント	型	説明
hint_range(min, max, step)	float/int	インスペクターのスライダー
source_color	vec4	インスペクターのカラーピッカー
filter_linear_mipmap	sampler2D	テクスチャのフィルタリングモード
repeat_enable	sampler2D	テクスチャのタイリングを許可
hint_normal	sampler2D	法線マップとして扱う

コードからの Uniform の設定

GDScript

var mat: ShaderMaterial = $Sprite2D.material
mat.set_shader_parameter("speed", 2.0)
mat.set_shader_parameter("tint_color", Color.RED)

C#

var mat = GetNode<Sprite2D>("Sprite2D").Material as ShaderMaterial;
mat.SetShaderParameter("speed", 2.0f);
mat.SetShaderParameter("tint_color", Colors.Red);

---

3. よく使う 2D シェーダーのレシピ

多くのプロジェクトで必要になる canvas_item のレシピは、ディゾルブ（ノイズ＋エッジグロー）、アウトライン（周囲をサンプリングしてアルファを拡張）、ホワイトフラッシュ（uniform で制御するヒットエフェクト）、色の置き換え（パレットのシフト）、UV スクロール（水／溶岩／雲）、波形ディストーションです。

6 つすべてのレシピの完全なシェーダーコードについては、references/2d-shader-recipes.md を参照してください。

---

4. 一般的な3Dシェーダーレシピ

空間シェーダーのレシピ：トゥーン／セルシェーディング（バンド状のNdotL）、リムライティング／フレネル（1 - NdotV）、シンプルな水面（UVスクロール＋法線マップのブレンド＋フレネル）。

各レシピのシェーダーソース全文は、references/3d-shader-recipes.md を参照してください。

---

5. ビジュアルシェーダー

ビジュアルシェーダーは、ノードベースのグラフエディターです（New ShaderMaterial → New VisualShader）。手早いプロトタイプ、アーティストが調整できる値、シンプルなエフェクトに使用し、複雑な計算、分岐、ループにはコードを使用してください。どちらも同じGPUコードにコンパイルされるため、パフォーマンスは同じです。

選択表、手順、主要なノード、4.7でのノード変更については、references/visual-shaders.md を参照してください。

---

6. ポストプロセスエフェクト

標準的なパターンは、ゲームプレイのキャンバス上に canvas_item シェーダーを適用した全画面サイズの ColorRect を配置することです。3Dでは、WorldEnvironment の Adjustment、Glow、またはカスタムシェーダーを使用します。エフェクトを連結するには、ワールドを SubViewport に描画してから、最終シェーダーパスでそのテクスチャをサンプリングします。

ColorRect オーバーレイのパターン、ビネット＋CRT／走査線シェーダーのソース、SubViewport パイプライン、WorldEnvironment による3Dポストプロセスの注意事項については、references/post-processing.md を参照してください。

---

7. コンポジターエフェクト（Godot 4.3+）

CompositorEffect は、3Dレンダリングパイプラインの5つのポイントでカスタムレンダーパスを実行します。最初の不透明パスより前から、透明パスの後まで対応し、いずれも組み込みのポストエフェクトとトーンマッピングより前に実行されます。ColorRect オーバーレイでは不十分な場合に使用します。マルチパスエフェクト、深度対応エフェクト、カスタムAO／SSRのバリエーションなどに適しています。スクリーンスペースシェーダーより設定が複雑なため、必要な場合にのみ使用してください。

セットアップ、カスタム CompositorEffect の GDScript サンプル、組み込み Compositor の使用例については、references/compositor-effects.md を参照してください。

---

8. レンダーモード

レンダーモードは shader_type の次の行に記述し、シェーダーがレンダリングパイプラインとどのように連携するかを制御します。

Canvas Item のレンダーモード

shader_type canvas_item;
render_mode unshaded;           // Ignore all lighting
render_mode light_only;         // Only visible where lit
render_mode blend_add;          // Additive blending (glow, fire)
render_mode blend_mix;          // Standard alpha blending (default)
render_mode blend_premul_alpha; // Pre-multiplied alpha

Spatial のレンダーモード

shader_type spatial;
render_mode unshaded;              // No lighting calculations
render_mode cull_disabled;         // Render both sides of faces
render_mode depth_draw_always;     // Always write to depth buffer
render_mode specular_toon;         // Toon specular model
render_mode diffuse_toon;          // Toon diffuse model
render_mode blend_add;             // Additive blending

---

9. ステンシルバッファエフェクト（Godot 4.5+）

Godot 4.5では、stencil_mode ステートメント（stencil_mode write, 1; ／ stencil_mode read, compare_equal, 1;）を使った空間シェーダーでのステンシルの書き込み／読み取りと、StandardMaterial3D の設定（Stencil: Outline / X-Ray / Custom）が、すべてのレンダリングバックエンドで利用できるようになりました。canvas_item シェーダーにはステンシルモードがありません。これにより、従来はコンポジターレベルでの処理が必要だったポータル、X線透視、アウトラインマスク、ジオメトリに穴を開けるエフェクトを実現できます。

stencil_mode のリファレンスと、X線透視ポータルの詳細な実装例については、references/stencil-buffer.md を参照してください。

---

10. SMAAアンチエイリアシング（Godot 4.5+）

サブピクセル形態学的アンチエイリアシング（SMAA 1x）は、Godot 4.5で追加された組み込みのポストプロセスAAモードです。FXAAよりもわずかに高いパフォーマンスコストで、より鮮明な結果が得られ、MSAAよりも大幅に低コストです。

SMAA の有効化

1. プロジェクト設定を開きます
2. レンダリング → アンチエイリアス → 品質に移動します
3. スクリーンスペース AAをSMAAに設定します

SMAA は MSAA（ジオメトリのエッジのエイリアシング対策）と組み合わせることも、単独で使用することもできます。シェーダーコードを変更する必要はありません。

AA モード	シャープさ	GPU 負荷	ゴースト
無効	該当なし	なし	なし
FXAA	低（ぼやける）	非常に低い	低い
SMAA	高い	低い（FXAA よりわずかに高い）	非常に低い
TAA	中程度（わずかにぼやける）	中程度	発生する可能性あり
MSAA 4x	高い	高い	なし

SMAA を使う場合： ほとんどのデスクトッププロジェクトでは、FXAA より SMAA を優先してください。負荷がわずかに高くなる一方で、テキストや細いエッジが目に見えて鮮明になります。中程度の負荷で最高の品質を得るには、SMAA と MSAA 2x を組み合わせてください。

このプロジェクト設定は起動時にのみ読み込まれます。実行時に切り替えるには、get_viewport().screen_space_aa = Viewport.SCREEN_SPACE_AA_SMAA（C#: GetViewport().ScreenSpaceAA = Viewport.ScreenSpaceAAEnum.Smaa）を設定します。Forward+ と Mobile でのみ使用でき、Compatibility では使用できません。

---

11. シェーダーベイカー — エクスポート時の事前コンパイル（Godot 4.5+）

シェーダーベイカーは、エクスポート時にプロジェクトのシェーダーをターゲットドライバーの形式に変換し、初回起動時の読み込み時間を短縮します。変換に時間がかかる macOS／iOS（Metal）や Windows（D3D12）で特に効果があります。マテリアルの初回レンダリング時に発生するパイプラインコンパイルのカクつきは解消されません。また、Forward+ と Mobile のレンダラーでのみ動作し、エクスポートを行うマシンの OS がサポートするドライバー向けにのみベイクします。リリースビルドではエクスポートプリセットごとに有効にし、開発時は無効のままにしてください。

有効化の手順と有効／無効の比較については、references/shader-baker.md を参照してください。

---

12. よくある問題

症状	原因	対処法
シェーダーの効果が見えない	マテリアルが割り当てられていない、またはシェーダーが保存されていない	インスペクターでノードの Material プロパティを確認します
透明な部分が黒く描画される	シェーダーでアルファが処理されていない	COLOR.a = tex.a; を設定し、適切なブレンドモードを使用します
インスペクターに Uniform が表示されない	Uniform 名の誤記、または型が正しくない	シェーダーを再保存し、コンパイルエラーがないか確認します
テクスチャが引き伸ばされたり、タイル状に表示されたりする	repeat_enable がない、または UV スケールが正しくない	sampler2D Uniform に repeat_enable ヒントを追加します
エディターでは動作するが、ゲームでは動作しない	スクリーンテクスチャ Uniform にバックバッファが必要	sampler2D Uniform に hint_screen_texture を使用します（Godot 4.x）
シェーダーが多いとパフォーマンスが低下する	固有のシェーダーごとにドローコールが分割される	ShaderMaterial インスタンスを共有し、バリエーションには Uniform を使用します
スクリーンスペース UV が正しくない	一部のコンテキストでは SCREEN_UV を利用できない	ノードが正しいビューポートに描画されていることを確認します
ビジュアルシェーダーノードが見つからない	新しい Godot バージョンでノード名が変更または削除された	Godot のドキュメントで現在のノード名を確認します

⚠️ Godot 4.7 での変更： textureQueryLod() はフラグメントシェーダーでのみ使用できるようになり、Godot 4.7 ではコンパイルエラーによってこれが強制されます。そのため、vertex() から呼び出しているシェーダーはアップグレード後にコンパイルできなくなります。呼び出しを fragment() 内に移してください。GH-118962 を参照してください。

---

13. 実装チェックリスト

• シェーダーの種類がノードの種類と一致している（2D は canvas_item、3D は spatial）
• ユニフォームに適切なヒントを使用している（hint_range、source_color、filter_linear_mipmap）
• 共通の視覚効果に同じ Shader リソースを使用し、個別の ShaderMaterial インスタンスを割り当てている
• ポストプロセス用シェーダーをゲームオブジェクトではなく、CanvasLayer（2D）または WorldEnvironment（3D）に設定している
• canvas_item シェーダーで TEXTURE をサンプリングしている（サンプリングしないとスプライトのコンテンツが失われます）
• アルファ透過シェーダーで COLOR.a を正しく設定し、blend_mix レンダーモードを使用している
• アニメーションするシェーダーパラメーター（ディゾルブ、フラッシュ）を _process ではなく、Tween または AnimationPlayer で駆動している
• 画面を読み取るシェーダーで、sampler2D ユニフォームに hint_screen_texture を使用している（Godot 4.x の方式）
• 複雑なシェーダーの GPU フレーム時間を確認するため、Godot プロファイラーで計測している
• ステンシル効果で 2 パスのマテリアルを使用し（書き込みパスを先、読み取りパスを後にする）、レンダー優先度を正しく設定している（Godot 4.5 以降）
• デスクトップビルドでは FXAA より SMAA を優先している（エッジがより鮮明で、コストはやや高め）— Project Settings → Rendering → Anti Aliasing で設定する（Godot 4.5 以降）
• 初回起動時の読み込みを短縮するため、D3D12 および Metal のターゲット向けリリースプリセットで Shader Baker を有効にしている（Forward+/Mobile のみ。Godot 4.5 以降）