t1k:playablelabs:base:pack
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: pack-report.json, packer cli, packer exit codes, pla-pack, playablelabs packer
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:pack<build dir> --out <dir> [--engine-host cocos-3.8|web|none]PlayableLabs packer: pla-pack
Section titled “PlayableLabs packer: pla-pack”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.
Get the CLI
Section titled “Get the CLI”dist/ is gitignored, so a fresh clone has no CLI until you build it (Node >= 20, package.json engines):
git clone git@github.com:The1Studio/PlaybleEngine.git <packer-clone> # branch mastercd <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 2The 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.
Subcommands (main() in src/cli.ts)
Section titled “Subcommands (main() in src/cli.ts)”| Command | Writes? | 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>] | no | Cocos engine modules declared vs used. Cocos-only: other host ids exit 2 |
audit-hierarchy --project <dir> [--build <dir>] [--json] | no | scene/prefab hierarchy lint |
optimize-audit --build <dir> [--json] [--engine-host <id>] | no | which 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.
bun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --out public/playable-lazy.json # no file yetbun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --check # file existsCommit 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)”| Flag | Default | Notes |
|---|---|---|
--build <dir> / --out <dir> | required | --build resolved against cwd once |
--budget-kb <n> | 5120 | studio requirement applied to EVERY network; overrides vendor ceilings |
--mode raw|gzip | raw | only applies to networks with no ceiling of their own; a network with a ceiling keeps its own mode |
--network <ids> | common | comma list or all. all = every id except defaultOff ones (ironsource) |
--layout flat|superhtml | flat | see Output layout |
--name <name> | derived | needed for superhtml unless --build ends in build/web-mobile |
--engine-host cocos-3.8|web|none | cocos-3.8 | see t1k-playablelabs-base-engine-hosts |
--engine <builtin|40-hex> | builtin | RECORDED, not applied; a short SHA is refused |
--cocos-tool <name> / --cocos-tool-path <p> | none | RECORDED, not applied |
--build-id <id> | $BUILD_NUMBER else none | recorded to buildIdentity.number; 1-64 non-space chars |
--game-sha <7-40 hex> | none | recorded; deliberately no env fallback |
--deflate / --webp / --no-vfs-dedupe | off / 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 entry | needs --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|off | auto | L2 sibling members for rows with a lazyLoad capability (yandex only) |
--emit-preview | off | writes <stem>.preview.html beside L2 artefacts |
--timing, --image-bitmap, --start-gate <p>, --audio-gate <src>[,true|false] | off | build-time A/B and emergency overrides; adapter table is the production source |
--minify-boot | ON 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-assets | off | web 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|default | all | needs --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> | none | needs --lazy-assets; JSON policy that wins over playable-lazy.json. Schema: references/lazy-assets.md |
--optimize, --optimize-<pass>, --font-keep-chars <f> | off | every pass OFF by default; --optimize-audio-mono is never part of --optimize |
--no-hierarchy-lint, --hierarchy-project <dir> | lint ON | warn-only, never changes exit code |
--json | off | report 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).
Exit codes (header of src/cli.ts)
Section titled “Exit codes (header of src/cli.ts)”| Code | pack | audit-modules / optimize-audit | optimize-apply |
|---|---|---|---|
| 0 | no row over budget | clean | tier changed bytes |
| 1 | at least one row fail (over budget, or a packer-owned index.html overflow) | findings / defeated audit / empty build | tier changed no bytes |
| 2 | usage or input error, or an uncaught exception (main().catch) | same | same |
audit-hierarchy always exits 0 (2 on usage). On any exit 2 read stderr: the message names the bad flag.
pack-report.json verdict fields
Section titled “pack-report.json verdict fields”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.
Output layout
Section titled “Output layout”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.
Self-improve: drift check
Section titled “Self-improve: drift check”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.
Verified against
Section titled “Verified against”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.
Hard rules
Section titled “Hard rules”- Source comments claim 23 of 27 networks give
unknownverdicts exiting 0. At d76f263 the pack path callscheckBudget(..., false)(cli.ts), so a row ispassorfail;unknownis not produced there today. Useemitted[].sizeVerified, notallVerified, to know whether a vendor ceiling backs a row. --budget-kbdefault 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-kbper network run.--engine,--cocos-tool*,--build-id,--game-shaselect nothing; they only label the report.--networkdefaults tocommon(one neutral artefact), notall.--webpdoes nothing when nocwebp(or ffmpeg for alpha-free PNG) is on PATH: the pack still exits 0 with PNG bytes unchanged, and with--json > pack-report.jsonthe one-line notice is easy to miss. After any--webprun checkwebp.requested: trueandwebp.toolinpack-report.json;tool: "missing"pluswebp.unavailableReasonmeans nothing was transcoded (requested: falsealso readsmissing, so read both). Jenkins provisionscwebp; a fresh dev box or ARC pod may not. WebP bytes also differ percwebpversion, so never byte-compare packs across hosts unless the version is pinned.--deflate-zopflishrinks the VFS payload entries--deflatecompresses (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 theyandexrow’s sibling archive members or any zip container (src/core/zip.tsstays zlib-9). ReaddeflateZopfli.fallbacksinpack-report.json:encoder-unavailableortime-budgeton every entry means the flag silently did nothing on that machine. The key is absent without the flag.--network allon awebbuild emits one row per network variant (orientation and zip variants included), so the count exceeds the network count: reademitted.length. Size is per row: reademitted[].verdict.statusandsizeVerified, and publish a per-network raw/gzip table (the CI template’s “Size table” step) rather than judging one artefact.