@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/gamedev-shaders/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: gamedev-shaders
+description: "Use when writing shaders, materials, VFX, or post-processing for a game engine, or asking \"how do I make this effect\" — covers the vertex→fragment pipeline, UVs / normals / coordinate spaces, and per-engine authoring in Godot 4.x (shader_type spatial/canvas_item/particles, source_color, hint_screen_texture, ShaderMaterial), Unity 6 (Shader Graph vs HLSL, URP/HDRP, ShaderLab), and Unreal 5.x (Material graph, material domains, Custom HLSL node). Includes recipes for dissolve, rim/outline, toon/cel, water/flow, force field, hologram; full-screen post-process; and shader performance (overdraw, texture-sample cost, branching, mobile). Triggers: \"write a dissolve shader\", \"rim light\", \"toon shading\", \"screen-space effect\", \"my shader is slow on mobile\", \"cómo hago un shader de agua\". NOT gameplay or engine-API code (→ godot / unity / unreal) and NOT physics simulation, collision, or rigid bodies (→ gamedev-physics)."
+tags: [shaders, vfx, materials, post-processing, shadergraph]
+recommends: [godot, unity, unreal, gamedev-shipping]
+profiles: [full]
+origin: risco
+---
+
+# Shaders & VFX (game engines)
+
+Author shaders, materials, and full-screen effects across Godot, Unity, and Unreal. One
+mental model — the GPU pipeline — mapped onto each engine's authoring surface, plus recipes
+for the effects people actually ask for. Fires on writing/debugging a shader or material,
+building a VFX/post-process effect, or "how do I make X look like Y".
+
+## Version contract — read first
+
+Target the current stable line of each engine and never emit its retired APIs. If unsure a
+symbol is current, say so rather than guess.
+
+| Engine | Target | Never emit → use instead |
+| --- | --- | --- |
+| **Godot** | 4.x (4.4/4.5 stable) | `SCREEN_TEXTURE`/`DEPTH_TEXTURE`/`NORMAL_TEXTURE` built-ins → declare a `uniform sampler2D … : hint_screen_texture` / `hint_depth_texture` / `hint_normal_roughness_texture`. `hint_color`/`hint_albedo` → `source_color`. `hint_white`/`hint_black` → `hint_default_white`/`hint_default_black`. GLES2-era guides. |
+| **Unity** | 6 (6000.x LTS), URP/HDRP | Surface shaders (`#pragma surface`) — Built-in-RP only, they do **not** compile under URP/HDRP. `CGPROGRAM`+`UnityCG.cginc`, `UnityObjectToClipPos`, `mul(UNITY_MATRIX_MVP, v)` → `HLSLPROGRAM` + URP `Core.hlsl` and `TransformObjectToHClip(posOS)`. `OnRenderImage`/`Graphics.Blit` post FX → URP Renderer Feature / Fullscreen Shader Graph. |
+| **Unreal** | 5.x (5.4+) | `SceneTexture:PostProcessInput0` outside a Post Process material; Opacity without a translucent blend mode; Opacity Mask without a Masked blend mode. Prefer graph nodes; drop to a Custom HLSL node only for logic nodes can't express. |
+
+`shader_type` tokens in Godot 4 are exact: `spatial`, `canvas_item` (underscore), `particles`
+(plural), `sky`, `fog`.
+
+## When to use / When NOT to use
+
+**Use when:** writing or debugging a `.gdshader`/`ShaderMaterial`, a `.shader`/Shader Graph, or
+a UE Material; building a VFX look (dissolve, rim, toon, water, shield, hologram, trails);
+authoring post-processing / screen-space effects; a shader is slow, flickers, or looks wrong;
+choosing per-vertex vs per-pixel; converting an effect between engines.
+
+**When NOT to use (delegate):**
+
+- Gameplay logic, nodes/components, input, engine APIs, scene setup → [`godot`](../godot/SKILL.md) /
+  [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md). This skill owns the *shading*, not the C#/GDScript/Blueprint around it.
+- Physics simulation, collisions, rigid bodies, character controllers → [`gamedev-physics`](../gamedev-physics/SKILL.md).
+  (A shader that *fakes* refraction is here; simulating fluid dynamics is not.)
+- Shipping, platform export, shader-variant stripping in the build pipeline → [`gamedev-shipping`](../gamedev-shipping/SKILL.md)
+  (this skill keeps the per-shader performance work).
+
+## Shader fundamentals (the pipeline)
+
+Every engine compiles your material into the same GPU stages. Two you write:
+
+- **Vertex stage** — runs **once per vertex**. Transforms position into clip space and passes
+  interpolated data (UVs, normals, custom `varying`s) down. Cheap; scales with mesh vertex count.
+- **Rasterizer** (fixed) turns triangles into fragments and *interpolates* the vertex outputs.
+- **Fragment / pixel stage** — runs **once per covered pixel** (× overdraw). Samples textures,
+  does lighting, writes the final color. Expensive; scales with screen coverage.
+
+**Per-vertex vs per-pixel is the core performance lever:** compute anything that interpolates
+linearly (position offsets, un-normalized directions, scalar masks) in the vertex stage and pass
+it as a `varying`; keep only what must be exact per-pixel (normalizing interpolated normals,
+texture sampling, lighting, fresnel) in the fragment stage.
+
+**UVs** are per-vertex 2D texture coordinates (0–1), interpolated across the face — you sample
+textures and drive scrolling/tiling/masks with them. **Normals** are surface directions used for
+lighting and rim; interpolated normals must be re-normalized per pixel. **Normal maps** store
+directions in **tangent space** (unpack with `×2−1`); respect handedness.
+
+**Coordinate spaces** — know which space each value is in before you do math on it:
+
+| Space | Meaning | Typical use |
+| --- | --- | --- |
+| Object / model | mesh-local, origin at the pivot | authoring positions/normals start here |
+| World | scene-global | world-space effects, triplanar, lighting |
+| View / camera | relative to the camera | Godot spatial `NORMAL`/`VIEW` live here |
+| Clip / NDC | post-projection homogeneous coords | the vertex stage's required output |
+| Tangent | per-fragment surface basis (T,B,N) | normal maps are decoded here |
+| Screen / UV | 0–1 across the framebuffer | post-process sampling (`SCREEN_UV`) |
+
+## Per-engine authoring
+
+### Godot 4.x
+
+Godot ships its own GLSL-like language (`.gdshader`). Pick a `shader_type`, declare `uniform`s
+(exposed as material parameters), pass data with `varying`, write `vertex()`/`fragment()`
+(+`light()`). A **ShaderMaterial** binds the shader to a node and holds uniform values; set them
+from code with `material.set_shader_parameter("name", value)`. Uniform hints: `source_color`
+(sRGB→linear color pickers), `hint_range(a,b)`, `hint_default_white`, `hint_screen_texture`,
+plus texture filters/repeats (`filter_linear_mipmap`, `repeat_enable`).
+
+Small **canvas_item** (2D) shader — scroll and tint a texture:
+
+```glsl
+shader_type canvas_item;
+uniform sampler2D noise : repeat_enable;
+uniform vec4 tint : source_color = vec4(1.0);
+uniform float speed = 0.1;
+
+void fragment() {
+    vec2 uv = UV + vec2(TIME * speed, 0.0);   // UV is the node's texcoord
+    COLOR = texture(noise, uv) * tint * COLOR; // in COLOR = vertex/modulate color
+}
+```
+
+Small **spatial** (3D) shader — a fresnel rim glow (`NORMAL` and `VIEW` are **view-space** here):
+
+```glsl
+shader_type spatial;
+render_mode blend_add, cull_back;
+uniform vec3 rim_color : source_color = vec3(0.2, 0.6, 1.0);
+uniform float power : hint_range(0.0, 8.0) = 3.0;
+
+varying vec3 v_normal;
+void vertex()   { v_normal = NORMAL; }        // pass to fragment via varying
+void fragment() {
+    float f = pow(1.0 - dot(normalize(v_normal), normalize(VIEW)), power);
+    EMISSION = rim_color * f;
+    ALPHA = f;
+}
+```
+
+Deep dive (built-in variables per type, render_modes, particles/sky/fog, screen/depth reads) →
+`references/godot-shading-language.md`.
+
+### Unity 6
+
+Two authoring paths, both on the Scriptable Render Pipeline (**URP** for most projects, **HDRP**
+for high-end):
+
+- **Shader Graph** — visual node graph feeding a *master stack* (Vertex + Fragment blocks).
+  Artist-friendly, URP/HDRP only, compiles to HLSL. Default choice for surface looks and VFX.
+- **Hand-written HLSL** — a `Shader "…" { … }` (ShaderLab) wrapping `Properties` and `Pass`
+  blocks; the program goes in an `HLSLPROGRAM … ENDHLSL` block that `#include`s URP's `Core.hlsl`
+  / `Lighting.hlsl`. Use for full control, custom lighting, or compute-driven effects.
+
+**Surface shaders are Built-in-RP only** — under URP/HDRP write a lit HLSL pass or a Shader Graph;
+use `TransformObjectToHClip` for the clip transform, not the retired `UnityObjectToClipPos`. Set
+parameters at runtime through a `MaterialPropertyBlock` or `Material.SetFloat/SetColor/SetTexture`.
+Full URP unlit + lit HLSL pass and a Shader Graph mapping → `references/unity-and-unreal-shaders.md`.
+
+### Unreal 5.x
+
+A **Material** is a node graph the engine compiles to HLSL. You wire outputs on the main result
+node — Base Color, Metallic, Roughness, Emissive Color, Normal, Opacity / Opacity Mask, World
+Position Offset. Key knobs on the material:
+
+- **Material Domain** — what the material drives: *Surface* (default meshes), *Deferred Decal*,
+  *Light Function*, *Volume*, *Post Process* (full-screen), *User Interface*.
+- **Blend Mode** (Opaque/Masked/Translucent/Additive…) and **Shading Model** (Default Lit,
+  Unlit, Subsurface, …). Opacity needs Translucent; Opacity Mask needs Masked.
+- **Material Instances** expose parameters (scalar/vector/texture/switch) for cheap variants and
+  runtime tweaks via a Dynamic Material Instance (`SetScalarParameterValue`, …).
+- **Custom node** — a raw HLSL escape hatch: set Output Type, add named Inputs, `return …;`.
+  Reach for it only when the node set can't express the logic (loops, bitops). Reuse via Material
+  Functions. UE5.5+ adds *Substrate* as an opt-in shading system; the standard material is still default.
+
+Custom-node HLSL, domains, and a Godot↔Unreal recipe mapping → `references/unity-and-unreal-shaders.md`.
+
+## Common effect recipes (concepts)
+
+Each is a *technique*, engine-agnostic — the reference has full per-engine code.
+
+| Effect | Core idea |
+| --- | --- |
+| **Dissolve** | Threshold a noise texture against an animated cutoff; `discard`/clip below it; add an emissive band at the edge. |
+| **Rim / outline** | Rim = fresnel `pow(1 − N·V, p)`. Outline = inverted-hull pass (scale along normals, flip culling) **or** a post-process depth/normal edge detect. |
+| **Toon / cel** | Quantize diffuse `N·L` into bands (`step`/`smoothstep` or a ramp texture); hard-stepped specular. |
+| **Water / flow** | Scroll two normal maps at different speeds (or advect a flow-map's RG); refract the screen texture; depth-difference foam at shorelines. |
+| **Force field** | Fresnel + scrolling hex/pattern texture + intersection glow from a scene-depth difference; additive. |
+| **Hologram** | Scanlines `sin(worldY·f + TIME)` + fresnel + flicker + slight RGB channel offset; additive/translucent. |
+
+**Worked example — dissolve (Godot spatial):**
+
+```glsl
+shader_type spatial;
+render_mode cull_disabled;
+uniform sampler2D dissolve_noise : hint_default_white;
+uniform float threshold : hint_range(0.0, 1.0) = 0.0;   // animate 0 → 1
+uniform float edge = 0.05;
+uniform vec3 edge_color : source_color = vec3(1.0, 0.4, 0.0);
+
+void fragment() {
+    float n = texture(dissolve_noise, UV).r;
+    if (n < threshold) discard;                      // cut the hole
+    float e = smoothstep(threshold, threshold + edge, n);
+    EMISSION = edge_color * (1.0 - e);               // glowing burn ring
+    ALBEDO = vec3(0.6);
+}
+```
+
+Drive `threshold` from an `AnimationPlayer` or `set_shader_parameter`. The same math ports to
+Unity (`clip(n - threshold)`) and Unreal (Opacity Mask + a threshold parameter). All six recipes,
+per engine → `references/effect-recipes.md`.
+
+## Post-processing / full-screen effects
+
+- **Godot** — a `canvas_item` shader on a full-rect `ColorRect` reading `hint_screen_texture`, or
+  a spatial unshaded full-screen quad reading `hint_screen_texture`/`hint_depth_texture`; or a
+  `CompositorEffect` (4.3+) for a custom render pass. Environment already covers glow/tonemap/SSAO.
+- **Unity (URP)** — a **Full Screen Pass Renderer Feature** driving a *Fullscreen* Shader Graph
+  (or a Blit pass). HDRP uses Custom Pass / Fullscreen. Legacy `OnRenderImage` is Built-in-RP only.
+- **Unreal** — a **Post Process Material** (Material Domain = Post Process) on a Post Process
+  Volume; read the frame with **SceneTexture** nodes (SceneColor, SceneDepth, custom stencil).
+  Blendable Location orders it against tonemapping.
+
+## Performance
+
+- **Overdraw** is the top cost: transparent/additive layers each re-shade the same pixels. Prefer
+  opaque, sort and minimize overlap, keep particle fill low. `discard`/`clip` **disables early-Z**
+  — don't use it as a cheap "invisible".
+- **Texture sampling** = a memory fetch + filter each call; *dependent* reads (UV derived from a
+  prior sample) stall the pipeline. Pack masks into channels, atlas, and cache samples in locals.
+- **Branching**: a divergent `if` across a GPU warp can execute *both* sides. Prefer
+  `step`/`mix`/`clamp`; branches on a **uniform** (same value for all pixels) are cheap; static
+  branches compile out.
+- **LOD & precision**: use mipmaps, shader LOD variants, and `mediump`/half precision on mobile;
+  full `float` only where banding shows. Move linear work to the vertex stage.
+- **Mobile / tile GPUs**: bandwidth-bound — keep render targets small, avoid mid-pass framebuffer
+  reads, and note that `discard` and large full-screen passes break tile hidden-surface removal.
+
+## Guardrails / gotchas
+
+- Godot 4: the `SCREEN_TEXTURE`/`DEPTH_TEXTURE` built-ins are gone — declare `hint_screen_texture`
+  / `hint_depth_texture` uniforms. `hint_color` → `source_color`. Author colors as `source_color`
+  so sRGB→linear conversion is correct.
+- Unity: don't write a surface shader or include `UnityCG.cginc` for a URP/HDRP project.
+- Unreal: `SceneTexture` post-process nodes only work in the Post Process domain; match Opacity to
+  the blend mode.
+- Normalize interpolated normals per pixel; unpack normal maps (`×2−1`) and mind tangent handedness.
+- Watch color space (linear vs sRGB) at every texture read and color output — the #1 "looks washed
+  out / too dark" bug.
+
+## Related skills
+
+- [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) — the
+  engine skills own gameplay code, nodes/components, and scene wiring; this skill owns the shaders/materials.
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — simulation, collision, rigid bodies (a shader that *fakes* an effect stays here).
+- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — platform export and shader-variant stripping in the build.
+
+## Checklist
+
+- [ ] Correct engine + version idiom (no banned API from the Version contract table).
+- [ ] Right `shader_type` / render pipeline / material domain for the target (2D vs 3D, URP vs HDRP, Surface vs Post Process).
+- [ ] Work placed in the right stage: linear math per-vertex via `varying`, exact math per-pixel.
+- [ ] Colors authored in the correct space (`source_color` / sRGB handling); normals normalized and unpacked.
+- [ ] Uniforms/parameters exposed and driven from code or an animation track — not hard-coded.
+- [ ] Performance sanity: overdraw, sample count, and branching considered; mobile precision set if targeted.
+- [ ] Post-process uses the engine's supported full-screen path (not a retired Built-in-RP mechanism).
+
+## References
+
+- `references/godot-shading-language.md` — shader types, built-ins per type, render_modes, `varying`, screen/depth reads, ShaderMaterial from code.
+- `references/unity-and-unreal-shaders.md` — Unity URP HLSL pass + Shader Graph mapping; Unreal domains, Custom node HLSL, Material Instances.
+- `references/effect-recipes.md` — dissolve, rim/outline, toon/cel, water/flow, force field, hologram — full code per engine.

package/skills/gamedev-shaders/evals/README.md

@@ -0,0 +1,14 @@
+# Eval harness — `gamedev-shaders` skill
+
+These cases are run by the rsc skill-eval harness (a Claude agent with the full catalog loaded),
+or read manually. They assert two things: **triggering** — the description fires on shader /
+material / VFX / post-process / "how do I make X effect" prompts (including Spanish and
+symptom-only phrasings like "slow on mobile") and stays quiet on near-misses, routing each to the
+right sibling (`godot`/`unity`/`unreal` for gameplay-or-setup, `gamedev-physics` for simulation,
+`gamedev-shipping` for variant stripping, `sql` for the false-friend "optimize"); and
+**capability** — that with `SKILL.md` and its references loaded, the generated Godot 4 dissolve
+shader satisfies the rubric (valid `shader_type`, `discard` against an animatable threshold, an
+emissive `smoothstep` edge, `source_color` hints, no removed `SCREEN_TEXTURE`/`hint_color` APIs,
+code-driven animation, and an overdraw note). Run 3–5 trials per prompt since routing is
+non-deterministic; a prompt passes on a majority. No network needed — the capability rubric is
+judged by reading the output against the points.

package/skills/gamedev-shaders/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: gamedev-shaders
+
+should_trigger:
+  - prompt: "Write me a dissolve shader in Godot 4 that burns an object away from bottom to top with a glowing orange edge."
+    why: "Dissolve is a named recipe and the core use case; Godot 4 .gdshader authoring is owned here."
+  - prompt: "How do I make a rim light / fresnel glow on a 3D character in Unity URP?"
+    why: "Rim/fresnel is a named recipe; 'how do I make X effect' is an explicit trigger; Unity shader authoring is per-engine mapped here."
+  - prompt: "My translucent particle shader tanks the framerate on mobile. How do I fix the overdraw?"
+    why: "Shader performance — overdraw, transparency, mobile — is a dedicated section; symptom-only trigger routes here, not to a generic profiler."
+  - prompt: "Set up a full-screen post-process effect in Unreal that reads scene depth and draws outlines."
+    why: "Post-processing / full-screen effects per engine is a core section; Unreal Post Process material + SceneTexture is covered."
+  - prompt: "Cómo hago un shader de agua con refracción y espuma en los bordes."
+    why: "Spanish water/flow recipe request; the description carries the Spanish 'cómo hago un shader de agua'."
+  - prompt: "Convert this toon/cel shading effect from my Godot project to a Unity Shader Graph."
+    why: "Toon/cel is a named recipe and cross-engine conversion is an explicit use case; the skill carries a Godot↔Unity↔Unreal map."
+  - prompt: "What coordinate space are NORMAL and VIEW in inside a Godot spatial fragment shader, and why does my world-space fresnel look wrong?"
+    why: "Coordinate-spaces / fundamentals plus a Godot-specific gotcha (view-space normals) both live in this skill."
+
+should_not_trigger:
+  - prompt: "Write the GDScript that spawns enemies on a timer and tracks the player's score."
+    route_to: "godot"
+    why: "Gameplay logic and engine APIs belong to the engine skill; this skill only owns the shading, not the script around it."
+  - prompt: "My rigid body tunnels through thin walls at high speed — how do I fix the collision detection?"
+    route_to: "gamedev-physics"
+    why: "Physics simulation and collision (continuous collision detection) is gamedev-physics; a shader has nothing to do with it."
+  - prompt: "My build has 40k shader variants and takes an hour to compile — how do I strip variants for the console ship?"
+    route_to: "gamedev-shipping"
+    why: "Shader-variant stripping in the build/ship pipeline is gamedev-shipping; this skill keeps per-shader authoring performance."
+  - prompt: "Optimize this SQL query that's doing a full table scan on every page load."
+    route_to: "sql"
+    why: "'Shader is slow' overlaps the word 'optimize' but this is database work with zero GPU/material surface."
+  - prompt: "Set up the URP asset, camera stack, and renderer features for my Unity project's rendering settings."
+    route_to: "unity"
+    why: "Project-level render pipeline configuration is engine setup (unity), not writing a shader/material; this skill starts once you're authoring the shader itself."
+
+capability:
+  - scenario: "Author a Godot 4.x spatial dissolve shader that burns an object away with a glowing edge, and expose it to be animated from code."
+    must_include:
+      - "Starts with 'shader_type spatial;' (a valid Godot 4 shader type token)"
+      - "Samples a noise texture and uses discard (or ALPHA_SCISSOR) below an animatable threshold uniform to cut the pixels"
+      - "Adds an emissive edge band via smoothstep around the threshold so the burn edge glows (uses EMISSION)"
+      - "Declares color uniforms with the ': source_color' hint (NOT the removed Godot 3 'hint_color')"
+      - "Does NOT use the removed SCREEN_TEXTURE/DEPTH_TEXTURE built-ins; if a screen/depth read is needed it declares a 'hint_screen_texture'/'hint_depth_texture' uniform"
+      - "Explains driving the threshold uniform from code via set_shader_parameter or an AnimationPlayer track (not hard-coded)"
+      - "Notes that discard disables early-Z / costs overdraw, or otherwise addresses the performance implication"

package/skills/gamedev-shaders/references/effect-recipes.md

@@ -0,0 +1,205 @@
+# Effect recipes
+
+Full per-engine detail behind SKILL.md's recipe table. Each recipe: the technique, then code.
+Godot examples are `.gdshader` (4.x); Unity is URP HLSL/Shader Graph; Unreal is Material graph
+described as node chains (drop to a Custom node only where noted).
+
+---
+
+## 1. Dissolve
+
+**Technique.** Sample a noise texture, compare to an animated `threshold`; cut pixels below it;
+add an emissive band in a thin range above the threshold so the edge glows as the object burns.
+
+**Godot (spatial):**
+
+```glsl
+shader_type spatial;
+render_mode cull_disabled;
+uniform sampler2D noise : hint_default_white;
+uniform float threshold : hint_range(0.0, 1.0) = 0.0;
+uniform float edge = 0.05;
+uniform vec3 edge_color : source_color = vec3(1.0, 0.4, 0.0);
+void fragment() {
+    float n = texture(noise, UV).r;
+    if (n < threshold) discard;
+    float e = smoothstep(threshold, threshold + edge, n);
+    ALBEDO = vec3(0.6);
+    EMISSION = edge_color * (1.0 - e) * 4.0;   // >1 for bloom
+}
+```
+
+**Unity URP (fragment):** `float n = SAMPLE_TEXTURE2D(_Noise, s, uv).r; clip(n - _Threshold);`
+then `emission = _EdgeColor * (1 - smoothstep(_Threshold, _Threshold + _Edge, n));`. In Shader
+Graph: Sample Texture → Step/Smoothstep → Alpha Clip Threshold + Emission.
+
+**Unreal:** Blend Mode = Masked. Noise Texture → Subtract Threshold parameter → **Opacity Mask**.
+For the glow, `Smoothstep` around the threshold → multiply EdgeColor → **Emissive Color**. Animate
+Threshold via a Dynamic Material Instance or a Curve.
+
+---
+
+## 2. Rim light & outline
+
+**Rim (fresnel).** Brightens grazing angles: `rim = pow(1 - saturate(dot(N, V)), power)`. Cheap,
+per-pixel, great for shields/highlights.
+
+**Godot:**
+
+```glsl
+shader_type spatial;
+uniform vec3 rim_color : source_color = vec3(0.4, 0.7, 1.0);
+uniform float power : hint_range(0.5, 8.0) = 3.0;
+void fragment() {
+    float f = pow(1.0 - dot(normalize(NORMAL), normalize(VIEW)), power);
+    EMISSION = rim_color * f;
+}
+```
+
+**Unity:** Fresnel Effect node (Power input) → multiply color → Emission. **Unreal:** Fresnel node
+→ multiply → Emissive Color.
+
+**Outline** — two approaches:
+- **Inverted hull** (mesh outline): a second pass that pushes vertices along their normals and
+  renders only back faces in the outline color. Godot: a second material pass with
+  `render_mode cull_front;` and `VERTEX += NORMAL * width;` in `vertex()`. Unity: an extra Pass
+  with `Cull Front` offsetting `positionOS` along the normal. Unreal: post-process, or a second
+  mesh scaled along normals.
+- **Post-process edge detect** (screen outline): compare neighboring **depth** and **normal**
+  samples; large deltas = an edge. Domain = Post Process (UE) / Full Screen (URP) / ColorRect
+  reading `hint_depth_texture` (Godot). Best for uniform-width screen outlines regardless of mesh.
+
+---
+
+## 3. Toon / cel
+
+**Technique.** Replace smooth diffuse `N·L` with quantized bands (a hard `step`, a few
+`smoothstep` bands, or a 1D ramp texture lookup). Add a stepped specular and optional rim.
+
+**Godot (custom lighting via `light()`):**
+
+```glsl
+shader_type spatial;
+uniform sampler2D ramp : hint_default_white, filter_linear;
+void light() {
+    float ndl = clamp(dot(NORMAL, LIGHT), 0.0, 1.0);
+    float band = texture(ramp, vec2(ndl, 0.5)).r;   // ramp = your toon gradient
+    DIFFUSE_LIGHT += ATTENUATION * LIGHT_COLOR.rgb * band;
+}
+```
+
+Cheaper hard cut without a ramp: `float band = step(0.5, ndl);` or two-step
+`smoothstep(0.48, 0.5, ndl)`. **Unity:** compute `NdotL` in a lit HLSL pass and quantize, or a
+Shader Graph with the main light direction + Step. **Unreal:** custom shading is limited without
+engine mods — approximate with a Post Process banding of scene color, or `CustomLighting`-style
+math in an Unlit material driven by a light vector parameter.
+
+---
+
+## 4. Water / flow
+
+**Technique.** Two scrolling normal maps at different speeds/scales summed for waves; refract the
+scene behind by offsetting the screen UV with the normal; add depth-based foam where scene depth
+is close to the surface. A **flow map** (RG = 2D flow direction) advects UVs for rivers.
+
+**Godot (spatial, refraction + normals):**
+
+```glsl
+shader_type spatial;
+render_mode cull_disabled;
+uniform sampler2D normal_map : hint_normal, repeat_enable;
+uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
+uniform sampler2D depth_tex  : hint_depth_texture;
+uniform float speed = 0.03;
+uniform float strength = 0.02;
+void fragment() {
+    vec2 uv1 = UV + vec2(TIME * speed, 0.0);
+    vec2 uv2 = UV - vec2(0.0, TIME * speed * 0.7);
+    vec3 n = normalize(texture(normal_map, uv1).xyz + texture(normal_map, uv2).xyz - 1.0);
+    vec2 refr = SCREEN_UV + n.xy * strength;
+    ALBEDO = texture(screen_tex, refr).rgb;
+    NORMAL_MAP = n * 0.5 + 0.5;
+}
+```
+
+Foam: compare linearized `depth_tex` at `SCREEN_UV` to the surface's own depth; where the
+difference is small, `mix` toward white. **Unity:** two Sample Texture 2D (normal) with
+Time-driven offsets → combine → Scene Color offset by normal; Scene Depth node difference for
+foam. **Unreal:** Panner nodes on normal maps, Refraction pin, and `SceneDepth − PixelDepth` for a
+foam mask; Single Layer Water shading model for oceans.
+
+---
+
+## 5. Force field / shield
+
+**Technique.** Fresnel base + a scrolling hex/pattern texture, boosted where the mesh intersects
+other geometry (scene-depth difference), additive/translucent. Optional hit ripples from a
+world-space impact point parameter.
+
+**Godot:**
+
+```glsl
+shader_type spatial;
+render_mode blend_add, cull_disabled, unshaded, depth_draw_never;
+uniform sampler2D pattern : repeat_enable;
+uniform sampler2D depth_tex : hint_depth_texture;
+uniform vec3 color : source_color = vec3(0.2, 0.7, 1.0);
+uniform float power : hint_range(0.5, 8.0) = 2.0;
+void fragment() {
+    float fres = pow(1.0 - dot(normalize(NORMAL), normalize(VIEW)), power);
+    float hex = texture(pattern, UV + TIME * 0.05).r;
+    // intersection glow
+    float scene = texture(depth_tex, SCREEN_UV).x;
+    vec4 v = INV_PROJECTION_MATRIX * vec4(SCREEN_UV * 2.0 - 1.0, scene, 1.0);
+    float edge = smoothstep(0.0, 1.0, abs(-v.z / v.w - (-VERTEX.z)));
+    EMISSION = color * (fres + hex * 0.3 + (1.0 - edge));
+    ALPHA = clamp(fres + hex * 0.3, 0.0, 1.0);
+}
+```
+
+**Unity/Unreal:** Fresnel + Panner on a pattern texture, additive/translucent blend, and a Scene
+Depth vs pixel-depth difference (Unity Scene Depth node; UE `SceneDepth − PixelDepth`) for the
+intersection band.
+
+---
+
+## 6. Hologram
+
+**Technique.** Scanlines from `sin(worldY * freq + TIME)`, fresnel edge glow, periodic flicker
+(noise or `sin`), a small per-channel UV offset for chromatic fringing, additive or translucent.
+
+**Godot:**
+
+```glsl
+shader_type spatial;
+render_mode blend_add, cull_disabled, unshaded;
+uniform vec3 color : source_color = vec3(0.3, 0.9, 1.0);
+uniform float lines = 120.0;
+uniform float speed = 2.0;
+varying vec3 wpos;
+void vertex() { wpos = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz; }
+void fragment() {
+    float scan = 0.5 + 0.5 * sin(wpos.y * lines + TIME * speed);
+    float fres = pow(1.0 - dot(normalize(NORMAL), normalize(VIEW)), 2.0);
+    float flicker = 0.9 + 0.1 * sin(TIME * 30.0);
+    EMISSION = color * (scan * 0.6 + fres) * flicker;
+    ALPHA = (scan * 0.5 + fres) * flicker;
+}
+```
+
+**Unity:** world-position Y into a Sine → scanlines; Fresnel node; Time-driven flicker; additive.
+**Unreal:** `WorldPosition.B` (Z-up) → Sine → scanlines, Fresnel, Time flicker → Emissive; Blend
+Mode Translucent/Additive, Unlit. Chromatic fringing: sample the effect at slightly offset UVs per
+R/G/B channel.
+
+---
+
+## Cross-cutting notes
+
+- **Additive/translucent** effects (shield, hologram, force field) stack overdraw — keep them
+  small on screen and unshaded (`render_mode unshaded` / Unlit / Emissive-only).
+- **Depth-based** recipes (foam, intersection glow, screen outline) need the engine's depth
+  texture enabled: URP *Depth Texture* toggle; UE reads SceneDepth natively; Godot's
+  `hint_depth_texture` is available in the forward+ / mobile renderers.
+- Author tunables (speed, power, colors, thresholds) as **parameters/uniforms** and drive them
+  from an animation track or code — never bake magic numbers you'll want to tweak live.

package/skills/gamedev-shaders/references/godot-shading-language.md

@@ -0,0 +1,133 @@
+# Godot 4.x shading language
+
+Depth behind SKILL.md's Godot section. Targets Godot 4.4/4.5. Godot ships its own GLSL-like
+language in `.gdshader` files; a `ShaderMaterial` binds a shader to a node and stores uniform values.
+
+## The five shader types
+
+Every `.gdshader` starts with exactly one `shader_type`:
+
+| `shader_type` | Drives | Key entry points |
+| --- | --- | --- |
+| `spatial` | 3D materials on `MeshInstance3D` etc. | `vertex()`, `fragment()`, `light()` |
+| `canvas_item` | 2D (`Sprite2D`, `TextureRect`, `Control`, …) | `vertex()`, `fragment()`, `light()` |
+| `particles` | GPU particle process (`GPUParticles2D/3D`) | `start()`, `process()` |
+| `sky` | `Sky` resource in an `Environment` | `sky()` |
+| `fog` | `FogVolume` local volumetric fog | `fog()` |
+
+Tokens are exact: `canvas_item` has an underscore, `particles` is plural.
+
+## Uniforms and hints
+
+`uniform`s become material parameters (editable in the inspector, settable from code). Hints tell
+the engine how to treat them:
+
+```glsl
+uniform vec4  albedo      : source_color = vec4(1.0);        // sRGB→linear color picker
+uniform float amount      : hint_range(0.0, 1.0, 0.01) = 0.5;// slider min,max,step
+uniform sampler2D tex      : source_color, filter_linear_mipmap, repeat_enable;
+uniform sampler2D mask     : hint_default_white;             // default when unbound (also _black, _transparent)
+uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
+uniform sampler2D depth_tex  : hint_depth_texture;
+uniform sampler2D nr_tex     : hint_normal_roughness_texture;
+global uniform float game_time;                              // shared project-wide global
+instance uniform vec4 tint : source_color;                   // per-instance override
+```
+
+Migration from Godot 3 (never emit the left side): `hint_color`/`hint_albedo` → `source_color`;
+`hint_white`/`hint_black` → `hint_default_white`/`hint_default_black`; the `SCREEN_TEXTURE`,
+`DEPTH_TEXTURE`, `NORMAL_TEXTURE` **built-ins** → `hint_screen_texture` / `hint_depth_texture` /
+`hint_normal_roughness_texture` **uniforms**.
+
+Texture filter/repeat qualifiers: `filter_nearest`, `filter_linear`, `filter_nearest_mipmap`,
+`filter_linear_mipmap`, `filter_linear_mipmap_anisotropic`; `repeat_enable`, `repeat_disable`.
+
+## varying — vertex → fragment
+
+Declare at file scope, write in `vertex()`, read (interpolated) in `fragment()`:
+
+```glsl
+varying vec3 world_pos;
+void vertex()   { world_pos = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz; }
+void fragment() { /* use world_pos */ }
+```
+
+Add an interpolation qualifier when needed: `varying flat int id;` (no interpolation),
+`varying smooth vec3 n;` (default).
+
+## render_mode
+
+Comma-separated flags right after `shader_type`. Common spatial modes:
+
+```glsl
+render_mode blend_add, cull_disabled, unshaded, depth_draw_opaque, depth_test_disabled, shadows_disabled;
+```
+
+`blend_mix|add|sub|mul`; `cull_back|front|disabled`; `unshaded` (skip lighting); `depth_draw_*`;
+`fog_disabled`. canvas_item supports `blend_*`, `unshaded`, `light_only`, etc.
+
+## Built-ins by type (most-used)
+
+**spatial `fragment()` — inputs:** `UV`, `UV2`, `NORMAL` (view space), `VIEW` (view space, toward
+camera), `VERTEX` (view-space position), `COLOR` (vertex color), `SCREEN_UV`, `TIME`,
+`FRAGCOORD`, matrices `MODEL_MATRIX`, `VIEW_MATRIX`, `INV_VIEW_MATRIX`, `PROJECTION_MATRIX`,
+`INV_PROJECTION_MATRIX`. **outputs:** `ALBEDO`, `ALPHA`, `METALLIC`, `ROUGHNESS`, `SPECULAR`,
+`EMISSION`, `NORMAL_MAP` (tangent-space, expects 0–1), `NORMAL_MAP_DEPTH`, `AO`, `RIM`,
+`CLEARCOAT`, `ALPHA_SCISSOR_THRESHOLD`.
+
+**spatial `vertex()`:** read/write `VERTEX`, `NORMAL`, `TANGENT`, `UV`, `COLOR`; write `POSITION`
+directly (in clip space) to bypass the standard transform — used for full-screen quads:
+`POSITION = vec4(VERTEX.xy, 1.0, 1.0);`.
+
+**canvas_item `fragment()`:** inputs `UV`, `COLOR` (vertex×modulate), `SCREEN_UV`, `TEXTURE`
+(the node's texture), `TEXTURE_PIXEL_SIZE`, `TIME`; output `COLOR`. `MODULATE` exposes the
+CanvasItem modulate separately.
+
+**particles `process()`:** `TRANSFORM`, `VELOCITY`, `COLOR`, `CUSTOM`, `LIFETIME`, `DELTA`,
+`RESTART`, `EMISSION_TRANSFORM`, `ATTRACTOR_FORCE`.
+
+## Screen and depth reads
+
+`SCREEN_TEXTURE` is gone — declare a uniform:
+
+```glsl
+shader_type canvas_item;
+uniform sampler2D screen_tex : hint_screen_texture, filter_linear_mipmap;
+void fragment() { COLOR = texture(screen_tex, SCREEN_UV); }  // what's behind this node
+```
+
+Depth to view/world position in a spatial full-screen pass:
+
+```glsl
+uniform sampler2D depth_tex : hint_depth_texture;
+void fragment() {
+    float d = texture(depth_tex, SCREEN_UV).x;
+    vec4 ndc = vec4(SCREEN_UV * 2.0 - 1.0, d, 1.0);
+    vec4 view = INV_PROJECTION_MATRIX * ndc; view.xyz /= view.w;   // view-space position
+    float linear_depth = -view.z;
+}
+```
+
+## ShaderMaterial from code (GDScript)
+
+```gdscript
+var mat := ShaderMaterial.new()
+mat.shader = preload("res://dissolve.gdshader")
+mesh.material_override = mat
+mat.set_shader_parameter("threshold", 0.7)
+mat.set_shader_parameter("edge_color", Color(1, 0.4, 0))
+# animate a uniform each frame
+func _process(delta): mat.set_shader_parameter("threshold", t)
+```
+
+C# parity: `mat.SetShaderParameter("threshold", 0.7f);`. Prefer an `AnimationPlayer` track on the
+material's `shader_parameter/<name>` for authored animations.
+
+## Common gotchas
+
+- `NORMAL` and `VIEW` in a spatial `fragment()` are **view space**, not world — transform with
+  `INV_VIEW_MATRIX` if you need world space (e.g. triplanar, world-space fresnel toward a point).
+- Re-`normalize()` interpolated normals per pixel.
+- `discard` (and `ALPHA_SCISSOR_THRESHOLD`) disables early depth — costs overdraw; use only for cutouts.
+- Set `render_mode unshaded` on pure-emissive/effect materials to skip the lighting cost.
+- Precompute in `vertex()` and pass a `varying` whenever the quantity interpolates linearly.