@genex-ai/cli-demo 0.52.0-dev.116 → 0.53.0-dev.118

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.116",
+  "version": "0.53.0-dev.118",
   "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-game-feel/SKILL.md

@@ -77,7 +77,11 @@ hits, layer two or three of:
   With the bundled physics pack this is built in — `physics.paused = true` /
   `physics.timeScale = 0.2` (see the physics skill's pause/slow-mo section) plus
   `anims.setPaused(true)` / `anims.setTimeScale(0.2)` for the character's
-  animations. Don't hand-roll a second clock.
+  animations. Don't hand-roll a second clock. **In multiplayer, hitstop is local
+  presentation feedback:** never pause the network pump, reconnect/quorum timers,
+  remote interpolation, or another player's/host's simulation. Slow/freeze only
+  your locally owned gameplay clock and visuals; the authoritative hit is still
+  deduped and applied once through the multiplayer skill's normal event path.
 
 One layer per small event, three for the biggest — uniform intensity flattens
 everything back out.
@@ -99,4 +103,6 @@ everything back out.
 - Restart requires reloading the page (kills the retry loop — and reloads
   re-run auth and asset loading).
 - Shake/flash spam with no cause — feedback inflation reads as noise.
+- Multiplayer hitstop pauses networking or host simulation, turning impact feedback
+  into packet bursts, quorum lag, or a freeze for players who were not hit.
 - Feel constants scattered through the code where nobody dares touch them.

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -29,20 +29,23 @@ whole reason this skill exists.
 Read [references/realtime-patterns.md](references/realtime-patterns.md) for the complete movement
 example, the shared-object/ball code, rotation, and host usage. Read
 [references/genre-recipes.md](references/genre-recipes.md) for ready-made per-genre setups
-(sports/ball, shooter, co-op with host-simulated enemies) — pick the one matching the game.
+(sports/ball, shooter, co-op with host-simulated enemies) — pick the one matching the game. Before
+calling multiplayer done, run the mandatory
+[netcode feel gate](references/genex-netcode-feel-checklist.md).
 
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.10.1
+npm i @genex-ai/multiplayer@^0.10.2
 ```
 
-> Pin `@^0.10.1` (not a bare `npm i`): live connected-player presence, supplier-form `connect()`
+> Pin `@^0.10.2` (not a bare `npm i`): unowned object writes now warn instead of failing silently;
+> live connected-player presence, supplier-form `connect()`
 > auth, regional relay selection (`getColyseusUrls()` + `urls`)
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.10.1** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.10.2** (`objects`/`host` since 0.4;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
 lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10).
@@ -56,18 +59,30 @@ ownership, match seating/adjudication, and rate/size caps — but a modified cli
 lie about its own position or score. Great for friends and casual lobbies; don't promise
 ranked-grade fairness.
 
-## Choose one net model first
+## Choose one net model from the player experience
 
-- **`connect()` — shared world:** everyone for this slug shares a room. Use for
-  persistent/co-op spaces where the game may remain valid with one player.
-  Pass auth as a FUNCTION so each explicit connect attempt reads fresh; after
-  a terminal disconnect the game starts a new connect flow.
-- **`matchmake()` — capped matches:** the queue seats players into separate
-  rooms. Use for duels, races, teams, and finite arenas. It requires
-  `genex.matchmaking` in `package.json`; auth is a FUNCTION; the handle may
-  replace `mm.session`, so the game polls and rebinds it.
+Infer this yourself when the experience is clear. Do **not** make the player choose an SDK API,
+preset, or config. Ask one plain-language question only when the design genuinely supports both
+models and the answer changes the experience — for example: *"Should this be one ongoing arena
+people drop into, or a fresh fair match that waits for everyone and then starts together?"*
 
-Do not combine the requirements or silently convert one model into the other.
+| Player experience | Model | Why |
+| --- | --- | --- |
+| One ongoing drop-in world; late joiners enter what is already happening; solo play remains valid | `connect()` | One shared room, no queue or round formation |
+| Fresh bounded match/mission; quorum, fair start, capacity, teams, or parallel sessions matter | `matchmake()` | Server forms capped rooms and exposes queue/waiting state |
+
+Genre names do not decide this. A sumo game may be an always-online drop-in ring (`connect()`) or a
+fair-start bout (`matchmake()`). A co-op game may be an ongoing shared space (`connect()`) or a
+bounded dungeon run (`matchmake()`). Write one plan line before coding:
+
+> Net model: `<connect|matchmake>` — `<player-experience reason>`; start/quorum: `<rule>`;
+> late join/backfill: `<rule>`; below-quorum/end tail: `<rule>`.
+
+Use `connect()` when the game is honestly one always-online world. Use `matchmake()` when it promises
+a match, run, race, mission, teams, a waiting count, or a synchronized start. If the brief says
+"100 players in the same world," or mixes a shared hub with instanced matches, do not guess: surface
+the platform/capacity mismatch or ask which experience matters. Do not combine the requirements or
+silently convert one model into the other.
 
 ## Matchmaking (competitive presets — server-owned)
 
@@ -372,6 +387,25 @@ const lobby = await joinPrivate<MyState>(code, { urls, room: slug, auth: () => g
 Pick your own per-player state shape (any JSON). `room` is the **project slug**
 (printed by `genex init`) — same id = same room, different ids are fully isolated.
 
+### WHEN to call `connect()` — make the screen tell the truth (MANDATORY)
+
+`connect()` immediately joins the shared world and makes the player present. Two lifecycles are
+valid; pick exactly one:
+
+- **Always-online world:** there is no Play/Online commitment screen. After identity is ready,
+  connect and spawn immediately. This is correct for a drop-in social space or an ongoing sumo ring
+  where loading the game already means joining it. A lightweight loading/reconnecting overlay is
+  honest; a Play button that appears to delay entry is not.
+- **Menu before online:** if the game shows **Play**, **Play Online**, **Join Arena**, or offers
+  Local/Bots, that click is the commitment point. Boot the menu/offline world with no relay contact,
+  call `connect()` only inside the online handler, and spawn the network player only after it
+  resolves. Local/Bots never connect. Leaving online calls `room.leave()`, disables terminal rejoin,
+  removes the online avatar, and returns to the pre-online state.
+
+Never auto-connect/spawn behind a title menu and then ask the player to press Play. The API is not
+the bug in that case; the lifecycle is. Likewise, do not add a fake queue/finding screen to an
+always-online `connect()` world — it has no match formation to report.
+
 **Joining requires the SDK's player identity — the relay rejects tokenless
 joins, but accepts guests** (accountless players named like `Guest-1234`).
 Load the `genex-threejs-embed-auth` skill first (it sets up `initEmbed(...)`),
@@ -587,6 +621,19 @@ is the newest value with no smoothing. **Draw** from `state`; **test** against `
 detection, "am I close enough to kick", pickups, and any discrete number (hp, ammo, animation id,
 a 0/1 flag) that must not arrive fractional. This holds for both players and objects.
 
+**HARD RULE — `state` is for RENDER ONLY.** Every GAMEPLAY read — hit tests, deflection/catch/
+return windows, physics seeding after adoption, distance and reach checks — uses `stateRaw`.
+The smoothed view is ~100–150 ms in the past; at projectile or ball speeds the REAL object has
+already passed where the ghost still is. Two field-verified failures caused by breaking this rule:
+- A pong-style game read the incoming ball via `state` for its deflection window — at top speed
+  the real ball crossed the paddle plane before the smoothed one arrived; returns were literally
+  impossible online while feeling fine in solo testing.
+- A dodgeball game aimed at opponents drawn from `state` — a strafing target's real position was
+  already elsewhere, so "direct hits" never registered damage.
+Corollary: **cap top speeds against the network, not just the physics** — an object's arena/table
+crossing time should stay above ~2× the smoothing delay (~0.25 s), or receivers are reacting to
+history no matter how correct the code is.
+
 ## Shared objects (the ball, the NPC) — use `objects`, never `shared`
 
 A ball belongs to no player. Put it on `objects`: exactly one client owns it at a time (the SDK +
@@ -611,6 +658,67 @@ contact remains valid. Keep object state flat. For Rapier pushables, install the
 with `genex controller networked-physics`; see
 [references/host-physics.md](references/host-physics.md).
 
+**OWNERSHIP INVARIANT — a host-simulated object MUST be claimed before it publishes.**
+`objects.set()` / `objects.snap()` on an object you do not own are ignored; SDK ≥0.10.2 warns once
+per object/operation instead of failing silently.
+The field-verified symptom is unmistakable — *the object moves on the host's screen and sits
+frozen at spawn for everyone else* (each client falls back to whatever local body it has; only
+the host's is simulated). If the host simulates an object (a crate, an NPC, a puck), it must:
+
+```ts
+let hostReady: Promise<boolean> | null = null;
+function ensureHostObjects(room: Session<S>) {
+  if (!room.isHost) return Promise.resolve(false);
+  if (hostReady) return hostReady;                    // one adoption flight, never per tick
+  hostReady = (async () => {
+    for (const id of HOST_OBJECT_IDS) {
+      const before = room.objects.get(id)?.stateRaw;  // last published truth, before claiming
+      const res = await room.objects.claimConfirmed(id, { authority: "host" });
+      if (!res.accepted) return false;
+      seedPhysicsFromRaw(id, before);                 // pose + velocity/cooldowns, never zero
+    }
+    return true;
+  })();
+  return hostReady;
+}
+
+room.on("host", () => { hostReady = null; void ensureHostObjects(room); });
+room.onHostTick(30, async () => {
+  if (!(await ensureHostObjects(room))) return;       // no step/publish before adoption
+  stepAndPublishHostPhysics();
+});
+```
+
+Do not assume `onHostTick` firing means you own anything — host *election* and object
+*ownership* are separate systems. Claim explicitly, check `accepted`, re-claim on migration, and
+do not step or publish until the whole host-owned set is ready.
+
+**RENDER SPLIT — the host draws its own authority, only NON-hosts read the wire.** Once the
+host owns the object and publishes, `objects.get(id).state` becomes defined on EVERY client
+including the host — and if the host now renders from that networked `state` instead of its
+own sim body, a subtle trap bites: a freshly-claimed object's smoothed `state` can briefly be
+a DEGENERATE transform (a zero/NaN quaternion, or a position mid-interpolation from origin),
+which renders the mesh to NaN and it vanishes ON EVERY SCREEN. Field-verified: enabling the
+claim above without this split made a crate invisible for everyone. The fix:
+
+```ts
+// Host renders its own authoritative sim; non-hosts render the published truth, GUARDED.
+const cs = room.isHost ? null : room.objects.get(id)?.state;
+const ok = cs && Number.isFinite(cs.x) && Number.isFinite(cs.y) && Number.isFinite(cs.z);
+if (ok) {
+  mesh.position.set(cs.x, cs.y, cs.z);
+  if (Array.isArray(cs.q) && cs.q.length === 4) {         // normalize — a bad sample must not vanish the mesh
+    const n = Math.hypot(cs.q[0], cs.q[1], cs.q[2], cs.q[3]);
+    if (n > 1e-3) mesh.quaternion.set(cs.q[0]/n, cs.q[1]/n, cs.q[2]/n, cs.q[3]/n);
+  }
+} else {
+  mesh.position.copy(localBodyPos); // host, offline, or non-host awaiting first valid sample
+}
+```
+Prefer syncing the MINIMAL transform a slide/roll needs (a puck on a plane is `{x,z}` + a
+constant y — no quaternion at all); every field you don't send is a field that can't arrive
+degenerate. The netcode-park reference does exactly this.
+
 ## Host authority (scores, rounds, enemies)
 
 One client is the `host`. Let *only* the host write agreed state and simulate shared enemies, so
@@ -776,11 +884,16 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.10.1` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.10.2` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks, unowned-write warnings); config wired into the build.
+- [ ] The plan names one net model, the player-experience reason, start/quorum, late-join/backfill,
+      and below-quorum/end behavior. The agent inferred it unless the experience was genuinely ambiguous.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] `connect()` terminal `disconnect` starts a guarded backoff rejoin that reruns
       `waitForPlayer()` and reads fresh auth on every attempt; deliberate leave stops it;
       replacement code `4409` NEVER auto-rejoins.
+- [ ] `connect()` lifecycle is honest: an always-online world has no fake Play screen and may
+      connect/spawn after identity; if a Play/Online/Local/Bots menu exists, connect and spawn happen
+      only after the online click, Local/Bots stay offline, and leaving calls `room.leave()`.
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.
 - [ ] Irreversible actions wait for `claimConfirmed`; held contact retries after `retryAfterMs` while still valid.
@@ -830,6 +943,8 @@ host-driven saving works as long as ANY account is in the room.
       per-client, never `mm.matchmaking.teams`, never a default for the unassigned — and you
       WATCHED two browsers land on OPPOSITE teams.
 - [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
+- [ ] Passed the [netcode feel gate](references/genex-netcode-feel-checklist.md), including the two-
+      identity real-input proof for the chosen model.
 
 ## Troubleshooting auth
 

package/templates/skills/genex-threejs-multiplayer/references/genex-netcode-feel-checklist.md

@@ -0,0 +1,61 @@
+# Genex multiplayer netcode feel gate
+
+Run this gate before calling any multiplayer loop playable. A build, screenshot, or one local client
+does not prove networking. Keep the check proportional: one focused two-client pass, not a new test
+suite for the game.
+
+## Before coding
+
+- Write the net-model line: `connect` or `matchmake`, the player-experience reason, start/quorum,
+  late-join/backfill, and below-quorum/end behavior.
+- Infer the model from the experience. Ask the user only if both an ongoing drop-in world and fresh
+  bounded sessions are plausible and the brief does not choose between them.
+- State authority per thing: local player, remote player, shared object, score/round, projectile/hit,
+  and host-simulated entity.
+- Budget the fastest interaction. Rendered remote state is delayed for smoothness; gameplay tests use
+  `stateRaw`, sweep between raw samples, and cap speeds so reaction windows remain humanly possible.
+
+## Lifecycle
+
+- `connect` always-online world: no fake Play/finding screen; identity may be followed by immediate
+  join/spawn. Leaving is explicit and stops terminal rejoin.
+- `connect` behind Play/Online/Local/Bots: no relay contact or network spawn before the online click;
+  Local/Bots stay offline; leaving online calls `room.leave()`.
+- `matchmake`: create the handle only on Play/Find Match; show searching/waiting only after that
+  commitment; leaving calls `mm.cancel()`; bind every replacement `mm.session`.
+- Quorum-required games leave `playing` when connected quorum falls below the declared minimum.
+  Ongoing shared worlds may continue solo only when that was the stated design.
+
+## Authority and interaction
+
+- Self movement and immediate reversible feedback happen locally on the input frame.
+- Remote players and non-owned objects render `state` directly, with no second interpolator.
+- Every gameplay read uses `stateRaw`: hit, return/deflect/catch, reach, pickup, goal, physics adoption,
+  hp/ammo/flags, and target selection.
+- Fast bodies/projectiles use a segment or swept-volume test from previous raw position to current raw
+  position; point samples are not enough.
+- Irreversible shared results wait for confirmed authority. `objects.set`/`snap` happen only after an
+  accepted claim; host simulation waits for single-flight adoption and seeds from last raw truth.
+- Every travel-time PvP projectile has attacker-side raw detection plus victim-side/self detection
+  where appropriate, both feeding one projectile-id-deduped hit application.
+- Hitstop never pauses the networking pump or another player's simulation. Freeze/slow the local
+  presentation and locally owned gameplay clock only; keep sends, receives, reconnects, and quorum
+  checks running.
+
+## One focused proof with two distinct identities
+
+Use regular + incognito guest identities, two accounts/devices, or ask the user to perform the exact
+sequence. Two tabs sharing one identity are one enforced seat.
+
+1. Enter online using real clicks. Then press Space/Enter/the main action using real key input; confirm
+   focus did not re-trigger Play/Leave and both sessions remain live.
+2. Confirm reciprocal presence and movement: A sees B move and B sees A move.
+3. Exercise the signature interaction at full intended speed: kick/return, projectile hit, shared
+   object claim, enemy hit, or vehicle seat. Confirm immediate local feedback and exactly one result.
+4. Exercise one authority transition: object ownership, seat, or host migration. Confirm no freeze,
+   teleport-to-origin, duplicate point/damage, or host-only visual divergence.
+5. For `matchmake`, drop one player, observe quorum/waiting behavior, then join a new identity and
+   confirm re-seat/backfill. For `connect`, verify the declared leave/solo/host-migration behavior.
+
+If this proof was not possible, say exactly which items remain unverified. Never substitute a
+screenshot or local-test mode for multiplayer evidence.

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -34,9 +34,18 @@ The genre where a single contested object is the whole game.
   everyone else) and writes the score to `shared`; everyone reads `shared.get("score_a")` in the HUD.
 - **A player quitting mid-match doesn't kill the ball** — if the owner leaves, the ball is
   reassigned to the host automatically and play continues.
+- **The receiver's interaction window reads `stateRaw`, never `state`** — return/deflect/catch
+  checks against the smoothed ball test a ghost ~120 ms in the past; at rally speeds the REAL
+  ball has already crossed your paddle/goal line before the ghost arrives (field-verified: it
+  made a pong-style game unreturnable online while feeling perfect in solo play). Render the
+  smoothed ball, but run the window on the raw one, sweeping raw-sample→raw-sample.
+- **Cap top ball speed against the network:** keep the arena/table crossing time above ~2× the
+  smoothing delay (≳0.25 s). Faster than that, no human can respond to what they're shown —
+  no amount of correct code fixes reacting to history.
 
 **Acceptance feel:** the kicker sees the ball respond the same frame; everyone else sees it glide;
-a contested kick settles on one owner within a snapshot; the owner leaving doesn't freeze the ball.
+a contested kick settles on one owner within a snapshot; the owner leaving doesn't freeze the ball;
+a full-speed shot is still humanly returnable by the receiving player.
 
 ---
 
@@ -94,6 +103,25 @@ slow physical projectiles, all against the same damage/defeat rules.)
 scores exactly one point even if the host changes mid-fight; the scoreboard survives a reload; one
 player on a throttled/backgrounded tab doesn't drag others.
 
+### Every travel-time projectile vs moving targets — the "visual hit, no damage" trap
+
+Any projectile that spends time moving through the world — object-owned, host-simulated, or
+deterministically replayed from a throw event (fireball, rocket, dodgeball) — inherits BOTH classic
+netcode failures, and the symptom is always the same: *the projectile visibly hits a strafing player
+and nothing happens.* Do not limit these rules to one implementation style:
+
+1. **Detection must run on the ATTACKER too, against `stateRaw`.** Target-only self-detection
+   ("each player owns their own hp, so only I test hits on me") silently fails against movers:
+   the thrower aimed at the smoothed ghost (~120 ms old), the deterministic projectile flies to
+   where the target WAS, and the target's self-test against its own REAL position never fires.
+   Run the attacker-side test each frame vs every remote's `stateRaw`, then send the damage
+   event the victim always honors (dedupe by projectile id so self-detection can coexist).
+2. **Sweep, never point-sample.** A projectile at 20 m/s moves ~0.33 m per 60 Hz frame — more
+   than most hit radii. Track `prev` each frame and test segment(prev→pos) vs the target
+   sphere, on both the attacker's and the target's tests.
+3. Both channels apply damage through ONE deduped `applyHit(projectileId)` on the victim, so a
+   ball registered by both sides still counts once.
+
 ---
 
 ## Recipe 3 — Co-op vs enemies (horde, tower defense, dungeon)
@@ -178,17 +206,22 @@ the short-handed side.
 
 Almost every game opens on a menu: **Play Online**, **Local / Single-player**, **Bots**. The rule
 that keeps online matches clean: **the menu is pre-multiplayer — there is no room, no queue, no
-server contact until the player commits to online.** `matchmake()` IS the "Play Online" button. Call
-it anywhere earlier (page load, boot code, beside `waitForPlayer()`) and a player who picks Bots is
-still parked in an online room, counting toward `minPlayers` while three real players wait for a
-fourth who never comes.
+server contact until the player commits to online.** The chosen online API — `matchmake()` for fresh
+bounded sessions, `connect()` for one ongoing shared world — IS the "Play Online" button. Call either
+one earlier (page load, boot code, beside `waitForPlayer()`) and a player who picks Bots is already
+present online. With matchmaking they contaminate quorum; with a shared world they spawn an avatar
+for someone who never chose to enter it.
+
+Exception: a truly always-online game may call `connect()` after identity and spawn immediately,
+but then loading the game already means "join" — it has no Local/Bots choice and no fake Play screen.
+An ongoing drop-in sumo ring can use that shape; a sumo title menu cannot auto-spawn behind Play.
 
 | Moment | What runs | Relay contact |
 | --- | --- | --- |
 | Page load → menu | An **offline world** generated locally, menu overlay on top | NONE. Not `connect()`, not `matchmake()`. `waitForPlayer()` may run (mints identity only, seats nobody). |
 | "Bots" / "Local" | The same offline world + local AI / single-player | NONE, ever. |
-| "Play Online" | `matchmake()` → queue → the server seats you | FIRST contact. Only now are you a counted participant. |
-| Leaving online (back to menu / quit / switch to Bots after being seated) | Tear down the online view, return to the offline menu | `mm.cancel()` — frees the seat so you stop counting toward `minPlayers`. |
+| "Play Online" | `matchmake()` → queue/seat, or `connect()` → ongoing shared world | FIRST contact. Only now are you an online participant. |
+| Leaving online (back to menu / quit / switch to Bots after joining) | Tear down the online view, return to the offline menu | `mm.cancel()` for matchmaking; intentional `room.leave()` for connect. |
 
 **Decisions:**
 - **Every menu action blurs its button before acting.** Otherwise the first gameplay Space/Enter
@@ -196,6 +229,9 @@ fourth who never comes.
   menu/lobby phases (see the game-ui skill).
 - **`matchmake()` is created lazily, on the click — not held from boot.** Keep the handle in a
   variable so you can `cancel()` it; create it inside the "Play Online" handler, not at module load.
+- **`connect()` follows the same commitment rule when this menu exists.** Create the session and
+  network avatar inside the online handler; intentional leave disables the rejoin loop, calls
+  `room.leave()`, removes the online avatar, and returns to the offline world.
 - **Bots/Local touch nothing networked.** They run the exact offline world the menu already booted.
   A player can sit in Bots forever and the online queue never knows they exist — which is the point.
 - **The waiting screen is an online-only, post-commit overlay.** Show it only when

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -181,17 +181,27 @@ room.inputs.on((fromId, payload) => {
   if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
 });
 
-room.onHostTick(30, async (dtMs) => {
-  // 1) First tick after election: adopt the objects + seed the physics world from the
-  //    last published truth (stateRaw) — NEVER from zero, or the world teleports.
-  for (const id of CONTESTED_IDS) {
-    const view = room.objects.get(id);
-    if (!view?.isMine) {
+let hostReady: Promise<boolean> | null = null;
+function ensureHostReady() {
+  if (!room.isHost) return Promise.resolve(false);
+  if (hostReady) return hostReady; // single flight: async host ticks never overlap adoption
+  hostReady = (async () => {
+    for (const id of CONTESTED_IDS) {
+      const raw = room.objects.get(id)?.stateRaw; // capture BEFORE claim changes local ownership view
       const result = await room.objects.claimConfirmed(id, { authority: "host" });
-      if (!result.accepted) continue;
-      seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
+      if (!result.accepted) return false;
+      seedRapierBody(id, raw); // position/rotation/velocity from the wire, NEVER zero
     }
-  }
+    pending.length = 0; // discard intent queued for the previous host/timeline
+    return true;
+  })();
+  return hostReady;
+}
+room.on("host", () => { hostReady = null; void ensureHostReady(); });
+
+room.onHostTick(30, async (dtMs) => {
+  // 1) No physics or publishing until the whole host-owned set is adopted and seeded.
+  if (!(await ensureHostReady())) return;
   // 2) Apply everyone's inputs to the ONE authoritative Rapier world.
   for (const { obj, push } of pending.splice(0)) applyImpulse(obj, push);
   // 3) Step and publish (flat state: numbers + one [x,y,z,w] quaternion).
@@ -206,10 +216,13 @@ room.onHostTick(30, async (dtMs) => {
 });
 const r2 = (v: number) => Math.round(v * 100) / 100; // quantize — floats are JSON bloat
 
-// ---- rendering: identical on every client, host included ----
+// ---- rendering: host draws its live simulation; followers draw the guarded smooth stream ----
 for (const id of CONTESTED_IDS) {
+  if (room.isHost) { drawFromBody(meshOf(id), bodyOf(id)); continue; }
   const view = room.objects.get(id);
-  if (view) meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
+  if (view && Number.isFinite(view.state.x) && Number.isFinite(view.state.y) && Number.isFinite(view.state.z)) {
+    meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
+  }
 }
 ```
 
@@ -218,6 +231,8 @@ Rules that make it correct:
 - `onHostTick` pauses during reconnect and stops on demotion/leave/terminal disconnect. Bound the input
   queue, attribute input from the callback's authenticated `fromId` (never payload `from`), and discard
   stale pre-failover inputs when a new host adopts raw state.
+- Host election and object ownership are separate. Adoption is one async flight per host term; never
+  issue claims every tick, and never step/publish until every required claim was accepted.
 
 - **Sim internals that must survive migration** (velocities, cooldowns, aggro) either live in
   the published object state or get mirrored at low rate into a dedicated object

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/SKILL.md

@@ -90,12 +90,16 @@ execution order.
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
 remote players **and shared objects**, and gives you server-enforced object ownership (a ball) and
-a room `host` (scores, enemies). Choose the net model before coding: `connect()` is one shared-world
-room; `matchmake()` creates capped queued rooms. Only `matchmake()` requires a server-owned
-`genex.matchmaking` block in `package.json`, reported by preview/publish. Both models accept a fresh
-auth supplier, but their terminal-recovery duties differ, so follow the chosen model's section rather than
-mixing the two. The skill also covers the rules that keep it smooth and its per-genre recipes
-(sports/ball, shooter, co-op).
+a room `host` (scores, enemies). Choose the net model from the player experience before coding:
+`connect()` is one ongoing drop-in world; `matchmake()` forms capped rooms for fresh matches or
+missions with quorum/fair-start/backfill rules. Infer it when clear; ask one plain-language
+ongoing-world-vs-fresh-session question only when both experiences genuinely fit. A Play/Online
+button is always the commitment point for either API; only a truly always-online `connect()` world
+may join/spawn immediately, and then it must not show a fake Play screen. Only `matchmake()` requires
+a server-owned `genex.matchmaking` block in `package.json`, reported by preview/publish. Both models
+accept a fresh auth supplier, but their terminal-recovery duties differ, so follow the chosen model's
+section rather than mixing the two. Run that skill's netcode feel gate before handoff. The skill also
+covers the rules that keep it smooth and its per-genre recipes (sports/ball, shooter, co-op).
 
 ## Real (AI-generated) assets — `npx genex` commands
 

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
@@ -223,4 +243,11 @@ claim-on-touch + a Rapier proxy — the soft handoff glides the ownership change
 **simultaneous** contest (two players pushing one crate against each other — sumo, tug-of-war)
 uses the host-authoritative pattern (`inputs` + `onHostTick`). Both are in that skill's
 host-physics reference.
+Choose the net model from player experience: one ongoing drop-in world uses `connect()`; a fresh
+bounded match/mission with quorum, fair start, teams, backfill, or parallel sessions uses
+`matchmake()`. Infer this when the brief is clear. Ask one experience-level question only when both
+are genuinely plausible — never ask the user to select an SDK API or preset. For either model, a
+Play/Online button is the first relay contact; immediate `connect()` + spawn is valid only when
+loading the game already means joining the always-online world and there is no fake Play screen.
+Before handoff, run the multiplayer skill's netcode feel gate with two distinct identities.
 Use only the APIs that skill documents — do not invent transport methods.

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.