@genex-ai/cli-demo 1.10.3-dev.535 → 1.10.4-dev.536

package/dist/index.js

@@ -7397,6 +7397,7 @@ function buildGenOptions(kind, opts) {
     if (opts.frameUrl) options.frameUrl = opts.frameUrl;
     if (opts.firstFrameUrl) options.firstFrameUrl = opts.firstFrameUrl;
     if (opts.lastFrameUrl) options.lastFrameUrl = opts.lastFrameUrl;
+    if (opts.refs?.length) options.referenceImageUrls = opts.refs;
   }
   return options;
 }
@@ -7475,6 +7476,23 @@ async function runGenerate(kind, opts) {
     }
     opts = { ...opts, frameUrl: inlined.dataUri };
   }
+  if (kind === "video" && opts.refs?.length) {
+    const refs = [];
+    for (const ref of opts.refs) {
+      if (isRemoteRef(ref)) {
+        refs.push(ref);
+        continue;
+      }
+      const inlined = await inlineLocalImage(ref, "--ref");
+      if (!inlined.ok) {
+        log.error(inlined.error);
+        process.exitCode = 1;
+        return;
+      }
+      refs.push(inlined.dataUri);
+    }
+    opts = { ...opts, refs };
+  }
   if (kind === "model" && opts.imageUrl && !isRemoteRef(opts.imageUrl)) {
     const inlined = await inlineLocalImage(opts.imageUrl, "--image");
     if (!inlined.ok) {
@@ -21725,13 +21743,18 @@ ${c.bold("Options for the generators (`model` `sfx` `music` `voice` `texture` `i
   --bg-mode <mode>     (image) background-removal model: sprite | glyph | sheet |
                        matte (BiRefNet soft alpha \u2014 hair/glow/smoke edges).
   --loop               (video) generate a seamless loop.
-  --resolution <r>     (video) 720p | 1080p (default 1080p; 720p halves the cost
-                       when quality genuinely doesn't matter \u2014 loop clips
-                       ignore it, model default).
+  --resolution <r>     (video) 480p | 768p | 2k | 4k (default 768p \u2014 the top
+                       native mode; 2k/4k are upscales of the same base and
+                       cost more; 480p is the cost opt-down; loop clips ignore
+                       it, model default).
   --frame <url|file>   (video) animate from THIS frame back to itself (seamless
                        loop) \u2014 an asset URL or a local image file (\u22644 MB).
   --first-frame <url>  (video) start frame for a two-frame motion \u2026
   --last-frame <url>   (video) \u2026 and its end frame.
+  --ref <url|file>     (video, repeatable \xD79) subject/style reference images \u2014
+                       cite them in the prompt as "Image 1"\u2026"Image N"; keeps
+                       the same character/style across many clips. Cannot be
+                       combined with --frame/--loop.
   --no-wait            Enqueue only; don't block waiting for the asset. Prints
                        the id that "genex wait <id>" picks the result up with.
   --no-download        (Genex Tools workspaces) print the asset URL only instead
@@ -22025,6 +22048,7 @@ function parseArgs(argv) {
     "--frame",
     "--first-frame",
     "--last-frame",
+    "--ref",
     "--resolution",
     // `genex model` mesh-lane value flags (AG-908).
     "--image",
@@ -22530,14 +22554,17 @@ function applyValueFlag(options, flag, value) {
       options.bgMode = value;
       break;
     case "--resolution":
-      if (!["720p", "1080p"].includes(value)) {
-        throw new Error(`Invalid --resolution value: ${value} (expected 720p|1080p)`);
+      if (!["480p", "768p", "2k", "4k", "720p", "1080p"].includes(value)) {
+        throw new Error(`Invalid --resolution value: ${value} (expected 480p|768p|2k|4k)`);
       }
       options.resolution = value;
       break;
     case "--frame":
       options.frameUrl = value;
       break;
+    case "--ref":
+      options.refs = [...options.refs ?? [], value];
+      break;
     case "--image":
       options.imageUrl = value;
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.10.3-dev.535",
+  "version": "1.10.4-dev.536",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -406,12 +406,15 @@ fight — the title in the display font is a finished title, not a stand-in:
   re-prompt the still against the new direction (or `--edit` it against the
   new reference) and re-run the video from the new still. Agent-initiated
   polish never does.
-- **The menu video renders 1080p by default — leave it alone.** Every video
+- **The menu video renders 768p by default — leave it alone.** Every video
   path, the frame-conditioned (`--frame`) menu route included, defaults to
-  1080p: the menu clip is full-screen key art, and 720p stretched across a
-  desktop reads soft. Don't pass a resolution flag at all; `--resolution 720p`
-  exists only as a deliberate cost opt-down for clips that are genuinely
-  incidental — never the main menu.
+  768p — the model's top NATIVE mode; `--resolution 2k` is an upscale of the
+  same base at ~2× the cost, worth it only if the menu still reads soft on a
+  large desktop. Don't opt DOWN: `--resolution 480p` exists for clips that are
+  genuinely incidental — never the main menu.
+- **The clip ships with a native audio track — keep the menu `<video>` muted.**
+  Autoplay requires `muted` anyway; menu music stays the `npx genex music`
+  track under the Music volume slider, not the clip's baked-in audio.
 - **Pause/victory/defeat variants reuse the same video — as GRADES.** Same
   `<video>` element or URL, different emotion via CSS `filter` on the
   background: pause = a plain dark overlay (`rgba(0,0,0,0.55)`); defeat =
@@ -439,12 +442,13 @@ fight — the title in the display font is a finished title, not a stand-in:
   frame: the seamless-loop mode. The URL must be one printed by `npx genex image`.
 - `--first-frame <url>` / `--last-frame <url>` (video) — two-frame mode for a
   genuine state change; expect a loop seam.
-- `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
-  default 8.
-- `--resolution <720p|1080p>` (video) — every path defaults to **1080p**, the
-  `--frame` menu route included. `720p` is the deliberate cost opt-down
-  (~half the credits) for incidental clips — not for the menu. Loop clips
-  (`--loop`) ignore it (that model has no resolution parameter).
+- `--duration <sec>` (video) — 5–15 for frame-conditioned clips; default 8
+  (menu loops read better long).
+- `--resolution <480p|768p|2k|4k>` (video) — every path defaults to **768p**
+  (the top native mode), the `--frame` menu route included. `2k` upscales for
+  ~2× the cost; `480p` is the cost opt-down for incidental clips — not for the
+  menu. Loop clips (`--loop`) ignore it (that model has no resolution
+  parameter).
 - `--aspect 16:9 --quality high` (image) — the right settings for a menu frame.
 - `--no-wait` — enqueue and return immediately with the generation id; pick
   the result up later with `npx genex wait <id>` (safe to re-run — it attaches

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

@@ -37,13 +37,17 @@ The clip lives in Genex storage (R2) and loads straight from that URL — you do
 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, 1080p** clip — the right default
-> for anything the player looks at directly. Only pass `--duration` when the content
-> genuinely needs to be longer (a cutscene), and `--resolution 720p` only when the
-> clip is genuinely incidental (a small in-world screen seen from a distance): it
-> halves the cost, but 720p stretched across the whole screen reads soft. mp4 has
-> **no alpha channel**, so a video is always a full rectangle (there are no
-> transparent video decals).
+> **Cost & length:** the default is a **5-second, 768p** clip (MiniMax H3's top
+> native mode) — the right default for anything the player looks at directly.
+> Only pass `--duration` when the content genuinely needs to be longer (5–15s;
+> a cutscene), `--resolution 2k`/`4k` only for hero shots (they upscale the
+> same native base and cost roughly 2–3×), and `--resolution 480p` only when
+> the clip is genuinely incidental (a small in-world screen seen from a
+> distance). Every clip carries a **native stereo audio track** (score, foley,
+> even dialogue) — in-game `<video>` elements autoplay muted, so unmute it only
+> when the sound is the point (a cutscene) and route it through the SFX volume
+> slider. mp4 has **no alpha channel**, so a video is always a full rectangle
+> (there are no transparent video decals).
 
 ## Play it in Three.js
 
@@ -133,15 +137,21 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 ## 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.
-- `--resolution 720p|1080p` — output resolution (default **1080p**). `--resolution
-  720p` halves the cost — use it only when quality genuinely doesn't matter (a small
-  far-away in-world screen). `--loop` clips ignore it (model default).
-- `--frame <url>` — one generated image as BOTH first and last frame — the
-  seamless-loop mode (motion must return to its start).
+- `--duration <sec>` — clip length 5–15; default 5. Only raise it when the content
+  genuinely needs more — clips bill per second.
+- `--resolution 480p|768p|2k|4k` — output resolution (default **768p**, the top
+  native mode). `2k`/`4k` upscale the same base for hero shots at ~2–3× the
+  cost; `480p` is the cost opt-down for genuinely incidental clips. `--loop`
+  clips ignore it (model default).
+- `--frame <url|file>` — one generated image (or a local file ≤4 MB) as BOTH
+  first and last frame — the seamless-loop mode (motion must return to its
+  start; the seam is mathematically exact).
 - `--first-frame <url>` / `--last-frame <url>` — two-frame motion between two
-  stills (a genuine state change; expect a loop seam).
+  stills (a genuine state change — a door opens, day turns to night).
+- `--ref <url|file>` — repeatable, up to 9 subject/style reference images.
+  Cite each in the prompt by its order: "Image 1 is the hero — she walks into
+  frame…". This is how the SAME character or art style holds across many clips
+  (a cutscene series, an episodic story). Cannot combine with `--frame`/`--loop`.
 - `--no-wait` — enqueue and return immediately, without the URL. Fire-and-forget
   only: re-running the command creates (and bills) a NEW video.
 - `--api-url <url>` — override the API base (local dev).
@@ -149,6 +159,23 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 Menu backdrops belong to `$genex-ai-menu`; a cohesive art-directed HUD sprite
 set belongs to `$genex-ai-hud` — both build on `npx genex image`/`video`.
 
+## Interactive video games
+
+Clips are cheap and fast enough to be a game's PRIMARY content, not just set
+dressing — an interactive movie (Detroit-style branching story), a generated-
+evidence detective game, a video-book. The pattern that makes it hold together:
+
+- **Branching scenes**: generate one clip per story node at build time, ship
+  the mp4 URLs in a scene-graph JSON, play them full-screen with DOM choice
+  buttons; preload the clips reachable from the current node while it plays.
+- **Visual continuity**: chain scenes with `--frame`/`--first-frame` so each
+  clip opens where the last one ended.
+- **Cast consistency**: give every scene the same `--ref` images of your
+  protagonist and key locations — the single biggest quality lever for any
+  multi-clip story.
+- Keep hard facts (dialogue you must control, exact text) in subtitles and
+  `npx genex voice` lines layered on top; the clip's own audio is atmosphere.
+
 ## Troubleshooting
 
 - **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).

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

@@ -18,6 +18,10 @@ npx genex video "candle flame flickering in the dark" --loop
 Blocks until ready, saves the mp4 into `./assets`, and prints the path. Wire the
 local path — a shipped build must never fetch the URL at runtime.
 
+Every clip carries a **native stereo audio track** (score, foley, ambience).
+Browsers only autoplay muted video, so keep the `<video>` element muted unless
+the sound is the point — and route it through your game's volume control.
+
 ## Animating a still
 
 The strongest results come from conditioning on an image you already approved,
@@ -33,9 +37,11 @@ npx genex video "camera drifts slowly forward, banners stirring" --frame ./asset
 
 ## Options
 
-- `--duration <sec>` — target clip length.
+- `--duration <sec>` — target clip length, 5–15 seconds (default 5; clips bill
+  per second).
 - `--loop` — a seamless loop.
-- `--resolution <720p|1080p>` — default 1080p. `720p` halves the cost, for clips where fidelity genuinely does not matter. Loop clips ignore it.
+- `--resolution <480p|768p|2k|4k>` — default 768p (the top native mode). `2k`/`4k` upscale the same base at ~2–3× the cost; `480p` is the opt-down for clips where fidelity genuinely does not matter. Loop clips ignore it.
+- `--ref <path|url>` — repeatable, up to 9 subject/style reference images, cited in the prompt as "Image 1"…"Image N" — the way one character or art style holds across many clips. Cannot combine with `--frame`/`--loop`.
 - `--open` — also open it in a browser, for something the user must approve.
 - `--out-dir <dir>` — where the file lands (default `./assets`).
 - `--no-download` — print the URL only.