Shader Craft

ShaderToy 互換の 36 個の GLSL シェーダー技術をカバーする統合スキル。リアルタイムビジュアルエフェクトに対応。

呼び出し

/shader-dev <request>

$ARGUMENTS はユーザーのリクエストを含みます（例：「ソフトシャドウ付きのレイマーチング SDF シーンを作成」）。

スキル構造

shader-dev/
├── SKILL.md                      # Core skill (this file)
├── techniques/                   # Implementation guides (read per routing table)
│   ├── ray-marching.md           # Sphere tracing with SDF
│   ├── sdf-3d.md                 # 3D signed distance functions
│   ├── lighting-model.md         # PBR, Phong, toon shading
│   ├── procedural-noise.md       # Perlin, Simplex, FBM
│   └── ...                       # 34 more technique files
└── reference/                    # Detailed guides (read as needed)
    ├── ray-marching.md           # Math derivations & advanced patterns
    ├── sdf-3d.md                 # Extended SDF theory
    ├── lighting-model.md         # Lighting math deep-dive
    ├── procedural-noise.md       # Noise function theory
    └── ...                       # 34 more reference files

使用方法

1. 以下の Technique Routing Table を読んで、ユーザーのリクエストに合致する技術を特定します
2. techniques/ フォルダの関連ファイルを読みます — 各ファイルには基本原理、実装手順、完全なコードテンプレートが含まれています
3. より深い理解が必要な場合（数学的導出、高度なパターン）、各技術ファイルの下部の参照リンクから reference/ に進みます
4. スタンドアロン HTML ページを生成する場合、以下の WebGL2 Adaptation Rules を適用します

Technique Routing Table

作成したい内容	主要技術	組み合わせ対象
数学から 3D オブジェクト / シーン	ray-marching + sdf-3d	lighting-model, shadow-techniques
複雑な 3D 形状（ブール演算、ブレンド）	csg-boolean-operations	sdf-3d, ray-marching
3D 内の無限反復パターン	domain-repetition	sdf-3d, ray-marching
オーガニック / 歪んだ形状	domain-warping	procedural-noise
流体 / 煙 / インクエフェクト	fluid-simulation	multipass-buffer
パーティクルエフェクト（炎、火花、雪）	particle-system	procedural-noise, color-palette
物理的なシミュレーション	simulation-physics	multipass-buffer
ライフゲーム / 反応拡散	cellular-automata	multipass-buffer, color-palette
海 / 水面	water-ocean	atmospheric-scattering, lighting-model
地形 / ランドスケープ	terrain-rendering	atmospheric-scattering, procedural-noise
雲 / 霧 / ボリューム火	volumetric-rendering	procedural-noise, atmospheric-scattering
空 / 夕焼け / 大気	atmospheric-scattering	volumetric-rendering
現実的なライティング（PBR、Phong）	lighting-model	shadow-techniques, ambient-occlusion
シャドウ（ソフト / ハード）	shadow-techniques	lighting-model
アンビエントオクルージョン	ambient-occlusion	lighting-model, normal-estimation
パストレーシング / グローバルイルミネーション	path-tracing-gi	analytic-ray-tracing, multipass-buffer
正確なレイ-ジオメトリ交差	analytic-ray-tracing	lighting-model
ボクセルワールド（Minecraft スタイル）	voxel-rendering	lighting-model, shadow-techniques
ノイズ / FBM テクスチャ	procedural-noise	domain-warping
タイル 2D パターン	procedural-2d-pattern	polar-uv-manipulation
Voronoi / セルパターン	voronoi-cellular-noise	color-palette
フラクタル（Mandelbrot、Julia、3D）	fractal-rendering	color-palette, polar-uv-manipulation
カラーグレーディング / パレット	color-palette	—
ブルーム / トーンマッピング / グリッチ	post-processing	multipass-buffer
マルチパス ping-pong バッファ	multipass-buffer	—
テクスチャ / サンプリング技術	texture-sampling	—
カメラ / 行列変換	matrix-transform	—
サーフェスノーマル	normal-estimation	—
極座標 / カレイドスコープ	polar-uv-manipulation	procedural-2d-pattern
2D 形状 / SDF から UI	sdf-2d	color-palette
手続き型音声 / 音楽	sound-synthesis	—
SDF トリック / 最適化	sdf-tricks	sdf-3d, ray-marching
アンチエイリアス処理	anti-aliasing	sdf-2d, post-processing
被写界深度 / モーションブラー / レンズエフェクト	camera-effects	post-processing, multipass-buffer
高度なテクスチャマッピング / no-tile テクスチャ	texture-mapping-advanced	terrain-rendering, texture-sampling
WebGL2 シェーダーエラー / デバッグ	webgl-pitfalls	—

Technique Index

Geometry & SDF

• sdf-2d — 形状、UI、アンチエイリアス処理用 2D 符号付き距離関数
• sdf-3d — リアルタイム暗黙面モデリング用 3D 符号付き距離関数
• csg-boolean-operations — 構成的立体幾何：和、差、交、スムーズブレンディング
• domain-repetition — 無限空間反復、折り畳み、制限付きタイリング
• domain-warping — ノイズでドメインを歪ませ、オーガニックで流動的な形状を作成
• sdf-tricks — SDF 最適化、バウンディングボリューム、二分探索改良、くり抜き、レイヤーエッジ、デバッグビジュアライゼーション

Ray Casting & Lighting

• ray-marching — SDF を使用した球体トレーシング、3D シーンレンダリング
• analytic-ray-tracing — 球、平面、ボックス、トーラス等の閉形式レイ-プリミティブ交差
• path-tracing-gi — フォトリアリスティックなグローバルイルミネーション用 Monte Carlo パストレーシング
• lighting-model — Phong、Blinn-Phong、PBR（Cook-Torrance）、トゥーンシェーディング
• shadow-techniques — ハードシャドウ、ソフトシャドウ（半影推定）、カスケードシャドウ
• ambient-occlusion — SDF ベース AO、スクリーンスペース AO 近似
• normal-estimation — 有限差分ノーマル、四面体技術

Simulation & Physics

• fluid-simulation — 移流、拡散、圧力投影を含む Navier-Stokes 流体ソルバー
• simulation-physics — GPU ベース物理：スプリング、布、N 体重力、衝突
• particle-system — ステートレスおよびステートフルパーティクルシステム（炎、雨、火花、銀河）
• cellular-automata — ライフゲーム、反応拡散（チューリングパターン）、砂シミュレーション

Natural Phenomena

• water-ocean — Gerstner 波、FFT 海、コースティクス、水中霧
• terrain-rendering — ハイトフィールドレイマーチング、FBM 地形、侵食
• atmospheric-scattering — Rayleigh/Mie 散乱、ゴッドレイ、SSS 近似
• volumetric-rendering — 雲、霧、炎、爆発用ボリュームレイマーチング

Procedural Generation

• procedural-noise — Value ノイズ、Perlin、Simplex、Worley、FBM、稜線ノイズ
• procedural-2d-pattern — レンガ、六角形、トルシェ、イスラム幾何学模様
• voronoi-cellular-noise — Voronoi 図、Worley ノイズ、割れた地面、結晶
• fractal-rendering — Mandelbrot、Julia セット、3D フラクタル（Mandelbox、Mandelbulb）
• color-palette — コサインパレット、HSL/HSV/Oklab、動的カラーマッピング

Post-Processing & Infrastructure

• post-processing — ブルーム、トーンマッピング（ACES、Reinhard）、ビネット、色収差、グリッチ
• multipass-buffer — Ping-pong FBO セットアップ、フレーム間の状態保持
• texture-sampling — バイリニア、バイキュービック、ミップマップ、手続き型テクスチャルックアップ
• matrix-transform — カメラ look-at、投影、回転、オービットコントロール
• polar-uv-manipulation — 極座標 / ログ極座標、カレイドスコープ、スパイラルマッピング
• anti-aliasing — SSAA、SDF 解析 AA、テンポラル AA（TAA）、FXAA ポストプロセス
• camera-effects — 被写界深度（薄レンズ）、モーションブラー、レンズディストーション、フィルムグレイン、ビネット
• texture-mapping-advanced — バイプレーナーマッピング、テクスチャ反復回避、レイディファレンシャルフィルタリング

Audio

• sound-synthesis — GLSL での手続き型音声：オシレーター、エンベロープ、フィルター、FM シンセシス

Debugging & Validation

• webgl-pitfalls — WebGL2/GLSL よくあるエラー：fragCoord、main() ラッパー、関数順序、マクロの制限、ユニフォーム null

WebGL2 Adaptation Rules

すべての技術ファイルは ShaderToy GLSL スタイルを使用しています。スタンドアロン HTML ページを生成する際、以下の適応を適用します：

シェーダーバージョン & 出力

• canvas.getContext("webgl2") を使用
• シェーダーの最初の行：#version 300 es、フラグメントシェーダーに precision highp float; を追加
• フラグメントシェーダーは以下を宣言する必要があります：out vec4 fragColor;
• バーテックスシェーダー：attribute → in、varying → out
• フラグメントシェーダー：varying → in、gl_FragColor → fragColor、texture2D() → texture()

フラグメント座標

• gl_FragCoord.xy を fragCoord の代わりに使用（WebGL2 に fragCoord ビルトインはありません）

// WRONG
vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;
// CORRECT
vec2 uv = (2.0 * gl_FragCoord.xy - iResolution.xy) / iResolution.y;

ShaderToy テンプレート用 main() ラッパー

• ShaderToy は void mainImage(out vec4 fragColor, in vec2 fragCoord) を使用
• WebGL2 は標準 void main() エントリーポイントが必要 — 常に mainImage をラップします：

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    // shader code...
    fragColor = vec4(col, 1.0);
}

void main() {
    mainImage(fragColor, gl_FragCoord.xy);
}

関数宣言順序

• GLSL では関数を使用前に宣言する必要があります — 使用前に宣言するか、再度順序付けします：

// WRONG — getAtmosphere() が定義される前に getSunDirection() を呼び出している
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Error!
vec3 getSunDirection() { return normalize(vec3(1.0)); }

// CORRECT — 被呼び出し関数を最初に定義
vec3 getSunDirection() { return normalize(vec3(1.0)); }
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Works

マクロの制限

• #define は関数呼び出しを使用できません — 代わりに const を使用します：

// WRONG
#define SUN_DIR normalize(vec3(0.8, 0.4, -0.6))

// CORRECT
const vec3 SUN_DIR = vec3(0.756, 0.378, -0.567); // Pre-computed normalized value

スクリプトタグの抽出

• <script> タグからシェーダーソースを抽出する際、#version が最初の文字であることを確認します — .trim() を使用します：

const fs = document.getElementById('fs').text.trim();

よくあるピットフォール

• 未使用のユニフォーム：コンパイラは未使用のユニフォームを最適化して除去する可能性があり、gl.getUniformLocation() が null を返す — ユニフォームを常にコンパイラが最適化できない方法で使用する
• ループインデックス：一部の ES バージョンではループで #define マクロの代わりにランタイム定数を使用
• 地形関数：terrainM(vec2) のような関数は XZ 成分が必要 — terrainM(pos + offset) ではなく terrainM(pos.xz + offset) を使用

HTML ページセットアップ

スタンドアロン HTML ページを生成する場合：

• キャンバスがビューポート全体を埋め、ウィンドウリサイズで自動リサイズ
• ページ背景が黒、スクロールバーなし：body { margin: 0; overflow: hidden; background: #000; }
• ShaderToy 互換ユニフォーム実装：iTime、iResolution、iMouse、iFrame
• マルチパスエフェクト（Buffer A/B）の場合、WebGL2 フレームバッファ + ping-pong を使用（multipass-buffer 技術参照）

よくあるピットフォール

JS 変数宣言順序（TDZ — ホワイトスクリーンクラッシュの原因）

let/const 変数は <script> ブロックの最上部で宣言する必要があります。それらを参照する関数よりも前：

// 1. State variables FIRST
let frameCount = 0;
let startTime = Date.now();

// 2. Canvas/GL init, shader compile, FBO creation
const canvas = document.getElementById('canvas');
const gl = canvas.getContext('webgl2');
// ...

// 3. Functions and event bindings LAST
function resize() { /* can now safely reference frameCount */ }
function render() { /* ... */ }
window.addEventListener('resize', resize);

理由：let/const は Temporal Dead Zone を持っています — 宣言前にそれらを参照すると ReferenceError がスローされ、ホワイトスクリーンが発生します。

GLSL コンパイルエラー（シェーダー作成後のセルフチェック）

• 関数署名の不一致：呼び出しは定義と正確にパラメーター数と型が一致する必要があります。float fbm(vec3 p) として定義されている場合、vec2 で fbm(uv) を呼び出せません
• 変数名として予約語を使用：以下を使用しないでください：patch、cast、sample、filter、input、output、common、partition、active
• 厳密な型マッチング：vec3 x = 1.0 は違法です — vec3 x = vec3(1.0) を使用してください；vec2 に .z でアクセスできません
• 構造体に対する三項演算子なし：ESSL では構造体型に対する三項演算子を使用できません — 代わりに if/else を使用

パフォーマンスバジェット

デプロイメント環境は限定的な GPU パワーのヘッドレスソフトウェアレンダリングを使用する可能性があります。これらの制限内に留まります：

• レイマーチング主ループ：≤ 128 ステップ
• ボリュームサンプリング / ライティング内ループ：≤ 32 ステップ
• FBM オクターブ：≤ 6 レイヤー
• ピクセルあたりの総ネストループ反復：≤ 1000（これを超えるとブラウザがフリーズします）

クイックレシピ

一般的なエフェクト組み合わせ — 技術モジュールから組み立てた完全なレンダリングパイプライン。

フォトリアリスティック SDF シーン

1. ジオメトリ：sdf-3d（拡張プリミティブ）+ csg-boolean-operations（cubic/quartic smin）
2. レンダリング：ray-marching + normal-estimation（四面体法）
3. ライティング：lighting-model（屋外 3 ライトモデル）+ shadow-techniques（改良ソフトシャドウ）+ ambient-occlusion
4. 大気：atmospheric-scattering（高さベースの霧と太陽色合い）
5. ポスト：post-processing（ACES トーンマッピング）+ anti-aliasing（2x SSAA）+ camera-effects（ビネット）

オーガニック / バイオロジカルフォーム

1. ジオメトリ：sdf-3d（拡張プリミティブ + 変形演算子：ツイスト、ベンド）+ csg-boolean（勾配認識 smin、マテリアルブレンディング）
2. ディテール：procedural-noise（導関数付き FBM）+ domain-warping
3. サーフェス：lighting-model（半 Lambert を介した サブサーフェススキャッタリング近似）

手続き型ランドスケープ

1. 地形：terrain-rendering + procedural-noise（導関数付き侵食 FBM）
2. テクスチャリング：texture-mapping-advanced（バイプレーナーマッピング + no-tile）
3. 空：atmospheric-scattering（Rayleigh/Mie + 高さ霧）
4. 水：water-ocean（Gerstner 波）+ lighting-model（フレネル反射）

スタイライズド 2D アート

1. 形状：sdf-2d（拡張ライブラリ）+ sdf-tricks（レイヤーエッジ、くり抜き）
2. カラー：color-palette（コサインパレット）+ polar-uv-manipulation（カレイドスコープ）
3. ポーリッシュ：anti-aliasing（SDF 解析 AA）+ post-processing（ブルーム、色収差）

シェーダーデバッグ技術

ビジュアルデバッグ方法 — 問題を診断するために出力を一時的に置き換えます。

チェック内容	コード	何を探すか
サーフェスノーマル	col = nor * 0.5 + 0.5;	スムーズグラデーション = 正しいノーマル；バンディング = epsilon が大きすぎる
レイマーチステップ数	col = vec3(float(steps) / float(MAX_STEPS));	赤いホットスポット = パフォーマンスボトルネック；均一 = 無駄なイテレーション
深度 / 距離	col = vec3(t / MAX_DIST);	正しいヒット距離を確認
UV 座標	col = vec3(uv, 0.0);	座標マッピングを確認
SDF 距離場	col = (d > 0.0 ? vec3(0.9,0.6,0.3) : vec3(0.4,0.7,0.85)) * (0.8 + 0.2*cos(150.0*d));	SDF バンドとゼロクロッシングを可視化
チェッカーパターン（UV）	col = vec3(mod(floor(uv.x*10.)+floor(uv.y*10.), 2.0));	UV 歪み、シームを確認
ライティングのみ	col = vec3(shadow); または col = vec3(ao);	シャドウ / AO 貢献を分離
マテリアル ID	col = palette(matId / maxMatId);	マテリアルアサインメントを確認