@genex-ai/cli-demo 0.52.0-dev.115 → 0.53.0-dev.117

package/dist/index.js

@@ -1949,13 +1949,99 @@ async function detectUiPhases(cwd = process.cwd()) {
     return true;
   }
 }
+function ctorArgs(content, ctor) {
+  const out = [];
+  const re = new RegExp(`new\\s+(?:THREE\\.)?${ctor}\\s*\\(`, "g");
+  let m;
+  while (m = re.exec(content)) {
+    let i = re.lastIndex;
+    let depth = 1;
+    while (i < content.length && depth > 0) {
+      const ch = content[i];
+      if (ch === "(" || ch === "{" || ch === "[") depth++;
+      else if (ch === ")" || ch === "}" || ch === "]") depth--;
+      i++;
+    }
+    out.push({ text: content.slice(re.lastIndex, i - 1), index: m.index });
+  }
+  return out;
+}
+function splitArgs(text) {
+  const out = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    else if (ch === "," && depth === 0) {
+      out.push(text.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  out.push(text.slice(start).trim());
+  return out;
+}
+var lineOf = (content, index) => content.slice(0, index).split("\n").length;
+var DEPTH_RATIO_LIMIT = 1e6;
+async function detectSurfaceScan(cwd = process.cwd()) {
+  const found = { guessedRepeat: [], squarePoints: [], depthRange: [] };
+  const srcDir = path11.join(cwd, "src");
+  let entries;
+  try {
+    entries = await fs10.readdir(srcDir, { recursive: true });
+  } catch {
+    return found;
+  }
+  for (const rel of entries) {
+    if (rel.includes("node_modules")) continue;
+    if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
+    const raw = await fs10.readFile(path11.join(srcDir, rel), "utf8").catch(() => "");
+    if (!raw) continue;
+    const content = raw.replace(/\/\*[\s\S]*?\*\//g, (m2) => m2.replace(/[^\n]/g, " ")).replace(/(^|[^:])\/\/[^\n]*/gm, (m2, p1) => p1 + " ".repeat(m2.length - p1.length));
+    const repeatRe = /\.repeat\.set\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
+    let m;
+    while (m = repeatRe.exec(content)) {
+      const u = Number(m[1]);
+      const v = Number(m[2]);
+      if (u === v) continue;
+      found.guessedRepeat.push({
+        where: `${rel}:${lineOf(content, m.index)}`,
+        detail: `repeat.set(${m[1]}, ${m[2]})`
+      });
+    }
+    for (const call of ctorArgs(content, "PointsMaterial")) {
+      if (/\b(map|alphaMap)\s*:/.test(call.text)) continue;
+      found.squarePoints.push({
+        where: `${rel}:${lineOf(content, call.index)}`,
+        detail: "PointsMaterial with no map/alphaMap"
+      });
+    }
+    for (const call of ctorArgs(content, "PerspectiveCamera")) {
+      const args = splitArgs(call.text);
+      if (args.length < 4) continue;
+      const near = Number(args[2]);
+      const far = Number(args[3]);
+      if (!isFinite(near) || !isFinite(far) || near <= 0 || far <= near) continue;
+      const ratio = far / near;
+      if (ratio <= DEPTH_RATIO_LIMIT) continue;
+      found.depthRange.push({
+        where: `${rel}:${lineOf(content, call.index)}`,
+        detail: `near ${near} / far ${far}`,
+        ratio
+      });
+    }
+  }
+  return found;
+}
 async function detectFeatures(log, cwd = process.cwd()) {
   return {
     embedSdkVersion: await detectEmbedSdkVersion(cwd),
     multiplayer: await detectMultiplayer(cwd),
     matchmaking: await detectMatchmaking(log, cwd),
     gameStateUsed: await detectGameStateUsage(cwd),
-    uiPhases: await detectUiPhases(cwd)
+    uiPhases: await detectUiPhases(cwd),
+    surfaces: await detectSurfaceScan(cwd)
   };
 }
 function advisoryNudges(log, d) {
@@ -1979,6 +2065,26 @@ function advisoryNudges(log, d) {
       "No menu/loader screens detected (no data-phase/setPhase) \u2014 players get a bare HUD with no title screen and no styled loading. Run the genex-threejs-game-ui plan (loader, menu, screen tiers); a cinematic menu is two commands away (genex-ai-menu)."
     );
   }
+  surfaceNudges(log, d.surfaces);
+}
+function surfaceNudges(log, s) {
+  if (s.guessedRepeat.length) {
+    const list = s.guessedRepeat.map((d) => `${d.where} \u2014 ${d.detail}`).join("; ");
+    log.warn(
+      `Texture tiling picked by eye, not derived from the mesh: ${list}. A hand-chosen repeat is right for at most ONE face \u2014 a BoxGeometry gives all six faces 0..1 UVs whatever their world size, and repeat lives on the Texture, so every mesh sharing that texture inherits it. Derive the UVs from world size instead: genex-ai-texture ships worldUV(geometry, TILE_M), after which repeat stays (1, 1) and cannot be wrong.`
+    );
+  }
+  if (s.squarePoints.length) {
+    const list = s.squarePoints.map((d) => d.where).join(", ");
+    log.warn(
+      `Particles will render as hard SQUARES: ${list} builds a PointsMaterial with no map/alphaMap, so every point is an opaque camera-facing quad. Give it a soft sprite (genex image --transparent) or a round gl_PointCoord cutout \u2014 and check the particle belongs there at all: genex-threejs-procedural-vfx decides that per moment.`
+    );
+  }
+  for (const d of s.depthRange) {
+    log.warn(
+      `Camera depth range ${d.detail} (far/near = ${d.ratio.toExponential(1)}) at ${d.where} is past what a 24-bit depth buffer can serve \u2014 touching surfaces will z-fight and flicker, and it reads fine right up until it doesn't. near is the expensive knob (resolvable depth \u2248 z\xB2 / (near \xD7 2^24)), so raise near to the closest the camera can actually get. If the range is genuinely astronomical, that is what WebGLRenderer's logarithmicDepthBuffer is for: genex-threejs-camera-direction.`
+    );
+  }
 }
 async function firstPreviewNudge(log, cwd = process.cwd()) {
   const meta = await readProject(cwd);
@@ -2503,8 +2609,9 @@ async function reportTextureSeam(url, log) {
       `Visible ${r.worstAxis} tiling seam \u2014 the tile boundary jumps ${r.worstRatio}\xD7 this texture's own detail (want \u2264 ${r.tolerance}\xD7).`
     );
     log.plain("  It will read as a repeating grid on any large surface. Before wiring it in:");
-    log.plain('  \u2022 regenerate with "seamless tiling, no visible edges" in the prompt (--terrain for ground), or');
-    log.plain("  \u2022 lower the mesh's UV repeat so the seam falls off-camera.");
+    log.plain('  \u2022 regenerate with "seamless tiling, no visible edges" in the prompt (--terrain for ground).');
+    log.plain("  Do NOT hide it by tiling less: a hand-picked repeat trades a seam you can name for a");
+    log.plain("  stretched texture you can't. Scale belongs in the UVs (worldUV \u2014 genex-ai-texture).");
     log.plain(`  Re-check any image any time: ${c.cyan("npx genex ui seams --in <url>")}`);
   } catch {
   }
@@ -4084,7 +4191,7 @@ async function uiSeams(opts, log) {
     return;
   }
   fail(
-    `Visible ${r.worstAxis} tiling seam in ${name}: the tile boundary jumps ${r.worstRatio}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable, or lower the mesh's UV repeat so the seam falls off-camera.`
+    `Visible ${r.worstAxis} tiling seam in ${name}: the tile boundary jumps ${r.worstRatio}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable. Don't hide it behind a hand-picked UV repeat \u2014 that trades a seam for a stretched texture (scale belongs in the UVs: worldUV, genex-ai-texture).`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.52.0-dev.115",
+  "version": "0.53.0-dev.117",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-texture/SKILL.md

@@ -40,6 +40,10 @@ published game, and remixes alike).
 
 ## Apply it (tiling material)
 
+Load the texture, then **measure the UVs off the geometry** — never set `repeat`
+by eye. `worldUV` (next section) is the whole reason this is two lines and not a
+judgement call.
+
 ```ts
 import * as THREE from "three";
 
@@ -48,25 +52,96 @@ const TEXTURE_URL = "https://assets.genex.technology/generations/<id>/texture-ba
 const map = await new THREE.TextureLoader().loadAsync(TEXTURE_URL);
 map.colorSpace = THREE.SRGBColorSpace;
 map.wrapS = map.wrapT = THREE.RepeatWrapping;
-map.repeat.set(8, 8);          // tile count — raise for large surfaces
 map.anisotropy = renderer.capabilities.getMaxAnisotropy();
+// NOTE: no map.repeat here, on purpose — worldUV puts the scale in the UVs.
 
-const material = new THREE.MeshStandardMaterial({ map, roughness: 0.9, metalness: 0 });
-groundMesh.material = material; // e.g. a PlaneGeometry ground
+const TILE_M = 4;               // one tile covers 4×4 metres — choose ONCE per material
+const geo = worldUV(new THREE.PlaneGeometry(200, 200), TILE_M);
+const ground = new THREE.Mesh(geo, new THREE.MeshStandardMaterial({ map, roughness: 0.9 }));
+ground.rotation.x = -Math.PI / 2;
+scene.add(ground);
+```
+
+Same two lines for a wall, a kerb, a platform, a crate — any shape, any size:
+
+```ts
+const wallGeo = worldUV(new THREE.BoxGeometry(19, 2.4, 1), TILE_M);
 ```
 
 ### Terrain
 
-Generate with `--terrain`, lay a large `PlaneGeometry` (rotated flat), and raise
-`repeat` so the texture tiles densely across it:
+Generate with `--terrain` and lay a large `PlaneGeometry` (rotated flat). Scale is
+the same call — `worldUV(geo, TILE_M)`. Pick `TILE_M` by what the material IS: a
+4 m gravel tile and a 0.6 m tile of floorboards are both right, for different
+materials. What is never right is a different density on two faces of one object.
+
+## Why you cannot pick `repeat` by eye
+
+Two facts make a hand-chosen `repeat` wrong on everything but the one face you
+were looking at:
+
+1. **Every `BoxGeometry` face spans UV 0..1 regardless of its world size.** A
+   `Box(1, 2.4, 17)` gives its 1×17 m top face the same 0..1 UV square as its
+   17×2.4 m side. One `repeat` therefore cannot serve both.
+2. **`repeat` lives on the `Texture`, not the `Material`.** Two meshes sharing one
+   loaded texture share its `repeat`, `offset` and `wrapS/T`. Setting it for the
+   wall silently re-tiles the crates. (If you truly need two densities from one
+   image, `map.clone()` — but `worldUV` means you almost never do.)
+
+A real game shipped `wallTex.repeat.set(6, 1)` on a four-box wall ring. The number
+was tuned against the long side face and landed there at a near-perfect 1.2:1 —
+and the same number put **1:102** on the wall tops, which read to the player as
+wooden planks rather than the riveted steel the texture actually shows. The
+texture was flawless. The wiring was not.
+
+## `worldUV` — measure the UVs, don't guess them
+
+Copy this in. It rewrites a geometry's UVs so one tile covers `tileM × tileM`
+metres on **every** face, whatever the shape. After it, leave `repeat` at (1, 1)
+and it cannot be wrong — there is no number left to pick.
 
 ```ts
-const ground = new THREE.Mesh(new THREE.PlaneGeometry(200, 200), material);
-ground.rotation.x = -Math.PI / 2;
-map.repeat.set(64, 64);
-scene.add(ground);
+/**
+ * Box-project a geometry's UVs in world metres. Call once at build time.
+ * Units are the geometry's own, so keep mesh.scale at 1 (or bake it in with
+ * geometry.scale(...)) — worldUV cannot see a scale applied to the mesh.
+ * Returns a non-indexed geometry: a shared vertex on a box corner belongs to
+ * faces pointing different ways and cannot carry one UV for both.
+ */
+function worldUV(geometry: THREE.BufferGeometry, tileM: number): THREE.BufferGeometry {
+  const g = geometry.index ? geometry.toNonIndexed() : geometry;
+  const pos = g.attributes.position;
+  const uv = new Float32Array(pos.count * 2);
+  const a = new THREE.Vector3(), b = new THREE.Vector3(), c = new THREE.Vector3();
+  const ab = new THREE.Vector3(), ac = new THREE.Vector3(), n = new THREE.Vector3();
+  for (let t = 0; t < pos.count / 3; t++) {
+    const i0 = t * 3, i1 = i0 + 1, i2 = i0 + 2;
+    a.fromBufferAttribute(pos, i0);
+    b.fromBufferAttribute(pos, i1);
+    c.fromBufferAttribute(pos, i2);
+    n.crossVectors(ab.subVectors(b, a), ac.subVectors(c, a));
+    const nx = Math.abs(n.x), ny = Math.abs(n.y), nz = Math.abs(n.z);
+    // Drop the face's dominant axis; the other two are the tile plane. One
+    // branch exactly — picking each axis independently collapses a 45° face to
+    // a zero-area UV.
+    const axis = nx >= ny && nx >= nz ? 0 : ny >= nz ? 1 : 2;
+    for (const i of [i0, i1, i2]) {
+      const x = pos.getX(i), y = pos.getY(i), z = pos.getZ(i);
+      const u = axis === 0 ? z : x;
+      const v = axis === 1 ? z : y;
+      uv[i * 2] = u / tileM;
+      uv[i * 2 + 1] = v / tileM;
+    }
+  }
+  g.setAttribute("uv", new THREE.BufferAttribute(uv, 2));
+  return g;
+}
 ```
 
+This is box projection: correct for the primitives games build out of (boxes,
+planes, kerbs, platforms, extrusions). A generated GLB arrives with its own
+authored UVs — leave those alone; `worldUV` is for geometry **you** construct.
+
 ## Tiling is checked FOR you — read the verdict
 
 `npx genex texture` measures the wrap seam of every texture it generates and
@@ -77,28 +152,17 @@ prints the verdict right under the URL. A bad one looks like this:
 ```
 
 `--terrain` ASKS the model for seamless; it does **not** guarantee it — a shipped
-game seamed at 6.6× with `--terrain` set. So when that line appears, fix it
-BEFORE wiring the texture in: **regenerate** with "seamless tiling, no visible
-edges" in the prompt, or **lower the `repeat`** so the seam falls off-camera. A
-good texture prints `tiles cleanly` instead. To re-check any image (including one
-you didn't just generate): `npx genex ui seams --in <png|url>`.
-
-## Scale by texel density — never hand-pick `repeat`
-
-The other half of "the floor looks wrong" is a `repeat` guessed out of the air.
-Keep texels SQUARE: derive BOTH axes from the surface's real world size and ONE
-chosen tile size.
-
-```ts
-const TILE_M = 4;                                // one tile covers 4×4 metres — choose once
-map.repeat.set(width / TILE_M, depth / TILE_M);  // a 40×400 m lane → (10, 100)
-```
-
-A non-uniform guess like `repeat.set(2, 40)` on a long lane stretches the texture
-20:1 along it: the pattern smears one way and crowds the other. That reads as
-"wrong scale / glued together" even when the texture itself is flawless — and it
-is exactly what shipped in a real game. Same rule for walls and platforms: derive
-from that surface's own width/height, not from the floor's numbers.
+game seamed at 6.6× with `--terrain` set. When that line appears, **regenerate**
+with "seamless tiling, no visible edges" in the prompt before wiring it in. Do
+not try to hide a seam by tiling less: that trades a visible defect you can name
+for a stretched one you can't, and a texture that only survives at `repeat` 1 on
+one axis is a texture that failed. To re-check any image (including one you
+didn't just generate): `npx genex ui seams --in <png|url>`.
+
+Note the two checks see different things and you need both to pass: the seam
+check judges the **image**, `worldUV` fixes the **wiring**. A flawless image
+wired at 1:102 and a seamed image tiled perfectly are both defects, and the
+first one is the one a screenshot of the whole arena will not show you.
 
 ## Publish checklist
 

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -323,6 +323,17 @@ near 0.2
 far 3.0e7
 ```
 
+**Do not copy those numbers into an ordinary game.** That range only works
+because a planet renderer pairs it with `WebGLRenderer({ logarithmicDepthBuffer:
+true })`; on a stock 24-bit depth buffer it throws the precision away and any two
+surfaces that touch will fight and flicker. The expensive knob is `near`, not
+`far`: resolvable depth at distance z is roughly `z² / (near × 2^24)`, so every
+halving of `near` halves precision at every distance. Set `near` to the closest
+the camera can genuinely get — for a third-person or top-down game that is
+metres, not centimetres — and `far` to the far edge of the world, and the ratio
+takes care of itself. `genex preview` warns when a camera's range is past what a
+plain depth buffer can serve.
+
 It prewarms pipelines by temporarily aiming at representative bodies, then
 restores both position and quaternion in `finally`.
 

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

@@ -1,23 +1,146 @@
 ---
 name: genex-threejs-procedural-vfx
-description: Author procedural real-time VFX for Genex Three.js games. Use for particles, trails, plasma, sparks, shockwaves, impacts, dissolving debris, ability effects, reentry wakes, event-timed visuals, effect pools, HDR emission hierarchy, and gameplay-readable spectacle.
+description: Author procedural real-time VFX for Genex Three.js games, and decide WHERE effects belong — walk the game's moments one by one, the way the visual-direction gate walks its surfaces. Use for particles, trails, plasma, sparks, shockwaves, impacts, dissolving debris, ability effects, reentry wakes, event-timed visuals, effect pools, HDR emission hierarchy, and gameplay-readable spectacle.
 ---
 
 # Genex Three.js Procedural VFX
 
 Build effects from an event envelope, motion field, geometry representation, and shading response. Avoid independent particle emitters that happen to share a color.
 
-## Effect graph
+## The moment gate — run this BEFORE writing any effect code
 
-```text
-ship/event state
-  → effect-specific geometry or instance attributes
-  → flow-facing masks or analytic age
-  → material response
-  → pool/lifetime ownership
-  → HDR and bloom contribution
+The visual-direction gate walks **surfaces** and asks "texture or shader?" for
+each. It cannot see effects, because effects don't live on surfaces — they live
+on **moments**. So walk the moments the same way, and decide each one.
+
+List every moment the game's own rules fire. Take them from the game's controls
+and contract, not from imagination — a bomb detonates, a crate breaks, a pickup
+is collected, a player dies, a round starts, a shot lands. Then judge each:
+
+> **Does the world change here in a way the player should SEE, and does the
+> existing feedback already say it?**
+
+Three answers, all legitimate, one forbidden:
+
+- **Effect earns it** — the moment has a cause the player made and a consequence
+  they must read, and nothing else is carrying it. Build it.
+- **Already covered** — a flash, a sound, hitstop, a decal, or an animation
+  already lands the beat. Adding particles buys nothing but fill rate. **Say so
+  in one line and move on.**
+- **Deliberately bare** — the look wants restraint. Valid. **Say so in one line.**
+- **Not deciding** — the only wrong answer. A game where bombs detonate and the
+  world does not react is not a style choice, it's an unfinished list.
+
+Then check the inverse, because the failure runs both ways: **an effect on a
+moment the player didn't cause and can't read is noise.** Ambient particles are
+the usual offender — they sell mood, not information. Budget **one** ambient
+layer for the whole scene, and only if the scene is visibly dead at rest.
+
+**Shape is part of this gate.** For a moment made of energy — fire, a blast, a
+shockwave — the question is never "what texture goes on this box?" It is "what
+is this energy shaped like?" A shipped game reasoned "the flame is deliberately
+untextured — it is pure emissive energy" and left a **cube** standing in for
+fire. That sentence answers the surface gate correctly and the moment gate not at
+all. If a primitive is standing in for an effect, it is a placeholder, whatever
+the comment says.
+
+## Particles do not render round by default
+
+`new THREE.PointsMaterial({ size, color })` draws every point as a **hard-edged
+camera-facing square**. There is no soft falloff, no roundness, no fade — those
+are things you add. Shipping the default is the "square flying things" look, and
+it is the single most common particle defect in real builds.
+
+The fix costs eight lines and no generation call:
+
+```ts
+/** A soft round dot drawn into a canvas — no network, no asset, works offline. */
+function dotTexture(size = 64): THREE.Texture {
+  const c = document.createElement("canvas");
+  c.width = c.height = size;
+  const ctx = c.getContext("2d")!;
+  const g = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+  g.addColorStop(0, "rgba(255,255,255,1)");
+  g.addColorStop(0.4, "rgba(255,255,255,0.5)");
+  g.addColorStop(1, "rgba(255,255,255,0)");
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, size, size);
+  const t = new THREE.Texture(c);
+  t.needsUpdate = true;
+  return t;
+}
+
+const material = new THREE.PointsMaterial({
+  map: dotTexture(),            // ← without this every mote is a square
+  color: 0xffb98a,
+  size: 0.06,
+  sizeAttenuation: true,        // near motes bigger than far ones
+  transparent: true,
+  depthWrite: false,            // motes must not occlude each other
+  blending: THREE.AdditiveBlending,
+});
+```
+
+For a mote with real art (embers with structure, snowflakes, leaves), generate the
+sprite instead — `npx genex image --transparent "single soft round ember, black
+background"` — and use it as `map`. The canvas dot is the right default for
+anything that is just light.
+
+`depthWrite: false` turns off the depth **write**, not the depth **test**: a
+particle still gets rejected by geometry in front of it. That's what you want —
+but it also means a mote sitting fractionally below the floor vanishes. Spawn
+above the surface, not on it.
+
+## Bursts are pooled, never allocated
+
+A burst that runs `new Points(...)` per explosion allocates during the exact
+frame the player is watching. Pre-build one pool at load, take from it, return on
+death — the same shape the rest of the scene uses for bombs and flames.
+
+```ts
+const N = 240;
+const pos = new Float32Array(N * 3);
+const vel = new Float32Array(N * 3);
+const life = new Float32Array(N);          // seconds remaining; 0 = free
+const geo = new THREE.BufferGeometry();
+geo.setAttribute("position", new THREE.BufferAttribute(pos, 3));
+const points = new THREE.Points(geo, material);
+points.frustumCulled = false;              // positions move; the bounds don't follow
+
+function burst(x: number, y: number, z: number, n = 24, speed = 3): void {
+  let spawned = 0;
+  for (let i = 0; i < N && spawned < n; i++) {
+    if (life[i] > 0) continue;
+    const th = Math.random() * Math.PI * 2;
+    const ph = Math.acos(2 * Math.random() - 1);
+    const s = speed * (0.5 + Math.random() * 0.5);
+    vel[i * 3] = Math.sin(ph) * Math.cos(th) * s;
+    vel[i * 3 + 1] = Math.abs(Math.cos(ph)) * s;   // bias up — debris arcs
+    vel[i * 3 + 2] = Math.sin(ph) * Math.sin(th) * s;
+    pos[i * 3] = x; pos[i * 3 + 1] = y; pos[i * 3 + 2] = z;
+    life[i] = 0.5 + Math.random() * 0.4;
+    spawned++;
+  }
+}
+
+function step(dt: number): void {
+  for (let i = 0; i < N; i++) {
+    if (life[i] <= 0) continue;
+    life[i] -= dt;
+    if (life[i] <= 0) { pos[i * 3 + 1] = -1000; continue; }  // park it offscreen
+    vel[i * 3 + 1] -= 9.8 * dt;                              // gravity
+    pos[i * 3] += vel[i * 3] * dt;
+    pos[i * 3 + 1] += vel[i * 3 + 1] * dt;
+    pos[i * 3 + 2] += vel[i * 3 + 2] * dt;
+  }
+  geo.attributes.position.needsUpdate = true;
+}
 ```
 
+Call `burst()` from the same place the game already plays the explosion sound —
+that call site IS the moment, and it is the proof the effect is event-driven
+rather than ambient decoration.
+
 Read [references/vfx-systems.md](references/vfx-systems.md)
 for ship-conforming reentry shells, capsule wakes, dense instanced
 spark/debris pools, HDR hierarchy, and implementation limits.
@@ -31,11 +154,14 @@ spark/debris pools, HDR hierarchy, and implementation limits.
 - Pool instances and trails; do not allocate per burst.
 - Expose spawn, simulation, overdraw, and luminance debug views.
 - Include a non-bloom baseline that remains legible.
+- Never ship a `PointsMaterial` without a `map` or `alphaMap` — see above.
 
 ## Routing boundary
 
 Use `$genex-threejs-temporal-surfaces` only for the screen-space
 frost/touch-history pipeline. Use `$genex-threejs-precipitation-surfaces` for
 falling rain or snow, splash flipbooks, and weather events that alter ground
-materials. Keep ship-space plasma, generated wakes, sparks,
+materials. Impact **residue** on a surface (scorch, bullet holes) is a decal —
+`$genex-ai-image` owns that; the spark that throws the residue is this skill, and
+a hit usually wants both. Keep ship-space plasma, generated wakes, sparks,
 and pooled debris in this skill.

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -64,7 +64,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
      the scene alive at rest — an emissive pulse along edges, heat shimmer,
      drifting dust, a slowly flowing texture. Shader/procedural, zero
      generations, built with the scene — a world that is perfectly still
-     reads as a screenshot, not a place;
+     reads as a screenshot, not a place. ONE is the budget, not the floor.
+     If the answer is particles, `$genex-threejs-procedural-vfx` carries the
+     recipe — a bare `PointsMaterial` renders hard squares, and picking this
+     bullet without that skill is how "drifting dust" ships as flying boxes;
    - **every primitive surface — texture it or shade it, decided one by one**:
      the ground is never the only surface. Walk the walls, barriers, kerbs,
      platforms and props the game BUILDS out of primitives, and give each a real
@@ -79,7 +82,24 @@ Three.js release or branch, and do not blindly copy demo architecture.
      ships when this bullet is skipped. `$genex-threejs-procedural-materials`
      and `$genex-threejs-procedural-vfx` own the craft. Whatever you apply, SEE
      it in the running game before calling it done — an unverified shader
-     disfigures as easily as it delights;
+     disfigures as easily as it delights. Scale is not a judgement call: derive
+     the UVs from world size (`worldUV`, `$genex-ai-texture`) and never hand-pick
+     a `repeat` — one `repeat` cannot be right for six box faces of different
+     sizes, and a shipped game put 1:102 on a wall top that way;
+   - **every moment the rules fire — decide the effect one by one**: the
+     surfaces above are only half the scene. Walk the moments the GAME
+     CONTRACT already names — a hit lands, a crate breaks, a pickup is taken, a
+     player dies, a round starts — and for each ask whether the world changes
+     in a way the player should see, and whether existing feedback already says
+     it. "A flash and a sound already carry this" is a real answer; so is "bare
+     on purpose". Say either in one line. Not deciding is the only wrong answer,
+     and it is why games ship where bombs detonate and nothing reacts. Then
+     check the inverse — an effect on a moment the player didn't cause and can't
+     read is noise, and ambient particles are the usual offender. For a moment
+     made of ENERGY (fire, a blast, a shockwave) the question is not "what
+     texture goes on this box" but "what shape is this energy": a primitive
+     standing in for an effect is a placeholder no matter how deliberate the
+     comment says it is. `$genex-threejs-procedural-vfx` owns this gate;
    - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
      wrote — one art direction across scene and UI.
    Planning is not building: effects still land LAST (steps 10–11); this step

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -66,6 +66,117 @@ everything twice.
    "click to aim/resume" cue appears. Headless caveat: `requestPointerLock`
    throws in headless Chromium — assert the wiring and the unlocked cue in a
    screenshot, and say plainly that the lock itself needs one manual click.
+7. **Ask the scene the two things the screenshot cannot answer** (below). Run it
+   once, in the same browser you already have open.
+
+### The screenshot has two blind spots — query them
+
+A capture of the whole arena is taken from one camera at one distance. Two real
+defect classes are invisible in it and both shipped to players:
+
+- **Texture scale on faces you aren't looking at.** A shipped game's wall tops
+  were 1:102 — the steel texture read as wooden planks — while the wall *sides*,
+  the faces at eye level, were a near-perfect 1.2:1. Nothing in the screenshot
+  says which is which; the numbers do.
+- **Coplanar surfaces.** Two boxes overlapping with faces at the same height
+  z-fight. It may look stable in a still and flicker the moment the camera
+  moves, so a screenshot is the one tool guaranteed to miss it.
+
+Expose the scene in dev (`if (import.meta.env.DEV) (window as any).__scene = scene;`),
+then paste this into the browser console once and read the verdict. It needs no
+imports — pass it straight to your JS-eval tool.
+
+```js
+(() => {
+  const S = window.__scene, MIN_M2 = 1.0;   // judge real faces, not GLB slivers
+  const out = { stretched: [], zfight: [] };
+  const xf = (e,x,y,z) => [e[0]*x+e[4]*y+e[8]*z+e[12], e[1]*x+e[5]*y+e[9]*z+e[13], e[2]*x+e[6]*y+e[10]*z+e[14]];
+  const sub = (a,b) => [a[0]-b[0], a[1]-b[1], a[2]-b[2]];
+  const cross = (a,b) => [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]];
+  const len = a => Math.hypot(a[0],a[1],a[2]);
+  const comb = (a,s,b,t) => [a[0]*s+b[0]*t, a[1]*s+b[1]*t, a[2]*s+b[2]*t];
+
+  // metres-per-tile along U and V, from each triangle's UV Jacobian. Geometry
+  // agnostic — a box, a plane and a GLB all measure the same way — and it reads
+  // texture.repeat, so it sees what the GPU will actually draw.
+  S.traverse(o => {
+    if (!o.isMesh) return;
+    const m = Array.isArray(o.material) ? o.material[0] : o.material;
+    const g = o.geometry, uv = g.attributes && g.attributes.uv;
+    if (!m || !m.map || !uv) return;
+    const pos = g.attributes.position, idx = g.index, e = o.matrixWorld.elements;
+    const rx = m.map.repeat.x, ry = m.map.repeat.y, faces = new Map();
+    for (let t = 0; t < (idx ? idx.count : pos.count) / 3; t++) {
+      const ix = [0,1,2].map(k => idx ? idx.getX(t*3+k) : t*3+k);
+      const p = ix.map(i => xf(e, pos.getX(i), pos.getY(i), pos.getZ(i)));
+      const e1 = sub(p[1],p[0]), e2 = sub(p[2],p[0]);
+      const nc = cross(e1,e2), area = len(nc)/2;
+      if (area < 1e-6) continue;
+      const nn = nc.map(v => v/(area*2));
+      const U = ix.map(i => uv.getX(i)*rx), V = ix.map(i => uv.getY(i)*ry);
+      const du1 = U[1]-U[0], dv1 = V[1]-V[0], du2 = U[2]-U[0], dv2 = V[2]-V[0];
+      const det = du1*dv2 - du2*dv1; if (Math.abs(det) < 1e-12) continue;
+      const a = len(comb(e1, dv2/det, e2, -dv1/det));
+      const b = len(comb(e2, du1/det, e1, -du2/det));
+      const k = nn.map(v => v.toFixed(1)).join(",");
+      const f = faces.get(k) || { area:0, u:0, v:0 };
+      f.area += area; f.u += a*area; f.v += b*area; faces.set(k, f);
+    }
+    for (const [k,f] of faces) {
+      if (f.area < MIN_M2) continue;
+      const mu = f.u/f.area, mv = f.v/f.area, asp = Math.max(mu/mv, mv/mu);
+      if (asp > 1.5) out.stretched.push({ mesh:o.name||o.type, face:k, aspect:+asp.toFixed(1),
+                                          m2:+f.area.toFixed(1), mPerTile:`${mu.toFixed(2)}x${mv.toFixed(2)}` });
+    }
+  });
+  out.stretched.sort((a,b) => b.m2 - a.m2);   // biggest surfaces first
+
+  // opaque depth-writing meshes that interpenetrate AND share a face plane
+  const solid = [];
+  S.traverse(o => {
+    const m = Array.isArray(o.material) ? o.material[0] : o.material;
+    if (!o.isMesh || o.isInstancedMesh || !m || m.transparent || m.depthWrite === false) return;
+    if (!o.geometry.boundingBox) o.geometry.computeBoundingBox();
+    const bb = o.geometry.boundingBox, e = o.matrixWorld.elements;
+    const lo = [Infinity,Infinity,Infinity], hi = [-Infinity,-Infinity,-Infinity];
+    for (const cx of [bb.min.x,bb.max.x]) for (const cy of [bb.min.y,bb.max.y]) for (const cz of [bb.min.z,bb.max.z]) {
+      const w = xf(e,cx,cy,cz);
+      for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i],w[i]); hi[i] = Math.max(hi[i],w[i]); }
+    }
+    solid.push({ o, lo, hi });
+  });
+  const E = 1e-4;
+  for (let i = 0; i < solid.length; i++) for (let j = i+1; j < solid.length; j++) {
+    const A = solid[i], B = solid[j];
+    if ([0,1,2].some(k => Math.min(A.hi[k],B.hi[k]) - Math.max(A.lo[k],B.lo[k]) <= E)) continue;
+    const shared = [];
+    for (const k of [0,1,2]) {
+      if (Math.abs(A.lo[k]-B.lo[k]) < E) shared.push("min."+"xyz"[k]+"="+A.lo[k].toFixed(2));
+      if (Math.abs(A.hi[k]-B.hi[k]) < E) shared.push("max."+"xyz"[k]+"="+A.hi[k].toFixed(2));
+    }
+    if (shared.length) out.zfight.push({ a:A.o.name||"mesh", b:B.o.name||"mesh", coplanar:shared });
+  }
+  return out;
+})()
+```
+
+Read it as: **`stretched` should be empty.** Every entry is a face over a square
+metre whose texels aren't square; `mPerTile` gives you the actual numbers, and
+`m2` tells you whether it's a kerb or a wall. `MIN_M2` is there because a
+generated GLB's authored UVs produce hundreds of tiny-triangle readings that
+drown the real finding — raise it if a model still floods the list, and note in
+the handoff that you did.
+
+**`zfight` should be empty.** Every entry is two solids that interpenetrate AND
+share a face plane, which will fight and flicker the moment the camera moves.
+
+Both are wiring defects, so fix the wiring: `worldUV` (`$genex-ai-texture`) for
+the first; for the second, stop the solids overlapping — butt the spans end to
+end rather than crossing them at the corners.
+
+Run against the shipped BomberDome build, this printed `aspect: 102, m2: 17,
+mPerTile: "0.17x17.00"` for the wall tops and four coplanar pairs at
+`max.y=2.40`. Both had been in front of the agent for an hour of screenshots.
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.