t1k:playablelabs:optimize:shared-libs
| Field | Value |
|---|---|
| Module | optimize |
| Version | 1.16.2 |
| Effort | medium |
| Tools | — |
Keywords: playable shared library pattern, rapier3d-compat playable, shared lib web playable, wasm base64 playable
How to invoke
Section titled “How to invoke”/t1k:playablelabs:optimize:shared-libs<library name> [--engine-host web|none]Shared library in a web / none playable
Section titled “Shared library in a web / none playable”Scope: a general pattern for adding ANY third-party library to a game packed with --engine-host web
or none; physics (Rapier in slingnshot) is only the worked example. Cocos games bring their own
engine modules: size work there is the Cocos kit’s t1k-cocos-playable-build-size (link only).
Packer pass details: t1k-playablelabs-optimize-passes. Any change touching shared/engine
code must be proven not to change Cocos output: change-proof.
How game code and libs are decoupled (public package API, @playablelabs/* CPM packages, neutral
core, import-graph CI gate): rule playablelabs-decouple-game-code.md; this skill is the size and
build checklist for the lib itself.
Checklist (do in order, stop at the first red)
Section titled “Checklist (do in order, stop at the first red)”- Pick an inlined build. The packer ships one self-contained HTML/ZIP per network; a library that
fetches its
.wasm/data at runtime from a URL has nothing to fetch in the ad container. Prefer the package’s single-file flavour (Rapier:@dimforge/rapier3d-compat, wasm embedded as base64). - Know what the bundler emits. After
bun run build, look for one huge base64 string literal in the JS (a bundler-inlined wasm/font/codec). Literals >= 16,384 chars are whatjs-base64-repacktargets (MIN_BASE64_LITERAL_CHARS). - Pack on host
webwith--deflate --optimize-js-base64-repack(or--optimize).nonerefuses the pass (exit 2); without--deflateit exits 2 too. See the passes skill for exact behavior. - Gate first frame on async init. Most wasm libs init asynchronously (
await RAPIER.init()). Build the world, then draw, and only then setwindow.__PLA_SCENE_UP__ = true(after the first frame of the first scene) andwindow.__plaGame__ = { running, scene, nodeCount() }(none-host-game-contract.md). Do not set__PLA_SCENE_WATCH__unless the game really sets__PLA_SCENE_UP__, or every load shows the fallback card after 30 s. - Budget from
classAttribution, not disk size. Readpack-report.jsonemitted[].classAttributionand the per-networkartefactraw/gzip against--budget-kb(default 5120, overrides vendor ceilings). A repacked literal GROWS raw JS and shrinks packed bytes, so a raw-size diff misleads. - Check the entrypoint and tree-shaking. Import only the subpath you use (slingnshot imports
three/examples/jsm/...per file) and re-pack to confirm the library’s share did not balloon. - Smoke on every network.
scripts/smoke.cjs --engine-host <web|none>: “booted” = >= 3 frames and a running scene with >= 1 node. Smoke is hermetic: it ABORTS every cross-origin request, and a lookup that misses the packed VFS passes the original URL through (src/runtime/boot.tsresolveVfsSrc), so a missed asset surfaces only as a failed request, recorded infailedRequestsand never failing a row (smoke.cjs: “DIAGNOSTIC ONLY”). A library asset that silently fails to load can still pass smoke: readfailedRequestsinsmoke-report.jsonyourself. - Prove both engines unchanged with
change-proof: the Cocos fixtures’ pack hashes must stay identical and the web fixture’s hashes change only where intended (ci/engine-matrix/baselines/*.pack-hashes.json).
Worked example: Rapier in slingnshot
Section titled “Worked example: Rapier in slingnshot”| Item | Fact | Source |
|---|---|---|
| Package | @dimforge/rapier3d-compat ^0.21.0 (3D); three ^0.186.1 | slingnshot:package.json |
| Init | static async create() { await RAPIER.init(); ... } in Physics | slingnshot:src/core/physics.ts |
| Scene-up flag | __PLA_SCENE_UP__ set in the first rendered frame() | slingnshot:src/game/game.ts |
| Inlined wasm | 3,082,103 B wasm as one 4,109,472-char base64 literal in the bundle | PlaybleEngine:src/optimize/passes.ts row js-base64-repack |
| Saving | JS member deflate-9 1,800,401 -> 1,506,670 B (-16.3%), N=1 | same row; ci/engine-matrix/fixtures.json slingnshot-web |
| 2D counterpart | a rapier2d build exists upstream: unverified (not in slingnshot or the packer clone) | n/a |
slingnshot’s own CI packs it with --engine-host none (no repack); the packer’s slingnshot-web
fixture packs the same dist with host web plus js-base64-repack
(ci/engine-matrix/fixtures.json), which is the configuration that gets the saving.
Adding a new shared lib: recipe
Section titled “Adding a new shared lib: recipe”bun install <lib>;bun run build; locate its bytes indist/(wasm literal? separate chunk? font?).- Add the init promise to the boot sequence BEFORE
__PLA_SCENE_UP__; keep the loading element until ready. - Pack on
web: baseline (no--optimize) vs--optimize-js-base64-repack; record raw and gzip per network. - Run smoke on all networks; read
smoke-report.jsonfailedRequests. - If a fixture is needed in CI, it belongs to the packer’s engine-matrix (
ci/engine-matrix/fixtures.json); a new fixture is a packer change, not this kit’s. - Decide per
references/lib-decision-table.md.
Verified against
Section titled “Verified against”PlaybleEngine@4ee4272 (2026-10-04): src/optimize/passes.ts, src/optimize/js-base64-repack.ts,
src/runtime/boot.ts, scripts/smoke.cjs, .claude/skills/playable-engine/references/none-host-game-contract.md,
ci/engine-matrix/fixtures.json; slingnshot@1363468: package.json, src/core/physics.ts,
src/game/game.ts, src/main.ts.
Hard rules
Section titled “Hard rules”- The repack decodes hex with
btoaat load (pass hazard note: tens of ms for 3 MB); behaviour on every network WebView is unverified, so smoke it. - A library that sniffs the environment for a fetchable
.wasmpath can fail only inside the packed page: smoke on a real network row, notvite preview. rapier2dand other libs not in the repos: do not claim sizes or flavours (see the table’s “unverified”).