@genex-ai/cli-demo 0.7.0 → 0.10.0

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -1,113 +1,56 @@
-# Realtime patterns: interpolation, prediction, persistence
+# Realtime patterns: rendering, objects, host, events, persistence
 
-The `@genex-ai/multiplayer` relay gives you the **latest** state of each player and
-nothing else — no timestamps, no smoothing. These are the pieces you add on top so the
-game feels good. All code is plain TypeScript; nothing here is provided by the package.
+The `@genex-ai/multiplayer` SDK smooths remote players **and shared objects** for you (client-side
+entity interpolation on a shared clock). These are the patterns you build on top — none of them
+re-implement smoothing, because doing so is the mistake that makes games lag.
 
-## Why you need this
+## The golden rule
 
-- You publish `me.set` at ~15 Hz but render at 60 fps. If you snap each remote player to
-  their last received position, they move in visible 15 Hz steps and jump on packet
-  jitter. **Fix: interpolation** — render each remote player slightly in the past and
-  lerp between their two surrounding snapshots.
-- Your *own* avatar would feel laggy if you waited for the server to echo your position
-  back. **Fix: prediction** — apply input locally and render yourself from that
-  immediately; the tick still publishes it for everyone else.
+- **Remote players & objects:** draw `players.get(id).state` / `objects.get(id).state` directly.
+  Already smoothed.
+- **Yourself & objects you own:** draw from your own local object. Never from the network echo.
 
-## RemoteInterpolator (render-delay interpolation)
+If you ever buffer `state` and lerp between snapshots, stop — you're rebuilding smoothing the SDK
+already did, and stacking two smoothers adds visible lag.
 
-Buffers timestamped snapshots per remote player and samples a smoothed value ~100 ms in
-the past. Stamp snapshots with the local clock on arrival (we don't get server time).
-
-```ts
-// interpolation.ts
-const RENDER_DELAY_MS = 100; // render remotes this far in the past; raise if jittery
-const BUFFER_MS = 1000;      // keep ~1s of history
-
-type Vec = { x: number; y: number; z: number; yaw: number };
-type Snap = { t: number; v: Vec };
-
-function lerp(a: number, b: number, k: number) {
-  return a + (b - a) * k;
-}
-// shortest-arc angle lerp (radians) — avoids spinning the wrong way across ±π
-function lerpAngle(a: number, b: number, k: number) {
-  let d = (b - a) % (Math.PI * 2);
-  if (d > Math.PI) d -= Math.PI * 2;
-  if (d < -Math.PI) d += Math.PI * 2;
-  return a + d * k;
-}
-
-export class RemoteInterpolator {
-  private buffers = new Map<string, Snap[]>();
-
-  /** Call whenever you read a remote player's latest state (e.g. each frame, or on 'change'). */
-  push(id: string, v: Vec, now = performance.now()) {
-    let buf = this.buffers.get(id);
-    if (!buf) this.buffers.set(id, (buf = []));
-    const last = buf[buf.length - 1];
-    // de-dupe identical repeats (players is re-read every frame)
-    if (last && last.v.x === v.x && last.v.z === v.z && last.v.yaw === v.yaw && last.v.y === v.y) return;
-    buf.push({ t: now, v });
-    const cutoff = now - BUFFER_MS;
-    while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
-  }
-
-  /** Smoothed value to render this frame, or null if we have nothing yet. */
-  sample(id: string, now = performance.now()): Vec | null {
-    const buf = this.buffers.get(id);
-    if (!buf || buf.length === 0) return null;
-    const target = now - RENDER_DELAY_MS;
-    if (buf.length === 1 || target <= buf[0].t) return buf[0].v;
-    if (target >= buf[buf.length - 1].t) return buf[buf.length - 1].v; // clamp (no extrapolation)
-    for (let i = 0; i < buf.length - 1; i++) {
-      const a = buf[i], b = buf[i + 1];
-      if (target >= a.t && target <= b.t) {
-        const k = (target - a.t) / (b.t - a.t || 1);
-        return {
-          x: lerp(a.v.x, b.v.x, k),
-          y: lerp(a.v.y, b.v.y, k),
-          z: lerp(a.v.z, b.v.z, k),
-          yaw: lerpAngle(a.v.yaw, b.v.yaw, k),
-        };
-      }
-    }
-    return buf[buf.length - 1].v;
-  }
-
-  remove(id: string) {
-    this.buffers.delete(id);
-  }
-}
-```
-
-**Tuning:** `RENDER_DELAY_MS` ≈ one tick interval + jitter (100 ms is safe for a 15 Hz
-tick). Lower = more responsive but more stutter on jitter. For sudden teleports (respawn,
-warp) clear that player's buffer and snap, so you don't lerp across the whole map.
-
-## Complete movement example
+## Complete movement example (players)
 
 ```ts
 import * as THREE from "three";
 import { connect } from "@genex-ai/multiplayer";
 import { GENEX } from "./genex.config";
-import { RemoteInterpolator } from "./interpolation";
 
-type S = { x: number; z: number; yaw: number };
+// Your published state — EVERY synced field, including discrete ones like hp. `me.set`
+// replaces your state wholesale, so the tick must send all of these every time (below).
+type S = { x: number; z: number; q: number[]; hp: number };
 
 const room = await connect<S>({ url: GENEX.colyseusUrl, room: GENEX.slug });
-const interp = new RemoteInterpolator();
 
-// --- local player: prediction. Input mutates this; we render yourself from it. ---
-const me = { x: 0, z: 0, yaw: 0 };
+// --- local player: input mutates this; we render yourself from it (zero latency) ---
+// This ONE object holds everything you sync. Keep hp/ammo/etc. here too — see the warning below.
+const me = { x: 0, z: 0, yaw: 0, hp: 100 };
 addEventListener("keydown", (e) => {
   if (e.key === "ArrowLeft") me.yaw += 0.1;
   if (e.key === "ArrowRight") me.yaw -= 0.1;
   if (e.key === "ArrowUp") { me.x += Math.sin(me.yaw); me.z += Math.cos(me.yaw); }
 });
 
-// --- publish at ~15 Hz (NOT per frame) ---
-const tick = setInterval(() => room.me.set(me), 66);
+// rotation helper — turn our yaw into the quaternion we publish (and send with shots, below)
+const _q = new THREE.Quaternion();
+const myQuat = (): number[] => _q.setFromAxisAngle(new THREE.Vector3(0, 1, 0), me.yaw).toArray();
+
+// --- publish at ~15 Hz (NOT per frame). Send the WHOLE state — a field you omit is deleted. ---
+const tick = setInterval(() => {
+  room.me.set({ x: me.x, z: me.z, q: myQuat(), hp: me.hp });
+}, 66);
+```
+
+> **`me.set` replaces your state wholesale.** Every tick must include EVERY field — position,
+> rotation, AND discrete values like `hp`/`ammo`. A field you leave out is gone on the wire, so
+> keep one local `me` object with all of them and publish it whole each tick. (Same for
+> `objects.set`.)
+
+```ts
 
 // --- meshes, one per id ---
 const meshes = new Map<string, THREE.Object3D>();
@@ -119,84 +62,156 @@ function meshFor(id: string) {
 room.on("leave", (id) => {
   const m = meshes.get(id);
   if (m) { scene.remove(m); meshes.delete(id); }
-  interp.remove(id);
 });
 
 function frame() {
-  // yourself: render from local predicted state (zero latency)
-  meshFor(room.id).position.set(me.x, 0, me.z);
-  meshFor(room.id).rotation.y = me.yaw;
+  // yourself: render from the local object (zero latency)
+  const self = meshFor(room.id);
+  self.position.set(me.x, 0, me.z);
+  self.rotation.y = me.yaw;
 
-  // everyone else: feed the interpolator, render the smoothed sample
+  // everyone else: draw state DIRECTLY — it is already smoothed
   for (const [id, p] of room.players) {
     if (id === room.id) continue;
-    interp.push(id, { x: p.state.x ?? 0, y: 0, z: p.state.z ?? 0, yaw: p.state.yaw ?? 0 });
-    const v = interp.sample(id);
-    if (!v) continue;
     const m = meshFor(id);
-    m.position.set(v.x, v.y, v.z);
-    m.rotation.y = v.yaw;
+    m.position.set(p.state.x ?? 0, 0, p.state.z ?? 0);
+    if (p.state.q) m.quaternion.fromArray(p.state.q);   // slerped for you by the SDK
   }
 
   renderer.render(scene, camera);
   requestAnimationFrame(frame);
 }
 frame();
-
-// cleanup if you ever tear down: clearInterval(tick); room.leave();
 ```
 
-## Custom events (shots, emotes, chat)
+No interpolation buffer, no render-delay constant, no lerp of remote state — the SDK owns all of it.
+
+## A shared object (the ball) — `objects`, not `shared`
 
-For one-off actions that aren't part of continuous state, use `send` — it doesn't belong
-in `me.set` (which is your *current* state, not events):
+A ball belongs to no player. On `objects`, exactly one client **owns** it at a time (server-
+enforced), the owner simulates it, and everyone else reads it auto-smoothed — on the same
+interpolation as a player. The stream is keyed by the object id, so it stays continuous when
+ownership changes (no snap), and the object survives its owner leaving (reassigned to the host).
 
 ```ts
-// shooter:
-room.send("shot", { from: room.id, x: me.x, z: me.z, yaw: me.yaw });
+// ball.ts
+const ball = { x: 0, y: 0.5, z: 0, vx: 0, vy: 0, vz: 0 }; // the owner's local sim
 
-// everyone else:
-room.on("shot", (msg: any) => spawnTracer(msg.x, msg.z, msg.yaw));
+// claim on contact (you kicked it) — NOT every frame
+function kick(dir: THREE.Vector3, power: number) {
+  room.objects.claim("ball");
+  ball.vx += dir.x * power; ball.vz += dir.z * power;
+}
+
+// in your fixed tick: if you own it, simulate + publish it (flat fields so it smooths)
+function publishBall() {
+  const view = room.objects.get("ball");
+  if (view?.isMine) {
+    stepBallPhysics(ball);                     // your own integrator or Rapier
+    room.objects.set("ball", { x: ball.x, y: ball.y, z: ball.z });
+  }
+}
+
+// render: owner draws its local sim (zero latency); everyone else draws the smoothed state
+function drawBall() {
+  const view = room.objects.get<{ x: number; y: number; z: number }>("ball");
+  if (!view) return;
+  ballMesh.position.set(view.state.x ?? 0, view.state.y ?? 0, view.state.z ?? 0);
+}
+```
+
+Rules that keep it correct:
+
+- **Claim on interaction, not continuously.** Whoever last kicked owns and simulates it.
+- **Keep object fields flat** (`x/y/z`, a 4-number quaternion). Nested objects snap instead of glide.
+- **Only the owner's `set` lands** — the relay drops writes from non-owners, so you never get two
+  clients fighting over the ball. You don't need to check "am I owner" before drawing, only before
+  simulating.
+- **Transient objects** (bullets, pickups): `room.objects.remove(id)` when they expire, so they
+  don't pile up.
+
+## Host authority (scores, rounds, world)
+
+One client is `room.host` (the first joiner, re-elected on leave). Let only the host write agreed
+state, so there's a single source of truth — no "who increments the score" races:
+
+```ts
+function updateHud() {
+  scoreEl.textContent = String(room.shared.get("score") ?? 0);   // everyone reads
+}
+function goal(team: "a" | "b") {
+  if (!room.isHost) return;                                       // only the host writes
+  const key = `score_${team}`;
+  room.shared.set(key, (Number(room.shared.get(key)) || 0) + 1);
+}
+room.on("host", () => {/* host migrated — the new host takes over writing */});
 ```
 
-## Shared room state (scores, round, world)
+`room.on('shared', …)` fires when a key is **first set**, not on every change — for a live value,
+read `room.shared.get(...)` in your loop (as `updateHud` does) rather than relying on the event.
+
+## Custom events (shots, emotes, chat)
+
+For one-off actions that aren't continuous state, use `send`. The shooter judges the hit **locally**
+against what it sees (favor-the-shooter) and announces it; the victim applies its own damage.
 
-`shared` is for state everyone agrees on, not per-player position:
+**`send` reaches only OTHER clients — it never echoes back to you.** So apply your own action's
+visible effect *directly* at fire time; use `on(...)` only to render everyone else's:
 
 ```ts
-room.shared.set("round", (Number(room.shared.get("round")) || 0) + 1);
-room.on("shared", (key, value) => { if (key === "score") updateScoreboard(value); });
+function fire() {
+  const hit = raycastAgainstWhatISee();       // favor-the-shooter: judge locally
+  spawnTracer(me.x, me.z, myQuat());          // MY tracer — right here, not via on("shot")
+  room.send("shot", { from: room.id, x: me.x, z: me.z, q: myQuat(), hit: hit ?? null });
+}
+
+room.on("shot", (m: any) => {
+  spawnTracer(m.x, m.z, m.q);                 // OTHER players' tracers
+  if (m.hit === room.id) me.hp -= 10;         // I was hit → my next me.set publishes the new hp
+});
 ```
 
-Any client can write any key (demo relay has no auth). For authority (who may change the
-score / advance the round), pick one client — e.g. the first/lowest session id present —
-and let only it write.
+Read remote positions for hit-testing from `stateRaw` (raw latest), not `state` (rendered in the
+past). Guard the lookup — a player may have just left:
+
+```ts
+const t = room.players.get(id);
+if (!t) return;
+const px = t.stateRaw.x, pz = t.stateRaw.z;   // test against the raw latest
+```
 
 ## Persistence helper
 
 ```ts
-// persistence.ts
+// persistence.ts — /state requires the embed identity: call only after
+// `await waitForAuth()` has resolved (see the genex-threejs-embed-auth skill).
+import { getEmbedToken } from "@genex-ai/embed-sdk";
+
 export async function loadWorld<T>(fallback: T): Promise<T> {
   try {
-    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`).then(r => r.json());
+    const { data } = await fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
+      headers: { Authorization: `Bearer ${getEmbedToken()}` },
+    }).then(r => r.json());
     return (data as T) ?? fallback;
   } catch { return fallback; }
 }
 
 let saveTimer: ReturnType<typeof setTimeout> | null = null;
 export function saveWorld(world: unknown) {
-  // debounce: at most one PUT per second, from ONE authority client
-  if (saveTimer) return;
+  if (saveTimer) return;                     // debounce: at most one PUT/sec, from the host only
   saveTimer = setTimeout(() => {
     saveTimer = null;
     fetch(`${GENEX.apiUrl}/api/projects/${GENEX.slug}/state`, {
       method: "PUT",
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${getEmbedToken()}`,
+      },
       body: JSON.stringify(world),
     }).catch(() => {});
   }, 1000);
 }
 ```
 
-State is one JSON blob per project, max 1 MB, last-write-wins. Save from a single
-authority (host) so concurrent writers don't clobber each other.
+State is one JSON blob per project, max 1 MB, last-write-wins. Save from a single authority
+(`room.isHost`) so concurrent writers don't clobber each other.

package/templates/skills/genex-threejs-precipitation-surfaces/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: genex-threejs-precipitation-surfaces
+description: Build coupled precipitation and weather-affected surfaces for Genex Three.js games. Use for falling snow, snow accumulation, model snow caps, rain, wet asphalt puddles, procedural ripple normals, splash flipbooks, rain streaks, shared weather envelopes, and surface wetness or coverage transitions.
+---
+
+# Genex Three.js Precipitation Surfaces
+
+Treat weather as a coupled event, particle, and surface-response system. Do not
+add rain or snow particles that are visually disconnected from the ground.
+
+## Build order
+
+```text
+weather envelope
+  -> falling precipitation volume
+  -> world/object surface mask
+  -> displaced or optical surface response
+  -> impact residue and splashes
+  -> shared lighting/post presentation
+```
+
+Read [references/precipitation-surfaces.md](references/precipitation-surfaces.md)
+for snow accumulation, object capping, wrapped precipitation volumes, wet
+puddle masks, procedural ripple normals, splash placement, and debug outputs.
+
+For the base ground surface under the wetness or snow (asphalt, dirt, stone),
+generate a real texture with `npx genex texture` and load it via
+`$genex-ai-texture`, then build the precipitation response on top of it.
+Splash flipbook atlases and ripple normals stay procedural (for example a
+canvas-drawn expanding-ring atlas) — they are not generated assets.
+
+## Required controls
+
+- precipitation density and speed;
+- wind direction and strength;
+- shared weather progress or coverage;
+- wetness, snow, or puddle mask threshold and softness;
+- ripple or drift normal strength;
+- surface roughness response;
+- particle/splash opacity;
+- debug modes for masks, normals, particles, and event progress.
+
+## Failure conditions
+
+- falling precipitation ignores the wind or timing used by surface response;
+- snow height and snow normals come from different fields;
+- model snow sticks to vertical faces without an upward-facing filter;
+- puddles only lower roughness without a mask, normal response, or ripples;
+- splashes appear on downward or hidden faces;
+- rain streaks allocate per drop or fail to wrap around the camera;
+- temporal wetness is faked with unrelated time noise.
+
+## Routing boundary
+
+Use `$genex-threejs-water-optics` for bounded pool simulation, caustics, Fresnel,
+refraction, and Beer-Lambert water volumes. Use `$genex-threejs-procedural-vfx` for
+general sparks, plasma, trails, and non-weather particles. Use
+`$genex-threejs-temporal-surfaces` for screen-space touch history or frost clearing.
+This skill owns precipitation events and the surfaces they visibly alter.

package/templates/skills/genex-threejs-precipitation-surfaces/references/precipitation-surfaces.md

@@ -0,0 +1,181 @@
+# Precipitation Surface Systems
+
+Precipitation reads as real only when particles, surface masks, normals,
+roughness, and impact residue share the same event state. The following
+contracts describe two reusable families: snow accumulation and wet rain
+puddles.
+
+## Contents
+
+- Weather state contract
+- Wrapped precipitation volume
+- Snow accumulation contract
+- Object snow capping
+- Wet puddle contract
+- Rain streaks and splashes
+- Debug outputs
+- Boundaries and failure modes
+
+## Weather state contract
+
+Use a small shared state object for weather systems. The state is passed by
+reference into both particles and surfaces.
+
+```js
+const weather = {
+  uTime: { value: 0 },
+  uWind: { value: new THREE.Vector3(1.2, 0, 0.5) },
+  uProgress: { value: 0 },
+};
+
+function updateWeather(delta, target) {
+  weather.uTime.value += delta;
+  weather.uProgress.value = THREE.MathUtils.damp(
+    weather.uProgress.value,
+    target,
+    0.9,
+    delta,
+  );
+}
+```
+
+Do not give rain particles one clock and puddle ripples another. Do not sample
+wind in screen space for particles and world space for surfaces. The wind vector
+is horizontal and is interpreted as world units per second for moving
+precipitation, while scalar progress controls wetness or coverage.
+
+## Wrapped precipitation volume
+
+A camera-centered volume avoids finite emitter edges. Each instance stores a
+normalized spawn point and a random seed. The vertex shader turns that into a
+world position and wraps all axes with `mod`.
+
+```glsl
+vec3 origin = uCameraPos - vec3(vol.x * 0.5, vol.y * 0.4, vol.z * 0.5);
+float speed = uSpeed * (0.6 + 0.7 * aRand);
+vec3 base = aSeed * vol;
+vec3 disp = vec3(uWind.x, -speed, uWind.z) * uTime + sway;
+vec3 pos = mod(base + disp - origin, vol) + origin;
+```
+
+For snow, use soft round camera-facing billboards with opacity around `0.9`,
+flake radius around `0.07`, speed around `3.2`, and a horizontal sway near
+`0.5`. For rain, use narrow vertical or uneven-capsule billboards and a faster
+fall speed, commonly around `5` world units per second in an inspection-scale
+scene.
+
+## Snow accumulation contract
+
+Ground snow needs one height function. The same function displaces vertices and
+feeds finite-difference normals.
+
+```glsl
+float snowMaskAt(vec2 worldXZ) {
+  vec2 p = worldXZ * uSnowScale + uSnowSeed;
+  float n = fbm(p) * 0.5 + 0.5;
+  float threshold = 1.0 - uSnowCoverage;
+  return smoothstep(threshold - uSnowEdge, threshold + uSnowEdge, n);
+}
+
+float snowHeightAt(vec2 worldXZ) {
+  float mask = snowMaskAt(worldXZ);
+  float drift = fbm(worldXZ * uSnowBumpScale) * 0.5 + 0.5;
+  float h = mask * (1.0 - 0.4 * uSnowBumpStrength +
+                    0.4 * uSnowBumpStrength * drift);
+  vec2 edge = smoothstep(10.0, 8.0, abs(worldXZ));
+  return uSnowDepth * h * edge.x * edge.y;
+}
+
+vec3 groundSurfaceNormal(vec2 worldXZ) {
+  float e = 0.08;
+  float h0 = snowHeightAt(worldXZ);
+  float hx = snowHeightAt(worldXZ + vec2(e, 0.0));
+  float hz = snowHeightAt(worldXZ + vec2(0.0, e));
+  vec2 grad = vec2(hx - h0, hz - h0) / e;
+  return normalize(vec3(-grad.x, 1.0, -grad.y));
+}
+```
+
+The snow material response should override albedo toward a cool white, push
+roughness to roughly `0.82`, and add sparse sparkle only inside the snow mask.
+The sparkle is a material response, not a separate particle layer.
+
+## Object snow capping
+
+Object snow must be model-locked. Compute a world-to-model matrix for the host
+object and sample coverage in that coordinate space so moving or rotating the
+object does not slide the snow pattern.
+
+```glsl
+float snowAccumAt(vec3 worldNormal, vec2 modelXZ) {
+  float up = clamp(worldNormal.y, 0.0, 1.0);
+  float top = smoothstep(uSnowFlatThreshold, 1.0, up);
+  return top * snowCoverageMask(modelXZ);
+}
+```
+
+Typical controls are `uSnowFlatThreshold = 0.35`, `uSnowThickness = 0.06`,
+`uSnowCoverage = 0.7`, and `uSnowEdge = 0.15`. Displace along the object normal
+but convert from world units to local units using the mapped normal length.
+
+## Wet puddle contract
+
+Wet asphalt is a material transition driven by rain progress. Use separate
+progress bands: roughness changes early, ripple normals arrive as the rain
+becomes heavy.
+
+```glsl
+float roughnessProgress = smoothstep(0.0, 0.75, uRainFactor);
+float normalProgress = smoothstep(0.75, 1.0, uRainFactor);
+float puddleNoise = getPuddle(vPosition.xy * 15.0);
+float puddleMask = smoothstep(0.0, 1.0, puddleNoise) * normalProgress;
+```
+
+The puddle roughness is intentionally collapsed toward the `0.0..0.1` range
+inside the mask. Ripple normals are analytic: every local cell emits expanding
+rings with finite-difference slope estimation. Keep the ripple normal separate
+from the static asphalt normal until the final normal handoff.
+
+## Rain streaks and splashes
+
+Rain streaks can be instanced quads. Their fragment shape may use an uneven
+capsule SDF and alpha around `0.1 * rainProgress`. Splash placement should use
+surface sampling weighted by upward normals.
+
+```js
+const skyWeight = normal.dot(new THREE.Vector3(0, 1, 0)) >= 0 ? 1 : 0;
+geometry.setAttribute("skyWeight", new THREE.BufferAttribute(weights, 1));
+sampler.setWeightAttribute("skyWeight");
+```
+
+Each splash instance owns a progress attribute. A flipbook shader maps progress
+to a tile in a `4 x 5` atlas, fades by rain progress, and uses additive
+blending. The splash mesh should face the camera around Y.
+
+## Debug outputs
+
+Expose at least:
+
+- `final`: complete weather and surface response;
+- `mask`: snow or puddle coverage only;
+- `normals`: accumulated snow normal or ripple normal;
+- `particles`: precipitation density and fall volume;
+- `progress`: shared rain or snow envelope.
+
+Diagnostics should report active instance count, coverage, and whether the
+surface response is reading the same time/wind uniforms as particles.
+
+## Boundaries and failure modes
+
+Use a water-volume skill when the system needs refraction through a bounded
+water body, caustics, or Beer-Lambert thickness. Use a general VFX skill for
+non-weather particles. Use a screen-space temporal-surface skill for touch
+history, not for world-space wetness.
+
+Known failure modes:
+
+- snow silhouettes rise but normals stay flat;
+- object snow uses world coordinates and slides under animation;
+- puddle masks are independent of roughness and normal changes;
+- splashes sample all triangles and appear under objects;
+- rain progress affects particles but not the material, or the reverse.

package/templates/skills/genex-threejs-procedural-architecture/SKILL.md

@@ -29,7 +29,8 @@ Read [references/architecture-systems.md](references/architecture-systems.md) be
 - Compile by material slot to reduce draw calls without destroying material separation.
 - Preserve real dimensions for floor height, bay width, trim projection, and texture density.
 - Randomness may select among valid designs; it must not repair invalid geometry.
-- Provide topology, placement, material-slot, and UV-density debug modes.
+- Provide topology, façade ownership, material/geometry, and shadow diagnostics
+  appropriate to the renderer path.
 
 ## Acceptance
 

package/templates/skills/genex-threejs-procedural-architecture/references/architecture-systems.md

@@ -73,7 +73,7 @@ Seeded randomness perturbs constrained decisions:
 
 ```text
 towerScale = clamp(
-  authoredTowerScale + random(-0.05, 0.04),
+  settings.towerScale + random(-0.05, 0.04),
   0.62,
   0.96
 )

package/templates/skills/genex-threejs-procedural-fields/SKILL.md

@@ -43,11 +43,6 @@ Read [references/field-systems.md](references/field-systems.md)
 before implementation. It records sphere, terrain, water, and
 structured-placement field contracts plus common parity defects.
 
-Read the
-[procedural planet surface](../threejs-procedural-planets/examples/procedural-planet-surface/planet-system.js)
-for a shared CPU/GLSL field bundle whose height, continents, climate, biomes,
-roughness, and normals remain independently inspectable.
-
 ## Non-negotiable rules
 
 - Independent noise per channel produces visual soup. Share structure.

package/templates/skills/genex-threejs-procedural-geometry/SKILL.md

@@ -21,11 +21,6 @@ Read [references/mesh-systems.md](references/mesh-systems.md)
 for the exact sculpted-frame profile, rail emission, tree rings, semantic mesh
 writer, and their observed scaling limits.
 
-Read the
-[authored financial tower compiler](../threejs-procedural-architecture/examples/authored-financial-tower/building-system.js)
-for semantic placement compilation and material-slot instancing at building
-scale.
-
 ## Failure conditions
 
 - profile orientation flips along a curve;

package/templates/skills/genex-threejs-procedural-materials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-procedural-materials
-description: Author production procedural materials for Genex Three.js games. Use for PBR identity, terrain materials, atlas filtering, specular anti-aliasing, wetness, biome surfaces, dissolves, procedural normals, roughness variation, and readable materials across gameplay distances.
+description: Author production procedural materials for Genex Three.js games. Use for PBR identity, terrain materials, atlas filtering, specular anti-aliasing, wetness, lava and hot emissive surfaces, raymarched material fields, biome surfaces, dissolves, procedural normals, roughness variation, and readable materials across gameplay distances.
 ---
 
 # Genex Three.js Procedural Materials
@@ -23,21 +23,6 @@ Read [references/material-systems.md](references/material-systems.md)
 for atlas filtering, specular AA, planetary coordinates,
 world-height wetness, per-instance dissolve, and authored PBR response bundles.
 
-Read the
-[sculpted gallery frame geometry](../threejs-procedural-geometry/examples/sculpted-gallery-frame/frame-geometry.js)
-for walnut, antique-gold, and ebony texture/roughness/metalness/clearcoat
-bundles under a grazing-light setup.
-
-Read the
-[procedural planet surface](../threejs-procedural-planets/examples/procedural-planet-surface/planet-system.js)
-for shared geological, climate, water, biome, roughness, and derivative-normal
-causes on a procedural planetary surface.
-
-Read the
-[analytic wave optics](../threejs-water-optics/examples/analytic-wave-optics/water-system.js)
-for coupled reflection, refraction, absorption, filtered microstructure,
-resolved crest response, and their diagnostic channels.
-
 ## Required controls
 
 - real or perceptual texture scale;
@@ -46,7 +31,7 @@ resolved crest response, and their diagnostic channels.
 - the causal fields required by the selected material pattern;
 - distance/derivative filtering;
 - specular antialiasing;
-- channel and mask debug modes.
+- channel and mask debug modes;
 - emissive-material debug modes when the material owns glow or volumetric
   accumulation.