@genex-ai/cli-demo 0.35.0 → 0.37.0

package/README.md

@@ -13,6 +13,8 @@ genex model "<prompt>"     # generate a 3D model  → prints an asset URL
 genex skybox "<prompt>"    # generate a 360° sky  → prints an asset URL
 genex sfx "<prompt>"       # generate a sound fx  → prints an asset URL
 genex texture "<prompt>"   # generate a texture   → prints an asset URL
+genex image "<prompt>"     # generate an image    → prints an asset URL
+genex video "<prompt>"     # generate a video     → prints an asset URL
 genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
 ```
 
@@ -72,8 +74,8 @@ Defaults: API `https://demo-api.glotech.world`, auth site
 
 ## Generating assets
 
-`genex model | skybox | sfx | texture "<prompt>"` turn a prompt into a real,
-game-ready asset stored in R2. The command blocks until the asset is ready (live SSE
+`genex model | skybox | sfx | texture | image | video "<prompt>"` turn a prompt into a
+real, game-ready asset stored in R2. The command blocks until the asset is ready (live SSE
 stream), then prints its public URL — the game loads it directly, nothing is
 downloaded or committed:
 
@@ -83,6 +85,8 @@ downloaded or committed:
 | `genex skybox "<prompt>"` | Blockade Labs | `…/generations/<id>/skybox-equirect` |
 | `genex sfx "<prompt>" [--duration <s>]` | ElevenLabs | `…/generations/<id>/audio-sfx` |
 | `genex texture "<prompt>" [--terrain]` | Gemini | `…/generations/<id>/texture-basecolor` |
+| `genex image "<prompt>" [--transparent] [--aspect <ratio>]` | fal.ai | `…/generations/<id>/image-main` |
+| `genex video "<prompt>" [--duration <s>] [--loop]` | fal.ai | `…/generations/<id>/video-mp4` |
 
 Each URL is a permanent `https://assets.genex.technology/...` address served straight
 from R2 (with CORS, so three.js loads it cross-origin without tainting). It resolves
@@ -92,9 +96,10 @@ Three.js loader code.
 
 Auth reuses the existing `GENEX_TOKEN` (run `genex init` first). Server-side, each
 provider is keyed by an env var (`TRIPO_API_KEY`, `BLOCKADE_LABS_API_KEY`,
-`ELEVENLABS_API_KEY`, `GEMINI_API_KEY`); when a key is unset that kind falls back to
-a built-in **mock** provider that returns sample assets, so the flow runs keyless.
-`--no-wait` enqueues without downloading.
+`ELEVENLABS_API_KEY`, `GEMINI_API_KEY`, and `FAL_KEY` for image + video); when a key
+is unset that kind falls back to a built-in **mock** provider that returns sample
+assets, so the flow runs keyless. `--no-wait` enqueues without downloading — useful
+for video, which is minutes-class end-to-end.
 
 ## Install / run
 

package/dist/index.js

@@ -1655,6 +1655,8 @@ async function runPublish(opts) {
     if (opts.sourceRepoUrl) body.sourceRepoUrl = opts.sourceRepoUrl;
     if (opts.sourceAuthor) body.sourceAuthor = opts.sourceAuthor;
     if (opts.license) body.license = opts.license;
+    if (opts.purchaseUrl) body.purchaseUrl = opts.purchaseUrl;
+    if (opts.productName) body.productName = opts.productName;
     if (detections.embedSdkVersion) body.embedSdkVersion = detections.embedSdkVersion;
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
@@ -1788,6 +1790,10 @@ async function runGenerate(kind, opts) {
   const options = {};
   if (kind === "texture" && opts.terrain) options.terrain = true;
   if (kind === "sfx" && opts.duration) options.durationSeconds = opts.duration;
+  if (kind === "image" && opts.transparent) options.transparent = true;
+  if (kind === "image" && opts.aspect) options.aspect = opts.aspect;
+  if (kind === "video" && opts.duration) options.durationSeconds = opts.duration;
+  if (kind === "video" && opts.loop) options.loop = true;
   log.plain(c.bold(`genex ${kind}`));
   log.dim(`  ${prompt}`);
   log.plain("");
@@ -1824,9 +1830,10 @@ async function runGenerate(kind, opts) {
   }
   log.step("Generating\u2026 (this can take up to a minute)");
   const onProgress = (p) => log.dim(`  ${p}%`);
-  const deadline = Date.now() + WAIT_TIMEOUT_MS;
+  const timeoutMs = waitTimeoutFor(kind);
+  const deadline = Date.now() + timeoutMs;
   const streamed = await waitViaSSE(apiUrl, token, id, onProgress, deadline);
-  const view = streamed === "unsupported" ? await poll(apiUrl, token, id, onProgress) : streamed;
+  const view = streamed === "unsupported" ? await poll(apiUrl, token, id, onProgress, timeoutMs) : streamed;
   if (!view) {
     log.error("Timed out waiting for the generation.");
     process.exitCode = 1;
@@ -1853,6 +1860,11 @@ async function runGenerate(kind, opts) {
   printHint(kind, files, log);
 }
 var WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
+var KIND_WAIT_TIMEOUT_MS = {
+  video: 15 * 60 * 1e3
+  // 15 min
+};
+var waitTimeoutFor = (kind) => KIND_WAIT_TIMEOUT_MS[kind] ?? WAIT_TIMEOUT_MS;
 var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed"]);
 async function waitViaSSE(apiUrl, token, id, onProgress, deadline) {
   let connectFailures = 0;
@@ -1905,8 +1917,8 @@ async function waitViaSSE(apiUrl, token, id, onProgress, deadline) {
   }
   return null;
 }
-async function poll(apiUrl, token, id, onProgress) {
-  const deadline = Date.now() + WAIT_TIMEOUT_MS;
+async function poll(apiUrl, token, id, onProgress, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
   let last = -1;
   while (Date.now() < deadline) {
     try {
@@ -1935,7 +1947,9 @@ function printHint(kind, files, log) {
     model: `Standard GLB \u2014 load with GLTFLoader straight from the URL \u2014 see the genex-ai-model skill. url = "${url}"`,
     skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. url = "${url}"`,
     sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. url = "${url}"`,
-    texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`
+    texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`,
+    image: `Load with TextureLoader (set colorSpace = SRGBColorSpace) onto any mesh/plane/sprite \u2014 see genex-ai-image. url = "${url}"`,
+    video: `Wire an HTMLVideoElement (crossOrigin="anonymous", muted, loop, playsInline) into a THREE.VideoTexture \u2014 see genex-ai-video. url = "${url}"`
   };
   log.dim(`  ${hint[kind]}`);
   log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
@@ -2196,7 +2210,7 @@ function rank(items, query) {
 }
 
 // src/index.ts
-var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
+var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);
 var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize, and publish 3D games.
 
 ${c.bold("Usage")}
@@ -2212,15 +2226,20 @@ ${c.bold("Usage")}
   genex skybox "<prompt>" [options]  Generate a skybox (equirect) into public/assets/skybox.
   genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into public/assets/sfx.
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
+  genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
+  genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
   genex controller <type> [--force]  Install a physics controller (character|car|drone)
                                      into src/controllers (+ assets into public/assets).
   genex explore ["<query>"] [options] Search the curated community gallery \u2014 proven
                                      Three.js systems you can clone or borrow parts
                                      from. No query lists the whole catalog.
 
-${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
+${c.bold("Options for the generators (`model` `skybox` `sfx` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
-  --duration <sec>     (sfx) target clip length in seconds.
+  --duration <sec>     (sfx, video) target clip length in seconds.
+  --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
+  --aspect <ratio>     (image) aspect preset (e.g. square, landscape, portrait).
+  --loop               (video) generate a seamless loop.
   --no-wait            Enqueue only; don't block waiting for the asset.
   --api-url <url>      Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
@@ -2263,6 +2282,9 @@ ${c.bold("Options for `preview` / `publish`")}
                        shown as "Ported from \u2026" credit on the game page.
   --source-author <name>   (publish) Upstream author to credit.
   --license <label>        (publish) Upstream license label (e.g. MIT).
+  --purchase-url <url>     (operator) External purchase URL \u2014 marks the game a
+                       paid-product demo ("Get \u2026" replaces Remix). Admin-only.
+  --product-name <name>    (operator) Product name for the "Get {name}" button.
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
@@ -2295,6 +2317,9 @@ ${c.bold("Examples")}
   genex skybox "golden hour over a misty mountain range"
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
+  genex image "retro arcade poster art" --aspect portrait
+  genex image "neon graffiti tag, spray-paint style" --transparent
+  genex video "swirling neon plasma, seamless loop" --loop
   genex controller character
   genex explore "grass"
   genex explore
@@ -2321,9 +2346,12 @@ function parseArgs(argv) {
     "--categories",
     "--timeout",
     "--duration",
+    "--aspect",
     "--source-repo-url",
     "--source-author",
-    "--license"
+    "--license",
+    "--purchase-url",
+    "--product-name"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -2353,6 +2381,12 @@ function parseArgs(argv) {
       case "--terrain":
         parsed.options.terrain = true;
         break;
+      case "--transparent":
+        parsed.options.transparent = true;
+        break;
+      case "--loop":
+        parsed.options.loop = true;
+        break;
       case "--force":
         parsed.options.force = true;
         break;
@@ -2442,6 +2476,12 @@ function applyValueFlag(options, flag, value) {
     case "--license":
       options.license = value;
       break;
+    case "--purchase-url":
+      options.purchaseUrl = value;
+      break;
+    case "--product-name":
+      options.productName = value;
+      break;
     case "--timeout": {
       const n = Number(value);
       if (!Number.isFinite(n) || n <= 0) {
@@ -2458,6 +2498,9 @@ function applyValueFlag(options, flag, value) {
       options.duration = n;
       break;
     }
+    case "--aspect":
+      options.aspect = value;
+      break;
   }
 }
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "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-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)
 

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -60,13 +60,12 @@ recipes (sports/ball, shooter, co-op).
 ## Real (AI-generated) assets — `npx genex` commands
 
 When the user wants a **specific, recognizable asset** (a named object, a described
-sky, a particular sound or surface) rather than something authored in code, generate
-it with an `npx genex` command (run inside the project, where the `@genex-ai/cli-demo`
-dev dependency makes `genex` resolve to the right CLI). Each drops a real file into
-`public/assets/<kind>/` so it ships with the built game — load it at runtime as
-`./assets/...` (the `public/` prefix is stripped when served; a bare `./assets/` dir
-would be dropped from the production build). Each skill has the exact Three.js
-loader code.
+sky, a particular sound, surface, image, or clip) rather than something authored in
+code, generate it with an `npx genex` command (run inside the project, where the
+`@genex-ai/cli-demo` dev dependency makes `genex` resolve to the right CLI). Each
+prints a permanent public `assets.genex.technology` URL you load straight from at
+runtime — the asset lives in Genex storage (R2), not your repo, so there's nothing to
+commit. Each skill has the exact Three.js loader code.
 
 | Work needed | Generate with | Skill |
 | --- | --- | --- |
@@ -74,6 +73,8 @@ loader code.
 | a described 360° sky / backdrop + image-based lighting | `npx genex skybox "<prompt>"` | `$genex-ai-skybox` |
 | a specific sound effect tied to an event | `npx genex sfx "<prompt>"` | `$genex-ai-sfx` |
 | a photoreal surface/material on a mesh or terrain | `npx genex texture "<prompt>" [--terrain]` | `$genex-ai-texture` |
+| a picture on a plane/sprite — poster, sign, sprite, card art, decal/sticker | `npx genex image "<prompt>" [--transparent]` | `$genex-ai-image` |
+| a video clip on a surface — in-game screen, billboard, cutscene, backdrop | `npx genex video "<prompt>" [--loop]` | `$genex-ai-video` |
 
 Prefer the **procedural** skills above for abstract/parametric/animated systems
 (geometry, materials, sky, water, VFX) — no files, infinite variation. Prefer the