@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/gamedev-physics/references/character-controllers.md

@@ -0,0 +1,120 @@
+# Character controllers — kinematic vs dynamic, per engine
+
+A "character controller" is the code that turns intent (move left, jump) into collision-resolved
+motion. Two approaches; pick one and commit.
+
+## Kinematic vs dynamic — the trade
+
+| | Kinematic character | Dynamic (rigidbody) character |
+| --- | --- | --- |
+| Motion | you set velocity, a sweep resolves it | forces/impulses, solver resolves it |
+| Feel | precise, snappy, fully authored | physical, momentum-y, harder to make crisp |
+| Pushed by physics | no (you handle it) | yes, for free |
+| Pushes dynamics | yes | yes |
+| Gravity | you add it manually | automatic |
+| Typical use | platformers, shooters, most players | ragdoll-ish, vehicles, physics puzzles |
+| Pain points | you re-implement gravity/slopes/steps | tipping, sliding, jitter — needs constraints + friction |
+
+Default to **kinematic** for a controllable character. Reach for dynamic only when physical
+interaction *is* the gameplay.
+
+## Godot 4 — CharacterBody (kinematic)
+
+`CharacterBody2D/3D` exposes a `velocity` property and `move_and_slide()`, which sweeps by
+`velocity` (already delta-scaled) and slides along surfaces.
+
+```gdscript
+extends CharacterBody3D
+
+const SPEED := 5.0
+const JUMP_VELOCITY := 4.5
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity += get_gravity() * delta          # get_gravity() is 4.3+; else read ProjectSettings
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = JUMP_VELOCITY
+    var input := Input.get_vector("left", "right", "up", "down")
+    var dir := (transform.basis * Vector3(input.x, 0, input.y)).normalized()
+    velocity.x = dir.x * SPEED
+    velocity.z = dir.z * SPEED
+    move_and_slide()
+```
+
+Tuning knobs on the node:
+- `up_direction` — defines "up" for floor/wall/ceiling classification (default `Vector3.UP`).
+- `floor_max_angle` — steepest slope treated as floor (radians; default 45°). Steeper = wall.
+- `floor_snap_length` — pulls the body to the ground while descending ramps/stairs (kills
+  launch-off-ramp and airborne-on-stairs). Requires `floor_stop_on_slope` behavior tuning.
+- `is_on_floor()` / `is_on_wall()` / `is_on_ceiling()`, `get_floor_normal()`,
+  `get_slide_collision_count()` + `get_slide_collision(i)` to inspect what was hit.
+- `move_and_collide(motion)` — lower-level single sweep returning a `KinematicCollision`; use when
+  you want full manual control (custom slide, wall-jump math).
+
+For one-off exact motion (dashes, kinematic bodies not needing slide) use `move_and_collide`.
+
+## Unity 6 — CharacterController (kinematic) and the dynamic alternative
+
+`CharacterController` is a built-in kinematic capsule with sweeping `Move`. It handles steps and
+slopes via `stepOffset` and `slopeLimit`; it does **not** apply gravity — you do.
+
+```csharp
+[RequireComponent(typeof(CharacterController))]
+public class Player : MonoBehaviour {
+    public float speed = 6f, jumpVelocity = 5f, gravity = -20f;
+    CharacterController cc;
+    Vector3 vel;               // world-space velocity we integrate ourselves
+
+    void Awake() => cc = GetComponent<CharacterController>();
+
+    void Update() {            // CharacterController is kinematic: Update is fine
+        if (cc.isGrounded && vel.y < 0f) vel.y = -2f;               // keep grounded
+        Vector3 wish = transform.right * Input.GetAxis("Horizontal")
+                     + transform.forward * Input.GetAxis("Vertical");
+        if (cc.isGrounded && Input.GetButtonDown("Jump")) vel.y = jumpVelocity;
+        vel.y += gravity * Time.deltaTime;                          // integrate gravity
+        cc.Move((wish * speed + Vector3.up * vel.y) * Time.deltaTime);
+    }
+}
+```
+
+Key fields: `isGrounded`, `slopeLimit` (max walkable slope), `stepOffset` (max step height),
+`skinWidth` (small penetration tolerance — keep ~10% of radius; too small causes jitter),
+`center`/`radius`/`height`. `Move` returns `CollisionFlags`; hook `OnControllerColliderHit` to push
+dynamic rigidbodies.
+
+**Dynamic rigidbody character** instead: `Rigidbody` with `freezeRotation = true` (or constrain
+X/Z rotation), a high-friction physics material, movement via `AddForce`/target-velocity in
+`FixedUpdate`, and a grounded raycast. More physical, more tuning.
+
+## Unreal (UE5) — Character + CharacterMovementComponent
+
+`ACharacter` bundles a capsule + `UCharacterMovementComponent` (CMC), a sophisticated kinematic
+controller. It sweeps, handles Walking / Falling / Swimming / Flying **movement modes**, and applies
+its own gravity scale.
+
+- **Input → movement:** `AddMovementInput(WorldDirection, ScaleValue)`; jump via `Jump()` /
+  `StopJumping()` (`ACharacter` overrides).
+- **Slopes/steps:** CMC `MaxStepHeight`, `SetWalkableFloorAngle` / `GetWalkableFloorAngle`,
+  `MaxWalkSpeed`, `GravityScale`, `JumpZVelocity`, `AirControl`.
+- **Ground state:** `Movement->IsMovingOnGround()`, `IsFalling()`; `CurrentFloor` holds the hit.
+- Moving platforms are handled by CMC's base-relative movement when the character stands on a
+  movable primitive set as its movement base.
+
+For non-Character pawns you can drive a movable component manually or add a `PawnMovementComponent`.
+
+## Ground detection, slopes, steps, moving platforms — the recurring problems
+
+- **Ground detection** must be robust: a single downward ray can miss on ledges. Use the built-in
+  `is_on_floor()` / `isGrounded` / `IsMovingOnGround()` where possible; if rolling your own, use a
+  short **shapecast** (capsule/sphere) slightly wider than the character, not a thin ray.
+- **Slopes:** set the max-walkable-angle knob so steep slopes read as walls; add slide-down on
+  too-steep surfaces if desired. Project intended velocity onto the floor plane to avoid bumpy speed
+  on ramps.
+- **Steps/stairs:** rely on `stepOffset` / `MaxStepHeight` / `floor_snap_length`. A capsule collider
+  climbs small steps far more smoothly than a box.
+- **Moving platforms:** the platform must be a **kinematic mover** that reports motion (Godot
+  `AnimatableBody` with `sync_to_physics = true`; Unity kinematic `Rigidbody.MovePosition` in
+  `FixedUpdate`; Unreal movable primitive as movement base). A **static** body will not carry a
+  character. For a kinematic character on a moving platform, add the platform's per-tick delta to the
+  character before moving, or parent to the platform's motion.

package/skills/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/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/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.