t1k:playablelabs:web:asset-compress
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| Tools | — |
Keywords: audio decode memory playable, duplicate assets dist audit, glb compression playable, ktx2 basis transcoder size, meshopt vs draco playable, paper deferral lazy load, playable over size ceiling, three.js playable asset size
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:asset-compress[texture | mesh | audio | audit <dist> | deferral]Web asset compression (three.js, web engine host)
Section titled “Web asset compression (three.js, web engine host)”Scope: which compression to spend bytes on for a web-host playable, and the decoder cost that each
choice puts back. Assets are 79-92% of shipped bytes (t1k-playablelabs-optimize-gate references/assets.md,
evidence M), so this is where a build over its ceiling is won or lost. Cocos games use the Cocos importer
and its own settings: out of scope, see theonekit-cocos:playable t1k-cocos-playable-build-size when that
module is installed.
Evidence labels: S sourced, M measured by this skill’s author on a real file (sample size given), H hypothesis, unverified recalled or unmeasured; never state H or unverified as fact.
Decide first, then read one reference
Section titled “Decide first, then read one reference”| Question | Short answer | Read |
|---|---|---|
| KTX2/Basis, WebP, or PNG? | WebP/PNG for bytes. KTX2 only to cut decoded GPU RAM, and its transcoder alone is 571 KB (M, n=1 version) | references/texture-format-decision.md |
| meshopt, Draco, or quantize? | Quantize first (no decoder), then meshopt (28.6 KB decoder, M). Draco only if its 245 KB decoder is repaid: measured A/B on 3 skinned GLBs (M, n=3), meshopt won raw totals on all three, Draco won gzip totals on two | references/mesh-compression-decision.md |
| Big decoded audio, or audio kbps? | Decoded RAM = seconds x context rate x channels x 4 bytes (Float32 AudioBuffer); 2 bytes is only the 16-bit WAV file size. A 30 s stereo 44.1 kHz loop is 10.09 MiB | references/audio-decode-memory.md |
| Same file shipped twice? A “lazy” split that saves nothing? | Run scripts/asset-audit.cjs on the built dir | references/duplicates-and-paper-deferral.md |
The audit script
Section titled “The audit script”bun scripts/asset-audit.cjs <dist-dir> [--ceiling-kb 4882] [--top 15] [--context-rate 48000] [--json]bun scripts/asset-audit.cjs pcm <seconds> <sampleRate> <channels> [bytesPerSample=4]Zero dependencies. Ranks files by size (raw and gzip-9), groups duplicates by MD5, reads PNG / WebP / KTX2 headers
for decoded RGBA8 RAM, reads WAV for decoded Float32 AudioBuffer RAM, compares the total to a ceiling, and flags
deferred-looking files that a boot file names. Read-only (never writes into the audited dir), one file in memory at a
time, symlinks skipped and counted, unreadable files listed. Exit 0 clean, 1 findings (or empty directory: NOT-RUN), 2 usage. Tests:
scripts/asset-audit.test.cjs (RED cases for duplicates, ceiling and paper deferral).
- Count the decoder. A saving is
bytes saved - decoder bytes shipped. In a single-HTML network a wasm decoder is base64-inlined (x4/3); in a zip network it is a stored member. Ceilings: Meta, Google, Snapchat 4882 KB, Yandex 3072 KB (t1k-playablelabs-base-networks); the packer’s--budget-kbdefault 5120 hides both. - Measure the asset in hand. A ratio from another game is a hint. Report before/after bytes and the sample size.
- Visual gate after any lossy step: the F3 SSIM floors in
t1k-playablelabs-optimize-gate. - Do not duplicate the draw-call tool. Joining primitives is
t1k-playablelabs-web-perfscripts/glb-reduce-draws.cjs; this skill compresses bytes. Run reduce-draws first, compress second. - Web-only. Nothing here changes a Cocos build; the checks A9 and A14 in the gate stay as written for Cocos.
Executed by
Section titled “Executed by”Running the audit and tabulating its rows is mechanical; choosing a codec or accepting a lossy step is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run scripts/asset-audit.cjs, list the rows per file | t1k-tester (read-only build-verification lane), or the calling agent itself |