@genex-ai/cli-demo 0.70.0-dev.182 → 0.71.0

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.