Skip to content

t1k:playablelabs:optimize:shared-libs

FieldValue
Moduleoptimize
Version1.16.2
Effortmedium
Tools—

Keywords: playable shared library pattern, rapier3d-compat playable, shared lib web playable, wasm base64 playable

/t1k:playablelabs:optimize:shared-libs
<library name> [--engine-host web|none]

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)”
  1. 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).
  2. 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 what js-base64-repack targets (MIN_BASE64_LITERAL_CHARS).
  3. Pack on host web with --deflate --optimize-js-base64-repack (or --optimize). none refuses the pass (exit 2); without --deflate it exits 2 too. See the passes skill for exact behavior.
  4. Gate first frame on async init. Most wasm libs init asynchronously (await RAPIER.init()). Build the world, then draw, and only then set window.__PLA_SCENE_UP__ = true (after the first frame of the first scene) and window.__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.
  5. Budget from classAttribution, not disk size. Read pack-report.json emitted[].classAttribution and the per-network artefact raw/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.
  6. 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.
  7. 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.ts resolveVfsSrc), so a missed asset surfaces only as a failed request, recorded in failedRequests and never failing a row (smoke.cjs: “DIAGNOSTIC ONLY”). A library asset that silently fails to load can still pass smoke: read failedRequests in smoke-report.json yourself.
  8. 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).
ItemFactSource
Package@dimforge/rapier3d-compat ^0.21.0 (3D); three ^0.186.1slingnshot:package.json
Initstatic async create() { await RAPIER.init(); ... } in Physicsslingnshot:src/core/physics.ts
Scene-up flag__PLA_SCENE_UP__ set in the first rendered frame()slingnshot:src/game/game.ts
Inlined wasm3,082,103 B wasm as one 4,109,472-char base64 literal in the bundlePlaybleEngine:src/optimize/passes.ts row js-base64-repack
SavingJS member deflate-9 1,800,401 -> 1,506,670 B (-16.3%), N=1same row; ci/engine-matrix/fixtures.json slingnshot-web
2D counterparta 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.

  1. bun install <lib>; bun run build; locate its bytes in dist/ (wasm literal? separate chunk? font?).
  2. Add the init promise to the boot sequence BEFORE __PLA_SCENE_UP__; keep the loading element until ready.
  3. Pack on web: baseline (no --optimize) vs --optimize-js-base64-repack; record raw and gzip per network.
  4. Run smoke on all networks; read smoke-report.json failedRequests.
  5. 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.
  6. Decide per references/lib-decision-table.md.

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.

  • The repack decodes hex with btoa at 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 .wasm path can fail only inside the packed page: smoke on a real network row, not vite preview.
  • rapier2d and other libs not in the repos: do not claim sizes or flavours (see the table’s “unverified”).