@genex-ai/cli-demo 0.36.0 → 0.38.0

package/templates/controllers/character/vrm/foot-ik.ts

@@ -68,6 +68,16 @@ export interface FootIKOptions {
    * so airborne legs keep their jump pose). Default: always active.
    */
   isActive?: () => boolean;
+  /**
+   * Gate for the terrain-relative reach (downward offsets + pelvis drop, and
+   * full plant-up). Return false while a full-body one-shot is playing
+   * (`() => !anims.oneShotActive`): those clips are choreography — a foot
+   * swinging over a lower step must not drag the pelvis down into a staircase,
+   * and a raised stance foot must not be yanked a full step up. While gated,
+   * feet are lifted only as much as needed to keep the sole out of the contact
+   * under them (anti dig-in). Default: always allowed.
+   */
+  allowReachDown?: () => boolean;
 }
 
 // three-vrm's own node type — same THREE.Object3D at runtime, but using the
@@ -96,6 +106,12 @@ const NORMAL_DAMPING = 12; // ground-normal smoothing
 const PLANTED_LIFT_MIN = 0.04; // below this lift the foot is fully planted (align at full weight)
 const PLANTED_LIFT_MAX = 0.16; // above this lift the foot is fully lifted (no align)
 const MAX_FOOT_TILT = 0.6; // clamp foot-to-slope tilt (rad)
+const PENETRATION_SLACK = 0.02; // ankle may dip this far below rest before the no-sink lift kicks in
+// Max anti-dig-in lift while reach-down is gated (one-shots). Retarget dips are
+// a few cm; a hard cap keeps a stance foot carried INTO a stair riser by the
+// choreography from being lifted a whole step ("knee to the chest") — beyond
+// the cap it stays buried, which the step itself mostly occludes.
+const GATED_LIFT_CAP = 0.12;
 const MIN_BONE_LENGTH = 1e-4;
 const IK_EPSILON = 1e-4;
 
@@ -136,6 +152,7 @@ export class FootIK {
   #pelvisDrop: boolean;
   #alignFeet: boolean;
   #isActive: (() => boolean) | undefined;
+  #allowReachDown: (() => boolean) | undefined;
   #enabled = true;
   #weight = 0;
   #restFootHeight = 0;
@@ -148,6 +165,7 @@ export class FootIK {
     this.#pelvisDrop = options.pelvisDrop ?? true;
     this.#alignFeet = options.alignFeet ?? true;
     this.#isActive = options.isActive;
+    this.#allowReachDown = options.allowReachDown;
     this.#modelRoot = vrm.scene;
 
     const h = vrm.humanoid;
@@ -157,7 +175,14 @@ export class FootIK {
       const lower = h.getNormalizedBoneNode(l);
       const foot = h.getNormalizedBoneNode(f);
       return upper && lower && foot
-        ? { upper, lower, foot, offset: 0, normal: new THREE.Vector3(0, 1, 0), animFootPos: new THREE.Vector3() }
+        ? {
+            upper,
+            lower,
+            foot,
+            offset: 0,
+            normal: new THREE.Vector3(0, 1, 0),
+            animFootPos: new THREE.Vector3(),
+          }
         : null;
     };
     const left = mk(VRMHumanBoneName.LeftUpperLeg, VRMHumanBoneName.LeftLowerLeg, VRMHumanBoneName.LeftFoot);
@@ -192,14 +217,27 @@ export class FootIK {
 
     const k = 1 - Math.exp(-this.#smoothing * dt);
     const kNormal = 1 - Math.exp(-NORMAL_DAMPING * dt);
+    const reachDown = this.#allowReachDown?.() ?? true;
 
     // 1. Sample the ground under each ANIMATED foot; smooth offset + normal.
-    //    The offset is TERRAIN-relative — the ground height under the foot vs the
-    //    body root (the VRM origin = its floor/sole level), NOT vs the animated
-    //    foot. That's the load-bearing choice: it's independent of the foot's
-    //    stride phase, so a lifted swing foot keeps its animation (no dragging /
-    //    sinking while running) while a planted foot still lands on its step, and
-    //    it self-corrects any residual capsule-float gap (feet reach true ground).
+    //    Two lift signals, merged:
+    //    - TERRAIN-relative plant: the ground height under the foot vs the body
+    //      root (the VRM origin = its floor/sole level), NOT vs the animated
+    //      foot. Stride-phase independent — a lifted swing foot keeps its
+    //      animation (no dragging/sinking while running) while a planted foot
+    //      still lands on its step, and it self-corrects any residual
+    //      capsule-float gap (feet reach true ground).
+    //    - needLift: raise the ankle ONLY as much as needed so the sole clears
+    //      the contact under it — the anti-dig-in floor for poses that dip the
+    //      animated feet below the clip's own ground (weapon recoil etc. on
+    //      differently-proportioned avatars).
+    //    With reach-down gated off (full-body one-shots), ONLY needLift
+    //    applies, capped at GATED_LIFT_CAP: choreography feet are left alone
+    //    unless they'd clip into a step, and a foot the stance carries INTO a
+    //    riser gets at most a small hop, not a knee-to-the-chest fold. The
+    //    lift-only offsets also mean min(0,offset)=0 keeps the pelvis drop
+    //    off. Smoothing eases every transition (one-shot start/end, a ray
+    //    crossing a step edge) without pops.
     for (const leg of this.#legs) {
       leg.foot.getWorldPosition(leg.animFootPos);
       const sample = active ? this.#query(leg.animFootPos) : null;
@@ -207,14 +245,30 @@ export class FootIK {
       _normalTarget.copy(
         sample !== null && typeof sample !== "number" && sample.normal ? sample.normal : UP,
       );
-      const desired =
-        groundY === null
-          ? 0
-          : THREE.MathUtils.clamp(
-              groundY + this.#soleClearance - _rootPos.y,
-              -this.#maxOffset,
-              this.#maxOffset,
-            );
+      let desired = 0;
+      if (groundY !== null) {
+        // Anti-dig-in signal: how much lift (if any) the ankle needs so the
+        // sole clears the contact under it. NEGATIVE when the foot is safely
+        // above the contact — and it must stay negative: flooring it at zero
+        // here would win every Math.max below and silently kill the downward
+        // reach (and with it the pelvis drop) for the whole planter.
+        const needLift =
+          groundY +
+          this.#soleClearance +
+          this.#restFootHeight -
+          PENETRATION_SLACK -
+          leg.animFootPos.y;
+        desired = reachDown
+          ? Math.max(
+              THREE.MathUtils.clamp(
+                groundY + this.#soleClearance - _rootPos.y,
+                -this.#maxOffset,
+                this.#maxOffset,
+              ),
+              Math.min(needLift, this.#maxOffset),
+            )
+          : THREE.MathUtils.clamp(needLift, 0, GATED_LIFT_CAP);
+      }
       leg.offset += (desired - leg.offset) * k;
       leg.normal.lerp(_normalTarget, kNormal).normalize();
     }
@@ -229,6 +283,8 @@ export class FootIK {
     }
 
     // 3. Per-leg two-bone IK to the grounded target, then flatten planted feet.
+    //    (Anti-dig-in is already folded into the smoothed offset — needLift in
+    //    step 1 — so the target needs no extra instant clamp here.)
     for (const leg of this.#legs) {
       _target.copy(leg.animFootPos);
       _target.y += leg.offset * this.#weight;

package/templates/controllers/character/vrm/vrm-retarget.ts

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: MIT
-// Retarget Quaternius Universal Animation Library clips (Blender Rigify `DEF-`
-// rig) onto a three-vrm normalized humanoid rig (Genex AG-747). Adapted from the
+// Retarget Quaternius Universal Animation Library clips onto a three-vrm
+// normalized humanoid rig (Genex AG-747/AG-775). Two source rigs are supported
+// and auto-detected: the free UAL's Blender Rigify `DEF-*` skeleton and the UAL
+// Pro's UE-mannequin-style skeleton (`pelvis`/`spine_01`/…) that the bundled
+// core library and every CDN animation pack use. Adapted from the
 // official three-vrm Mixamo retarget recipe (@pixiv/three-vrm examples, MIT):
 // rewrite each bone track into the VRM's normalized-bone local space using the
 // SOURCE rig's rest-pose world rotations, and scale the hips translation by the
@@ -56,26 +59,81 @@ const DEF_TO_VRM: Record<string, VrmBone> = {
   "DEF-toe.R": VRMHumanBoneName.RightToes,
 };
 
+// Quaternius UAL Pro (UE-mannequin-style skeleton) -> VRM humanoid bone. Bone
+// names verified against the UAL1 master GLB ("Head" really is capitalized).
+// Fingers are omitted, same policy as the DEF map.
+const UE_TO_VRM: Record<string, VrmBone> = {
+  pelvis: VRMHumanBoneName.Hips,
+  spine_01: VRMHumanBoneName.Spine,
+  spine_02: VRMHumanBoneName.Chest,
+  spine_03: VRMHumanBoneName.UpperChest,
+  neck_01: VRMHumanBoneName.Neck,
+  Head: VRMHumanBoneName.Head,
+  clavicle_l: VRMHumanBoneName.LeftShoulder,
+  upperarm_l: VRMHumanBoneName.LeftUpperArm,
+  lowerarm_l: VRMHumanBoneName.LeftLowerArm,
+  hand_l: VRMHumanBoneName.LeftHand,
+  clavicle_r: VRMHumanBoneName.RightShoulder,
+  upperarm_r: VRMHumanBoneName.RightUpperArm,
+  lowerarm_r: VRMHumanBoneName.RightLowerArm,
+  hand_r: VRMHumanBoneName.RightHand,
+  thigh_l: VRMHumanBoneName.LeftUpperLeg,
+  calf_l: VRMHumanBoneName.LeftLowerLeg,
+  foot_l: VRMHumanBoneName.LeftFoot,
+  ball_l: VRMHumanBoneName.LeftToes,
+  thigh_r: VRMHumanBoneName.RightUpperLeg,
+  calf_r: VRMHumanBoneName.RightLowerLeg,
+  foot_r: VRMHumanBoneName.RightFoot,
+  ball_r: VRMHumanBoneName.RightToes,
+};
+
+/**
+ * Pick the source-rig bone map by looking for each rig's hips bone in the
+ * scene: `DEF-hips` -> Rigify (free UAL), `pelvis` -> UE-style (UAL Pro).
+ * Returns null for unrecognized rigs.
+ */
+export function detectBoneMap(sourceRoot: THREE.Object3D): Record<string, VrmBone> | null {
+  let map: Record<string, VrmBone> | null = null;
+  sourceRoot.traverse((object) => {
+    if (map !== null) return;
+    if (object.name === "DEF-hips") map = DEF_TO_VRM;
+    else if (object.name === "pelvis") map = UE_TO_VRM;
+  });
+  return map;
+}
+
 /**
  * Retarget UAL clips onto `vrm`.
  * @param vrm           the loaded VRM (already through {@link loadVrm}).
- * @param animationRoot the animation-library GLB's scene — its `DEF-` bones in
- *                      rest pose supply the source frame the tracks are relative to.
- * @param clips         that GLB's animations (all 46 UAL clips).
+ * @param animationRoot the animation GLB's scene — its bones in rest pose
+ *                      supply the source frame the tracks are relative to.
+ * @param clips         that GLB's animations.
+ * @param boneMap       source-bone-name -> VRM humanoid bone. Defaults to
+ *                      {@link detectBoneMap} on `animationRoot` (Rigify or
+ *                      UE-style rigs bind automatically).
  * @returns new clips whose tracks target the VRM's normalized humanoid bones.
  */
 export function retargetClips(
   vrm: VRM,
   animationRoot: THREE.Object3D,
   clips: THREE.AnimationClip[],
+  boneMap?: Record<string, VrmBone>,
 ): THREE.AnimationClip[] {
+  const sourceToVrm = boneMap ?? detectBoneMap(animationRoot);
+  if (sourceToVrm === null) {
+    console.warn(
+      "[vrm-retarget] unrecognized animation rig (no DEF-hips or pelvis bone found) — returning no clips; pass an explicit boneMap to retargetClips.",
+    );
+    return [];
+  }
+
   animationRoot.updateWorldMatrix(true, true);
   vrm.scene.updateWorldMatrix(true, true);
 
   // three's GLTFLoader SANITIZES node names in animation track targets
   // (PropertyBinding strips `[].:/ ` and turns spaces into `_`), so a Rigify bone
   // "DEF-upper_arm.L" shows up in tracks as "DEF-upper_armL". Map those sanitized
-  // names back to the real bones, whose actual names carry the dots DEF_TO_VRM
+  // names back to the real bones, whose actual names carry the dots the map
   // keys on. (Mixamo names are dotless, so the upstream recipe never needed this.)
   const sanitize = (name: string): string => name.replace(/\s/g, "_").replace(/[[\]./:]/g, "");
   const sourceByTrackName = new Map<string, THREE.Object3D>();
@@ -83,9 +141,9 @@ export function retargetClips(
     if (o.name) sourceByTrackName.set(sanitize(o.name), o);
   });
   // glTF load sanitizes bone names too, so `source.name` is already dot-stripped —
-  // key the VRM-bone lookup by the sanitized DEF name, matching the track's nodeName.
-  const sanitizedDefToVrm: Record<string, VrmBone> = {};
-  for (const [def, bone] of Object.entries(DEF_TO_VRM)) sanitizedDefToVrm[sanitize(def)] = bone;
+  // key the VRM-bone lookup by the sanitized source name, matching the track's nodeName.
+  const sanitizedSourceToVrm: Record<string, VrmBone> = {};
+  for (const [src, bone] of Object.entries(sourceToVrm)) sanitizedSourceToVrm[sanitize(src)] = bone;
 
   // Reusable bind-pose quaternions. Both rigs are at rest here (nothing has
   // animated them yet), so getWorldQuaternion reads the bind pose.
@@ -99,8 +157,10 @@ export function retargetClips(
   // hips' vertical bob/crouch on the target hips as a rest-relative DELTA, so
   // the physics controller still owns the whole-body base translation while the
   // pose keeps the pelvis (and therefore the feet) at the right height.
-  const HIPS_SANITIZED = sanitize("DEF-hips");
-  const srcHips = sourceByTrackName.get(HIPS_SANITIZED) ?? null;
+  const hipsSourceName = Object.entries(sanitizedSourceToVrm).find(
+    ([, bone]) => bone === VRMHumanBoneName.Hips,
+  )?.[0];
+  const srcHips = (hipsSourceName ? sourceByTrackName.get(hipsSourceName) : undefined) ?? null;
   const tgtHips = vrm.humanoid.getNormalizedBoneNode(VRMHumanBoneName.Hips);
   const hipsSrcParentWorld = new THREE.Quaternion();
   const hipsTgtParentWorldInv = new THREE.Quaternion();
@@ -128,7 +188,7 @@ export function retargetClips(
       const nodeName = track.name.slice(0, lastDot);
       const prop = track.name.slice(lastDot + 1);
       const source = sourceByTrackName.get(nodeName);
-      const vrmBone = sanitizedDefToVrm[nodeName];
+      const vrmBone = sanitizedSourceToVrm[nodeName];
       if (!source || !vrmBone) continue;
 
       const target = vrm.humanoid.getNormalizedBoneNode(vrmBone);

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

@@ -0,0 +1,181 @@
+---
+name: genex-ai-image
+description: Generate a real image (PNG/JPEG) from a text prompt with `npx genex image`, then load it into Three.js on any mesh, plane, or sprite. Use for posters, paintings, billboards, signs, logos, sprites, card/item art, loading screens, textures for in-game screens, and decals/stickers ("wanted poster", "arcade cabinet marquee", "neon graffiti tag") rather than a procedural/shader look. Pass `--transparent` for anything with an alpha channel.
+---
+
+# Genex AI · Image
+
+Turn a prompt into a real raster image and put it anywhere in the game — a poster,
+a painting, a billboard, a sign, a logo, a sprite, card/item art, a loading screen,
+art on an in-game screen, or a decal/sticker.
+
+## When to use this vs. procedural materials
+
+- **Use `npx genex image`** for a specific, recognizable picture you can describe —
+  "vintage travel poster of Mars", "guild crest with crossed swords", "arcade
+  marquee art". You get a real image.
+- **Use `$genex-threejs-procedural-materials`** for stylized/abstract or fully
+  parametric surfaces authored in shaders. Use `$genex-ai-texture` for a *tiling*
+  PBR surface (floors, ground, walls) — this skill is for a single flat picture.
+
+## Run
+
+```bash
+npx genex image "<prompt>"
+npx genex image "neon graffiti tag, spray-paint style" --transparent   # PNG with alpha (decals/stickers/logos)
+```
+
+Blocks until ready, then prints its public URL:
+
+```
+https://assets.genex.technology/generations/<id>/image-main
+```
+
+The image lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (local dev,
+published game, and remixes alike).
+
+## Load it into the scene
+
+Load the image and apply it to any mesh, plane, or sprite:
+
+```ts
+import * as THREE from "three";
+
+// the URL `npx genex image` printed (R2 sends CORS headers, so cross-origin works):
+const IMAGE_URL = "https://assets.genex.technology/generations/<id>/image-main";
+const map = await new THREE.TextureLoader().loadAsync(IMAGE_URL);
+map.colorSpace = THREE.SRGBColorSpace;                    // pictures are sRGB — without this they look washed/dark
+map.anisotropy = renderer.capabilities.getMaxAnisotropy(); // stays sharp at grazing angles
+
+// a poster/painting/sign on a wall — a flat plane:
+const poster = new THREE.Mesh(
+  new THREE.PlaneGeometry(2, 3),                          // match the image aspect (w:h)
+  new THREE.MeshStandardMaterial({ map, roughness: 0.9, metalness: 0 }),
+);
+scene.add(poster);
+```
+
+For a `--transparent` PNG, set `transparent: true` on the material so the alpha shows.
+For a screen-space sprite (HUD art, an icon) use `new THREE.Sprite(new THREE.SpriteMaterial({ map }))`.
+For art that must glow (a lit sign, a screen) use `MeshBasicMaterial` (unlit) so scene lighting doesn't darken it.
+
+## Decals & stickers
+
+**Anything applied *on top* of a surface — a decal, sticker, spray tag, logo, or
+bullet hole — needs an alpha channel, so always generate it with `--transparent`.**
+Without alpha you get an opaque rectangle instead of a shaped mark.
+
+Project it onto the target mesh with `DecalGeometry` (the canonical spray-paint look —
+clips to the surface and wraps around corners):
+
+```ts
+import * as THREE from "three";
+import { DecalGeometry } from "three/addons/geometries/DecalGeometry.js";
+
+// ONE shared texture + material for all sprays (generated with --transparent):
+const map = await new THREE.TextureLoader().loadAsync(IMAGE_URL);
+map.colorSpace = THREE.SRGBColorSpace;
+map.anisotropy = renderer.capabilities.getMaxAnisotropy();
+const sprayMat = new THREE.MeshStandardMaterial({
+  map, transparent: true, depthTest: true, depthWrite: false,
+  polygonOffset: true, polygonOffsetFactor: -4,          // pulls the decal forward — kills z-fighting
+});
+
+const raycaster = new THREE.Raycaster();
+const helper = new THREE.Object3D();                     // orientation scratch — never added to the scene
+const decals: THREE.Mesh[] = [];
+const MAX_DECALS = 20;
+
+function spray(): void {
+  raycaster.setFromCamera(new THREE.Vector2(0, 0), camera);      // screen centre
+  const hit = raycaster.intersectObjects(sprayables, false)[0];  // sprayables = your wall meshes
+  if (!hit || !hit.face) return;
+  const n = hit.face.normal.clone()                              // face.normal is LOCAL space —
+    .applyNormalMatrix(new THREE.Matrix3().getNormalMatrix(hit.object.matrixWorld)); // must transform it
+  helper.position.copy(hit.point);
+  helper.lookAt(hit.point.clone().add(n));
+  const S = 1;                                                    // metres; for non-square art size.y = S * imgH/imgW
+  const geom = new DecalGeometry(hit.object as THREE.Mesh, hit.point,
+    helper.rotation.clone(), new THREE.Vector3(S, S, S * 0.5));   // size.z = wrap depth
+  const decal = new THREE.Mesh(geom, sprayMat);
+  decal.renderOrder = 100 + decals.length;                        // newer sprays draw on top
+  (hit.object as THREE.Mesh).attach(decal);                       // verts are world-space; attach keeps them correct
+  decals.push(decal);
+  if (decals.length > MAX_DECALS) {                               // FIFO cap — dispose the oldest
+    const old = decals.shift()!;
+    old.removeFromParent();
+    old.geometry.dispose();      // geometry is per-spray — MUST dispose; the shared material/map are never disposed here
+  }
+}
+
+window.addEventListener("keydown", (e) => {
+  if (e.code === "KeyT" && !e.repeat) spray();
+});
+```
+
+Gotchas (all bite in practice):
+
+- **`hit.face.normal` is LOCAL space** — apply the normal-matrix from `matrixWorld`.
+  Skipping it "works by accident" only on an unrotated, unscaled wall; any rotated
+  wall gets the decal facing the wrong way.
+- **`depthWrite: false` means overlap order is draw order** — increment `renderOrder`
+  per spray, or stacked decals flicker and sort wrongly.
+- **One decal clips against ONE mesh** — a spray straddling two wall meshes gets cut
+  at the boundary. Pass the single `hit.object`, or make walls separate meshes.
+- **`size.z` too large on a thin wall wraps the decal onto the back face** (visible
+  from behind). Keep `size.z` below the wall thickness.
+- **`DecalGeometry` is static-mesh only** — no `SkinnedMesh`/morph targets. For a
+  moving or skinned target, use a small `PlaneGeometry` quad offset along the normal
+  (`hit.point + n * 0.01`, `quad.lookAt(hit.point.clone().add(n))`) instead.
+
+## Multiplayer
+
+The asset URL is public, permanent, and CORS-open, so it is safe to broadcast the
+string to every player. A placed-at-runtime mark (a decal included) is static shared
+world state — put it on `room.shared`, **not** `objects` (no movement to smooth) and
+**not** `send` (late joiners would see a bare wall; `shared` keys replay on connect).
+
+Use a **fixed ring of slots** and overwrite the oldest — **never a fresh key per
+spray**. The relay caps game-writable `shared` keys at **256 per room, keys are
+permanent and undeletable, and new keys past the cap are silently dropped forever**,
+so a new key per spray eventually breaks the game:
+
+```ts
+let next = 0;
+const RING = 32;                                   // decal:0 .. decal:31
+function placeShared(url: string, hit: { point: THREE.Vector3; normal: THREE.Vector3 }) {
+  room.shared.set(`decal:${next % RING}`, { url, p: hit.point.toArray(), n: hit.normal.toArray() });
+  next++;
+}
+room.on("shared", (key, value) => {                // every player (incl. late joiners) rebuilds the decal
+  if (key.startsWith("decal:") && value) spawnDecalFromShared(value);
+});
+```
+
+See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API.
+
+## Publish checklist
+
+- Load it from the **URL** the command printed — absolute and permanent, so it resolves
+  the same in local dev, the published game, and remixes. Nothing to commit.
+- Don't copy the image into `public/assets/` — generated assets live in R2, not the repo.
+
+## Options
+
+- `--transparent` — PNG with an alpha channel (mandatory for decals/stickers/logos —
+  anything laid on top of a surface).
+- `--aspect <ratio>` — image shape (e.g. `square`, `16:9`, `9:16`); default is square.
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it).
+- `--api-url <url>` — override the API base (local dev).
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
+  This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
+- **Decal is an opaque rectangle** — the image has no alpha. Regenerate with
+  `--transparent`.
+- **Colors look washed/dark** — ensure `map.colorSpace = THREE.SRGBColorSpace`.
+- **Decal blurs at oblique angles** — set `map.anisotropy = renderer.capabilities.getMaxAnisotropy()`.

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

@@ -0,0 +1,148 @@
+---
+name: genex-ai-video
+description: Generate a real video clip (H.264 mp4) from a text prompt with `npx genex video`, then play it in Three.js on any surface via VideoTexture. Use for in-game TVs/screens/monitors, animated billboards, cutscene clips, ambient backdrops, portals, and video decals ("news broadcast on a TV", "swirling portal", "animated arcade attract screen") rather than a static image or shader effect. Pass `--loop` for a seamless loop.
+---
+
+# Genex AI · Video
+
+Turn a prompt into a real mp4 clip and play it anywhere in the game — an in-game
+TV/screen/monitor, an animated billboard, a cutscene, an ambient backdrop, a portal,
+or a video decal.
+
+## When to use this vs. a static image or shader
+
+- **Use `npx genex video`** for moving footage you can describe — "static-y CRT
+  news broadcast", "swirling neon portal", "rain running down glass". You get a real
+  mp4.
+- **Use `$genex-ai-image`** for a single still picture, or
+  `$genex-threejs-procedural-vfx` for parametric real-time effects (particles,
+  trails, shockwaves) authored in code.
+
+## Run
+
+```bash
+npx genex video "<prompt>"
+npx genex video "swirling neon plasma, seamless loop" --loop   # seamless loop for screens/backdrops
+```
+
+Video takes a **minute or two** end to end (queue + generation). If you're building
+other things meanwhile, add `--no-wait` to enqueue and come back for it. Blocks until
+ready, then prints its public URL:
+
+```
+https://assets.genex.technology/generations/<id>/video-mp4
+```
+
+The clip lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (local dev,
+published game, and remixes alike).
+
+> **Cost & length:** the default is a **5-second, 720p** clip, and that IS the right
+> default for a looping screen or backdrop — only pass `--duration` when the content
+> genuinely needs to be longer (a cutscene). Longer, higher-res clips cost more and
+> take longer. mp4 has **no alpha channel**, so a video is always a full rectangle
+> (there are no transparent video decals).
+
+## Play it in Three.js
+
+Video needs an `HTMLVideoElement`, and browsers block autoplay — the first
+`video.play()` must run inside a user gesture (any click or keypress). Wrap it in a
+`VideoTexture` and put it on any surface:
+
+```ts
+import * as THREE from "three";
+
+// the URL `npx genex video` printed (R2 sends CORS headers, so cross-origin works):
+const VIDEO_URL = "https://assets.genex.technology/generations/<id>/video-mp4";
+const video = document.createElement("video");
+video.src = VIDEO_URL;
+video.crossOrigin = "anonymous";   // REQUIRED to upload cross-origin video to WebGL (else a tainted-source error)
+video.muted = true;                // muted is what lets it play under autoplay policy
+video.loop = true;
+video.playsInline = true;          // iOS: no fullscreen takeover
+
+const texture = new THREE.VideoTexture(video);   // auto-updates every frame — no per-frame code
+texture.colorSpace = THREE.SRGBColorSpace;
+
+// an in-game TV / animated billboard — MeshBasicMaterial so it glows regardless of scene lighting:
+const screen = new THREE.Mesh(
+  new THREE.PlaneGeometry(3.2, 1.8),             // 16:9
+  new THREE.MeshBasicMaterial({ map: texture }),
+);
+scene.add(screen);
+
+// start playback on a user gesture (never swallow the rejection):
+window.addEventListener("keydown", () => {
+  video.play().catch((e) => console.warn("video play", e));
+}, { once: true });
+```
+
+One `VideoTexture` can feed **many** surfaces — a bank of monitors, N sprays. Cost is
+per distinct `<video>` element (media decode + one GPU upload per frame), **not** per
+surface, so sharing one element for every screen is nearly free (all play in sync).
+Keep clips **≤720p**. Pause the element (`video.pause()`) when no video surface is
+visible.
+
+## Video decals
+
+A video decal is the same `DecalGeometry` projection as an image decal — read the
+**Decals & stickers** section of `$genex-ai-image` for the full recipe and gotchas —
+with one change: swap the `TextureLoader` map for the `VideoTexture` above, and call
+`video.play().catch(...)` inside the spray handler (the keypress is the user gesture).
+All decals can share the one `VideoTexture`. Because mp4 has no alpha, a video decal
+is a full rectangle (fine for a screen-shaped mark; use `$genex-ai-image --transparent`
+for a shaped sticker). **Layering gotcha:** an opaque video decal draws in the opaque
+pass — *before* any `transparent: true` image decal — so image decals always land on
+top regardless of spray order or `renderOrder`. If you mix both and need strict
+newest-on-top, set `transparent: true` on the video decal material too.
+
+## Multiplayer
+
+The asset URL is public, permanent, and CORS-open, so it is safe to broadcast the
+string to every player. A placed-at-runtime surface (a video decal included) is static
+shared world state — put it on `room.shared`, **not** `objects` (no movement to smooth)
+and **not** `send` (late joiners would see a bare wall; `shared` keys replay on connect).
+
+Use a **fixed ring of slots** and overwrite the oldest — **never a fresh key per
+placement**. The relay caps game-writable `shared` keys at **256 per room, keys are
+permanent and undeletable, and new keys past the cap are silently dropped forever**:
+
+```ts
+let next = 0;
+const RING = 32;                                   // decal:0 .. decal:31
+function placeShared(url: string, hit: { point: THREE.Vector3; normal: THREE.Vector3 }) {
+  room.shared.set(`decal:${next % RING}`, { url, p: hit.point.toArray(), n: hit.normal.toArray() });
+  next++;
+}
+room.on("shared", (key, value) => {                // every player (incl. late joiners) rebuilds it
+  if (key.startsWith("decal:") && value) spawnVideoDecalFromShared(value);
+});
+```
+
+See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API.
+
+## Publish checklist
+
+- Load it from the **URL** the command printed — absolute and permanent, so it resolves
+  the same in local dev, the published game, and remixes. Nothing to commit.
+- Don't copy the mp4 into `public/assets/` — generated assets live in R2, not the repo.
+
+## Options
+
+- `--loop` — a seamless loop (for screens, ambient backdrops, video decals).
+- `--duration <sec>` — clip length 1–15; default 5. Only raise it when the content
+  genuinely needs more — longer clips cost more and take longer.
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it). Handy for video since it takes a minute or two.
+- `--api-url <url>` — override the API base (local dev).
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
+  This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
+- **Nothing plays / black surface** — the first `video.play()` must run inside a user
+  gesture (click/keydown); confirm it's called and its promise rejection is logged.
+- **Tainted-source / security error** — set `video.crossOrigin = "anonymous"` before
+  `video.src`.
+- **Colors look washed/dark** — ensure `texture.colorSpace = THREE.SRGBColorSpace`.

package/templates/skills/genex-getting-started/SKILL.md

@@ -37,13 +37,16 @@ npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)
 npx genex skybox "golden hour over mountains"  # a 360° sky + lighting
 npx genex sfx "punchy laser zap" --duration 2  # a sound effect (mp3)
 npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
+npx genex image "vintage travel poster"        # a picture (poster/sign/sprite/decal)
+npx genex video "swirling neon portal" --loop  # a video clip (screen/backdrop)
 ```
 
 (Run them inside your project — the `@genex-ai/cli-demo` dev dependency makes
 `npx genex` resolve to the right CLI.)
 
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
-`$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
+`$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`, `$genex-ai-image`,
+`$genex-ai-video`.
 
 ## Identity & saves (every game)