@bitmagic/cli 0.1.73-dev.0 → 0.1.74-dev.0

package/README.md

@@ -1385,6 +1385,37 @@ runtime module (`src/work/metahuman/`), the lip-sync tool and a headless verific
 each failure a raw export produces (arms crossed into the chest, a torn shirt, hair left behind by a
 head turn, tinted skin, black eyes) with the fix that resolved it.
 
+## Optimizing assets
+
+The scaffolded `optimizing-assets` skill makes a game's GLBs smaller and faster to load with no
+visible change, the same way in every project. It measures first (`--audit` ranks `world.json` rows
+by bytes, `--report` gives triangles, texture formats and estimated GPU memory) and sorts each asset
+into a class by how close the player gets. It then runs the skill's own `scripts/optimize-glb.mjs`
+with that class's preset: `distant-prop`, `hero-prop`, `character`, `code-driven` or `level`. The
+script compresses textures (KTX2 ETC1S or UASTC, WebP, JPEG 4:4:4) and vertex buffers (meshopt,
+quantization) and enforces the rules the first games learned: separate vertex layout, int8 normals,
+float positions on skinned meshes and on nodes that code reads by name, and no pruned marker nodes.
+It keeps solid-colour textures, keeps a base map and the mask code pairs with it the same size,
+keeps a KTX2 atlas already in the target encoding instead of encoding it twice, keeps every
+animation key on characters, prints before and after numbers, lists every named node whose origin
+quantization moved, and runs the Khronos validator. It refuses to run outside a project root,
+where it could not see which node names the code reads. The candidate is A/B'd in the running
+game before anything is uploaded (a temporary `?preview=1` redirect under `bitmagic dev`), scored
+by the skill's `scripts/ab-compare.mjs` (luma SSIM, luminance and silhouette ratios, a sheet). A
+`glb` row is then replaced in place with `bitmagic assets add --keep-glb --asset-id`, its
+`sourceGlbUrl` pointed back at the original so Blender and `assets revoxelize` can still read it;
+a `character` or other row gets a new row and its references repointed.
+
+The encoder runs on tools shared by every project on the machine, in `~/.bitmagic/tools`
+(glTF-Transform, meshoptimizer and sharp at pinned versions, and KTX-Software). They are not CLI
+dependencies. The skill asks the creator before installing them and gives no-sudo steps for macOS,
+Linux and Windows. The skill checks the vendored engine's source rather than its version number:
+meshopt output needs a loader factory that attaches three's `MeshoptDecoder`, KTX2 on WebGPU needs
+the factory's wait for the device (`expectGltfLoaderSupport`), and `assets revoxelize` needs a
+voxelizer that reads quantized attributes. Engines older than the Sep 2026 loader factory read no
+KTX2 at all. For a gap the skill offers `bitmagic upgrade`, meshopt-off and non-KTX2 settings, or a
+game-side shim for the missing half.
+
 ## Art style
 
 A 3D game is voxel-built unless `src/work/game.json` says otherwise:

package/assets/blender-level/README.md

@@ -21,6 +21,10 @@ skill's step 1 tells an agent how to copy them into a project's `tools/blender-l
 | `sync_world.py` | python3 | carries the doors, spawn and `terrain.shape: 'none'` into `src/work/world.json` |
 | `tests/` | python3 | `python3 -m unittest discover -s tests` — no Blender needed; `cli`'s `pnpm test` runs it |
 
+`bmedit`'s `load(id)` and `review_asset.py` use Blender's glTF importer, which refuses
+`EXT_meshopt_compression` and `KHR_texture_basisu`. For an asset the `optimizing-assets` skill has
+compressed, put the original it recorded in `build/inputs/`, and run its preset again on the export.
+
 `review.py` and `audit.py` are the skill's **inner loop**: with the build they answer every
 geometric and (under `--lighting game`) every lighting question about a level for a few seconds
 and no network, which is what lets the engine handoff — `bitmagic assets add`, `sync_world.py`,

package/assets/character-rigging/SKILL.md

@@ -15,8 +15,11 @@ With no visual inspection capability, produce a technical diagnostic and leave v
 Read the project's AGENTS.md and identify the input GLB or blend file, desired animation clips,
 runtime skeleton constraints and output location. Infer these from the project before asking.
 Copy the source to a per-character work directory; never overwrite the only original. Record its
-SHA-256. Keep the repair profile, scripts, candidate, review images and verdict together there.
-Do not put per-character work inside this shipped skill: GDK upgrade refreshes its files.
+SHA-256. Blender's importer refuses a GLB that carries `EXT_meshopt_compression` or
+`KHR_texture_basisu`. If it is an `optimizing-assets` output, start from the original that skill
+recorded, then run its preset again on your result. Keep the repair profile, scripts, candidate,
+review images and verdict together there. Do not put per-character work inside this shipped
+skill: GDK upgrade refreshes its files.
 
 Find Blender with `blender --version`, BLENDER_BIN, or the installed application executable
 (macOS commonly `/Applications/Blender.app/Contents/MacOS/Blender`; Windows installations commonly

package/assets/character-skin-authoring/SKILL.md

@@ -9,7 +9,7 @@ The local agent makes anatomical/material decisions from images. Do not replace
 
 ## Establish evidence
 
-Locate the model, its physical height, materials, texture resolution and rig. Keep the original immutable and write a separate material revision. Inspect the original generated image when available, but make the **actual mesh and its textures** authoritative: the generated mesh may differ from that image.
+Locate the model, its physical height, materials, texture resolution and rig. Keep the original immutable and write a separate material revision. Blender cannot import a GLB that carries `EXT_meshopt_compression` or `KHR_texture_basisu`: if it is an `optimizing-assets` output, work from the original that skill recorded, then optimize the result again. Inspect the original generated image when available, but make the **actual mesh and its textures** authoritative: the generated mesh may differ from that image.
 
 Use the local `scripts/skin_views.py` helper to create unlit, occlusion-correct views with their UV correspondences. Read [the projection contract](references/projection.md) for commands and formats. It requires local Blender and a Python environment with NumPy/Pillow. The helper performs no semantic recognition. Verify orientation from the resulting images; its axes are not anatomical labels.
 

package/assets/optimizing-assets/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: optimizing-assets
+description: Make this game's models and textures smaller and faster to load with no visible change. Measure the download, GPU memory and triangles; classify each asset by how close the player gets; compress its textures (KTX2, WebP, JPEG) and vertex buffers (meshopt, quantization) with the shipped optimize-glb.mjs presets; A/B it in the game, then swap it in. Use when the creator asks to optimize, compress, shrink or slim assets, cut the download size or load time, reduce memory, fix a slow first load on phones, or prepare a mobile game for publishing.
+---
+
+# Optimizing assets
+
+A shipped game's download is mostly a handful of GLBs, and most of their bytes are things the player
+never sees: 2048² maps on a rock seen from 40 m, float32 normals, a second rig nobody animates. Two
+games shipped with this recipe. Squall Riders' phone download went 43.3 → 13.5 MiB; Trick or Roll's
+stages went 92 → 28 MB and its animals 17.9 → 1.7 MB. Both results passed an in-game A/B.
+You measure first, then choose one preset per asset class from one script. The script enforces the
+safety rules, and nothing ships until the player's view says so.
+
+The scripts are in `.agents/skills/optimizing-assets/scripts/`: `optimize-glb.mjs` encodes and
+`ab-compare.mjs` scores an A/B. Run them from the project root with `node`: the encoder reads
+`src/` and `engine/` for the node names code uses, and refuses to run where neither exists. They
+never edit `world.json` and never overwrite their input. Optimizing is the last step (see 6.4).
+
+## 1. Measure before touching anything
+
+```sh
+O=.agents/skills/optimizing-assets/scripts/optimize-glb.mjs
+node $O --audit src/work/world.json   # every asset row by bytes, cumulative %, and what refers to it
+node $O --report big.glb              # triangles, textures (format, size, bytes), estimated GPU memory
+```
+
+- **Fetch each GLB into a work directory**, e.g. `.bitmagic/optimize/<asset>/` (git ignores
+  `.bitmagic/`). Get it from its row's `url`, record its SHA-256, and never edit the only copy.
+  Keep per-asset work out of this skill folder, because `bitmagic upgrade` rewrites it.
+- **Start from the original, never from a variant.** Rows marked `(variant?)`, and files whose
+  report says `already EXT_meshopt_compression`, are earlier optimized copies. Re-encoding one
+  stacks the losses, so find the original row or URL first.
+- **Rank by what players actually download.** A row without a recorded size is sized by a HEAD
+  request (marked `~`) or listed first as `unknown`. `used` says what names the row: world.json,
+  code, or nothing. Neither proves a fetch, so confirm in `bitmagic dev`'s network panel. In Squall
+  Riders, 12 assets were 38.5 of 43 MiB.
+- **Write down the baseline for each candidate:** transfer bytes, estimated GPU memory, triangles,
+  and the total first download. Every later claim is measured against these numbers.
+- **Out of scope:** voxel (`vxl`) rows (`bitmagic assets revoxelize` changes those) and audio.
+  For images, see the end of [recipes](references/recipes.md).
+
+## 2. Classify each asset by how the player sees it
+
+Pick the class from the **closest distance a player can reach**, not the usual one. When you are
+unsure, take the closer, less lossy class. Recipes, rejected alternatives and when to override are
+in [recipes](references/recipes.md). "Measured" is this script's default on the original file.
+
+| Class (preset) | What it is | What the preset does | Measured |
+|---|---|---|---|
+| `distant-prop` | landmarks, scenery, ~30 m or more away | simplifies (normal-weighted, bounds locked); one 512 ETC1S base map with AO baked in; normal and ORM maps dropped; 14-bit positions | beacon 4.45 MiB → 180 KiB, 61k → 10k triangles (bytes only: riders reach its rocks, see recipes) |
+| `hero-prop` | sculpts and buildings passed at ~10–20 m | no simplification; 1024 JPEG 4:4:4 base and normal maps; 512 UASTC ORM; float positions | rock islet 4.93 → 1.71 MiB, SSIM ≥ 0.984 at 12 m |
+| `character` | skinned or animated, fills the screen | float positions; exact int8 normals; every animation key kept; 1024 UASTC (RDO) atlas, a UASTC source kept as it is | penguin rider 2.43 → 1.58 MiB (0.69 at 512) |
+| `code-driven` | vehicles, anything whose vertices, node positions or pixels code reads | float positions; base maps kept, the ORM/mask slot as lossless WebP (same pixels); never KTX2 | jet ski 1.26 → 0.70 MiB (0.40 at 512) |
+| `level` | stages and level meshes | float positions and triangle order kept; normals int8, UVs 16-bit; textures untouched | a Trick or Roll stage 2.26 → 1.01 MiB |
+
+**Phone variants differ per class.** For `character`, `code-driven` and `level`, add
+`--max-texture=512`: a kept texture is resized in its own format, and a base map stays paired with
+its mask. `distant-prop` is already 512. `hero-prop`'s default already is Squall Riders' phone set:
+at 512 the islet scored 0.906–0.940 at 12 m, so do not go lower without passing that A/B.
+
+**Check what code reads before you choose.** The script scans `src/` and the vendored engine for the
+node names code compares. It also warns about game files that parse GLB bytes themselves (collision
+read from a stage file, `bufferViews`), because the engine's decoder never reaches them. Give such a
+parser the meshopt decoder and normalized-int handling, or use `--meshopt=off` and still check that
+it reads int8 normals.
+
+## 3. Tools: check first, ask before installing
+
+```sh
+ls ~/.bitmagic/tools/gltf/node_modules/@gltf-transform/core ~/.bitmagic/tools/ktx/bin/ktx
+```
+
+If both exist, go on. If not, installing them downloads about 70 MB. **Ask the creator first**, then
+follow [tools](references/tools.md): pinned versions, no-sudo steps for macOS, Linux and Windows,
+and the shared README. Never run the plain `gltf-transform meshopt` or `etc1s` commands on game
+assets, whatever an older `~/.bitmagic/tools/README.md` suggests: they quantize skinned and named
+meshes and encode normal maps as ETC1S. The script warns when the installed versions differ from
+the ones it was tested with. On Windows, [tools](references/tools.md) has PowerShell equivalents.
+
+## 4. Run the script
+
+```sh
+node $O in.glb out.glb --preset=distant-prop
+node $O in.glb out-mobile.glb --preset=character --max-texture=512   # a phone variant
+```
+
+`--help` lists the overrides. Change **one variable at a time** and keep each output. These rules
+hold on every run, and no flag turns them off:
+
+- The vertex layout is SEPARATE, and normals and tangents are int8.
+- Skinned or morphed files keep float32 positions.
+- Mesh nodes that code reads keep float positions and their exact TRS, and are not simplified:
+  `BM_*` engine nodes, names that `src/` or `engine/` compares node names against (literals,
+  `startsWith`/`includes` arguments, regex words), and anything given with `--keep-float`.
+- Empty nodes are never pruned, nodes and materials are never renamed, and no texture is folded
+  into a material colour (a solid-white mask is still a texture code paints into).
+- Simplification locks the bounding box.
+
+The script prints before and after numbers, every texture's format and size, notes and checks:
+node names, texture slots, paired sizes (`code-driven`), layout, kept nodes, skinned positions,
+bounds drift, smaller, and the Khronos validator. **Exit code 1 means do not ship this output.**
+Read every note; each is a decision:
+
+- **`kept exact`** names the file and string that matched. A false match only costs bytes. To drop
+  one, rerun with `--code=none --keep-float=<the nodes code really reads>`.
+- **`positions quantized: … a different transform`** lists named nodes whose origin moved. If code
+  reads the position of one (a lamp, an anchor), add it with `--keep-float`.
+- **`AO not baked`** (the occlusion map uses other UVs or a texture transform), a metalness warning,
+  or `already EXT_meshopt_compression` (you started from a variant).
+- **`KTX2 kept as it is`**: a library atlas already in the slot's encoding is not encoded twice.
+  An explicit slot spec re-encodes it for fewer bytes; that output must pass the A/B on its own.
+- **`names the clip`**: code plays a clip `--only-default-scene` or `--drop-animations` removed.
+- `TEXCOORD_0 leaves 0-1` is harmless: tiling UVs stay float. glTF-Transform prints it as
+  `quantize: Skipping TEXCOORD_0; out of [0,1] range.`
+
+## 5. The engine must decode what the script writes
+
+Check the vendored engine's source, not its version: a build number does not say which fixes it
+carries. A grep that prints 0 (or a missing file) is a gap:
+
+```sh
+ls engine/engine/loaders/GltfLoaderSupport.ts                            # missing: no KTX2 at all
+grep -c setMeshoptDecoder engine/engine/loaders/GltfLoaderSupport.ts     # meshopt decodes
+grep -c expectGltfLoaderSupport engine/engine/loaders/GltfLoaderSupport.ts   # KTX2 waits for WebGPU
+grep -c packedFloats engine/engine/GLBVoxelizer.ts                       # voxelizes quantized files
+grep -rlE "setMeshoptDecoder|meshoptDecoder" src/                        # a game-side decoder
+grep -rlE "gltfLoaderSupportsKtx2|KHR_texture_basisu" src/               # a game-side KTX2 wait
+```
+
+- **meshopt** (every preset): with no decoder, a meshopt GLB fails with `setMeshoptDecoder must
+  be called`. A game-side decoder in `src/` covers it.
+- **KTX2 on WebGPU** (`character`, `hero-prop`, `distant-prop`): without the wait, a KTX2 GLB that
+  arrives before the renderer's `init()` (a smaller file arrives sooner) fails with `setKTX2Loader
+  must be called`. A `src/` shim covers it only if the last grep finds it: Squall Riders' waits,
+  Trick or Roll's does not. With no `GltfLoaderSupport.ts` (before September 2026), no loader
+  reads KTX2 at all. Without `packedFloats`, `bitmagic assets revoxelize` misreads quantized files.
+
+When a check fails, pick one:
+
+1. `bitmagic upgrade`. Read its `--help` first: it refuses a dirty working tree. Then grep again.
+2. `--meshopt=off` (quantization only, which three reads natively; 20–60% larger) and, where KTX2
+   fails, no KTX2: `--base=webp:1024:90`, plus `--orm=webp-lossless:512` where the preset writes
+   UASTC. With no `GltfLoaderSupport.ts` that is every asset, not only those loaded during boot.
+3. The game-side shim in [runtime](references/runtime.md), or the half an existing `src/` shim
+   lacks. Its KTX2 wait needs `GltfLoaderSupport.ts`. Delete it once an upgrade passes the greps.
+   The dev asset panel runs no game code, so it cannot open meshopt files: verify in the game.
+
+## 6. A/B, then swap it in
+
+1. **A/B before anything is uploaded.** Under `bitmagic dev` the candidate is served from its work
+   directory (`/.bitmagic/optimize/<asset>/out.glb`), and the preview module in
+   [runtime](references/runtime.md) loads it in place of the original on `?preview=1`: one build
+   shows both. A game that already rewrites asset URLs needs its originals override on both sides
+   (runtime says how to tell). Confirm the swap happened, capture the views in
+   [verification](references/verification.md), score them with `ab-compare.mjs`, and show the
+   creator the sheet. Delete the preview module afterwards.
+2. **Re-read `src/work/world.json`.** Note the row's `id`, `name`, `type` and `targetHeight`, and
+   every reference to its id **and** its URL: `grep -rn "<id>\|<file name>" src/`. The player's
+   model is `worldProfileData.characterUrl`, a URL, and skies and code often load by URL too.
+3. **Swap it in, by the row's type:**
+   - **`glb`:** `bitmagic assets add out.glb --keep-glb --asset-id <id> --name <its name> --height <its targetHeight>`.
+     The new record wins field by field: leaving out `--name` renames the asset to the file name,
+     and leaving out `--height` resets it to 2 m. Then edit the row's `sourceGlbUrl` back to the
+     original URL, because the replace points it at the optimized file. Placements follow the id;
+     every URL reference from step 2 needs the new URL.
+   - **Any other type** (`character`, `polygon-mesh`, `gltf`): not in place. `--keep-glb` would turn
+     the row into a 2 m `glb`: refused under id references without `--force`, silent otherwise.
+     Add a new row with `bitmagic assets add out.glb --keep-glb --name <name>_opt` and point each
+     reference from step 2 at it: `characterUrl` gets the new URL, code the new id or URL. For many
+     rows, or per-device sets, use the variant map in [runtime](references/runtime.md) instead.
+4. **Optimization is the last step, so keep the original importable.** Blender cannot import
+   meshopt or KTX2, a voxel bake wants full detail, and an engine without `packedFloats` (step 5)
+   misreads quantized attributes when it voxelizes. Rigging, skin authoring, Blender edits and
+   `bitmagic assets revoxelize` start from the original file or URL; then re-run the preset on
+   their result. Record the original URL and SHA-256 next to the new URL in the work directory,
+   so a rollback is one command.
+
+## 7. Verify after the swap: all three verdicts
+
+1. **Numbers:** the script's report per asset, then the game's total first download before and
+   after, from the network panel with the cache disabled.
+2. **Decode:** play the scene that uses the asset. The console must show no `setMeshoptDecoder`,
+   `KTX2` or WebGPU pipeline errors. Run `bitmagic verify`. After a `glb` swap the dev asset panel
+   shows `sourceGlbUrl`, the original, so it proves nothing about the new file. Open
+   `/asset-preview?kind=glb&url=<new URL, encoded>` on the dev view: the vendored engine's loader.
+3. **Look:** capture the step 6.1 views again, with the swapped asset and no preview, and compare
+   them with the original captures. That proves the game loads what you tested.
+
+Keep the numbers verdict and the visual verdict separate. A good SSIM does not approve a look. Show
+the creator the A/B sheet; the look is theirs to call.
+
+## Pitfalls, and why each one bites
+
+- **Interleaved quantized vertex buffers** crash WebGPU pipeline creation (`unorm32x4 is not a
+  valid enum`).
+- **int16 normals with tangents** drew camouflage blotches on WebGPU, on both desktop and phone.
+- **Quantized positions on a skinned mesh** rewrite its inverse bind matrices, so code that reads
+  the bind pose silently mis-poses the character.
+- **Quantized positions on a named mesh node** move its origin (lamp centres, anchors) or push the
+  mesh onto an unnamed child.
+- **Quantized positions under `positionLocal` or noise materials, or merged batches,** make the
+  pattern swim and reopen coplanar seams. Use `level` or `--pos-bits=0`.
+- **`prune()` with default options** deletes empty marker nodes (spawns, items, goals) and folds a
+  solid-colour texture into its material colour, which deletes a mask code paints into.
+- **ETC1S up close** blotches colour, and on a hero prop it came out larger than the JPEG.
+- **Lossy WebP for normal maps** is always 4:2:0. Use JPEG 4:4:4 or UASTC.
+- **KTX2 on pixels code reads** (`getImageData`, livery masks) makes them unreadable. That is what
+  `code-driven` is for.
+- **The game's first KTX2 texture** adds the Basis transcoder download (~0.25 MB). For a lone small
+  atlas, `--base=webp:512:90` avoids it.
+- **Simplifying a sculpt** loses the detail that lives in its vertex normals. Every attempt on the
+  hero props failed the A/B.
+- **A shrunken bounding box** makes the engine rescale and re-centre the prop to its targetHeight.
+- **Downsizing an atlas without filling its gutters** bleeds dark seams. The script fills them.
+- **Baking AO and dropping the ORM map** shifts brightness by up to about 5–10%. Check luminance in
+  the A/B.
+- **The octahedral normal filter** is about 1° off and also filters animation. Characters stay exact.
+- **A loaded machine** auto-drops the quality tier mid-capture. Pin it with `?quality=<rung>`.
+- **Quantized attributes are padded to a 4-byte stride** (int8 normals to 4 bytes, int16 positions
+  to 8), with or without meshopt. Code reading attribute arrays directly then gets an
+  `InterleavedBufferAttribute`: read values through `getX()`, which also denormalizes them.

package/assets/optimizing-assets/references/recipes.md

@@ -0,0 +1,171 @@
+# Recipes per asset class
+
+Each preset below is what held up in a shipped game, with the numbers that justified it and the
+alternatives that were measured and rejected. Override a preset only for a reason you can name, and
+A/B the override the same way. "SR" is Squall Riders, a photoreal WebGPU racer. "TOR" is Trick or
+Roll, a stylised ball game. SSIM is luma SSIM on the object (`ab-compare.mjs`'s `SSIM (luma,
+object)`), original against new, at the stated view. "This script" numbers are `optimize-glb.mjs`
+with the preset's defaults on the original file.
+
+## distant-prop: seen from about 30 m or more
+
+These read as silhouettes: landmarks, background ships, scenery. With this script, SR's beacon went
+4.45 MiB → 180 KiB (61,487 → 10,349 triangles) and its trawler 4.02 MiB → 329 KiB (74,577 → 20,637).
+SR's shipped set, four landmarks, went from 15.0 MB of originals to 0.84 MB and 8–12k triangles each,
+with no visible change at race distance. That set also had per-region budgets and a Blender re-bake
+on the trawler; its earlier phone set was 4.32 MB.
+
+**The beacon shows the bytes, not a clean pass.** Riders can reach its rock ring (SR's collision
+hulls stop a ski on the awash rocks), so by the closest-distance rule it is a `hero-prop`: 1.26 MiB,
+SSIM 0.999 at 40 m in golden and storm light, and 0.958 (0.981 on the crop) at 15 m. As
+`distant-prop`, in a neutral viewer at 40 m it scored 0.70–0.74 on the object and 0.875–0.887 on the
+crop, its storm luminance ratio fell to 0.94 at one azimuth, and the rock visibly lost its
+normal-map relief. Shipping it as a distant prop takes the extra work below.
+
+- **Texture:** one base-colour map, 512² (256² for a "lite" tier), as KTX2 ETC1S at qlevel 255 with
+  full mips.
+  - AO from the ORM map is baked into it in linear light: `base × (1 − w·(1 − ao))`, w = 0.6. The
+    bake needs both maps on the same UV set with no `KHR_texture_transform`; otherwise the script
+    skips it and says so, and the dark-scene A/B decides.
+  - The normal map, the ORM map and TANGENT are dropped. Roughness and metalness become constants,
+    the ORM map's own means; the script prints them.
+  - If metalness comes out above 0.1, the prop has painted metal. Keep the ORM map with
+    `--orm=uastc:512` instead of flattening it.
+  - Crisp high-contrast graphics (stripes, signage) blotch less as UASTC: `--base=uastc:512:2`.
+    One SR beacon shipped that way.
+- **Geometry:** meshopt `simplifyWithAttributes`. The error bound is 0.2% of the model's largest
+  dimension, and normals are weighted 0.1, so shading survives and not just the outline.
+  - UV seams are kept, and vertices on the bounding box are locked.
+  - Plain geometric simplification left soft shading gradients. Weights of 0.25–0.5 with
+    re-derived normals were needed once, on a rusty wreck: A/B before reaching for them.
+- **If the player can get close to one side** (a rider could touch SR's trawler), that side needs
+  its own budget. One global error bound erased the nets and cables at 6k triangles. SR fixed it
+  with per-region budgets and a Blender re-bake, which is beyond this script. Classify such an asset
+  as `hero-prop` unless the creator wants the extra work.
+- **Vertex data:** 14-bit positions, int8 octahedral normals, 12-bit UVs (enough for 512²).
+- **Gate:** views at 40, 80 and 150 m from 3 azimuths, golden and storm lighting, desktop and
+  portrait. The mean-luminance ratio should stay within 0.96–1.10 in both lights. The silhouette
+  pixel ratio, within 0.99–1.01, is read on the golden or a mask capture: in storm light the dark
+  rock barely clears the background, and the beacon's unchanged outline read 0.89–1.01. Look at the
+  40 m view yourself at 100%: there SSIM runs lower (0.91–0.96 for the trawler in a neutral viewer,
+  with the luminance ratio up to 1.09; the beacon's numbers are above) and shading on thin parts
+  such as booms and nets can change. If it shows, try the closer class.
+
+## hero-prop: closest approach about 10–20 m
+
+Sculpted rocks, a lighthouse, anything the course passes close to. With this script the rock islet
+went 4.93 → 1.71 MiB, SSIM 0.984–0.988 at 12 m. SR's shipped set: the sea stack 10.90 → 2.34 MiB,
+the islet 4.93 → 1.69 and the lighthouse 4.70 → 1.53, SSIM 0.986–0.987 on phones at 12–20 m.
+
+- **Textures:**
+  - Base colour and normal map: 1024 JPEG, q90–92, 4:4:4, mozjpeg.
+  - ORM: 512 KTX2 UASTC, RDO λ2, zstd, linear.
+  - TANGENT is kept.
+  - Where strata-like detail is the point, use `--normal=jpeg:2048:92`. The stack at 12 m scored
+    only 0.954–0.973 with a 1024 normal map on desktop.
+- **This default is already SR's phone set.** `--max-texture=512` took the islet to 1.19 MiB but
+  scored 0.906–0.940 at 12 m, with visibly softer lichen and normal detail. Go below the default
+  only when the 12 m A/B passes.
+- **Rejected, with the numbers:**
+  - An ETC1S base colour blotched at 10 m and came out larger than the JPEG (732 vs 653 KB).
+  - A UASTC normal map is 4.4 MB at 2048².
+  - A lossy WebP normal map scored 0.960.
+  - A 256² set passed the course views and failed at 12 m (0.895–0.925). Gate at the closest
+    approach.
+- **No simplification.** Every attempt failed, down to 0.873 on the islet, because a sculpt keeps
+  its detail in its vertex normals. The only path left is a Blender normal bake onto a decimated
+  mesh.
+- **Vertex data:** float32 positions, int8 normals and tangents, 14-bit UVs.
+- **The trade-off:** a JPEG uploads as RGBA8. At 2048², one map is 21 MiB of GPU memory.
+
+## character: skinned or animated
+
+With this script, SR's penguin rider went 2.43 → 1.58 MiB, and 0.69 MiB with `--max-texture=512`.
+The croc rider went 4.88 → 1.77 MiB with `--only-default-scene`, at SSIM 0.999 or more at 1 m and
+3.4 m, posed and in the bind pose. SR's five riders shipped at 15.94 → 6.98 MiB at 1024 and
+3.66 MiB at 512 (atlases re-encoded), with SSIM ≥ 0.985, IK grip misses of 0.0000 m and exact bind
+positions. In TOR, 4 animals went 17.9 → 1.73 MB.
+
+- **Texture:** 1024 KTX2 UASTC, RDO λ4, zstd 18, sRGB with mips. Use `--max-texture=512` for
+  phones.
+  - A source that is already UASTC at 1024 or less (library characters ship one) is kept as it is.
+    Re-encoding it is a second lossy generation: it saves about 18% of the atlas (the croc's
+    1.13 MiB → 830 KiB) and cost the croc 0.986 against 0.9996 at 3.4 m in the bind pose. An
+    explicit `--base=uastc:1024:4` does it anyway; A/B that output on its own.
+  - A larger or different KTX2 source is transcoded to RGBA and re-encoded. If the re-encode is
+    not smaller than the source at the same size, the source is kept.
+  - ETC1S was rejected: 0.983 at the chase view, and banding on flat panels at 512.
+  - RDO λ10 saved only 25 KB.
+  - TOR's alternative was `--base=webp:512:90`: 7.1 → 0.23 MB of atlases, and no Basis transcoder
+    download, because they were the game's only KTX2 files.
+- **Vertex data:** positions ALWAYS float32. The script enforces this for skins and morphs.
+  Normals are exact int8, UVs 16-bit (float where outside 0–1), joints uint8 and weights unorm8.
+- **No simplification.** At 8–11k triangles a character fills the screen. SR's decimated "lite"
+  riders scored 0.87–0.91.
+- **Opt-in clean-up, only after checking the code:**
+  - `--only-default-scene`: library characters carry a second "static eyes" rig and scene. The
+    flag drops that scene with every node, mesh, skin and clip only it used, and names them: the
+    croc lost five of its ten clips (`NewIdle_Static`, `HandsGrip_Skin2`, …). First check that
+    nothing reads `gltf.scenes` or those node names, and grep the clip names. The script warns
+    when code names a clip it dropped.
+  - `--drop-animations`: TOR's game poses the bones itself; SR kept every clip. First grep for
+    the clip names.
+  - Duplicate textures (two library atlases stored the same 1024² image) are always merged.
+- **Animation:** every key is kept, never quantized or resampled. `--resample=on` drops keys the
+  neighbouring keys reproduce within 1e-4: it saved 1–2% of the file (croc 20 KB,
+  penguin 36 KB) and moved the croc's hands by up to 1.2 mm, enough to fail the 1 m face view
+  (0.962). The `octahedral` normals mode would also filter the clips.
+- **Replacing one:** a character row is not a `glb` row. Swap it in as a new row and repoint its
+  references (SKILL.md step 6), never in place.
+
+## code-driven: code reads its vertices, node positions or pixels
+
+This covers vehicles and props that code rebuilds from raw geometry, reads node world positions
+from, or samples pixels from (a livery mask read through `getImageData`). With this script SR's
+jet ski went 1.26 → 0.70 MiB, and 0.40 MiB with `--max-texture=512`. Of the saving at full size,
+0.14 MiB is the mask stored as lossless WebP instead of PNG, and the rest is the vertex buffers.
+
+- **Positions stay float32.** Quantized positions drew SR's skis as black tubes.
+- **Textures stay readable images.** The preset refuses KTX2. Base maps are kept as they are; the
+  ORM slot, where SR's jet ski keeps its livery mask, becomes lossless WebP with the exact pixels
+  (colour under transparent texels, and every alpha value, included). It stays a PNG or JPEG when
+  that is smaller, and a 16-bit PNG stays as it is: WebP has 8 bits per channel.
+- **A base map and the mask the code pairs with it must stay the same size**, or every racer falls
+  back to the stock livery. The script fails the `paired sizes` check when textures of one
+  material that matched in the input no longer do. `--max-texture=512` resizes both; overriding
+  one slot alone (`--base=jpeg:512:90`) fails.
+- **Halving the triangles failed** (0.965–0.977).
+
+## level: stages and level geometry
+
+Positions are float32, triangle order is untouched (coplanar overlaps resolve by draw order),
+vertices are renumbered by first use, and textures and animation clips are untouched. Normals and
+tangents are stored as int8 and in-range UVs as 16-bit, which no stage has shown. One TOR stage went
+2.26 → 1.01 MiB.
+
+- **Positions must not be quantized.** TOR's painterly materials sample `positionLocal` noise, so
+  quantizing shifts the pattern. Its batching merges identity transforms and would break.
+  Quantizing also reopens coplanar seam ties.
+- **Never delete "hidden" faces.** three draws shadow casters from their back faces, so the
+  undersides nobody sees are what cast the shadows.
+- **Empty marker nodes** carry spawn, item and goal data. The script never prunes them.
+- **It can save nothing.** Most of the saving is meshopt. With `--meshopt=off`, a TOR stage whose
+  export was already int8 came out 2% larger; the script then fails its `smaller` check, and the
+  original is what ships.
+- **A stage built by `building-levels-in-blender` is rebuilt from its script.** Every rebuild writes
+  an unoptimized GLB: run the preset on each new build before registering it.
+- **TOR went further, to 92 → 28 MB for 30 stages,** by dropping flat-shaded normals and rebuilding
+  them at load in game code. That is game-specific; do it only with the creator, as its own change.
+  TOR's own collision reader parses the stage GLBs directly, and it needed the meshopt decoder too.
+
+## Images outside GLBs (skies, backgrounds)
+
+The script handles GLBs only. SR's three skies went 0.81 → 0.17 MiB as 2048×1024 WebP at q97, and
+0.07 MiB at 1024×512 for phones, with no visible change. The shared tools include sharp:
+
+```sh
+node -e "import('$HOME/.bitmagic/tools/gltf/node_modules/sharp/dist/index.mjs').then(({default: s}) => s('sky.png').webp({ quality: 97 }).toFile('sky.webp'))"
+```
+
+A smaller sky blurs differently. SR gave each sky slot `lodBias = log2(2048 / width)` so a 1024 sky
+matched.

package/assets/optimizing-assets/references/runtime.md

@@ -0,0 +1,156 @@
+# Runtime: older engines, the A/B preview and per-device variants
+
+## A game-side decoder shim, for an engine without the decoder or the KTX2 wait
+
+SKILL.md step 5 greps the vendored engine for each half. An engine whose `GltfLoaderSupport.ts`
+has no `setMeshoptDecoder` cannot load `EXT_meshopt_compression`. One with no
+`expectGltfLoaderSupport` attaches the KTX2 loader on WebGPU only after the renderer's `init()`: a
+KTX2 GLB whose parse starts before that fails with `setKTX2Loader must be called before loading
+KTX2 textures`, and an optimized file, being smaller, arrives sooner. An engine with both does
+this in `createGltfLoader`. First choice: `bitmagic upgrade`, then grep again. Second:
+`--meshopt=off`, and non-KTX2 textures. Third, when the game must ship now: add this file and
+import it first thing in the game's entry module, before anything loads a GLB.
+
+- **A shim already in `src/`** counts only for the half it has. Squall Riders' `GltfDecoders.ts`
+  sets the decoder and waits for KTX2. Trick or Roll's sets only the decoder, so KTX2 assets there
+  need the wait below added to it, or non-KTX2 slot specs (`--base=webp:1024:90`).
+- **No `engine/engine/loaders/GltfLoaderSupport.ts`** (engines from before September 2026): the
+  engine reads no KTX2 anywhere, and the `gltfLoaderSupportsKtx2` import below does not compile.
+  Keep the decoder half: drop that import, `needsKtx2` and the wait, and call `parse` directly.
+  Give every asset non-KTX2 slots.
+
+```ts
+// src/work/GltfDecoderShim.ts: delete it once an upgrade passes SKILL.md step 5's engine greps.
+// Wraps GLTFLoader.prototype.parse once, so it covers every loader, including the ones the engine
+// builds, which game code cannot reach. It never replaces a decoder or KTX2 loader already set.
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';   // the engine's exact specifier
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
+import { gltfLoaderSupportsKtx2 } from 'engine/loaders/GltfLoaderSupport.js';
+
+type Parse = GLTFLoader['parse'];
+type Fields = { meshoptDecoder: unknown; ktx2Loader: unknown };
+const proto = GLTFLoader.prototype as unknown as { parse: Parse; decoderNotice?: string };
+
+/** Does this GLB (or glTF JSON) use KHR_texture_basisu? Reads the JSON chunk only. */
+function needsKtx2(data: unknown): boolean {
+    if (typeof data === 'string') return data.includes('"KHR_texture_basisu"');
+    if (!(data instanceof ArrayBuffer) || data.byteLength < 20) return false;
+    const view = new DataView(data);
+    const isGlb = view.getUint32(0, true) === 0x46546c67;
+    const start = isGlb ? 20 : 0, length = isGlb ? view.getUint32(12, true) : data.byteLength;
+    const json = new TextDecoder().decode(new Uint8Array(data, start, Math.min(length, data.byteLength - start)));
+    return json.includes('"KHR_texture_basisu"');
+}
+
+if (!proto.decoderNotice) {
+    // Kept as a string: minifiers strip the decoder's licence comment, and MIT asks for the notice.
+    proto.decoderNotice = 'meshoptimizer decoder, MIT License, Copyright (c) Arseny Kapoulkine';
+    const parse = proto.parse;
+    proto.parse = function (this: GLTFLoader, ...args: Parameters<Parse>): void {
+        const self = this as unknown as Fields;
+        self.meshoptDecoder ??= MeshoptDecoder;   // GLTFLoader reads it when it parses, not when built
+        if (self.ktx2Loader || gltfLoaderSupportsKtx2() || !needsKtx2(args[0])) return parse.apply(this, args);
+        // A KTX2 file that beat the renderer's init: wait (up to 20 s) for the engine to attach KTX2.
+        const started = performance.now();
+        const tick = (): void => {
+            if (!self.ktx2Loader && !gltfLoaderSupportsKtx2() && performance.now() - started < 20000) {
+                setTimeout(tick, 30);
+                return;
+            }
+            try {
+                parse.apply(this, args);
+            } catch (err) {   // a deferred throw must still reach the caller's onError
+                const onError = args[3];
+                if (onError) onError(err as ErrorEvent); else console.error(err);
+            }
+        };
+        setTimeout(tick, 30);
+    } as Parse;
+}
+```
+
+The decoder module embeds its WebAssembly, so it needs no second file. It is still a module: in the
+CDN lane, whose import map points `three/addons/` at esm.sh, it is one more request (~8 KB gzip);
+single-file builds inline it. Squall Riders and Trick or Roll vendored a copy into `src/`, so
+their CDN-lane publish bundles it instead of fetching it. Squall Riders shipped both halves before
+the engine took them over. Run `bitmagic check`, then decode the asset in the game as in
+[verification](verification.md): the dev asset panel does not load game code, so it cannot open
+meshopt files under this shim.
+
+## Previewing a candidate without uploading it (A/B)
+
+`bitmagic dev` serves the project folder, so a candidate in `.bitmagic/optimize/<asset>/` is at
+`/.bitmagic/optimize/<asset>/out.glb`. This temporary module swaps it in for the original URL on
+`?preview=1`, for every engine loader, without touching world.json. Import it first in the game's
+entry module, run the A/B, then delete the file and its import.
+
+```ts
+// src/work/AssetPreview.ts: TEMPORARY, for an A/B under `bitmagic dev`. Delete it after the A/B.
+import * as THREE from 'three';
+
+/** The row's `url` -> the candidate in its work directory. */
+const PREVIEW: Record<string, string> = {
+    'https://<the original url>.glb': '/.bitmagic/optimize/<asset>/out.glb',
+};
+
+if (new URLSearchParams(window.location.search).has('preview')) {
+    // Every GLTFLoader and TextureLoader the engine builds fetches through this manager.
+    const manager = THREE.DefaultLoadingManager;
+    const resolve = manager.resolveURL.bind(manager);
+    const swapped = new Set<string>();
+    manager.resolveURL = (url: string): string => {
+        const candidate = PREVIEW[url];
+        if (candidate && !swapped.has(url)) {   // logged on a real hit only, never at boot
+            swapped.add(url);
+            console.info('[preview] swapped', url, '->', candidate);
+        }
+        return resolve(candidate ?? url);
+    };
+}
+```
+
+- **Confirm the swap before capturing.** The `[preview] swapped` line appears only when the engine
+  asks for a mapped URL, and the network panel must show the `/.bitmagic/optimize/…` request. With
+  neither, the key differs from the URL the engine fetches (a query string, another encoding, a
+  variant), the "candidate" capture is the original, and the A/B passes at the noise floor.
+- **A game that rewrites asset URLs itself** (`grep -rlE "resolveURL|setURLModifier" src/`, such
+  as the variant map below) wraps the same function later, at game start, so its rewrite runs
+  first: the original URL becomes its variant before this module sees it. The candidate never
+  loads, and both sides show the variant. Capture both sides with that game's originals override
+  (Squall Riders: `?preview=1&assets=orig` against `?assets=orig`). That also makes the original,
+  not a variant, the baseline.
+- The published bundle has no `/.bitmagic/` folder, which is one more reason the module must go
+  before a publish.
+
+## Per-device variants (optional)
+
+One optimized set, swapped in, is usually enough. Squall Riders' creator saw no difference and
+moved every device to the phone set. Reach for variants when the phone set is visibly worse on a
+large screen, or when the asset is a `character` or other non-`glb` row, which cannot be replaced
+in place. The pattern, not a framework:
+
+- **Rows:** keep the original rows byte-identical. Add each variant as its own row, named after the
+  original with a suffix (`bitmagic assets add <file> --keep-glb --name <name>_mobile`). A new row
+  gets a new id, and nothing places it.
+- **The map:** a small module in `src/work/` maps each original asset id or URL to
+  `{ hq, mobile }` variant URLs.
+- **The decision:** make it once per page load from the device quality tier, the engine's answer
+  to what a device can afford (the engine's `DeviceQuality.ts`). `activeDeviceQualityTier()` of
+  `low` or `minimal` gets the small set, and so does a phone-sized screen
+  (`min(screen.width, screen.height) < 600` CSS px), which cannot show the difference anyway.
+  Everything else gets hq. Do not decide by `isMobileRuntime()`: it answers the UI question (a
+  small touch screen), not capability, so a Steam Deck would get the phone set and a slow Chromebook
+  the hq one. The auto-tuner can lower the tier later, but by then the assets are loaded. Log the
+  decision once at boot.
+- **Override:** `?assets=orig|hq|mobile|auto` on the URL, for A/B captures and a one-page rollback.
+  It wins over the tier, including a tier pinned with `?quality=`.
+- **Loads the engine owns** (placed props, the player character): rewrite the URL at fetch time,
+  as the preview module above does: wrap `THREE.DefaultLoadingManager.resolveURL` so it maps
+  original → variant for registered URLs only. **Never write variant URLs into `world.json` or its
+  in-memory copy.** The editor would save them back.
+- **Fallback:** if a variant fails to load, retry the original once, then report the error as
+  before.
+- **Rollback:** make the decision function return `orig`, or empty the map.
+
+The same device decision can drive non-asset savings too. SR skipped music on phones (−1.04 MiB)
+and capped a code-painted livery canvas at 512.