godot-shaders-basics

シェーダーで絶対にしてはいけないこと

• 最適化のために無条件で discard を使用しないでください — 深度プリパスが効果的に機能しなくなります。ピクセルを破棄しても頂点処理のコストはかかります。場合によっては、オブジェクトを描画しないほうが適切です [1]。
• 高性能シェーダーで動的な状態に if/else を使用しないでください — GPU は分岐を嫌います。数学的に選択でき、ハードウェアに最適化された mix()、step()、smoothstep() を使用してください [5, 21]。
• 浮動小数点数を完全一致で比較しないでください — ハードウェアによって精度が異なるため、if (v == 0.5) は信頼できません。abs(a - b) < epsilon または step() を使用してください。
• 大量の葉に標準のアルファブレンディングを使用しないでください — 影と SSR が無効になります。アルファスシザーまたはアルファハッシュ（ディザリング）を使用すると、深度プリパスとシャドウキャストを有効にできます [7]。
• 4.3 以降のフルスクリーンクアッドで POSITION を vec4(VERTEX, 1.0) に固定しないでください — Godot 4.3 では Reversed-Z 深度を使用しているため、クリッピングが発生します。POSITION = vec4(VERTEX.xy, 1.0, 1.0) を使用してください [8, 9]。
• 多くの敵の色や値を一つ変更するためにマテリアルを複製しないでください — instance uniform を使用してください。これにより、単一のドローコール（バッチ処理）を維持しながら、数千のノードに個別の値を設定できます [10]。
• 速度の乗数を指定せずに TIME を使用しないでください — さまざまなゲームプレイ状態で一貫性を保てるよう、フラグメントの速度はユニフォームで制御できるようにしてください。
• カラーのユニフォームに hint_source_color を指定し忘れないでください — 指定しないと、エンジンはカラーを線形演算として扱うため、ガンマが不正確になり、インスペクターで色が白っぽく表示されます。
• vertex() で計算できる複雑な処理を fragment() で計算しないでください — vertex() はポイントごとに一度実行されますが、fragment() はフレームごとに何百万回も実行されます。値は varying を使って補間してください。
• 実行時に動的に切り替えるトグルに #define マクロを使用しないでください — 新しいシェーダーのバリエーションが作成され、ゲーム内で初めて使用したときに大きなコンパイル停止が発生します。代わりにユニフォームを使用してください。
• ベクトルの正規化を忘れないでください — 正規化されていないベクトルに reflect(dir, normal) を使用すると、深刻なレンダリングアーティファクトや不正確なライティング計算が発生します。
• 境界チェックまたは fract() を使わずに UV を変更しないでください — repeat によるラップ処理やクランプ処理をせずに UV を 0.0～1.0 の範囲外に移動すると、端のピクセルがサンプリングされたり、黒が返されたりして、テクスチャの一貫性が損なわれます。

シナリオ → スクリプトの使い分け

該当する効果には必須です。ここでは初心者向けの canvas_item 色付けレシピや組み込み変数の用語集を読み込まないでください。

目的	スクリプト
バッチを崩さず、敵ごとにヒットフラッシュを適用する	必須 instance_uniform_hitflash.gdshader
葉の風揺れ＋影	必須 foliage_wind_sway_expert.gdshader（アルファスシザー／ハッシュを使用。無条件の discard は使用しません）
深度プリパスを維持するディゾルブ	必須 dissolve_scissor_expert.gdshader
ポストエフェクトのピクセル化／スタイライズ	必須 screenspace_hex_pixelate.gdshader
フルスクリーンクワッド（逆Z）	必須 screenspace_full_quad.gdshader
水／霧向けの深度からワールド座標への変換	必須 depth_world_reconstruction.gdshader
プレイヤーによる草の倒れ込み	global_grass_flatten.gdshader
UV のない崖／岩	triplanar_world_mapping.gdshader
インスタンス化メッシュに個別のテクスチャを適用する	instance_texture_array.gdshader
頂点変位による地形表現	noise_terrain_displacement.gdshader
実行時のユニフォームアニメーション	shader_parameter_animator.gd
VFX 移植用テンプレート	vfx_port_shader.gdshader

切り抜き／ディゾルブの基本方針： ALPHA_SCISSOR ／アルファハッシュを使用します（dissolve および foliage スクリプトを参照）。最適化のために discard を使用しないでください。理由を説明する項目は決して列挙しないでください。

利用可能なスクリプト

instance_uniform_hitflash.gdshader

インスタンスユニフォームによるフラッシュ。1 つのマテリアルで複数の異なる強度を設定できます。

dissolve_scissor_expert.gdshader

深度プリパスと影に対応した、ALPHA_SCISSOR によるマスクディゾルブです。

foliage_wind_sway_expert.gdshader

葉のバッチに対応したワールド空間での風揺れです。

global_grass_flatten.gdshader

global uniform によるプレイヤーとのインタラクションで草を倒します。

screenspace_hex_pixelate.gdshader

hint_screen_texture を使ったスタイライズドポストエフェクトです。

screenspace_full_quad.gdshader

逆 Z に安全な全画面矩形のポストパスです。

depth_world_reconstruction.gdshader

hint_depth_texture からワールド座標を取得します。

triplanar_world_mapping.gdshader

UV を使わずに、ワールド軸に沿って投影します。

instance_texture_array.gdshader

sampler2DArray とインスタンスユニフォームで、バッチ内の各インスタンスに異なるテクスチャを適用します。

noise_terrain_displacement.gdshader

頂点をノイズで変位させます。

vfx_port_shader.gdshader

検証済みの VFX シェーダーテンプレートです。

shader_parameter_animator.gd

AnimationPlayer を使わずに、Tween／実行時のユニフォームアニメーションを行います。

shader_warmup_loader.gd

ロード画面中にシェーダーパイプラインを事前ウォームアップし、初回フレームのカクつきを防ぎます。

エキスパート向けのヒント

• 不変の計算は vertex() に移し、varying で渡します。
• 色のユニフォームには hint_source_color が必要です。
• シェーディング言語の組み込み関数については公式ドキュメントを優先してください。このスキルでは、バッチ処理、スシザー、スクリーンスペース処理、深度の受け渡しを扱います。

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

LLM が知らないことは、一般的なエージェントが読む前に知り得ない情報であれば、ここか scripts/ に置きます。削除せず、移動してください。

トピック	リファレンス
2Dのディゾルブ／波形／アウトライン	2d-effect-recipes.md
3Dのトゥーン＋ビネット	3d-and-postfx-recipes.md
Uniform／組み込み機能	uniforms-and-builtins.md
フォグ、コンピュート、ウォームアップ	expert-advanced-patterns.md

リファレンス

段階的な情報開示：特定の API を調査するときだけ公式ドキュメントへのリンクを開いてください。 作業を関連分野に引き継ぐときは関連スキルを読み込み、スキル群全体を事前に読み込まないでください。

公式ドキュメント

• シェーダーの概要 — シェーダーの種類、レンダリングモード、ShaderMaterial と StandardMaterial3D の使い分けを示す導入マップです。
• シェーディング言語 — このスキル全体で使用する、uniform、ヒント、varying、組み込み機能、プリプロセッサルールなど、GLSL に似た基本構文です。
• CanvasItem シェーダー — スプライト、UI、2Dのポストエフェクト向けの2D canvas_item 組み込み機能（UV、COLOR、TEXTURE、SCREEN_UV）です。
• Spatial シェーダー — マテリアルや全画面クワッド向けの3D spatial 組み込み機能（ALBEDO、NORMAL、instance uniform、深度／画面テクスチャ）です。
• 初めての2Dシェーダー — ShaderMaterial を割り当ててからフラグメントに色を付けるまでの、最小限の canvas_item ワークフローです。
• 初めての3Dシェーダー — 最小限の spatial ワークフローと、StandardMaterial3D から編集可能なシェーダーへの変換方法です。
• ShaderMaterial — アニメーションやヒット時のフラッシュのバッチ処理で使用する、実行時の set_shader_parameter／インスタンスパラメーター API です。
• カスタムポストプロセッシング — ピクセル化やビネット風のエフェクトに使う、画面読み取りシェーダー、hint_screen_texture、合成パターンです。
• 高度なポストプロセッシング — 水／フォグ／デバッグ用ビジュアライザーに必要な、深度バッファー、逆Z、ワールド再構築について説明します。
• コンピュートシェーダー — パーティクルシミュレーションなど、フラグメント以外の処理に使う RenderingDevice の GPGPU パスです。
• VisualShaders の使用 — エキスパート向けパターンで扱う、グラフエディターと VisualShaderNodeCustom による拡張性です。
• GPU最適化 — アルファスキッサー、インスタンス uniform、頂点とフラグメントのコストの根拠となる、オーバードロー、透明度、バッチ処理のガイダンスです。

関連スキル

前提条件

• godot-project-foundations — ShaderMaterial の割り当てと .gdshader アセットの出荷に必要な、ノード、リソース、プロジェクトの構成を説明します。
• godot-resource-data-patterns — uniform とインスタンスパラメーターをバッチ処理に適した状態に保つための、ShaderMaterial／Shader リソースの共有と複製について説明します。

補完

• godot-3d-materials — まずStandardMaterial3D/ORMを使用し、トライプラナー、ディゾルブ、インスタンスユニフォームの効果には空間シェーダーへ移行します。
• godot-3d-lighting — カスタムのALBEDO/EMISSION/light()出力がForward+、GI、フォグボリュームとどのように相互作用するかを解説します。
• godot-particles — パーティクルのプロセス／描画マテリアルとアルファ処理パイプラインでは、このスキルのシザー／ハッシュとブレンドの選択に合わせる必要があります。
• godot-2d-animation — アニメーションスプライトにスタイリッシュな2Dモーション、アウトライン、ディゾルブを適用するCanvasItemシェーダーフックを解説します。
• godot-camera-systems — スクリーンスペースシェーダーや深度再構築シェーダーが依存するカメラのnear/farとビュー／プロジェクション行列について解説します。
• godot-performance-optimization — ドローコールのバッチ処理、MultiMesh、GPU予算を解説します。これらはinstance uniformの使用や固有マテリアルの回避を正当化します。
• godot-debugging-profiling — GPU／オーバードローのプロファイラーとデバッグビューを使って、シェーダーのコストや深度／法線の可視化を検証します。

下流／利用側

• godot-procedural-generation — プロシージャルメッシュ／地形では、このスキルのノイズ変位、トライプラナー、UVを使用しない空間パターンを利用します。
• godot-3d-world-building — 大規模な環境プロップでは、レベル規模に合わせて、葉の風揺れ、草の踏みつけ、ワールド投影シェーダーを適用します。
• godot-genre-open-world — オープンワールドの葉の相互作用、距離に応じたエフェクト、共有マテリアルのバッチ処理で、これらのシェーダーテンプレートを利用します。

マスター

• godot-master — ライブラリのルーターであり、スキル間の探索に使用するミラー化されたモジュールエントリーです。