@genex-ai/cli-demo 0.78.1-dev.203 → 0.80.2-dev.213

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

@@ -1,266 +0,0 @@
----
-name: genex-threejs-skill-router
-description: Route Genex 3D browser-game work to the smallest useful Three.js skill set. Use for new game scenes, graphics upgrades, visual reference matching, game-feel passes, render-pipeline work, publishing readiness, multiplayer-aware scene architecture, or requests spanning cameras, geometry, materials, atmosphere, water, VFX, lighting, shadows, post-processing, and validation.
----
-
-# Genex Three.js Skill Router
-
-Use this skill first for broad 3D browser-game requests. Load only the skills
-that change the result; do not load the whole pack by default.
-
-Read [references/routing-map.md](references/routing-map.md) for the full routing
-map, execution order, and acceptance gate.
-
-## Route by system
-
-| Work needed | Load |
-| --- | --- |
-| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
-| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
-| a custom generated playable humanoid or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, explicit candidate + 10k-remesh approvals, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
-| the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
-| playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |
-| phone-survivable rendering — device tiers, DPR/shadow/post budgets, the runtime quality governor, per-tier asset rungs for generated skyboxes/textures, the Quality picker, dispose-on-swap discipline — **mandatory for every game at boot wiring** | `$genex-threejs-adaptive-quality` |
-| anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
-| launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |
-| reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
-| atlas-filtered blocks, planetary surfaces, terrain wetness, lava/emissive procedural surfaces, authored frame PBR, specular AA | `$genex-threejs-procedural-materials` |
-| sculpted rails/frames, branch rings, semantic mesh writers, material groups | `$genex-threejs-procedural-geometry` |
-| trees, stylized grass, GPU-computed grass fields, branching organisms, roots, foliage, rooted wind deformation | `$genex-threejs-procedural-vegetation` |
-| buildings, façade grammars, profiles, ornaments, modular mesh writers | `$genex-threejs-procedural-architecture` |
-| planets, terrain, craters, biome fields, coastlines, spherical detail | `$genex-threejs-procedural-planets` |
-| sky scattering, planetary shells, depth-based aerial perspective | `$genex-threejs-atmosphere-aerial-perspective` |
-| weather-driven raymarched clouds and cloud shadows | `$genex-threejs-volumetric-clouds` |
-| hero open-water FFT oceans (expensive — only when open water IS the game): spectral cascades, hybrid FFT/Gerstner clear water, choppy derivatives, Jacobian whitecaps | `$genex-threejs-spectral-ocean` |
-| **default water**: an ocean, sea, lake, river, or pool the game plays on or around — authored analytic waves, bounded heightfield pools, object ripples, differential-area caustics, shared normals, heuristic refraction, fallback absorption, crest foam | `$genex-threejs-water-optics` |
-| falling snow, snow accumulation, model snow caps, wet asphalt puddles, procedural ripple normals, splash flipbooks, rain streaks, shared weather envelopes, surface wetness | `$genex-threejs-precipitation-surfaces` |
-| curved-ray black holes, accretion disks, wormholes | `$genex-threejs-raymarched-space-effects` |
-| particles, trails, plasma, shockwaves, layered event effects | `$genex-threejs-procedural-vfx` |
-| accumulated screen frost, touch clearing, reduced blur, and refraction masks | `$genex-threejs-temporal-surfaces` |
-| the light rig and where light belongs: sun/moon key, practical lights (campfire, torch, neon, lava), emissive-to-light coupling, light shafts and visible beams, fog mood, light signals, flicker, a scene that reads flat or uniformly lit | `$genex-threejs-lighting-design` |
-| stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
-| GTAO, bent normals, bilateral reconstruction | `$genex-threejs-screen-space-ambient-occlusion` |
-| HDR bloom and selective emission contribution | `$genex-threejs-bloom` |
-| 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` |
-| game content named in the plural or a content genre: quests, objectives, NPCs, dialogue, shops, inventory, loot, XP/progression, an RPG/adventure/story game — **mandatory whenever the ask names content**, and its content contract is written before the asset batch | `$genex-threejs-game-content` |
-| a big/open world: kilometers of terrain, multiple regions or locations, exploration, points of interest, biomes, world streaming | `$genex-threejs-open-world` |
-| 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` |
-
-**Identity is mandatory routing:** every Genex game ships with the embed SDK — load
-`$genex-threejs-embed-auth` unconditionally before writing boot code (it wires
-`initEmbed(...)` and the `waitForPlayer()` gate), and route to it whenever the task
-mentions sign-in, saves, progress, per-player state, a persistent world, or
-leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
-
-**Adaptive quality is mandatory routing:** every game wires the device tier at
-boot — `$genex-threejs-adaptive-quality` (three lines: `detectTier()` before the
-renderer, tier-capped `setPixelRatio`, the governor in the loop; generated
-skyboxes/textures load through their rungs). Phones enforce a hard GPU-memory
-kill desktops never show you; the tier is what keeps a phone boot alive while
-desktop keeps the full look. This is a completion gate like the post stack —
-cheap to wire, not a new testing burden (desktop-only verification stands).
-
-**Character-animation routing:** use the existing VRM + UAL character
-controller by default. Use `npx genex character` when the game needs a custom
-generated humanoid or an action unavailable in UAL. Before generating a Meshy
-character, discuss two or three visual directions. When the user names a visual
-reference, inspect references before writing the concept prompt. Recommend a
-neutral A-pose for characters that will be rigged.
-
-Generate concept images first and show the actual images to the user. Do not
-start Image-to-3D until the user explicitly selects a candidate. Generate
-exactly three concepts, all neutral A-pose; never use a dynamic concept pose or
-silently fall back to T-pose. Warn that held, slung, or overlapping props and
-straps can fuse into the body or obscure limbs, and recommend separate gameplay
-props.
-
-Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
-front, back, left, and right views and report its measured face count. Preserve
-that model in R2. Before rigging, ask the user to approve a separate
-10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
-rigged and animated. Keep every pre-animation generation in the selected
-neutral A-pose.
-
-Load `$genex-ai-character`, search Meshy actions first with
-`npx genex animations search "<intent>" --json`, and use returned action IDs;
-never invent IDs. Meshy limb rotations play unchanged. Never freeze hand tracks
-or apply post-mixer arm, hand, leg, or foot corrections. Only horizontal root
-or hip translation may be normalized for Rapier. In both lanes, the
-ECCTRL-derived character controller owns collision and world translation.
-
-**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 frame-anchored Tier-2 generations
-(cinematic menu, sprite HUD) are enqueued async (`--no-wait` + `npx genex wait
-<id>`) the moment the user approves the concept, so they land while the game is
-being built — they never block a playable v0, and the game is
-not done, published, or handed off until they've been picked up (`npx genex wait`)
-and wired in.
-
-**Content is mandatory routing when the ask names it:** if the request names
-game content in the plural — quests, enemies, bosses, locations, spells, items,
-factions — or a content genre (an RPG, an adventure, an open world, a story
-game), load `$genex-threejs-game-content` and write its **content contract**
-into the same plan message as the UI gate, BEFORE the asset batch: every
-plural noun of the request becomes a countable line (how many quests and what
-chain, which locations, what progression), plus the minute-ten answer. Those
-lines are hard floors exactly like the sprite HUD — the game is not done,
-published, or handed off while a contract line is missing, and shrinking one
-is a structured question to the user, never a silent cut ("vertical slice
-first" is a build order, not a smaller destination) — use your environment's
-structured question tool when it has one (Claude Code: `AskUserQuestion`;
-Codex: `request_user_input`); if it has none (e.g. Cursor), a short numbered
-list in chat. A request that says
-**big/open world** also loads `$genex-threejs-open-world` and fixes the
-world's scale as a number in the same plan — world size comes from streamed
-terrain, never from fog hiding the edges of a small plane. This routing
-exists because the failure it prevents is invisible to every visual gate: a
-"Skyrim-like big world with quests" can pass every look floor as a
-300-meter single-quest vignette.
-
-**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 — read off the concept frame's OWN look (the grade, bloom
-level, haze, grain it already shows) and which post the 2–3 AAA references lean
-on, not a default single bloom; ONE built render-pass effect is the FLOOR
-against no-post for EVERY game, never the target — ship the richness the concept
-implies. The floor is TIER-AWARE (`$genex-threejs-adaptive-quality`): on phone
-tiers it is satisfied by the built tone-mapping/output pass with the light
-additions the tier allows (FXAA/vignette), while the full named stack remains
-the desktop floor — never ship the heavy stack undropped to phones (the UI
-vignette div or a CSS canvas filter does not count on any tier;
-`$genex-threejs-image-pipeline` owns ordering when 2+ compose), a decision for
-**every primitive surface** the game builds — walls, barriers, kerbs and
-platforms each get a real texture or a **shader** where that surface wants motion
-or energy (a pulsing force barrier, an electric fence, a scrolling hazard strip),
-judged one by one: a shader that gives a barrier life earns its place, the same
-effect everywhere disfigures, deliberate flat black is valid if you say so — but
-a flat-colour box beside textured geometry is the "stopped halfway" tell
-(`$genex-threejs-procedural-materials` / `$genex-threejs-procedural-vfx`, and SEE
-it in the running game), one named
-**ambient-motion loop** that keeps
-the scene alive at rest (emissive pulse, shimmer, drifting dust — shader
-work, zero generations), and the lighting/atmosphere mood from that
-same brief — walked source by source, every light with a visible cause
-(`$genex-threejs-lighting-design` owns that gate). 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
-a room `host` (scores, enemies). Choose the net model from the player experience before coding:
-`connect()` is one ongoing drop-in world; `matchmake()` forms capped rooms for fresh matches or
-missions with quorum/fair-start/backfill rules. Infer it when clear; ask one plain-language
-ongoing-world-vs-fresh-session question only when both experiences genuinely fit. A Play/Online
-button is always the commitment point for either API; only a truly always-online `connect()` world
-may join/spawn immediately, and then it must not show a fake Play screen. Only `matchmake()` requires
-a server-owned `genex.matchmaking` block in `package.json`, reported by preview/publish. Both models
-accept a fresh auth supplier, but their terminal-recovery duties differ, so follow the chosen model's
-section rather than mixing the two. Run that skill's netcode feel gate before handoff. The skill also
-covers the rules that keep it smooth and its per-genre 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, 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 |
-| --- | --- | --- |
-| a specific prop / item / non-playable static figure / vehicle body as a real mesh | `npx genex model "<prompt>"` | `$genex-ai-model` |
-| a custom generated playable humanoid with a rig and controller-ready animation pack | `npx genex character "<prompt>"` | `$genex-ai-character` |
-| 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
-**`npx genex` generators** for concrete, describable, photoreal assets. They complement
-each other.
-
-**Generate a core asset set by default — don't wait to be asked.** For any game that
-needs concrete objects or surfaces, decide a small core set from the game IDEA and start
-generating it **up front, in parallel** — this set is concept-INDEPENDENT (prompted from
-the idea, not the concept image, and it mostly survives a style change), so it does NOT
-wait on the concept yes (each `npx genex` is an independent ~1-minute
-job — launch them concurrently in the background, then scaffold the scene while they run
-and wire each asset in as it lands, with a procedural placeholder as fallback until then):
-
-- the **hero model** the player controls or chases (`npx genex model`),
-- one key **texture** for the ground/main surface (`npx genex texture --terrain` for ground),
-- a **skybox** when the scene is outdoors (`npx genex skybox`),
-- a **sfx** or two for the core action/feedback (`npx genex sfx`).
-
-Skip generation only for purely abstract/geometric games. Keep the set small and
-concept-driven — a richer first build beats a grey-box one.
-
-## Routing rules
-
-- Start from the playable game target: player verb, scene scale, camera distance,
-  input mode, and frame budget.
-- Pointer bucket (decide before building, state it in the plan): the bundled
-  `FollowCamera` locks the pointer by default on desktop, so this is mostly a
-  decision to opt OUT. **mandatory pointer lock** — first-person of any kind, and
-  any mouse-aimed action (third-person shooter, turret/range); leave it on.
-  **Lock by default** — third-person free-camera action/adventure; on already,
-  drag-orbit (`pointerLockAim: false`) only with a stated reason (e.g. a
-  cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
-  defense, builder, card/puzzle), orbit showcases, touch-only; these MUST pass
-  `pointerLockAim: false`. Keyboard-only games (racer, platformer) lock too —
-  the cursor is either a gameplay tool or locked away during play. The mechanism
-  and the full aim contract live in `$genex-threejs-camera-direction`.
-- Input direction (always — every game that moves with keys or pointer):
-  D/ArrowRight must move or turn the player screen-RIGHT, mouse-right must turn
-  the view right, drag-pan axes share one convention. The screen-direction
-  contract and verified copy-paste bases live in
-  `$genex-threejs-camera-direction` — hand-rolled steering/pan/look math copies
-  one instead of deriving signs, and the smoke check's input-direction pass
-  verifies it.
-- 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.
-- Use `$genex-threejs-visual-validation` before declaring graphics/procedural-system
-  work done. **Game fast path:** for game tasks that loaded no procedural/visual-system
-  skill, done = a screenshot plus an interaction smoke check (load the page, press each
-  control, see the visible response in its labeled direction) — don't run the full diagnostic gate — PLUS the
-  floors from the routing-map's acceptance gate: the generated sprite HUD wired in
-  (not the CSS placeholder), pause on Escape, the branded loader with its key-art
-  background, the brief's fonts actually loaded, the renderer baseline + at least one
-  built render-pass effect, every placed 2D/media piece screenshot-verified in
-  situ, no UI element left as default browser CSS, and no placeholder primitive
-  left where a generated asset was planned. These floors gate `npx genex publish`
-  and the final handoff of a session the
-  same way — they do not wait for the word "done" to be said.
-- Entering an **existing or remixed project**: read before writing — learn the
-  current renderer choice, physics setup, and file conventions first, then
-  extend them. Don't rebuild working systems or switch renderers mid-project.
-- For three.js APIs **not covered by any skill here**, consult the official
-  three.js documentation (https://threejs.org/docs/) rather than guessing —
-  the skills cover Genex-specific and hard-won patterns, not the whole engine.