@genex-ai/cli-demo 0.57.0-dev.129 → 0.59.0-dev.133

package/package.json

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

package/templates/controllers/character/character-animations.ts

@@ -351,6 +351,7 @@ export class CharacterAnimations {
   // Every provided clip by name — lets playOneShot reach clips beyond the 9
   // locomotion states (any installed pack clip: Punch_*, Sword_*, Sitting_*…).
   #clipsByName = new Map<string, THREE.AnimationClip>();
+  #missingOneShotWarnings = new Set<string>();
   #oneShotAction: THREE.AnimationAction | null = null;
   #locomotionOneShotAction: THREE.AnimationAction | null = null;
   #oneShotOnDone: (() => void) | undefined;
@@ -615,7 +616,13 @@ export class CharacterAnimations {
   playOneShot(clipName: string, options: PlayOneShotOptions = {}): boolean {
     if (this.#disposed) return false;
     const clip = this.#clipsByName.get(clipName);
-    if (!clip) return false;
+    if (!clip) {
+      if (!this.#missingOneShotWarnings.has(clipName)) {
+        this.#missingOneShotWarnings.add(clipName);
+        console.warn(`[character-animations] one-shot clip "${clipName}" is not installed; playOneShot() returned false.`);
+      }
+      return false;
+    }
 
     const action = this.mixer.clipAction(clip);
 

package/templates/controllers/character/meshy/meshy-loader.ts

@@ -139,7 +139,7 @@ export function resolveMeshyLocomotion(
 }
 
 export async function loadMeshyCharacter(manifestUrl: string): Promise<MeshyCharacter> {
-  const response = await fetch(manifestUrl);
+  const response = await fetch(manifestUrl, { cache: "no-store" });
   if (!response.ok) throw new Error(`[meshy-character] ${manifestUrl} returned HTTP ${response.status}`);
   const manifest = validateManifest(await response.json());
   const loader = new GLTFLoader();

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

@@ -17,7 +17,9 @@ npx genex character "stylized desert courier, practical layered clothing"
 ```
 
 The default request uses Meshy 6 to generate and texture an A-pose humanoid,
-remeshes and rigs it, adds the preview-reviewed neutral-v2
+validates the rig's arm pose, and retries the full generation once in a strict
+T-pose before requesting controller-pack animations when the A-pose is invalid.
+It remeshes and rigs the accepted model, adds the preview-reviewed neutral-v2
 idle/walk/run/crouch/jump controller pack,
 and stores every successful model
 and clip at permanent Genex asset URLs. It prints the complete Genex-credit
@@ -75,6 +77,12 @@ animation job completes, rerun `genex controller character --character <id>`
 to refresh `public/assets/meshy-character.json`; existing controller source is
 preserved unless `--force` is explicitly used.
 
+Meshy manifests bypass browser cache, so newly installed actions must work
+after preview without asking the player to disable cache.
+
+`playOneShot()` returns false and emits one warning when a requested clip is
+absent; treat that as an installation failure, not a successful action.
+
 Load `$genex-threejs-character-controller` for the actual wiring. The install
 command copies the shared controller plus `character/meshy/meshy-loader.ts`.
 The manifest points at the current rigged model and compact animation-only GLBs

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -45,6 +45,11 @@ dynamic controller stays authoritative for collision, grounding, facing, and
 world translation. The animation layer poses the visual rig; it never
 translates the visual root.
 
+Meshy manifests bypass browser cache, so newly installed actions must work
+after preview without asking the player to disable cache. `playOneShot()`
+returns false and emits one warning when a requested clip is absent; treat
+that as an installation failure, not a successful action.
+
 Because these files are game-owned, never run `genex controller character --force` over an edited
 fork as a migration strategy. Install a fresh copy elsewhere and port only the named changes.
 

package/templates/skills/genex-threejs-exposure-color-grading/SKILL.md

@@ -22,6 +22,59 @@ Read [references/exposure-grading.md](references/exposure-grading.md)
 for the exact 64x36 meter, encoded readback, adaptation constants, 32-cube LUT,
 and signal-ownership ambiguities.
 
+## Film grain — add it only if the look calls for it, and author it correctly
+
+Film grain is a legitimate look. **Badly-authored grain is the single most common
+post defect** — it reads as a cheap noise sheet laid over the frame, not as
+emulsion, and an owner will call it "some texture rippling over everything." The
+exact shape that ships when an agent hand-rolls it:
+
+```glsl
+// ✗ DO NOT. This is what "very bad grain" looks like in code.
+float g = hash(vUv * 900.0 + fract(uTime) * 133.0) - 0.5;  // measured live in a real game
+c += g * 0.045;
+```
+
+Four independent defects in that one line, each visible:
+
+1. **`fract(uTime)` re-seeds every frame → it SHIMMERS.** Measured on the shipped
+   game: 64.5% of the pixels on a *static* floor change frame-to-frame from grain
+   alone (0% with grain off). This is the loudest defect and the easiest to fix:
+   grain is **static** unless you deliberately want a slow film cadence.
+2. **`vUv * 900` is blocky and stretched.** vUv is 0..1, so ×900 makes ~900 cells
+   across the frame — on a 1600×900 window at DPR 2 that's ~3.5×2 px **non-square**
+   blocks, not fine grain. Seed on **device pixels** (`gl_FragCoord.xy`), which is
+   1 cell per pixel and aspect-correct for free.
+3. **Flat additive → it dirties the blacks and blows the highlights.** Real grain
+   lives in the **mids**. Weight it by luminance so shadows and speculars stay clean.
+4. **`hash()` = `fract(sin(dot()))` has visible blotch structure** — wormy
+   low-frequency clumps, not grain. Use interleaved-gradient noise (below) or,
+   best, sample a tiling **blue-noise texture** at screen resolution.
+
+The corrected pass — copy this instead of inventing one:
+
+```glsl
+// Interleaved-gradient noise: cheap, well-distributed, no sin() blotches.
+float ign(vec2 p) {
+  return fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715))));
+}
+
+// ...at the end of the grade, before the output conversion:
+float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+float lw   = 1.0 - abs(2.0 * luma - 1.0);   // peaks at mid-grey, 0 at black & white
+float g    = ign(gl_FragCoord.xy) - 0.5;    // one sample PER DEVICE PIXEL — fine, aspect-correct
+c += g * uGrain * lw;                        // uGrain ~0.02–0.03, NOT 0.045
+```
+
+- **Static by default** (no `uTime`). If the look truly wants moving grain, reseed
+  at a film cadence, not per frame: `ign(gl_FragCoord.xy + floor(uTime * 12.0))` —
+  12 Hz, not 60. Per-frame reseed is the shimmer.
+- **A blue-noise texture beats the hash.** `ign` is the no-asset fallback; a
+  32–64 px tiling blue-noise PNG sampled at `gl_FragCoord.xy / texSize` gives the
+  cleanest grain and is what to reach for if you can generate one.
+- **See it in the running game**, and specifically look for shimmer while nothing
+  moves (`$genex-threejs-visual-validation` has the two-frozen-frame check).
+
 ## Failure conditions
 
 - tone mapping occurs in both materials and post;
@@ -30,7 +83,9 @@ and signal-ownership ambiguities.
 - adaptation speed is the same toward light and dark;
 - LUT input/output spaces are undocumented;
 - sRGB encoding happens twice;
-- a display-domain LUT is moved before tone mapping without being rebuilt.
+- a display-domain LUT is moved before tone mapping without being rebuilt;
+- grain is re-seeded per frame (it shimmers), tiled in UV space (it blocks), or
+  applied flat instead of luminance-weighted (it dirties the blacks).
 
 ## Routing boundary
 

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -353,7 +353,11 @@ Order the HUD by what the player loses the game for ignoring:
 - **One cohesion layer.** A single full-screen vignette div (a subtle radial
   gradient darkening the corners, optionally faint grain) over canvas + UI is
   the cheapest way to make DOM-over-WebGL read as one composed image instead
-  of a web page floating over a game. Keep it `pointer-events: none`.
+  of a web page floating over a game. Keep it `pointer-events: none`. If you add
+  grain here, it's a **static** fine-noise tile (a small data-URI at 1:1, not a
+  stretched image); grain that belongs to the rendered LOOK goes in the WebGL
+  grade instead — see `$genex-threejs-exposure-color-grading` for why per-frame
+  `vUv` grain shimmers.
 - **Desktop first.** Verify at desktop sizes and survive window resizes
   without clipping; don't design phone layouts or test mobile viewports unless
   the user asks. Exception: touch *input* is wired by default when a recipe

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

@@ -36,19 +36,21 @@ calling multiplayer done, run the mandatory
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.10.2
+npm i @genex-ai/multiplayer@^0.11.0
 ```
 
-> Pin `@^0.10.2` (not a bare `npm i`): unowned object writes now warn instead of failing silently;
+> Pin `@^0.11.0` (not a bare `npm i`): cross-region invites can select the inviter's exact
+> relay with the optional `url` override; unowned object writes 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.2** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.11.0** (`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).
+lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10;
+exact-relay `url` overrides for cross-region invites since 0.11).
 
 ## Trust model (say it plainly in your game's copy)
 
@@ -884,7 +886,7 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `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.
+- [ ] `npm i @genex-ai/multiplayer@^0.11.0` (connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks, unowned-write warnings, cross-region exact-relay overrides); 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).

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

@@ -54,7 +54,12 @@ Three.js release or branch, and do not blindly copy demo architecture.
      target: match the concept's richness, don't stop at one token pass. "No
      post at all" is the stock default, not a plan, and "it's only a draft" is
      not a lower floor. When 2+ effects compose, `$genex-threejs-image-pipeline`
-     owns the pass ordering;
+     owns the pass ordering. **If the stack includes film grain, author it from
+     `$genex-threejs-exposure-color-grading`'s grain recipe — static, seeded on
+     device pixels, luminance-weighted. A hand-rolled per-frame `vUv` hash
+     shimmers across the whole screen and reads as a cheap noise sheet; it is the
+     most common post defect in shipped games, and "add grain" without that
+     recipe is how it happens;**
    - **references**: name 2–3 AAA games whose look this game borrows
      (conventions, lighting mood, palette, post — never trade dress); the
      same 2–3 the UI gate named, extended from the interface to the scene,

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

@@ -47,8 +47,13 @@ everything twice.
    fires. For an animated character, capture idle, walk, run, crouch-idle,
    crouch-move, and jump. Inspect shoulders, elbows, wrists, and hands as well
    as the feet: a fully bound non-T-pose can still be stylistically broken.
+   Reject shrugging palms-up poses, permanently raised elbows, or a gait whose
+   upper-body style contradicts the requested character. “No T-pose” is not
+   an animation-quality check.
    For Meshy characters, crouch passes only when the capsule behavior and a
-   visibly crouched pose both respond.
+   visibly crouched pose both respond. If a control calls `playOneShot()`, a
+   false result or missing-clip warning is an installation failure even when
+   locomotion continues normally.
 3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
    gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
    NOT gameplay evidence. Evidence captured in local test mode must be labeled
@@ -70,18 +75,23 @@ 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
+7. **Ask the scene the three 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
+### The screenshot has three 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:
+A capture of the whole arena is taken from one camera at one distance. Three real
+defect classes are invisible in it and all 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.
+- **Post-grade grain that shimmers.** A still frame cannot show a temporal
+  effect. Animated film grain — a noise term re-seeded by time every frame —
+  ripples across the entire screen in motion and reads as a cheap noise sheet
+  laid over the game; a screenshot looks fine. It shipped this way in a real game
+  (64.5% of a static floor's pixels changed frame-to-frame from grain alone).
 - **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.
@@ -182,6 +192,37 @@ 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.
 
+**Grain shimmer — inspect the mechanism, not the pixels.** A pixel diff is
+confounded by the scene's own ambient motion; the deterministic check is to read
+the post stack. Expose the composer in dev alongside the scene
+(`if (import.meta.env.DEV) (window as any).__composer = composer`), then:
+
+```js
+(() => {
+  const passes = (window.__composer && window.__composer.passes) || [];
+  const suspect = [];
+  for (const p of passes) {
+    const fs = p.material && p.material.fragmentShader;
+    if (!fs) continue;
+    const names = Object.keys(p.material.uniforms || {});
+    // a grain/noise term, by shader text OR a uGrain-style uniform
+    const hasGrain = /grain|\bnoise\b|fract\s*\(\s*sin|\bhash\s*\(|\bign\s*\(/i.test(fs)
+      || names.some(u => /grain|noise/i.test(u));
+    // a time-ish uniform actually referenced in the fragment shader
+    const timeU = names.find(u => /time|frame|seed|tick/i.test(u) && new RegExp('\\b' + u + '\\b').test(fs));
+    if (hasGrain && timeU) suspect.push({ pass: p.constructor.name, timeUniform: timeU });
+  }
+  return suspect; // ideally empty
+})()
+```
+
+A non-empty result means the grade has grain AND a per-frame time uniform — very
+likely the grain is re-seeded every frame and shimmers. Confirm which the time
+term drives; if it's the grain, make it **static** (drop the time term) or reseed
+at ≤12 Hz, seeded on `gl_FragCoord.xy` and luminance-weighted —
+`$genex-threejs-exposure-color-grading` has the recipe. This is the exact defect
+an owner described as "some texture rippling over the whole screen."
+
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.