@genex-ai/cli-demo 0.71.0-dev.186 → 0.71.0

package/templates/skills/genex-threejs-adaptive-quality/SKILL.md

@@ -1,141 +0,0 @@
----
-name: genex-threejs-adaptive-quality
-description: Make a Genex Three.js game phone-survivable with the vendored adaptive-quality kit — device-tier detection, tier-budgeted renderer settings, a runtime governor that steps quality down before phones run out of memory, per-tier asset rungs for generated skyboxes/textures, and a Quality picker in settings. Load for every game at boot wiring time, and whenever a game is heavy, crashes on phones, or gets flagged desktop-only.
----
-
-# Genex Three.js Adaptive Quality
-
-Phones enforce a hard GPU-memory ceiling desktops don't have: iOS silently
-kills the page when a game allocates too much, and the kill arrives at BOOT —
-exactly when a skybox, models, and the post stack all decode at once. This
-skill wires the vendored quality kit so the game boots conservatively on
-phones, steps quality UP when the device proves smooth, and never gets uglier
-on desktop. **You can recover from ugly; you cannot recover from a killed
-page.**
-
-This is a completion gate like the post stack: every game wires the tier at
-boot before it is called done. It costs three lines, not a testing burden —
-you still verify on desktop only.
-
-## Install
-
-```bash
-npx genex controller quality
-```
-
-Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts}` —
-game-owned code, edit freely.
-
-## Wire the tier at boot (before renderer construction)
-
-```ts
-import { detectTier } from "./controllers/quality/tier.ts";
-import { QualityGovernor } from "./controllers/quality/governor.ts";
-
-const tier = detectTier(); // phone-low | phone | desktop; manual Quality setting wins
-const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias });
-renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap));
-```
-
-The tier owns every budget decision: `dprCap` (1.5 on phones — the single
-biggest framebuffer lever), `antialias` (off on phones; it is fixed at context
-creation and can never change live), `shadowMapSize` (1024 phone / 2048
-desktop), `postLevel` (`'light'` = tone mapping + cheap passes on phones;
-`'full'` = the named stack on desktop), `particleScale`, `drawDistanceScale`,
-`frameCap`, and `remoteAvatarCap` for multiplayer. The exact ladder and which
-knobs may change at runtime vs load time vs never: [references/adaptive-quality.md](references/adaptive-quality.md).
-
-## Wire the governor (runtime — phones throttle over minutes)
-
-```ts
-const governor = new QualityGovernor(tier, {
-  setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)),
-  setPostEnabled: (on) => (composerEnabled = on),
-  setDrawDistanceScale: (m) => (scene.fog!.far = baseFogFar * tier.drawDistanceScale * m),
-}, renderer);
-
-// In the render loop, with the same performance.now() delta the loop already computes:
-governor.frame(deltaMs);
-```
-
-Sustained slow frames step down (DPR ×0.8 → post off → draw distance →
-30 fps cap); twenty smooth seconds step back up; a knob that failed twice
-stays down for the session. It keeps governing forever — thermal throttling
-arrives at minute eight, not second thirty. It also pauses judgment when the
-tab is hidden and publishes memory counts the platform's crash telemetry
-reads; pause your own loop and audio on `visibilitychange` too.
-
-## Generated assets: load through the rungs
-
-Generated skyboxes are 8192×4096 — about 178 MB decoded, over half a phone's
-whole budget in one texture. Every generated image asset ships with downscale
-rungs; phones must load through them:
-
-```ts
-import { detectTier } from "./controllers/quality/tier.ts";
-import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
-
-const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
-  new THREE.TextureLoader().loadAsync(u),
-);
-```
-
-Desktop loads the original, phones the `@2048` rung (~11 MB), and a missing
-rung falls back to the original — never a broken boot. The `$genex-ai-skybox`
-and `$genex-ai-texture` skills show the wiring in place.
-
-## Quality picker in settings
-
-The pause/settings screen (see `$genex-threejs-game-ui`) always carries a
-Quality entry: **Auto / Low / Medium / High**, wired to
-`setQualitySetting(...)` from `tier.ts` + a reload or re-tier. Persisted
-per-device in localStorage on purpose — quality is a property of the phone,
-not the player's account. Default Auto.
-
-## Budgets that ride the tier (not separate rules)
-
-- Shadows: `tier.shadowMapSize`, `shadow.autoUpdate = false` for static scenes,
-  at most 2 cascades on phones (`$genex-threejs-shadow-systems`).
-- Post: phone floor is a BUILT tone-mapping/output pass (`postLevel: 'light'`
-  adds FXAA/vignette); SSAO, volumetrics, and DoF are desktop-tier only
-  (`$genex-threejs-skill-router` owns the floor wording).
-- Particles/scatter: multiply counts by `tier.particleScale`; render heavy
-  transparency at half resolution and upsample.
-- Animation: distant mixers update at 1/2–1/4 rate; multiplayer remotes above
-  `tier.remoteAvatarCap` billboard instead of animating
-  (`$genex-threejs-multiplayer`).
-- Physics: phone tiers prefer hull/cuboid colliders for props — trimesh only
-  where gameplay demands it (`$genex-threejs-physics-rapier`).
-- Shaders: default `mediump` (iOS exception: float-texture sampling needs
-  `highp sampler2D`); precompile with `renderer.compileAsync(scene, camera)`
-  during the loader screen so first-frame jank doesn't read as a stall; skip
-  max anisotropy on phones.
-- Disposal: level swaps traverse the outgoing scene and dispose geometry,
-  materials, AND textures (three never frees them for you); watch
-  `renderer.info.memory` while testing — if textures/geometries climb across
-  swaps, you leak toward the kill.
-
-## WebGPU games
-
-The scaffold ships WebGL and stays the default; if this project already uses
-`WebGPURenderer`, keep it (never switch renderers mid-project). Context loss
-differs: WebGL fires `webglcontextlost` events; WebGPU exposes a
-`device.lost` promise — attach a handler that pauses the loop and rebuilds,
-mirroring the scaffold's WebGL pattern. All tier knobs apply identically
-except `antialias` (WebGPU MSAA is per-render-target and CAN change at
-runtime).
-
-## Failure conditions
-
-- Renderer constructed before `detectTier()` → context-creation knobs
-  (antialias) are locked wrong for the session. Tier first, renderer second.
-- Governor wired to context-creation flags → no-op at best. Runtime knobs
-  only: DPR, post toggles, distances, frame cap.
-- Skybox loaded with a bare `TextureLoader.loadAsync(SKYBOX_URL)` on a game
-  that targets phones → ~178 MB decoded; route it through
-  `loadTextureWithFallback`.
-- Quality stepping on every spike → shader compiles read as slowness. The
-  governor requires SUSTAINED slow windows; do not shorten them.
-- Testing quality tiers by resizing the desktop window → tiers key off touch +
-  OS, not viewport. Trust desktop verification plus the preflight report
-  `genex preview` prints.

package/templates/skills/genex-threejs-adaptive-quality/references/adaptive-quality.md

@@ -1,105 +0,0 @@
-# Genex adaptive quality — tiers, knobs, and the governor in depth
-
-Use this reference when tuning the tier ladder, deciding which knob may change
-when, or teaching the governor a game-specific step.
-
-## Why boot-conservative
-
-The phone budget is a hard ceiling that includes GPU memory (textures,
-framebuffers), and the OS kill arrives with no catchable event. Boot is the
-danger window: skybox + models + post targets decode together. So phone tiers
-START one notch below what the heuristics suggest and the governor steps UP
-after ~20 smooth seconds. The cost of guessing low is moments of softness; the
-cost of guessing high is a dead page.
-
-## The tier ladder
-
-| Knob | phone-low | phone | desktop |
-|---|---|---|---|
-| DPR cap | 1.0 | 1.5 | 2 |
-| antialias (context) | off | off | on |
-| Shadow map | 512 (static-cached) | 1024 | 2048 |
-| Post level | tone map only | + FXAA/vignette | full named stack |
-| Skybox rung | @2048 (~11 MB) | @4096 (~45 MB) | original |
-| Texture rung (props) | @1024 | @2048 | original |
-| Particles/scatter | 0.25× | 0.5× | 1× |
-| Draw distance | 0.5× | 0.75× | 1× |
-| Frame target | stable 30 | 60 | 60 |
-| Remote avatars animated | 4 | 8 | all |
-| Prop colliders | hull/cuboid | hull | as designed |
-
-A DPR drop from 3 (raw iPhone) to 1.5 cuts every full-screen surface — color,
-depth, and each post target — to a quarter of the bytes. It is the single
-strongest lever the tier owns.
-
-## The knob split — what may change when
-
-Getting this wrong produces silent no-ops or a session stuck ugly:
-
-- **Context-creation-fixed (never changes live):** `antialias`, `alpha`,
-  `stencil`, `powerPreference` on WebGL. Changing them means a new context and
-  a full re-init — the tier must decide them BEFORE the renderer exists.
-  (WebGPU differs: MSAA is per-render-target sample count and is runtime-
-  changeable.)
-- **Load-time (fixed for the session once fetched):** asset rungs (skybox and
-  texture resolutions), model LOD sets. `pickAsset` decides them from the tier
-  at load; switching later means a re-fetch — treat as fixed.
-- **Runtime-free (the governor's domain):** `setPixelRatio`, post passes on/off
-  and their target resolutions, shadow map size (realloc), draw distance and
-  fog, LOD bias, particle counts, mixer update rates, frame cap, remote-avatar
-  animation count.
-
-## Governor mechanics
-
-- Slow = frame delta over budget for a SUSTAINED window (4 s) — never single
-  spikes, which are usually shader compiles or GC. Precompiling with
-  `renderer.compileAsync` during the loader screen removes most spikes at the
-  source (and keeps first-frame jank from reading as a stall to the platform's
-  telemetry).
-- Step-down order: DPR ×0.8 → post off → draw distance ×0.6 → 30 fps cap.
-  Each step is the cheapest remaining lever with the biggest headroom return.
-- Step-up needs 20 smooth seconds (hysteresis), and a step that had to be
-  re-applied twice is pinned for the session — oscillating quality reads worse
-  than stable-low.
-- The governor never stops: thermal throttling degrades phones after minutes
-  of play, so a boot-time benchmark alone always ends up wrong.
-- A stable 30 fps cap beats a stuttery 40–50: consistent frame pacing reads
-  smoother and halves GPU work per second (heat, battery, memory bandwidth).
-- Backgrounded tab (`visibilitychange`): pause the render loop and audio, not
-  just the governor — a hidden game burning GPU is pure thermal debt on the
-  device class that can least afford it.
-
-## Detection honesty
-
-- Apple devices mask the GPU renderer string ("Apple GPU") — screen dims + DPR
-  + iOS major version are the usable signals there, and the governor corrects
-  the rest from measured frames.
-- Android exposes real renderer strings (Adreno/Mali/Xclipse); the vendored
-  lookup in `tier.ts` promotes strong GPUs to the `phone` tier. It is a
-  heuristic on purpose — extend the regex when field data shows a
-  misclassified family, and let the governor absorb the rest.
-- Never burn a probe context on a memory-strapped phone at play time; the one
-  probe in `tier.ts` runs at boot and frees its context immediately.
-
-## Memory discipline that rides the tier
-
-- Dispose on every level swap: traverse the outgoing scene and call
-  `.dispose()` on geometry, material, AND each material's textures — material
-  dispose does not free textures, and three frees nothing automatically.
-- Watch `renderer.info.memory.{textures,geometries}` across swaps in dev; a
-  monotonic climb is a leak marching toward the OS kill. The governor
-  publishes these counts for the platform's field telemetry.
-- Prefer meshopt/instanced geometry for repeats; `BatchedMesh` batches
-  HETEROGENEOUS static meshes into one draw where instancing (identical
-  meshes only) can't.
-- Half-resolution transparency: render heavy particle/transparency passes to a
-  half-size target and composite up — fill-rate is the phone bottleneck.
-
-## Multiplayer at tier
-
-Remotes are visual-only; with the shared avatar file, `loadVrmClone` gives N
-remotes one set of GPU geometry/textures. Animate and fully draw only the
-nearest `tier.remoteAvatarCap`; beyond it, freeze the mixer and billboard or
-hide. Matchmade games can also declare a lower `maxPlayers` in
-`genex.matchmaking` for phone-heavy audiences — capacity is a server-owned
-knob.