Skip to content

t1k:playablelabs:optimize:passes

FieldValue
Moduleoptimize
Version1.16.2
Effortmedium
Tools—

Keywords: js-base64-repack, js-minify, optimize-apply, optimize-audit, packer budget-kb, packer optimize passes

/t1k:playablelabs:optimize:passes
[pass id | audit | apply <tier>]

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.

  • Everything is opt-in. With no --optimize* flag, the packed artefact (--out) is byte-identical to a build from before the flag existed; only pack-report.json gains "optimization": null and a text line optimize: disabled (PlaybleEngine:src/cli.ts USAGE, --audio-mono paragraph).
  • With a flag, --build is COPIED to a scratch dir and passes run on the copy; --build is never written.
  • Result per pass is in pack-report.json under optimization (files changed, bytes saved, before/after totals).
TierMeaning
L0container only (deflate); carries no pass rows
L1lossless / pixel-identical: engine-module prune, PNG->WebP lossless, dead-asset report, metadata strip, audio silence trim, font subset, js-minify, js-base64-repack
L2bounded loss, opt-in: audio crush, PNG quantise
L3visible loss, opt-in: texture downscale, mesh simplify, audio mono, anim extraction
FlagNotes
--optimizeumbrella: 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-monoone 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-bootNOT 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.

Terminal window
bun dist/cli.js optimize-audit --build <dir> [--json] [--engine-host <id>] # read-only, writes nothing
bun dist/cli.js optimize-apply --build <dir> --tier <L0|L1|L2|L3> [--json] [--engine-host <id>] # WRITES

Audit 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.

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 (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.

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).

  1. pack-report.json (--json): per network emitted[].artefact (raw/gzip) and emitted[].classAttribution (packedBytes per class, plus a per-network text-encoded share). Compare before/after on classes, not disk size.
  2. First frame: pack with --timing, then node scripts/bench-first-frame.cjs --report <pack-report.json> --out <dir> --out-json <path> [--runs n] [--throttles ...]. Read firstSceneFrame for “the player sees the game”; firstFrame fires 0.8-1.9 s earlier, during scene load (script header). A report packed without --timing yields null firstFrameMs and exits as missing data.
  3. Headline Cocos vs web numbers (Arrow3D): not found in the packer’s plans or reports: omitted.

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.

  • --budget-kb above 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-downscale only touches textures proven 3D-material-only; a SpriteFrame/atlas reference fences it off.
  • The slingnshot-style CI uses --engine-host none: js-base64-repack and js-minify are refused there. Use web.