Skip to content

t1k:playablelabs:base:pack

FieldValue
Modulebase
Version2.29.2
Effortmedium
Tools—

Keywords: pack-report.json, packer cli, packer exit codes, pla-pack, playablelabs packer

/t1k:playablelabs:base:pack
<build dir> --out <dir> [--engine-host cocos-3.8|web|none]

The packer (The1Studio/PlaybleEngine, master, package @playablelabs/packer) does not render a game. It packs a built game into one deliverable per ad network, adapts it (CTA, start gate, store links), and a separate smoke harness boots the result. Authoring Cocos 3.8.7 game code is the Cocos kit’s job (t1k-cocos-playable-build-size, t1k-cocos-playable-sdk-core, t1k-cocos-playable-pipeline); Jenkins job edits are core’s t1k-jenkins-job / t1k-jenkins-cocos. This is not t1k-repomix (“pack” a repo for an LLM).

Hard constraint before changing anything in the packer: Cocos customers must see zero behaviour change. Read t1k-playablelabs-base-change-proof first. PlaybleEngine, PlayableLabs and ParamTool are not T1K repos: never force-push or rebase there, and merge main into your branch instead.

dist/ is gitignored, so a fresh clone has no CLI until you build it (Node >= 20, package.json engines):

Terminal window
git clone git@github.com:The1Studio/PlaybleEngine.git <packer-clone> # branch master
cd <packer-clone> && bun install --frozen-lockfile && bun run build # tsc -> dist/cli.js (bin name: pla-pack)
bun dist/cli.js --bogus 2>&1 | head -60 # no --help: bad args print the full USAGE, exit 2

The packer pins typescript 7.0.2 exactly (the native compiler; it used to be a ^5.6.0 range). bun run build still emits with tsc; bun run typecheck runs TSRS, the typecheck gate. tsconfig.json needs "types": ["node"] (7.x no longer auto-includes @types). It only compiles the Node CLI (src -> dist); the in-page runtime ships as JS strings, so the compiler cannot change playable bytes (evidence: references/toolchain.md). A GAME project keeps its own TypeScript version. A tool that drives the TypeScript JS API (typescript-eslint, which t1k-playablelabs-optimize-gate loads) is NOT verified against 7.x.

There is no --help flag: parseArgs returns null on any unknown flag and main prints USAGE to stderr, exit 2, so bun dist/cli.js --bogus shows the authoritative flag list for the SHA you built. Do not install into a shared clone another session uses; copy it to a scratch dir first.

CommandWrites?Purpose
pla-pack --build <dir> --out <dir> [opts]--out (+ temp copy if optimizing)pack (the default, no subcommand word)
audit-modules --project <dir> [--against-build <dir>] [--canary-out <p>] [--json] [--engine-host <id>]noCocos engine modules declared vs used. Cocos-only: other host ids exit 2
audit-hierarchy --project <dir> [--build <dir>] [--json]noscene/prefab hierarchy lint
optimize-audit --build <dir> [--json] [--engine-host <id>]nowhich optimize passes could touch the build
optimize-apply --build <dir> --tier L0|L1|L2|L3 [--json] [--engine-host <id>]yes (the build)applies a tier; explicit tier required

Optimize passes and measuring are the optimize module’s topic; this skill only lists the flags.

Before you pack: lazy policy (web or none game that targets Google)

Section titled “Before you pack: lazy policy (web or none game that targets Google)”

Run this on the built dist/ of the game, before the pack, so the pack reads a policy. Cocos: skip.

Terminal window
bun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --out public/playable-lazy.json # no file yet
bun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --check # file exists

Commit public/playable-lazy.json: vite copies public/ into the build root, where the packer reads it. Exit codes: 0 ok, 1 --check violation, 2 usage, 3 browser unavailable in runtime mode (never a silent static fallback), 4 a file was written but nothing is deferrable. Modes, --first-frame-ms and the contract: t1k-playablelabs-web-lazy-load.

Pack flags and defaults (USAGE + parseArgs, verified)

Section titled “Pack flags and defaults (USAGE + parseArgs, verified)”
FlagDefaultNotes
--build <dir> / --out <dir>required--build resolved against cwd once
--budget-kb <n>5120studio requirement applied to EVERY network; overrides vendor ceilings
--mode raw|gziprawonly applies to networks with no ceiling of their own; a network with a ceiling keeps its own mode
--network <ids>commoncomma list or all. all = every id except defaultOff ones (ironsource)
--layout flat|superhtmlflatsee Output layout
--name <name>derivedneeded for superhtml unless --build ends in build/web-mobile
--engine-host cocos-3.8|web|nonecocos-3.8see t1k-playablelabs-base-engine-hosts
--engine <builtin|40-hex>builtinRECORDED, not applied; a short SHA is refused
--cocos-tool <name> / --cocos-tool-path <p>noneRECORDED, not applied
--build-id <id>$BUILD_NUMBER else nonerecorded to buildIdentity.number; 1-64 non-space chars
--game-sha <7-40 hex>nonerecorded; deliberately no env fallback
--deflate / --webp / --no-vfs-dedupeoff / off / dedupe ON--webp needs cwebp (or ffmpeg for alpha-free PNG)
--deflate-zopfli, --deflate-zopfli-iterations <1-1000>, --deflate-zopfli-budget-ms <n>off; 15 passes (5 over 2 MiB); 30000 ms per entryneeds --deflate (exit 2 without; the tuning flags need --deflate-zopfli). Lossless, standard raw deflate, so the page’s inflate is unchanged. Keeps the smaller of zopfli and zlib-9 per entry; falls back to zlib-9 on budget or encoder fault. Report: deflateZopfli (present only with the flag)
--lazyload auto|offautoL2 sibling members for rows with a lazyLoad capability (yandex only)
--emit-previewoffwrites <stem>.preview.html beside L2 artefacts
--timing, --image-bitmap, --start-gate <p>, --audio-gate <src>[,true|false]offbuild-time A/B and emergency overrides; adapter table is the production source
--minify-bootON for web, off for cocos-3.8 and none (--no-minify-boot opts out)terser over the packer’s OWN boot code (runtime IIFE, WebGL fallback, Cocos import-map replay); any engine host; per piece kept only if smaller raw AND deflated; cocos and none default bytes unchanged; emitted[].bootMinify in the report only when minified (see t1k-playablelabs-optimize-passes)
--lazy-assetsoffweb and none hosts only (cocos-3.8 exits 2). Audio leaves the boot payload and loads on first touch or on idle. Policy: --lazy-config <f>, else <build>/playable-lazy.json when present, else audio only. JS, CSS, wasm and html are never deferred. A missing late payload or a failed zip member download rejects with an error, no fallback. Flags, schema, report fields: references/lazy-assets.md
--lazy-assets-scope all|defaultallneeds --lazy-assets. default = the rows whose network adapter declares lazyAssetsDefault (google, google_portrait, google_landscape today); every other row is byte-identical to a build without the flag. Jenkins PARAM_LAZY_ASSETS=auto passes default
--lazy-config <f>noneneeds --lazy-assets; JSON policy that wins over playable-lazy.json. Schema: references/lazy-assets.md
--optimize, --optimize-<pass>, --font-keep-chars <f>offevery pass OFF by default; --optimize-audio-mono is never part of --optimize
--no-hierarchy-lint, --hierarchy-project <dir>lint ONwarn-only, never changes exit code
--jsonoffreport JSON on stdout (capture it: > pack-report.json)

pack-report.json is not written by the CLI itself: it is the --json stdout, redirected by the caller (the Jenkinsfile does --json > dashboard-pack-report.json; CI uploads pack-report.json).

Codepackaudit-modules / optimize-auditoptimize-apply
0no row over budgetcleantier changed bytes
1at least one row fail (over budget, or a packer-owned index.html overflow)findings / defeated audit / empty buildtier changed no bytes
2usage or input error, or an uncaught exception (main().catch)samesame

audit-hierarchy always exits 0 (2 on usage). On any exit 2 read stderr: the message names the bad flag.

allPass (no row failed), allVerified, unknownCount, and per row emitted[].verdict {status: pass|fail|unknown, mode, actualBytes, budgetBytes, budgetUnverified, archiveBreach?} plus emitted[].sizeVerified (this network’s vendor ceiling was read from the vendor page). Also top-level breakdown, engine, cocosTool, webp, vfsDedupe, storeUrls, mode, buildIdentity, optimization (null when no optimize flag), composition. The schema is additive-only (packer SKILL.md). Gate on allPass for size. archiveBreach is reported evidence, not a failure, except the packer-owned index.html overflow which sets status: fail.

flat: <out>/<network>/index.html or index.zip (zip when the adapter is not singleFile). superhtml: <out>/<folder>/<name>_<suffix>.<ext>, the same tree super-html v5.4.0 wrote. Selecting a network also emits its variant rows (google -> google, google_portrait, google_landscape; facebook -> facebook_zip too; inmobi_zip is row-level default-off). Per-network detail: t1k-playablelabs-base-networks.

references/drift.md holds the one-liner that tells you whether this skill is stale against the packer. Wrong or stale content found while working goes to the lesson queue / /t1k:sync-back, never a local patch.

PlaybleEngine@d76f263 (2026-10-07): src/cli.ts (USAGE, parseArgs, main, exit-code header, JSON report block), src/core/measure.ts (checkBudget), src/adapters/channels.ts (channelsFor), package.json, .claude/skills/playable-engine/SKILL.md. git diff 4ee4272 d76f263 over src/ and package.json is empty, so the 4ee4272 read of those files stands; playable-engine/SKILL.md was not re-read.

The TypeScript 7.0.2 note above is read from PlaybleEngine@faed329: package.json (typescript pin, engines.node >=20, build / typecheck both tsc -p tsconfig.json at that SHA; the typecheck script is TSRS after the packer migration) and tsconfig.json ("types": ["node"]). That read covers the build only — the CLI claims above stay at d76f263, and git diff d76f263 faed329 over the watched files is NOT empty (src/cli.ts, Jenkinsfile/PlayablePacker, src/engine/cocos38/modules.ts). The --minify-boot row is read from PlaybleEngine@2f4443f src/cli.ts (--no-minify-boot at :791, the web default at :959, bootMinify in the report at :2852; default flipped by #230). The --lazy-assets* rows and references/lazy-assets.md are read from PlaybleEngine@8f7dc9d (src/cli.ts USAGE and parseArgs, plans/lazy-assets.md, src/adapters/networks.ts); no packer was run for them.

  • Source comments claim 23 of 27 networks give unknown verdicts exiting 0. At d76f263 the pack path calls checkBudget(..., false) (cli.ts), so a row is pass or fail; unknown is not produced there today. Use emitted[].sizeVerified, not allVerified, to know whether a vendor ceiling backs a row.
  • --budget-kb default 5120 overrides vendor ceilings: a build between Meta/Google/Snapchat 4882 KB (or Yandex 3072 KB) and 5120 KB reports PASS and bounces on upload. Pass --budget-kb per network run.
  • --engine, --cocos-tool*, --build-id, --game-sha select nothing; they only label the report.
  • --network defaults to common (one neutral artefact), not all.
  • --webp does nothing when no cwebp (or ffmpeg for alpha-free PNG) is on PATH: the pack still exits 0 with PNG bytes unchanged, and with --json > pack-report.json the one-line notice is easy to miss. After any --webp run check webp.requested: true and webp.tool in pack-report.json; tool: "missing" plus webp.unavailableReason means nothing was transcoded (requested: false also reads missing, so read both). Jenkins provisions cwebp; a fresh dev box or ARC pod may not. WebP bytes also differ per cwebp version, so never byte-compare packs across hosts unless the version is pinned.
  • --deflate-zopfli shrinks the VFS payload entries --deflate compresses (JS, JSON), measured -1.2% (arrow3d-three-web) to -3.2% (slingnshot-web) per network row, at +4 to +7 s pack time on those fixtures. It does NOT touch the yandex row’s sibling archive members or any zip container (src/core/zip.ts stays zlib-9). Read deflateZopfli.fallbacks in pack-report.json: encoder-unavailable or time-budget on every entry means the flag silently did nothing on that machine. The key is absent without the flag.
  • --network all on a web build emits one row per network variant (orientation and zip variants included), so the count exceeds the network count: read emitted.length. Size is per row: read emitted[].verdict.status and sizeVerified, and publish a per-network raw/gzip table (the CI template’s “Size table” step) rather than judging one artefact.