@genex-ai/cli-demo 0.93.0 → 0.94.0-dev.249

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

@@ -131,7 +131,7 @@ and re-link the clone to the same live game:
 ```bash
 git clone <the game's repo url> my-game && cd my-game
 npm install
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 ```
 
 Don't know the slug? **`npx genex list`** prints every game on your account —
@@ -158,7 +158,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

package/templates/skills/genex-threejs-exposure-color-grading/SKILL.md

@@ -18,10 +18,6 @@ HDR scene
   → final output conversion
 ```
 
-Read [references/exposure-grading.md](references/exposure-grading.md)
-for the exact 64x36 meter, encoded readback, adaptation constants, 32-cube LUT,
-and signal-ownership ambiguities.
-
 ## Film grain — add it only if the look calls for it, and author it correctly
 
 Film grain is a legitimate look. **Badly-authored grain is the single most common
@@ -89,6 +85,6 @@ c += g * uGrain * lw;                        // uGrain ~0.02–0.03, NOT 0.045
 
 ## Routing boundary
 
-Use `$genex-threejs-bloom` for HDR glow contribution and
-`$genex-threejs-image-pipeline` when this color path must share ownership with AO,
-atmosphere, or effect-local render targets.
+Keep HDR glow, AO, atmosphere, and shared render-target ordering in the game's
+existing post stack. This skill owns exposure, tone mapping, grading, and output
+conversion only.

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -46,10 +46,10 @@ npm i @genex-ai/multiplayer@^0.12.0
 > landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
 > in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.12.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
+This skill targets `@genex-ai/multiplayer` **≥ 0.13.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
-lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10;
+lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10; host-only `setRoomOpen()` since 0.13;
 exact-relay `url` overrides for cross-region invites since 0.11).
 
 ## Trust model (say it plainly in your game's copy)
@@ -598,6 +598,23 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 
   The same rule covers anything else you lazily load per player or per object (nameplates, weapon
   models, audio): a check that straddles an `await` is not a guard.
+- `room.setRoomOpen(open)` — **host only.** Stop (or resume) the matchmaker putting NEW players
+  into THIS room. A lobby game needs this: once your match starts, arrivals would otherwise be
+  dropped into a fight already in progress. Close the room at match start and the next arrival
+  forms the NEXT room instead; reopen when you return to the lobby. Everyone already inside keeps
+  playing, and a reconnecting player still gets back in (reconnection uses a reserved seat, not
+  matchmaking). A non-host call is ignored, so check `isHost` first — and because the host can
+  change, re-assert it on `on('host')` rather than only once at match start:
+
+  ```ts
+  function startMatch() {
+    if (room.isHost) room.setRoomOpen(false);   // late arrivals form the next lobby
+  }
+  function backToLobby() {
+    if (room.isHost) room.setRoomOpen(true);
+  }
+  room.on("room:open", ({ open }) => showLobbyClosedBadge(!open)); // every client is told
+  ```
 - `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected

package/templates/skills/genex-threejs-procedural-assets/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: genex-threejs-procedural-assets
+description: Build editable, parameterized Three.js props from reference images or explicit procedural requests. Use when the user asks for a procedural, parametric, code-built, customizable, seeded, or variation-ready prop, hard-surface object, modular decoration, or simple structure. Do not trigger merely because an image exists.
+---
+
+# Genex Three.js Procedural Assets
+
+Build a recognizable asset as local, editable Three.js code when code is the
+requested product—not as a fallback for every object.
+
+## Choose the route
+
+- Start directly when the user says procedural, parametric, code-built,
+  customizable, seeded, or asks for controlled variations.
+- An attached or available image does not activate this skill by itself.
+- If “make this image 3D” could honestly mean either route, ask exactly one
+  question: **“Do you want a generated textured GLB, or editable procedural
+  Three.js code?”**
+- Use `$genex-ai-model` when the user chooses a generated textured GLB.
+- Use this skill for props, hard-surface objects, modular decorations, and
+  simple structures or environment pieces.
+- Do not use it for characters, creatures, rigging, skeletal animation, or
+  character likeness. Keep those in their existing specialist lanes.
+
+## Keep the reference safe
+
+A user attachment, local file, or private URL is build input only. Inspect it
+in place. Do not upload it, place it in `public/`, publish it, or commit a copy
+without the user's permission.
+
+When no reference exists and one would materially improve the requested
+asset, use the existing `npx genex image` route. Record that image as its own
+normal paid generation row in `DESIGN.md`, including its generation ID and
+landed URL. Do not create another image pipeline or automatically re-roll a
+reference.
+
+State which geometry is visible and which geometry is inferred. A single view
+does not prove its hidden sides. Ask for another view only when the requested
+fidelity or gameplay behavior genuinely depends on it; otherwise make a
+reasonable inference and name it.
+
+## Record the work in `DESIGN.md`
+
+Give the procedural result a separate row in the existing Assets table:
+
+```markdown
+| <asset> | procedural-code | building (blockout) | — |
+```
+
+Use this status flow:
+
+```text
+proposed → planned → building (blockout | detail | material | runtime)
+→ landed (<local TypeScript path>) → wired
+```
+
+A Genex-generated reference keeps its separate image row and normal paid
+generation status. Note that the procedural-code row is derived from that
+image. A private user reference is not a paid generation row.
+
+Keep only useful state: intended use, fidelity target, reference provenance,
+visible versus inferred regions, any required moving parts or collision
+shape, current stage, output path, and comparison evidence. Do not add a
+second review ledger.
+
+## Build the asset
+
+1. Identify the silhouette, proportions, part relationships, material zones,
+   and the few details that make the subject recognizable.
+2. Define meaningful parameters before geometry: dimensions, part counts,
+   thicknesses, palette or material choices, and variation ranges. Add an
+   optional seed only when controlled variation is useful.
+3. Build the smallest blockout that proves massing and scale. Use named child
+   objects for semantic parts rather than one anonymous group of primitives.
+4. Add only the detail and material behavior required by the user's target.
+   Preserve real dimensions and keep randomness inside valid ranges.
+5. Render one reference-matched view plus one off-axis or in-game-scale view.
+   Fix meaningful silhouette, proportion, attachment, and material mismatches.
+6. Stop when the requested acceptance level is reached, then integrate the
+   factory and move its `DESIGN.md` row from `landed` to `wired`.
+
+The output is a local TypeScript factory that returns a `THREE.Group`, for
+example `createMarketStall(options): THREE.Group`. Give it stable defaults,
+intentional parameters, and named parts that gameplay code can address.
+
+Add pivots or sockets only for parts that must move or attach. Expose a
+collider description only when gameplay needs collision, and let the game's
+existing physics owner create the real collider. Add destruction groups only
+for a destructible asset. A static decoration needs none of this ceremony.
+
+## Respect existing owners
+
+Consume the game's existing Three.js scene and runtime. Never replace or
+silently configure its renderer, camera, lighting, shadows, post-processing,
+physics, animation, adaptive-quality, or mobile systems. If the request grows
+from one asset into a general mesh library, building grammar, or world
+generator, pause and confirm that expanded deliverable instead of turning this
+skill into a catch-all runtime.
+
+Do not replace `$genex-ai-model`, the character or creature lanes, rigging,
+animation, or any protected platform pipeline.
+
+## Keep the loop proportional
+
+The user's acceptance target controls the work. A rough background prop may
+finish after blockout and material; a hero prop may earn more refinement.
+Continue autonomously through unambiguous fixes and keep unrelated game work
+moving.
+
+Do not impose mandatory pass counts, numeric fidelity scores, review ledgers,
+weapon-specific rules, automatic re-rolls, or user approval after every pass.
+Ask only when a real product choice remains.

package/templates/skills/genex-threejs-procedural-materials/SKILL.md

@@ -19,10 +19,6 @@ stable coordinates
   → lighting/shadow extensions
 ```
 
-Read [references/material-systems.md](references/material-systems.md)
-for atlas filtering, specular AA, planetary coordinates,
-world-height wetness, per-instance dissolve, and authored PBR response bundles.
-
 ## Required controls
 
 - real or perceptual texture scale;
@@ -47,6 +43,6 @@ world-height wetness, per-instance dissolve, and authored PBR response bundles.
 
 ## Routing boundary
 
-Use `$genex-threejs-procedural-fields` when the main problem is designing shared
-scalar/vector causes. Use `$genex-threejs-procedural-planets` for a complete
-orbit-to-close-approach body, not merely its material.
+Keep shared scalar/vector causes and complete world or planetary bodies in the
+request's owning implementation. This skill owns the material response, not a
+general field library or world generator.

package/templates/skills/genex-threejs-procedural-vfx/SKILL.md

@@ -141,10 +141,6 @@ Call `burst()` from the same place the game already plays the explosion sound
 that call site IS the moment, and it is the proof the effect is event-driven
 rather than ambient decoration.
 
-Read [references/vfx-systems.md](references/vfx-systems.md)
-for ship-conforming reentry shells, capsule wakes, dense instanced
-spark/debris pools, HDR hierarchy, and implementation limits.
-
 ## Rules
 
 - Every layer must have a role in silhouette, motion, illumination, or residue.
@@ -158,10 +154,9 @@ spark/debris pools, HDR hierarchy, and implementation limits.
 
 ## Routing boundary
 
-Use `$genex-threejs-temporal-surfaces` only for the screen-space
-frost/touch-history pipeline. Use `$genex-threejs-precipitation-surfaces` for
-falling rain or snow, splash flipbooks, and weather events that alter ground
-materials. Impact **residue** on a surface (scorch, bullet holes) is a decal —
-`$genex-ai-image` owns that; the spark that throws the residue is this skill, and
-a hit usually wants both. Keep ship-space plasma, generated wakes, sparks,
-and pooled debris in this skill.
+Keep accumulated screen frost, persistent weather/surface state, and ground
+material changes in the request's owning scene system. Impact **residue** on a
+surface (scorch, bullet holes) is a decal — `$genex-ai-image` owns that; the
+spark that throws the residue is this skill, and a hit usually wants both.
+Keep ship-space plasma, generated wakes, sparks, and pooled debris in this
+skill.

package/templates/skills/genex-threejs-shadow-systems/SKILL.md

@@ -42,6 +42,5 @@ Read [references/shadow-systems.md](references/shadow-systems.md) before impleme
 
 ## Routing boundary
 
-Use this skill for light-space directional shadow maps. Use
-`$genex-threejs-screen-space-ambient-occlusion` for view-dependent ambient
-visibility; AO is not a replacement for cast shadows.
+Use this skill for light-space directional shadow maps. View-dependent ambient
+visibility is an AO concern; AO is not a replacement for cast shadows.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -18,10 +18,6 @@ Evaluate the mechanism that creates the image. A beautiful hero screenshot can h
 7. Record image, geometry, memory, and timing budgets.
 8. Keep a small regression set tied to visual invariants.
 
-Read [references/visual-validation.md](references/visual-validation.md)
-for visual contracts, required inspection controls, mechanism-specific
-evidence, temporal checks, budgets, and explicit rejection criteria.
-
 ## Meshy character approval evidence
 
 Before generating a Meshy character, discuss two or three visual directions.

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/SKILL.md

@@ -1,46 +0,0 @@
----
-name: genex-threejs-atmosphere-aerial-perspective
-description: Implement sky and aerial perspective for Genex Three.js games. Use for planetary atmospheres, ground-to-space transitions, Rayleigh/Mie-style scattering, sun and moon discs, depth-based haze, distance color, atmospheric lighting, and scale-readable outdoor scenes.
----
-
-# Genex Three.js Atmosphere And Aerial Perspective
-
-**Static sky at a fixed time of day → `$genex-ai-skybox` instead** (one command,
-a real 360° image + lighting). This skill is for dynamic, animated, or
-scale-transitioning skies (time-of-day, ground-to-space).
-
-Treat sky rendering and aerial perspective as two views of the same scattering model. They must share radii, density profiles, coefficients, sun direction, exposure scale, and coordinate transforms.
-
-## Choose the implementation tier
-
-- Small scene with no orbital camera: analytic height/distance approximation.
-- Planetary ground-to-space camera: ray integration or precomputed LUTs.
-- Large geospatial world: LUTs plus world-to-planet transform, altitude correction, and depth-aware aerial perspective.
-
-Read [references/atmosphere.md](references/atmosphere.md)
-before implementation. It separates the LUT/ellipsoid architecture from
-dynamic integration and the shell/post handoff.
-
-## Required outputs
-
-- sky radiance;
-- sun transmittance/color;
-- segment transmittance from camera to visible surface;
-- segment inscattering;
-- optional sky irradiance for materials;
-- explicit scale conversion between world units and atmosphere units.
-
-## Failure conditions
-
-- sky and terrain haze use different sun directions or coefficients;
-- the atmosphere is a uniformly transparent sphere;
-- camera altitude is measured in a local flat frame during orbital motion;
-- scene depth is treated as linear when it is not;
-- exposure is used to hide incorrect radiance scale;
-- atmosphere fades abruptly at shell entry.
-
-## Routing boundary
-
-This skill owns molecular/aerosol sky scattering and surface-segment aerial
-perspective. Use `$genex-threejs-volumetric-clouds` for weather-shaped cloud density,
-temporal cloud reconstruction, and cloud shadows.

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/references/atmosphere.md

@@ -1,213 +0,0 @@
-# Atmosphere system contract
-
-Use this contract to choose between a precomputed LUT/ellipsoid atmosphere and bounded dynamic integration while keeping sky, aerial perspective, surface lighting, and coordinate transforms coherent.
-
-## Contents
-
-- Shared parameter model
-- LUT atmosphere implementation LUT contract
-- Ellipsoid and depth ownership
-- planet-space implementation body profiles
-- planet-space implementation integration
-- Shell/post handoff
-- Implementation limits
-- Diagnostics
-
-
-## Shared parameter model
-
-`LUT atmosphere implementation` keeps one atmosphere object for sky and aerial perspective.
-Earth-like defaults:
-
-```text
-solar irradiance = (1.474, 1.8504, 1.91198)
-sun angular radius = 0.004675 rad
-bottom radius = 6,360,000 m
-top radius = 6,420,000 m
-Rayleigh scattering = (0.005802, 0.013558, 0.0331)
-Mie scattering = (0.003996, 0.003996, 0.003996)
-Mie extinction = (0.00444, 0.00444, 0.00444)
-Mie phase g = 0.8
-absorption extinction = (0.00065, 0.001881, 0.000085)
-ground albedo = 0.1
-```
-
-Density profiles are two-layer functions:
-
-```text
-density(h) =
-  clamp(
-    expTerm * exp(expScale * h)
-    + linearTerm * h
-    + constantTerm,
-    0,
-    1
-  )
-```
-
-The default Rayleigh exponential scale is `-0.125`, Mie `-0.833333`.
-Absorption uses two linear layers centered around the ozone region rather than
-another ground-heavy exponential.
-
-One explicit meter-to-render-unit conversion is applied when parameters become
-uniforms. Preserve this single conversion boundary.
-
-## LUT atmosphere implementation LUT contract
-
-The sky material and aerial-perspective effect consume the same:
-
-```text
-transmittance texture
-scattering 3D texture
-irradiance texture
-optional single-Mie and higher-order scattering textures
-atmosphere parameters
-sun direction
-```
-
-The sky material reconstructs rays from inverse projection and inverse view
-matrices. It can render sun, moon, ground, and shadow-length integration.
-
-The aerial-perspective effect owns:
-
-```text
-camera projection/view and inverses
-camera world position
-depth
-optional normal buffer
-ellipsoid radii
-world-to-ECEF transform
-altitude correction
-geometric-error correction
-overlay/cloud shadow/light-mask inputs
-```
-
-Default composition enables segment transmittance and inscatter. Direct sun
-light and sky-light relighting are separate switches. Do not collapse these
-signals into one fog color.
-
-## Ellipsoid and depth ownership
-
-The geospatial path defaults to `Ellipsoid.WGS84` and can correct both
-camera altitude and geometry error. Atmosphere altitude is therefore not
-`worldPosition.y`.
-
-Required coordinate contract:
-
-```text
-world position
-  -> world-to-ECEF
-  -> ellipsoid-relative position
-  -> corrected altitude
-  -> LUT coordinates / segment scattering
-```
-
-The aerial effect declares depth ownership through its post-processing effect
-attribute. It also supports octahedral normals or normal reconstruction when
-lighting terms require orientation.
-
-## planet-space implementation body profiles
-
-planet-space implementation derives profiles by body kind and density. Terrestrial baseline:
-
-```text
-Rayleigh = (0.0058, 0.0135, 0.0331)
-Mie scattering = (0.0022, 0.0022, 0.0022)
-Mie extinction = (0.0032, 0.0032, 0.0032)
-Rayleigh scale height = lerp(7.2, 10.8, normalized density) km
-Mie scale height = lerp(0.9, 1.7, normalized density) km
-Mie g = 0.76
-ozone extinction = (0.00065, 0.001881, 0.000085)
-solar intensity = 13.8
-```
-
-Rocky bodies reduce scattering and remove ozone. Gas/ice giants use much
-larger scale heights and `g` around `0.80–0.82`.
-
-The implementation enforces:
-
-```text
-mieExtinction[channel] >= mieScattering[channel] + 0.0001
-g <= 0.92
-```
-
-This prevents negative absorption and unstable phase behavior.
-
-## planet-space implementation integration
-
-For each camera ray, planet-space implementation:
-
-1. intersects the top atmosphere sphere;
-2. clamps the segment against the surface sphere;
-3. marches `ATMOSPHERE_VIEW_SAMPLES`;
-4. accumulates Rayleigh, Mie, and triangular ozone depth;
-5. at every view sample, marches a sun segment with
-   `ATMOSPHERE_LIGHT_SAMPLES`;
-6. tests planet occlusion of the sun;
-7. evaluates Rayleigh and anisotropic Mie phase;
-8. returns in-scattered radiance and view transmittance.
-
-It adds an upper-Rayleigh exponential term and fades density over the final
-`24%` of atmosphere thickness to soften the shell edge.
-
-The compact path includes a small multiple-scattering approximation derived
-from `1 - transmittance`; it is not equivalent to the precomputed higher-order
-scattering available in `LUT atmosphere implementation`.
-
-## Shell/post handoff
-
-planet-space implementation renders a double-sided shell and a depth-aware post path from one
-profile. Runtime face-opacity weights avoid a hard front/back cull switch.
-
-The post blend is based on altitude above the atmosphere top:
-
-```text
-entry blend near = 140 km
-entry blend far = max(448 km, visual atmosphere height * 0.58)
-post blend = 1 - smoothstep(near, far, altitudeFromTop)
-```
-
-The post path applies only where scene depth represents a surface. The shell
-continues to own sky pixels and limb appearance.
-
-Preserve:
-
-```text
-one body center and radius
-one atmosphere profile
-one sun direction
-one unit conversion
-surface-depth classification
-continuous shell/post blend
-```
-
-## Implementation limits
-
-- planet-space implementation performs nested dynamic integration and is expensive compared with
-  LUT lookup.
-- Its atmosphere uses spheres, while `LUT atmosphere implementation` supports an ellipsoid
-  and ECEF correction.
-- planet-space implementation’s multiple-scattering term is an artistic approximation.
-- `LUT atmosphere implementation` is version-sensitive and built around its own
-  post-processing/coordinate utilities; adapt the architecture, not imports
-  blindly.
-- Do not combine LUT radiance and dynamic integrated radiance at full weight.
-  Choose ownership or a validated transition.
-
-## Diagnostics
-
-Expose:
-
-```text
-planet/ECEF coordinates and corrected altitude
-top and bottom intersections
-Rayleigh, Mie, and absorption density
-view and sun optical depth
-sun visibility
-segment transmittance
-single and multiple scattering
-sky versus surface depth classification
-shell front/back opacity
-post blend
-LUT coordinates and texture slices
-```

package/templates/skills/genex-threejs-bloom/SKILL.md

@@ -1,44 +0,0 @@
----
-name: genex-threejs-bloom
-description: Implement controlled HDR bloom for Genex Three.js games. Use for selective emission, glow hierarchy, bloom thresholds, multi-scale blur, material restoration, effect isolation, exposure coupling, and diagnostics where glow supports form without replacing it.
----
-
-# Genex Three.js Bloom
-
-Bloom is a camera/display response to bright HDR signal. Establish scene exposure and emissive luminance before tuning blur.
-
-## Workflow
-
-1. Inspect pre-tone-map luminance.
-2. Choose which scene values should bloom.
-3. Choose a single-node or dual selective-render ownership model.
-4. Calibrate threshold, radius, smooth width, and strength in HDR.
-5. Restore all substituted materials transactionally for selective passes.
-6. Composite before exposure/tone mapping.
-7. Validate base, contribution, and final views.
-
-Read [references/bloom.md](references/bloom.md) for the
-HDR ordering, dual selective-bloom transaction, compact emissive hierarchy,
-and the costs and limits of each ownership model.
-
-Apply the material substitution/restoration ownership pattern in the
-reference before adding selective bloom to a composed scene.
-
-## Failure conditions
-
-- bloom creates the only visible form of an effect;
-- all bright materials share one arbitrary emission multiplier;
-- threshold is tuned after tone mapping;
-- selective bloom requires mutating scene materials every frame without restoration guarantees;
-- transparent particles disappear from extraction because pass ownership is unclear;
-- bloom radius changes wildly with resolution;
-- highlights become gray because energy is clamped too early;
-- bloom ships un-tiered: phone tiers run the light post level
-  (`$genex-threejs-adaptive-quality`) — bloom is a desktop-tier pass, and its
-  full-res HDR target is exactly the allocation phones get killed for.
-
-## Routing boundary
-
-Use `$genex-threejs-exposure-color-grading` for metering, adaptation, tone mapping,
-and LUTs. Load `$genex-threejs-image-pipeline` only when bloom must be composed with
-several shared image-space systems.