@genex-ai/cli-demo 0.47.0-dev.71 → 0.47.0-dev.74

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

@@ -1,15 +1,80 @@
 ---
 name: genex-threejs-game-ui
-description: Design the 2D interface of a Genex Three.js game — HUD, menus, pause/win/lose screens, score and health displays, overlays, loading screens, and UI state flow. Use whenever the game needs on-screen text, meters, buttons, or menus, or when the interface reads as a generic dashboard, covers the action, or shifts around as numbers change.
+description: Design the 2D interface of a Genex Three.js game — plan the full screen set up front (loader, menu, HUD, pause/win/lose, lobby) under one shared art direction, then build it as an animated DOM overlay. Use for every new game before writing UI code, and whenever the game needs on-screen text, meters, buttons, or menus, or the interface reads as a generic dashboard, covers the action, or shifts as numbers change.
 ---
 
 # Genex Three.js Game UI
 
-The interface is part of the game, not chrome around it. A strong HUD tells the
-player what to protect, what to chase, and what just happened — without ever
-stealing attention from the scene. This skill covers the 2D layer of a vanilla
-Three.js game: architecture, the states every game needs, readability rules,
-and wiring UI to game state.
+The interface is part of the game, not chrome around it. A strong UI layer tells
+the player what to protect, what to chase, and what just happened — and it moves:
+screens fade and stagger in, values tween, defeat feels different from victory.
+This skill is the UI director for the 2D layer of a vanilla Three.js game: the
+plan, the architecture, the states, motion, and readability rules.
+
+## Plan the UI first — before any UI code
+
+Run this gate ONCE, right after the game concept is locked. It takes two
+minutes and prevents the two failure modes no later polish can fix: a screen
+set discovered piecemeal, and a menu styled in one world while the HUD lives
+in another.
+
+**1. Screen inventory — derived from the game type, not discovered later:**
+
+| Screen | When it exists | Default tier |
+| --- | --- | --- |
+| Loader | always | 1 — branded (see loader spec below) |
+| Main menu | always for a game headed to publish | 2 — cinematic (`$genex-ai-menu`); 1 for a quick prototype |
+| Pause | always | 1 — menu backdrop under a dark overlay |
+| Fail / retry | always | 1 — a *graded* variant of the menu screen |
+| Win / next | always | 1 — graded variant, warm |
+| Settings | when there is anything to set | 1 |
+| Lobby / waiting | multiplayer only | 1 over the menu backdrop |
+| HUD | always | 1 CSS; 2 (`$genex-ai-hud`) when the identity earns it |
+
+The lobby row is bound by `$genex-threejs-multiplayer`'s MANDATORY rule: the
+waiting overlay's visibility is re-read from `mm.matchmaking.status` every
+frame and closes the instant it flips to `playing` — verified in two browser
+windows. Plan the lobby as a styled screen (roster + count over the menu
+backdrop), not an afterthought `<div>`.
+
+**2. One shared style brief — for the WHOLE game, not just the UI.** Write it
+once — 4–5 named hues, materials, one display + one body font, mood — and
+store it as a comment block near the UI code. `$genex-ai-menu`,
+`$genex-ai-hud`, the loader, and every plain-CSS screen consume THIS brief
+verbatim — and so does the scene: the visual-direction plan (the router's
+next gate) derives its lighting mood, fog, grading, and post-stack choices
+from the same block. Two style briefs in one game is a bug; a scene graded in
+one world under a UI styled in another is the same bug.
+
+**3. Name your references.** Pick the closest capsule in
+[references/style-capsules.md](references/style-capsules.md), name 2–3 top
+games of the genre, and state in one line which structural conventions you're
+borrowing. Conventions only — never logos, exact layouts, or trade dress.
+
+**4. Ask only when genuinely ambiguous.** If the concept pins the mood (a
+"gothic horror dungeon crawler" pins it), decide and state the plan in one
+line. Only when the art direction is truly open, ask ONE structured question
+(your environment's `AskUserQuestion`-style tool) with 2–3 concrete directions,
+each naming its palette + font pair. Never ask about the screen inventory —
+it derives from the game type.
+
+**5. Style follows THIS game's concept.** The examples in every Genex skill
+are examples, not defaults. Do not default to neon/cyberpunk/synthwave — or
+any other single register — unless the concept calls for it.
+
+## The tier ladder
+
+- **Tier 1 — instant baseline, every game.** Everything in this skill: planned
+  screens, shared brief, branded loader, animated CSS menu with keyboard
+  navigation, phase transitions, UI sounds, vignette. Zero generations — the
+  game is playable immediately.
+- **Tier 2 — generated upgrades, async.** The cinematic menu video
+  (`$genex-ai-menu`) and the sprite HUD (`$genex-ai-hud`). Enqueue with
+  `--no-wait`, keep building, pick results up with `npx genex wait <id>`, swap
+  them in as they land. **Tier 2 must never block a playable v0.**
+- **Tier 3 — offer, don't build.** Video layers over the HUD, 9-slice panel
+  sprites, a generated logotype, animated menu sprites. Offer in one line
+  after the player has seen Tier 1+2 working; build on request.
 
 ## Architecture: DOM overlay by default
 
@@ -43,8 +108,8 @@ exception for things that belong to the world, not the default.
 Build these as show/hide layers over one state machine, not as ad-hoc DOM
 edits scattered through the code:
 
-1. **Loading** — visible until assets are ready; players must never stare at a
-   black screen. Even "Loading… 3/5" over the dark background is enough.
+1. **Loading** — the branded loader below; players must never stare at a black
+   screen or a bare percentage.
 2. **Playing HUD** — the minimal always-on layer (see hierarchy below).
 3. **Pause** — freeze the loop, dim the scene, show resume/restart. (With the
    bundled physics pack, freezing is built in: `physics.paused = true` plus
@@ -59,6 +124,67 @@ edits scattered through the code:
    HUD state come from `$genex-threejs-multiplayer`; render what the SDK
    reports, don't guess at it.
 
+## The loader
+
+The loader is the first thing every player sees — a bare "Loading… 3/5" over
+black reads as a broken page. The branded version costs nothing:
+
+- **Background:** the menu's still frame — when the game has a cinematic menu,
+  that image exists BEFORE the video does; show it dimmed
+  (`filter: brightness(0.6)`) behind the progress. Menu-less game: one
+  `npx genex image` key-art call in the house style, enqueued first thing.
+  Until the image arrives, the flat darkest hue from the style brief.
+- **Progress:** a thin bar styled from the brief (its accent hue), driven by
+  real asset counts — never an indeterminate spinner alone.
+- **Reveal:** when ready, fade the loader out (400–600 ms) into the menu or
+  game. No hard cut.
+
+## Motion — screens move or the game feels dead
+
+Phase changes animate. `hidden` alone hard-cuts; pair it with a class so
+opacity can transition:
+
+```ts
+function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
+  for (const s of document.querySelectorAll<HTMLElement>("#ui .screen")) {
+    const on = s.dataset.phase === phase;
+    s.classList.toggle("is-on", on);
+    if (on) s.hidden = false;                       // show immediately, then fade in
+    else setTimeout(() => { if (!s.classList.contains("is-on")) s.hidden = true; }, 300);
+  }
+}
+```
+
+```css
+#ui .screen { opacity: 0; transition: opacity 280ms ease; }
+#ui .screen.is-on { opacity: 1; }
+
+/* Entrance choreography: title first, buttons staggered, corner text last.
+   Stamp --i per element: <button class="stagger" style="--i: 1"> … */
+.screen .stagger { opacity: 0; transform: translateY(12px);
+                   transition: opacity 320ms ease, transform 320ms ease;
+                   transition-delay: calc(var(--i, 0) * 70ms); }
+.screen.is-on .stagger { opacity: 1; transform: none; }
+```
+
+- **Defeat and victory are grades, not new screens.** Same backdrop, different
+  emotion via CSS `filter` on the background — defeat
+  `saturate(0.25) brightness(0.55)` with a ~600 ms beat before buttons stagger
+  in; victory `saturate(1.15) brightness(1.05)` with the score counting up
+  (tween the displayed number over ~800 ms; never snap it).
+- **Buttons react**: a hover/focus state (scale, glow, or an indicator chevron)
+  plus a pressed state. Menus are keyboard-first — ↑/↓ moves focus, Enter
+  activates, and the hovered/focused item is visibly selected.
+- **Values tween.** Score, coins, timers tick to their new value; health bars
+  slide. A number that teleports reads as a bug even when it's correct.
+
+## Sound — a silent UI is a bug
+
+Hover tick, confirm click, and a fail/win stinger are three
+`npx genex sfx` calls (`$genex-ai-sfx`); a cinematic menu also wants a quiet
+ambient loop, because its video is necessarily muted. Wire hover sounds to
+`mouseenter`/`focus` (throttled), keep them short and quiet.
+
 ## Hierarchy: if everything shouts, nothing reads
 
 Order the HUD by what the player loses the game for ignoring:
@@ -79,6 +205,10 @@ Order the HUD by what the player loses the game for ignoring:
 - **Contrast against the real scene.** Test text over the brightest AND
   darkest areas of actual gameplay; a soft dark plate or text-shadow beats
   restyling per level.
+- **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`.
 - **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: when a bundled controller (character/car/drone) is
@@ -94,26 +224,27 @@ timer in the game WILL drift apart). Buttons and menu keys emit the same
 intents the gameplay input path uses — a "Restart" button and the R key must
 run identical code.
 
-```ts
-// Each .screen carries data-phase (see the HTML block above); the names must match exactly.
-function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
-  for (const s of document.querySelectorAll<HTMLElement>("#ui .screen"))
-    s.hidden = s.dataset.phase !== phase;
-}
-```
-
-UI sounds (clicks, confirms, win stingers) are one `npx genex sfx` away — see
-`$genex-ai-sfx`.
+When the game deserves generated art in this layer: a cinematic menu (looping
+video backdrop behind the buttons) is `$genex-ai-menu`; an art-directed HUD
+built from a generated sprite set is `$genex-ai-hud`. Both slot into this
+exact `#ui` + `data-phase` architecture and consume the shared style brief.
 
 ## Failure modes to catch before the player does
 
+- No UI plan: screens invented one at a time, menu and HUD styled in two
+  different worlds.
 - A generic stat dashboard (rows of labels + numbers) instead of a designed
   HUD — pick the 2–3 numbers that matter and style them by hierarchy.
+- Hard-cut phase swaps, a menu whose elements just appear, numbers that
+  teleport.
+- A silent menu; a bare "Loading…" over black.
 - UI panels covering the player or the thing about to kill them.
 - Layout shifting as numbers grow.
 - A fail state with no visible restart key, or a restart that reloads the page.
 - Buttons that render but don't emit the game's real input intents.
 - UI logic duplicating game rules and drifting out of sync.
+- A waiting/lobby overlay that can miss its dismissal — see the multiplayer
+  skill's status-driven rule.
 
 Before calling UI done, check it over real gameplay footage at desktop size —
 `$genex-threejs-visual-validation` has the capture discipline.

package/templates/skills/genex-threejs-game-ui/references/style-capsules.md

@@ -0,0 +1,89 @@
+# Style capsules — top-tier UI conventions by genre
+
+How to use: pick the capsule closest to the game, name 2–3 top games of the
+genre yourself (you know them), and state in one line which structural
+conventions you're borrowing. Borrow **conventions** — placement, hierarchy,
+type treatment, material language. Never logos, exact layouts, or a specific
+game's trade dress. Then write the shared style brief in the game's OWN world:
+the capsule says a racing HUD leans oblique and bottom-right-heavy; your brief
+says what it's made of in THIS game.
+
+Every capsule below assumes the base rules from the skill: corners/edges for
+UI, one display + one body font, tabular numerals, contrast plates over
+arbitrary scenes.
+
+## Fantasy / action RPG
+
+- Survival cluster anchored to the bottom corners or bottom-center (orbs,
+  framed bars); ability/item hotbar bottom-center; quest/objective text
+  top-right, quiet.
+- Ornament lives on widget FRAMES (metal, carved wood, parchment edges) —
+  never as full-screen ambient texture.
+- Serif or engraved display type; humanist body; muted earthy palette with ONE
+  saturated accent reserved for danger/low-health.
+- Feedback is material: gold glints on pickup, red vignette pulse on damage.
+
+## Clean sci-fi / space
+
+- Hairline strokes (1px), thin geometric panels, generous empty space between
+  widgets; data clusters hug the screen edges.
+- Uppercase display type with wide letter-spacing; small caps or condensed
+  body; monochrome (near-white on near-black) plus a single accent hue.
+- Panels read as glass: slight transparency, subtle inner glow, no drop
+  shadows heavier than a whisper.
+- Motion is precise and quick (120–200 ms), no bounce.
+
+## Racing / arcade sport
+
+- Speed/tacho cluster bottom-right — one huge numeral, small unit label;
+  position/lap counter top-left; the top edge stays nearly empty (the road is
+  the point).
+- Oblique/italic display type reads as speed; chunky high-contrast chips for
+  position and lap deltas.
+- Saturated team/brand hues are fine — but two, not six.
+- Values tween FAST (speed) or pop (position change); a gear change may
+  flash — a full-screen flash may not.
+
+## Military / modern shooter
+
+- Ammo bottom-right (large current mag / small reserve), health bottom-left,
+  compass strip top-center, hit markers at the crosshair.
+- Stencil or condensed grotesque display; desaturated palette — amber/red
+  exist ONLY as warnings, so they still mean something.
+- Damage reads as a directional vignette, not a number cloud.
+
+## Horror
+
+- The strongest HUD is almost none: surface health/resources on change, then
+  fade them away; keep permanent chrome minimal and dim.
+- Typewriter, worn serif, or handwriting display type; heavy vignette and
+  grain in the cohesion layer.
+- UI motion is slow (400 ms+) and quiet; a sudden UI move is itself a scare —
+  spend it deliberately.
+
+## Retro / 8-bit
+
+- Pixel font at INTEGER scales only, hard edges — no anti-aliasing, no blur,
+  no gradients; 4–8 color palette total, chosen once.
+- Score top-left or top-center, lives as repeated icons — conventions players
+  already know; lean on them.
+- Motion is stepped (frame-quantized), not eased; an optional scanline overlay
+  in the cohesion layer sells it.
+
+## Cozy / casual
+
+- Rounded shapes, soft single-direction shadows, cream/pastel palette with one
+  warm accent; big friendly numerals.
+- Buttons are plump and obviously pressable; transitions bounce slightly
+  (scale 0.95 → 1.02 → 1) instead of fading.
+- Nothing flashes red; even failure is gentle (desaturate + a soft "try
+  again").
+
+## Painterly / stylized adventure
+
+- UI elements read as brushwork: irregular edges, hand-drawn frames, paper or
+  canvas texture on PLATES (not full-screen).
+- A display face with calligraphic character; body stays clean for
+  readability.
+- Palette lifted from the scene's own key art — sample it, don't invent a
+  second palette.

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

@@ -40,7 +40,9 @@ map, execution order, and acceptance gate.
 | eye adaptation, tone mapping, LUT grading, output color | `$genex-threejs-exposure-color-grading` |
 | shared depth/normal/velocity ownership and multi-pass ordering | `$genex-threejs-image-pipeline` |
 | fixed-view diagnostics, seed sweeps, temporal and budget evidence | `$genex-threejs-visual-validation` |
-| HUD, menus, pause/win/lose screens, score and health displays, overlays, loading screens, on-screen text and buttons, UI state flow | `$genex-threejs-game-ui` |
+| the 2D interface — HUD, menus, pause/win/lose screens, loaders, lobby, on-screen text and buttons, UI state flow — **mandatory for every game**, and its "Plan the UI first" gate runs right after the concept is locked | `$genex-threejs-game-ui` |
+| a cinematic menu — main menu/title/pause/victory/defeat/lobby/credits with a looping generated video backdrop behind DOM buttons | `$genex-ai-menu` |
+| a cohesive art-directed HUD — generated sprite set (matched frames, masks, icons in one style) wired with masked fills | `$genex-ai-hud` |
 | the game works but feels flat, floaty, or unresponsive: input response, acceleration curves, camera shake, hit feedback, hitstop, cooldowns, difficulty ramp, fail/retry loop | `$genex-threejs-game-feel` |
 | realtime multiplayer: movement sync, a shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
 | player identity, sign-in, guests, saves/progress, per-player state, a shared persistent world, leaderboards — **mandatory for every game** | `$genex-threejs-embed-auth` |
@@ -51,6 +53,23 @@ map, execution order, and acceptance gate.
 mentions sign-in, saves, progress, per-player state, a persistent world, or
 leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
+**UI is mandatory routing:** every game has an interface — load
+`$genex-threejs-game-ui` for every NEW game and run its "Plan the UI first" gate
+(screen inventory, one shared style brief, tier decisions) right after the game
+concept is locked, before any UI code. Its Tier-2 generations (cinematic menu,
+sprite HUD) are enqueued async (`--no-wait` + `npx genex wait <id>`) so they land
+while the game is being built — they never block a playable v0.
+
+**The look is planned up front too:** right after the UI gate, lock the visual
+direction in the same plan block — the camera rig + pointer bucket
+(`$genex-threejs-camera-direction`), the renderer baseline (tone mapping,
+exposure, output color space — set deliberately at boot; stock three.js
+defaults are not a look, `$genex-threejs-exposure-color-grading`), the post
+stack this game ships and deliberately skips (bloom/AO/grade — justified by
+the shared style brief; `$genex-threejs-image-pipeline` owns ordering when 2+
+compose), and the lighting/atmosphere mood from that same brief. Planning is
+not building — effects still land last in the execution order.
+
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
 remote players **and shared objects**, and gives you server-enforced object ownership (a ball) and
@@ -106,9 +125,16 @@ concept-driven — a richer first build beats a grey-box one.
   cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
   defense, builder, card/puzzle), orbit showcases, touch-only. The mechanism and
   the full aim contract live in `$genex-threejs-camera-direction`.
+- Art direction follows THIS game's concept. The style examples inside skills
+  are examples, not defaults — never default to neon/cyberpunk/synthwave (or any
+  other single register) unless the concept calls for it.
 - Build silhouette, motion, and material readability before adding image effects.
   Never dress a primitive shape in glow or bloom to fake quality — authored
   forms first, then materials, then lighting, then effects last.
+- Set the renderer baseline deliberately at boot — tone mapping, exposure,
+  output color space (`$genex-threejs-exposure-color-grading`). A game that
+  ships on stock defaults hasn't chosen a look; a game that stacks post
+  effects it never planned has chosen several.
 - Prefer deterministic seeds and named controls for every procedural system.
 - Keep game logic, simulation state, visual fields, and screen-space passes
   separated unless coupling is intentional.

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

@@ -20,29 +20,49 @@ Three.js release or branch, and do not blindly copy demo architecture.
 2. Wire player identity before any boot code: `$genex-threejs-embed-auth` is
    mandatory for every game (`initEmbed(...)` + the `waitForPlayer()` gate) —
    saves, leaderboards, and multiplayer auth all come from it.
-3. Wire the gameplay layer for the player verb: the physics world via
+3. Run `$genex-threejs-game-ui`'s "Plan the UI first" gate: screen inventory,
+   one shared style brief, a tier per screen. Enqueue any Tier-2 UI
+   generations now with `--no-wait` (pick them up later with
+   `npx genex wait <id>`) — they render server-side while you build the game.
+4. Lock the visual direction — the same plan-first logic as the UI gate, in
+   the same plan block, before any rendering code:
+   - **camera**: the rig type and the pointer bucket
+     (`$genex-threejs-camera-direction` — the bucket decision is mandatory);
+   - **renderer baseline**: tone mapping, exposure, and output color space set
+     deliberately at boot (`$genex-threejs-exposure-color-grading` owns the
+     staging — stock three.js defaults are not a look);
+   - **the post stack**: which image effects THIS game ships (bloom? AO?
+     grade?) and which it deliberately doesn't — each named and justified by
+     the shared style brief; when 2+ effects compose,
+     `$genex-threejs-image-pipeline` owns the pass ordering;
+   - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
+     wrote — one art direction across scene and UI.
+   Planning is not building: effects still land LAST (steps 10–11); this step
+   only fixes the target so the look isn't improvised pass-by-pass at the end.
+5. Wire the gameplay layer for the player verb: the physics world via
    `$genex-threejs-physics-rapier` when anything falls, collides, or gets
    pushed; on-foot movement via `$genex-threejs-character-controller`;
    driving/flying and character↔vehicle enter/exit via
    `$genex-threejs-vehicle-controllers`.
-4. Select the minimum scene-generation skills: geometry, materials, vegetation,
-   architecture, planets, water, precipitation, clouds, or VFX. Show a loading
-   overlay from the very first asset load — a player must never stare at a black
-   screen; the rest of the UI states come at step 10.
-5. Add camera direction when framing, controls, transitions, or scale perception
-   affect play — or the game aims with the mouse (shooter/FPS/turret): pointer-lock
-   bucket decisions live there.
-6. Add procedural animation when object motion needs authored phases,
+6. Select the minimum scene-generation skills: geometry, materials, vegetation,
+   architecture, planets, water, precipitation, clouds, or VFX. Show the
+   planned loader from the very first asset load — a player must never stare
+   at a black screen; the rest of the UI states come at step 12.
+7. Add camera direction when framing, controls, transitions, or scale perception
+   affect play — or the game aims with the mouse (shooter/FPS/turret): the
+   step-4 bucket decision executes here.
+8. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
-7. Add shared fields before writing multiple independent noise layers.
-8. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
-9. Add image-pipeline, bloom, exposure, grading, or AO last.
-10. Once the loop is playable, wire the interface states via
+9. Add shared fields before writing multiple independent noise layers.
+10. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
+11. Add image-pipeline, bloom, exposure, grading, or AO last — building out the
+    step-4 post plan, not inventing one now.
+12. Once the loop is playable, build the planned interface states via
     `$genex-threejs-game-ui` (HUD, pause, fail/retry, win, and the full loading
-    state grown from the step-4 overlay) and run a feel pass via
-    `$genex-threejs-game-feel` (input response, camera, impact feedback, retry
-    speed).
-11. Validate in a real browser with fixed seeds, captures, interaction checks,
+    state grown from the step-6 loader), swap in any landed Tier-2 UI assets,
+    and run a feel pass via `$genex-threejs-game-feel` (input response, camera,
+    impact feedback, retry speed).
+13. Validate in a real browser with fixed seeds, captures, interaction checks,
     and performance evidence.
 
 ## Acceptance gate