t1k:playablelabs:optimize:passes
| Field | Value |
|---|---|
| Module | optimize |
| Version | 1.16.2 |
| Effort | medium |
| Tools | — |
Keywords: js-base64-repack, js-minify, optimize-apply, optimize-audit, packer budget-kb, packer optimize passes
How to invoke
Section titled “How to invoke”/t1k:playablelabs:optimize:passes[pass id | audit | apply <tier>]Packer optimize passes
Section titled “Packer optimize passes”Scope: what the packer’s optimize module does, which flag turns on which pass, and how to measure a
saving. Per-network ceilings live in the networks skill (link only). Cocos-side size work is the
Cocos kit’s t1k-cocos-playable-build-size (link only). Any pass that changes Cocos output
violates the hard constraint “web work must not change Cocos bytes”: run change-proof before
claiming it does not.
Reviewing a whole playable (assets, code technique, CPU, memory, per-PR PASS/FAIL table) is t1k-playablelabs-optimize-gate, which calls this skill for the flags; this skill stays the flag and pass reference.
Contract
Section titled “Contract”- Everything is opt-in. With no
--optimize*flag, the packed artefact (--out) is byte-identical to a build from before the flag existed; onlypack-report.jsongains"optimization": nulland a text lineoptimize: disabled(PlaybleEngine:src/cli.tsUSAGE,--audio-monoparagraph). - With a flag,
--buildis COPIED to a scratch dir and passes run on the copy;--buildis never written. - Result per pass is in
pack-report.jsonunderoptimization(files changed, bytes saved, before/after totals).
Tiers (src/optimize/passes.ts TIERS)
Section titled “Tiers (src/optimize/passes.ts TIERS)”| Tier | Meaning |
|---|---|
| L0 | container only (deflate); carries no pass rows |
| L1 | lossless / pixel-identical: engine-module prune, PNG->WebP lossless, dead-asset report, metadata strip, audio silence trim, font subset, js-minify, js-base64-repack |
| L2 | bounded loss, opt-in: audio crush, PNG quantise |
| L3 | visible loss, opt-in: texture downscale, mesh simplify, audio mono, anim extraction |
Flags (pack)
Section titled “Flags (pack)”| Flag | Notes |
|---|---|
--optimize | umbrella: metadata-strip, audio-silence-trim, texture-downscale, font-subset (AUTO_OPTIMIZE_PASS_IDS); plus every web-only pass on --engine-host web. NOT audio-mono |
--optimize-metadata-strip, --optimize-audio-silence-trim, --optimize-font-subset, --optimize-texture-downscale, --optimize-js-minify, --optimize-js-base64-repack, --optimize-audio-mono | one pass each. js-minify needs no --deflate; js-base64-repack does (PassRow.needsDeflate) |
--deflate-zopfli (+ --deflate-zopfli-iterations <n>, --deflate-zopfli-budget-ms <n>) | NOT an optimize pass (no row in PASS_ROWS, not in --optimize): a better encoder for the entries --deflate compresses. Needs --deflate (exit 2 without), any engine host, lossless, same raw-deflate format. Composes with js-minify / js-base64-repack (they change the bytes, zopfli encodes whatever results). Details: t1k-playablelabs-base-pack |
--minify-boot | NOT an optimize pass and not in --optimize: terser over the packer’s own boot code, any engine host, on by default for the web host (--no-minify-boot opts out), off for cocos-3.8 and none (see ## minify-boot) |
--font-keep-chars <file> | extra codepoints for font subset; needs font-subset enabled |
--budget-kb <n> | default 5120; applies to EVERY network and overrides vendor ceilings (studio decision 2026-09-22, src/cli.ts USAGE); `—mode raw |
Host rules: Cocos-only passes (engine-module-prune, texture-downscale, anim-extraction,
mesh-simplify; cocosOnlyPassIds()): umbrella skips them on a non-Cocos host, naming each on stderr
and in optimization.skipped; naming one by flag there exits 2. Web-only (webOnlyPassIds(), today
js-minify, js-base64-repack): on a non-web host the umbrella ignores it silently, naming it exits 2.
In CI (opt-in, default off). Jenkins PARAM_OPTIMIZE and the GitHub Actions template’s optimize input /
PLA_OPTIMIZE take off | lossless | all. lossless is the explicit lossless flags per host, NEVER
--optimize (lossy texture-downscale on Cocos); all is --optimize. One mapping, scripts/optimize-flags.cjs
(bun scripts/optimize-flags.cjs --choice lossless --engine-host web --deflate), tested against this table both
directions (tests/optimize-flags.test.js): a new lossless pass fails that test until it is placed deliberately.
Audit and apply (separate subcommands)
Section titled “Audit and apply (separate subcommands)”bun dist/cli.js optimize-audit --build <dir> [--json] [--engine-host <id>] # read-only, writes nothingbun dist/cli.js optimize-apply --build <dir> --tier <L0|L1|L2|L3> [--json] [--engine-host <id>] # WRITESAudit reports per pass available / unavailable (names the missing tool) / report-only /
not-applicable (Cocos-only pass on non-Cocos host). Apply needs an explicit --tier, audits first,
and never deletes anything. Run --help for the full status vocabulary. Tools a pass needs
(cwebp, magick, ffmpeg encoders, pyftsubset, pngquant, gltfpack) are probed, never assumed.
js-minify
Section titled “js-minify”Web only, lossless in behaviour (L1), .js/.mjs members. Rewrites a game-owned member with terser
(a normal dependency, the packer’s first runtime one): compress + LOCAL-name mangle only; top-level
names, module and property mangling are off, class/function names and debugger are kept, no
unsafe* option. Terser runs in a worker thread with a 60 s per-member limit (timeout = skipped,
recorded) and is never loaded unless the pass runs. Kept only when smaller raw AND deflated
(shouldKeepMinified); otherwise the original stays byte for byte and the reason is in the pass
detail. Skips: already-minified source (whitespace under 8% of the characters, base64 blobs and long
data lines excluded), engine/vendor paths, non-UTF-8, a worker that cannot start, and anything terser
throws on (recorded, never fails the pack). Needs no --deflate. Runs BEFORE js-base64-repack
(the table order is the run order): minify sees the plain base64 literal, the repack then turns it
into hex.
Measured, N=2, not a corpus: both web fixtures are already-minified Vite bundles, the pass skips both
and the packed bytes do not move (0%). Forced past the skip terser is no better (arrow3d-three-web
game.js raw +1.7%, deflated -0.7%; slingnshot-web raw +1.0%, deflated +0.3%). On a synthetic
beautified arrow3d game.js it takes the packed common/index.html 1,166,692 -> 1,143,275 B (-2.0%).
Worth it only for unminified JS.
minify-boot
Section titled “minify-boot”--minify-boot (src/optimize/boot-minify.ts) minifies the packer’s OWN text that is spliced into every
page, on any engine host: the runtime IIFE (renderRuntime, with the engine-host hooks, params hook,
decoder, inflate fallback and MANIFEST inside it), glFallback and, on the Cocos host, importMapReplay.
Network-supplied text (CTA, start gate, compat) is never touched. It reuses the js-minify worker and
options (runTerser), so no option is duplicated: local names only, top-level and property names and
class/function names kept. The payload blob never reaches terser (a sentinel stands in for it). A piece is
kept only when smaller raw AND deflated; one terser cannot parse, that times out, or that would lose a
top-level name or window. property the page calls (checked after the rewrite) is left as rendered, with the
reason in emitted[].bootMinify[] (rawSaved/deflatedSaved per piece, sizes exclude the blob). The key
exists only when boot minify ran (src/cli.ts:2852): pack-hashes.json baselines embed the whole report.
Measured (3 fixtures, 34 rows each, --deflate): single-file HTML rows shrink 20-60 KB (1-2%), ZIP rows
6-18 KB (the page is deflated in the archive). On by default for the web host since PlaybleEngine #230 (src/cli.ts:959; --no-minify-boot
opts out); off for cocos-3.8 and none, whose bytes stay unchanged. Flipping those needs
t1k-playablelabs-base-change-proof evidence. --emit-preview artefacts keep the unminified runtime.
Separate from the pass: bun run build && bun run build:min writes a minified copy of the packer’s own
dist/ to git-ignored dist-min/ (scripts/minify-dist.cjs); dist/ is never touched.
js-base64-repack
Section titled “js-base64-repack”Web only, lossless (L1). A bundler inlines a wasm/font as one giant base64 string literal; deflate
handles base64 badly, hex is byte-aligned. The pass rewrites each literal of >= 16,384 chars
(MIN_BASE64_LITERAL_CHARS) in .js/.mjs members as a hex-backed expression that evaluates to the
SAME string, proven per literal (encode(decode(x)) === x), and keeps it only when the deflated member
is smaller. Needs --deflate: named without it exits 2; via the umbrella it is dropped with a
stderr line. Raw JS grows, packed bytes shrink; adds a one-off hex->btoa at load (tens of ms for 3 MB).
Skips non-canonical base64, data: URIs, object keys, module specifiers.
Measured: -16.3% on the deflate-9 JS member of the slingnshot-web fixture (1,800,401 -> 1,506,670 B;
packed applovin index.html 2,118,230 -> 1,782,537 B). Source: PlaybleEngine:src/optimize/passes.ts
js-base64-repack row and src/optimize/js-base64-repack.ts header; N=1, one literal, “not a corpus”.
The fixtures arrow3d-three-web and slingnshot-web pack with it (ci/engine-matrix/fixtures.json).
Measuring
Section titled “Measuring”pack-report.json(--json): per networkemitted[].artefact(raw/gzip) andemitted[].classAttribution(packedBytesper class, plus a per-network text-encoded share). Compare before/after on classes, not disk size.- First frame: pack with
--timing, thennode scripts/bench-first-frame.cjs --report <pack-report.json> --out <dir> --out-json <path> [--runs n] [--throttles ...]. ReadfirstSceneFramefor “the player sees the game”;firstFramefires 0.8-1.9 s earlier, during scene load (script header). A report packed without--timingyields nullfirstFrameMsand exits as missing data. - Headline Cocos vs web numbers (Arrow3D): not found in the packer’s plans or reports: omitted.
Verified against
Section titled “Verified against”PlaybleEngine@4ee4272 (2026-10-04): src/optimize/passes.ts, src/optimize/apply.ts,
src/optimize/js-base64-repack.ts, src/cli.ts (USAGE, flag parsing), scripts/bench-first-frame.cjs,
ci/engine-matrix/fixtures.json.
Hard rules
Section titled “Hard rules”--budget-kbabove a vendor ceiling reports PASS in pack and can still bounce at the network.- Measured savings in the pass table are projections from named runs, never summed into a total.
texture-downscaleonly touches textures proven 3D-material-only; a SpriteFrame/atlas reference fences it off.- The slingnshot-style CI uses
--engine-host none:js-base64-repackandjs-minifyare refused there. Useweb.