@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/gamedev-physics/references/determinism-and-queries.md

@@ -0,0 +1,124 @@
+# Determinism, stability & queries
+
+Most "my physics is unstable" reports reduce to running simulation in the wrong loop, scaling by the
+wrong delta, or tunneling. This is the fix list plus the query APIs.
+
+## The fixed timestep — where physics must live
+
+Engines separate the **render frame** (variable rate, once per drawn image) from the **physics tick**
+(fixed rate, e.g. 60 Hz). The solver assumes a constant `dt`; feeding it a variable frame time makes
+behavior frame-rate-dependent — the same jump reaches different heights at 30 vs 144 fps.
+
+| Engine | Fixed-tick callback | Rate setting |
+| --- | --- | --- |
+| Godot 4 | `_physics_process(delta)` | `Engine.physics_ticks_per_second` / Project Settings → Physics → Physics Ticks per Second (default 60) |
+| Unity 6 | `FixedUpdate()` | `Time.fixedDeltaTime` / Project Settings → Time → Fixed Timestep |
+| Unreal | Chaos **substepping** / Async Physics Tick | Project Settings → Physics → Substepping (`Max Substep Delta Time`, `Max Substeps`) |
+
+**Pattern:** poll input in the frame update (`_process` / `Update` / `Tick`), cache intent, then
+*apply* forces/velocity and run physics queries in the fixed tick. Never move a physics body or read
+physics state from the render frame.
+
+In Unreal, enabling **Substepping** lets the solver take several fixed sub-steps within a long frame,
+keeping constraints stable at low fps; for hard determinism use the Chaos async physics tick, which
+runs your callback at a fixed rate off the game thread.
+
+## Scale by delta — but not twice
+
+- Manual position changes, accelerations, and continuous forces you integrate yourself: multiply by
+  the tick delta (`delta` / `fixedDeltaTime`).
+- Helpers that already integrate time: do **not** delta-scale their input. Godot `move_and_slide()`
+  takes a per-second `velocity` and applies the timestep internally. Unity `CharacterController.Move`
+  expects a per-*frame* displacement, so you pass `velocity * Time.deltaTime` (velocity is per
+  second) — the classic mistake is forgetting the delta there while double-applying it elsewhere.
+- Gravity done by hand: `velocity += gravity * delta` each tick (gravity is an acceleration).
+
+## Interpolation — smooth visuals without touching the sim
+
+At frame rates above the tick rate, rendering the raw physics position looks choppy. Turn on
+interpolation to render an in-between pose; it is **purely visual** and never alters the simulation.
+
+- Godot 4: physics interpolation (Project Settings → Physics → Common → Physics Interpolation, plus
+  per-node where applicable).
+- Unity: `Rigidbody.interpolation = RigidbodyInterpolation.Interpolate` (or `Extrapolate`).
+- Unreal: interpolation handled by the movement/render sync; async physics results are interpolated.
+
+## Tunneling & CCD
+
+A fast body moving more than its own thickness per tick can pass fully through a thin collider before
+any overlap is tested (discrete collision). Fixes, cheapest first:
+
+1. Make the wall/collider thicker than the fastest per-tick travel, or the projectile bigger.
+2. Enable **Continuous Collision Detection** on the *fast* body only (it is expensive):
+   - Godot: `continuous_cd` (RigidBody2D: Disabled / Cast Ray / Cast Shape; RigidBody3D: on/off).
+   - Unity: `Rigidbody.collisionDetectionMode = Continuous` / `ContinuousDynamic` /
+     `ContinuousSpeculative`.
+   - Unreal: **Use CCD** on the body instance.
+3. For bullets, prefer a **raycast/shapecast-then-move**: sweep from last position to next, and if it
+   hits, resolve at the hit point. This is more reliable than CCD for very small, very fast objects.
+
+## Other stability rules
+
+- **Mass ratios:** keep interacting/jointed bodies within ~10:1 (100:1 blows up). Very light bodies
+  under very heavy ones jitter or get ejected.
+- **Never scale a collider at runtime.** Scaling the transform of a body with a collider (especially
+  non-uniform scale) corrupts the shape and broadphase — swap the shape or size the shape resource
+  instead.
+- **Never write `transform`/`position`/`rotation` on a dynamic (simulated) body.** It teleports past
+  the solver, producing explosions, missed contacts, and ghost collisions. Move dynamics with
+  forces/impulses/velocity; move kinematics with the provided API (`MovePosition`,
+  `move_and_slide`, `SetWorldLocation` with sweep).
+- **Sleeping:** resting bodies sleep to save CPU and stop micro-jitter. Applying a force or a query
+  may need to wake them (`RigidBody.sleeping = false`, `Rigidbody.WakeUp()`); don't fight the sleep
+  system with tiny constant forces.
+- **Solver iterations:** if stacks/joints sag or jitter, raise solver iteration counts (Project/
+  physics settings) before hacking masses.
+
+## Queries — raycast, shapecast, overlap
+
+Run queries in the fixed tick so they see the simulated state, and filter by layer/mask/channel.
+
+**Godot 4** — via the space state (works in `_physics_process`):
+
+```gdscript
+var space := get_world_3d().direct_space_state
+var q := PhysicsRayQueryParameters3D.create(from, to)
+q.collision_mask = 0b0001                    # only scan layer 1
+q.exclude = [self]                           # ignore ourselves
+var hit := space.intersect_ray(q)            # {} if nothing; else position, normal, collider, ...
+```
+
+Shape sweep: `PhysicsShapeQueryParameters3D` + `intersect_shape` (overlap) or `cast_motion` (how far
+a shape can move before hitting). Node helpers `RayCast2D/3D` and `ShapeCast2D/3D` update every tick.
+
+**Unity 6:**
+
+```csharp
+int mask = LayerMask.GetMask("Ground");
+if (Physics.Raycast(origin, dir, out RaycastHit hit, dist, mask)) { /* hit.point, hit.normal */ }
+if (Physics.SphereCast(origin, radius, dir, out RaycastHit sh, dist, mask)) { /* swept */ }
+Collider[] hits = Physics.OverlapSphere(center, radius, mask);   // overlap test
+bool blocked = Physics.CheckSphere(center, radius, mask);        // cheap boolean
+```
+
+Use `RaycastNonAlloc` / `OverlapSphereNonAlloc` in hot paths to avoid garbage. 2D equivalents live on
+`Physics2D` (`Raycast`, `OverlapCircle`, `CircleCast`).
+
+**Unreal (UE5):**
+
+```cpp
+FHitResult Hit;
+FCollisionQueryParams Params(NAME_None, /*bTraceComplex=*/false, this);
+bool bHit = GetWorld()->LineTraceSingleByChannel(
+    Hit, Start, End, ECC_Visibility, Params);          // trace channel
+GetWorld()->SweepSingleByChannel(                      // shapecast
+    Hit, Start, End, FQuat::Identity, ECC_Pawn,
+    FCollisionShape::MakeSphere(30.f), Params);
+TArray<FOverlapResult> Overlaps;                       // overlap test
+GetWorld()->OverlapMultiByChannel(
+    Overlaps, Center, FQuat::Identity, ECC_WorldDynamic,
+    FCollisionShape::MakeBox(FVector(50)), Params);
+```
+
+Use `...ByObjectType` variants to query by object channels, `...ByChannel` for trace channels. Set
+`bTraceComplex = true` only when you need per-triangle precision (costly).

package/skills/shared/gamedev-physics/references/layers-and-masks.md

@@ -0,0 +1,115 @@
+# Collision layers & masks — the filtering that trips everyone up
+
+The single most common physics bug that is not a crash: "these two things should collide and they
+don't," or "this ghost trigger fires on everything." Both are filtering. The concept is universal;
+only the words change.
+
+**Layer = what I *am*. Mask = what I *scan for*.** They are independent bit sets. A body being in
+layer 3 says nothing about what it collides with — that is the mask's job.
+
+## Godot 4
+
+Two properties on every `CollisionObject2D/3D` (StaticBody, RigidBody, CharacterBody, Area):
+
+- `collision_layer` — the layer bits this body occupies (what it *is*).
+- `collision_mask` — the layer bits this body scans (what it *looks for*).
+
+**The rule:** a contact is registered when **either** body's `collision_mask` intersects the
+other's `collision_layer`. It is an **OR**, which is why detection can be *asymmetric* — body A can
+detect body B even if B does not scan for A. This is deliberate (one-way triggers, sensors) but is
+also the classic footgun. **Keep layer/mask symmetric for solid collisions** unless you truly want
+one-way behavior.
+
+For an `Area2D/3D`, the split matters: the Area's **mask** determines which bodies/areas it
+*detects* (fires `body_entered` / `area_entered`); the Area's **layer** determines whether something
+else can detect the Area. A detector-only Area often has a mask set and layer cleared.
+
+Name your layers in **Project Settings → Layer Names → 2D/3D Physics** so the inspector shows
+"player / enemy / world / pickup" instead of bare numbers. Set bits from code with the helpers, not
+raw math:
+
+```gdscript
+set_collision_layer_value(2, true)   # I am on layer 2
+set_collision_mask_value(1, true)    # I scan layer 1
+set_collision_mask_value(3, true)    # ...and layer 3
+```
+
+Bits are 1-indexed in these helpers; the raw `collision_layer` int is a bitmask (layer 1 = value 1,
+layer 2 = value 2, layer 3 = value 4, ...). `collision_layer = 0b101` means layers 1 and 3.
+
+## Unity 6
+
+Physics filtering is layer-pair based, not per-object masks:
+
+1. Assign each GameObject a **Layer** (Inspector top-right; define names in Tags & Layers). Physics
+   layers are the same 32 layers used everywhere.
+2. **Project Settings → Physics → Layer Collision Matrix** (and Physics 2D separately) is a
+   checkbox grid: an unticked cell means those two layers **never** collide or trigger. This is the
+   global filter.
+3. Toggle a single pair at runtime: `Physics.IgnoreLayerCollision(layerA, layerB, true)` — or
+   `Physics.IgnoreCollision(colliderA, colliderB)` for two specific colliders.
+
+Queries take a **`LayerMask`** argument, which is a *different* use of the same layers — it says
+which layers the ray/overlap considers:
+
+```csharp
+// Build a mask from names, then raycast only against Ground + Enemy.
+int mask = LayerMask.GetMask("Ground", "Enemy");
+if (Physics.Raycast(origin, dir, out RaycastHit hit, 50f, mask)) { /* ... */ }
+```
+
+A `LayerMask` is a bitfield: `1 << layerIndex`. Combine with `|`, exclude with `~`. A common mistake
+is passing a layer *index* where a *mask* is expected — always shift or use `LayerMask.GetMask`.
+
+## Unreal (UE5, Chaos)
+
+Two axes per primitive component, configured via **Collision Presets** (Details → Collision):
+
+- **Object Type** — the single channel this component *is* (WorldStatic, WorldDynamic, Pawn,
+  PhysicsBody, or a custom object channel). This is "what I am."
+- **Collision Responses** — for every channel, one of **Block / Overlap / Ignore**. This is "how I
+  react to each kind of thing."
+
+For two components to physically **block**, *both* must respond Block to the other's object type. For
+an **overlap** event, at least one responds Overlap (and the other not Ignore) and **Generate
+Overlap Events** is enabled on both. Bundle a configuration into a named **Collision Preset**
+(Project Settings → Collision) so a whole class of actors shares it — e.g. a `Trigger` preset that
+overlaps Pawns and ignores everything else.
+
+**Trace channels** (Visibility, Camera, or custom) are a *separate* set used only by line/shape
+traces, distinct from object channels used for physical collision. A common error is tracing on an
+object channel or vice versa.
+
+```cpp
+// Custom object channel example (defined in DefaultEngine.ini as ECC_GameTraceChannel1).
+Comp->SetCollisionObjectType(ECC_Pawn);
+Comp->SetCollisionResponseToAllChannels(ECR_Ignore);
+Comp->SetCollisionResponseToChannel(ECC_WorldStatic, ECR_Block);
+Comp->SetCollisionResponseToChannel(ECC_Pawn, ECR_Overlap);
+Comp->SetGenerateOverlapEvents(true);
+```
+
+## Worked example — player / enemy / pickup / wall
+
+Desired: player and enemies collide with walls and each other; the pickup collides with nothing but
+detects the player touching it.
+
+| Thing | Godot layer | Godot mask | Unity layer / matrix | Unreal preset |
+| --- | --- | --- | --- | --- |
+| Wall | World | (none needed) | World; collides with Player, Enemy | BlockAll |
+| Player | Player | World, Enemy, Pickup | Player; collides World, Enemy | Pawn (blocks World/Pawn) |
+| Enemy | Enemy | World, Player, Enemy | Enemy; collides World, Player, Enemy | Pawn |
+| Pickup (Area/Trigger) | Pickup | Player | Pickup; **only** Player pair ticked, `IsTrigger` | Custom `Pickup`: overlap Pawn, ignore all else |
+
+The pickup is a **trigger/Area**: it scans only for the Player layer and produces an overlap event,
+never a solid collision.
+
+## Debug checklist when a collision "doesn't happen"
+
+- Do the layer/mask bits actually overlap? (Godot: is one body's mask covering the other's layer?)
+- Unity: is the pair ticked in the **Layer Collision Matrix**, and did you use 2D matrix for 2D?
+- Unity trigger: is there a **Rigidbody** on at least one of the two objects? Trigger events need one.
+- Unreal: are **both** set to Block (for solid) or is Generate Overlap Events on **both** (for overlap)?
+- Query returns nothing: are you passing a **mask/channel** that includes the target? Passing a raw
+  layer index instead of a shifted mask silently matches the wrong layer.
+- One-way collision you did not intend → Godot asymmetric mask; make it symmetric.

package/skills/shared/gamedev-shaders/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: gamedev-shaders
+description: "Use when authoring or debugging a shader, material, VFX, or full-screen post-process in a game engine — Godot 4.x `.gdshader`, Unity 6 URP/HDRP, Unreal 5.x Materials, effect recipes, shader performance. NOT gameplay or engine-API code (that is `godot`/`unity`/`unreal`), NOT physics (`gamedev-physics`), NOT build variant stripping (`gamedev-shipping`)."
+tags: [shaders, vfx, materials, post-processing, shadergraph]
+recommends: [godot, unity, unreal, gamedev-shipping]
+profiles: [full]
+origin: ai-hub
+---
+
+# 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.
+
+## 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`.
+
+## 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 not an option under URP/HDRP (see the Version contract) — a lit look is an
+HLSL pass or a Shader Graph. 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.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+| --- | --- |
+| Porting a tutorial verbatim from Godot 3, Built-in RP, or pre-5.0 UE | Translate it through the Version contract table first — retired symbols still compile in old guides, not in your project. |
+| Reading a texture or writing a color without minding linear vs sRGB | Author color uniforms as `source_color` (Godot) / sRGB-marked properties and check the space at every read and output — the #1 "looks washed out / too dark" bug. |
+| Using interpolated normals raw, or a normal map straight from the sample | Re-normalize per pixel; unpack with `×2−1` and mind tangent handedness. |
+| Writing the shader before choosing the target surface | Pick `shader_type` / render pipeline / material domain first (2D vs 3D, URP vs HDRP, Surface vs Post Process) — it decides which built-ins and blend modes exist. |
+| Fresnel, normalization, or lighting math in the vertex stage | Only linearly-interpolating work goes per-vertex; exact math stays per-pixel. |
+| `discard`/`clip` as a cheap "make it invisible" | Cull it or scale to zero — `discard` disables early-Z and breaks tile hidden-surface removal on mobile. |
+| Stacking additive/translucent layers until the look works | Count the overdraw: each layer re-shades the same pixels. Prefer opaque, minimize overlap, keep particle fill low. |
+| Full-screen effects via `OnRenderImage`/`Graphics.Blit`, or `SceneTexture` outside the Post Process domain | Use the engine's supported path — URP Renderer Feature / Fullscreen Shader Graph, UE Post Process material, Godot `ColorRect` + `hint_screen_texture` or `CompositorEffect`. |
+
+## Related skills
+
+- [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) — gameplay
+  code, nodes/components, input, scene wiring; this skill owns the *shading*, not the C#/GDScript/Blueprint around it.
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — simulation, collision, rigid bodies, character
+  controllers (a shader that *fakes* refraction is here; simulating fluid dynamics is not).
+- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — platform export and shader-variant stripping in
+  the build (this skill keeps the per-shader performance work).
+
+## 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).

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

@@ -0,0 +1,14 @@
+# Eval harness — `gamedev-shaders` skill
+
+These cases are run by the ai-hub 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/shared/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 the core shape of a shader request; 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; water/flow is a named recipe and matching is by meaning, not by language."
+  - 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"