t1k:playablelabs:optimize:gate
| Field | Value |
|---|---|
| Module | optimize |
| Version | 1.16.2 |
| Effort | high |
| Tools | — |
Keywords: pla size cpu memory budget, playable code complexity, playable optimization gate, playable perf checklist, playable review gate
How to invoke
Section titled “How to invoke”/t1k:playablelabs:optimize:gate<packed out dir | pack-report.json> [--phase A|B|C|D|E|F]Playable optimization gate
Section titled “Playable optimization gate”Scope: the checklist every PLA passes before a PR or release, for the smallest size, best runtime
performance and good looks. It does not re-explain the packer: pass mechanics are
t1k-playablelabs-optimize-passes (this gate is the review checklist; it calls that skill for every --optimize* flag, tier and optimize-audit/optimize-apply detail, and never restates them), ceilings are t1k-playablelabs-base-networks, the CLI and
pack-report.json are t1k-playablelabs-base-pack, smoke is t1k-playablelabs-base-smoke, the web-host
patterns are the packer’s web-perf-playbook.md (link, not copied). Any gate fix that touches shared
packer code must also pass t1k-playablelabs-base-change-proof (Cocos bytes unchanged).
How to read a check
Section titled “How to read a check”ID | check | threshold or rule | verify | severity | basis
- MUST blocks the PR. SHOULD needs a written waiver line in the PR (who, why, until when).
- Basis says how far to trust the number: S = vendor/standards source fetched
[retrieved 2026-10-07], M = measured: either in a packer report tracked inPlaybleEnginemaster or in the 2026-10-07 baseline (n = 6 builds, one desktop; numbers inlined inreferences/evidence.md§ Measured baseline; n is always stated next to an M, and an M from n = 6 describes that sample, not the fleet), H = hypothesis: a proposed budget, calibrate on the first real low-end phone run, never quote as a vendor limit. - A threshold marked H is still enforced; changing it is a studio decision, not a per-PR edit.
- No ad network publishes a numeric memory, CPU or FPS limit (none found in the 2026-10-07 sweep): every runtime number below is H or M, and every FPS number measured so far is a desktop CPU-throttle stand-in.
- Noise-floor rule (one rule, no exemption state). Before E1/E2/E3/E5 run
scripts/noise-floor/through the same command in the same session; a row’s limit ismax(absolute threshold, floor + margin)(per-gate form:references/measure-properly.md§ 5). Paste the floor numbers and the load line in the PR; a row that passes only because of the floor isPASS (floor-adjusted). There is noNOT-RUN (noise): a loaded box widens the limit, it never skips a row. A named quiet runner (references/evidence.mdQ11) would remove the widening. - A p90 of n = 6 is an interpolation between the 5th and 6th value: read it as near-max, not as a fleet percentile.
Phases (run in order, record every row)
Section titled “Phases (run in order, record every row)”| Phase | Gate topic | Detail file |
|---|---|---|
| A | Asset authoring: textures, meshes, audio, fonts, Blender export | references/assets.md, references/blender.md |
| B | Scene and engine: graph size, draw calls, modules, lazy init | references/engine-scene.md |
| C | Code technique and complexity: hot paths, big-O, leaks, bundle | references/code-technique.md |
| D | Pack: per-network verdicts, size shares, banned APIs | below (this file) |
| E | Runtime: CPU, frame budget, long tasks, memory | references/runtime-cpu-memory.md |
| F | Verify: smoke, A/B bench, real device, visual diff | references/verify-gates.md |
Tools that are not installed yet, with install cost and the ask-first rule: references/tools-to-install.md.
How to measure a number properly (commands, reps, warm-up, noise floor, what to report): references/measure-properly.md;
the three measuring scripts and the noise-floor/ page it uses ship in scripts/.
Per-state frame cost, long tasks, heap, draws and pass isolation, with a software-GL honesty verdict and a before/after compare that refuses unlike runs: scripts/frame-cost/ (references/frame-cost-harness.md).
When the screen is black at start (how long, and what runs before the first visible frame; the capture item 7 of
playablelabs-zero-black-first-load asks for): scripts/load-profile/ (measure.cjs, profile.cjs, analyze-packed.cjs), usage, number
definitions and caveats in references/load-time-profile.md.
Never install one inside a gate run; list it and ask the caller.
Headline checks (full tables in the references)
Section titled “Headline checks (full tables in the references)”| ID | Check | Threshold / rule | Verify | Sev | Basis |
|---|---|---|---|---|---|
| A1 | Largest texture side | <= 2048 px (sample max 2000, 0 of 226 over); hero 1024, bg 256-512 stay H | texture-audit list (see assets.md) | MUST | M (n=226 textures, 6 builds) for 2048; H for 1024/256-512 |
| A3 | Decoded texture RAM, whole build | report always; SHOULD cap 30 MiB RGBA8 without mips (sample p50 18.0, near-max 28.0, max 28.4; x1.33 with mips) | scripts/measure-inventory.mjs | MUST report / SHOULD cap | M distribution (n=6 builds); H for the 30 MiB cap (sample max + 5%, a regression guard, not a device limit) |
| A9 | Audio | mono, BGM 48 kbps, SFX 64 kbps, trimmed | ffprobe per file | SHOULD | M+H |
| B1 | Live scene graph size | no growth without a reason; prune inert subtrees | node count at first-scene-frame | SHOULD | M |
| B2 | Draw calls per frame | within +10% of the base build, per-scene baseline (sample: 4.6-224/frame, n=1 each, no spread yet) | runtime-bench --shim | MUST | H (n=1) |
| C1 | Cyclomatic complexity | MUST <= 20 (ESLint default); SHOULD <= 15 (flags 0.11% of game functions) and <= 10 hot-path (0.79% over 10, all functions) | bunx --no-install eslint with the complexity rule | MUST (20) / SHOULD (10/15) | S (20); M descriptive only (10/15: n=6 repos, 3 share template code, so ~4 independent codebases) |
| C2 | Steady-state allocation in update | 0 B/frame after warm-up | runtime-bench --profile heap | MUST | H |
| C21 | Unused code and deps | zero unused files/exports/deps, or each justified | bunx --no-install knip | SHOULD | S (tool), H (zero rule) |
| D1 | Pack verdict per network | every emitted[].verdict.status == "pass", allPass == true | pack-report.json | MUST | M |
| D2 | Headroom | packed bytes <= ceiling - 5% (11 published games: p50 2869 KB, p90 4008 KB; 1 of 11 over; 5 of the 11 are also among the 6 measured builds, so corroboration, not an independent sample) | actualBytes vs budgetBytes | SHOULD | H (context, n=11) |
| D3 | Engine vs asset share | list top 20 assets by raw bytes in the PR | classAttribution | SHOULD | M |
| D4 | Banned APIs per network | netlint clean (XHR, JS redirect, mraid.js presence) | bun scripts/netlint.cjs --out out --report pack-report.json | MUST | S (ceilings come from vendor-sourced adapter rows) |
| E1 | Long tasks after first scene frame, x4 | floor-adjusted: quiet floor (0 tasks) = none > 50 ms; else count <= floor + 5 and max <= floor max + 50 ms; never above base | boot-heap probe (runtime-cpu-memory.md) | MUST | S (definition) + H (limits; not calibrated on a quiet box) |
| E2 | p95 frame time at CPU x4 | <= max(33.3 ms, floor p95 + 5 ms); no regress > 10% vs base | runtime-bench --cpu 4 | MUST | H (not calibrated on a quiet box) |
| E3 | First scene frame at CPU x4 | median <= base + max(10%, 2 x CV of base reps), interleaved; 2 x CV >= 100% = not measured, re-run n >= 9 | bench-first-frame.cjs | SHOULD (MUST once Q11 names a quiet runner) | H (rep spread 4-114% at n=3 under load) |
| E4 | JS heap after N play loops | ratio loop 5 / loop 2 <= 1.05 (only when heap after loop 2 >= 4 MB, else N/A with reason); slope <= 0.5 MB per 5 s loop | runtime-cpu-memory.md leak recipe | MUST (ratio) / SHOULD (slope) | ratio: M observed 1.002-1.035, limit H; slope: H (HEADesign9PLA 0.58 MB/loop is one unproven leak candidate, n=1 build, 3 loops) |
| E9 | Perf-PR evidence | a PR claiming a perf gain reports the throttle x entity-count sweep before to after (interleaved, n >= 3) and a same-frame selfdiff pixel proof with a negative control; any “fps on phone” claim needs the on-device probe build output | references/runtime-cpu-memory.md § E9 | MUST for perf-claim PRs, else N/A | M (method), H (thresholds) |
| F1 | Smoke | every network row boots, CTA fires, zero console errors | smoke.cjs | MUST | M |
| F2 | Real low-end Android | one run on the lab device, recorded | references/verify-gates.md | SHOULD until a device exists | H |
| F3 | Visual diff | SSIM floor per asset class vs reference shots | references/assets.md | MUST for any L2/L3 pass | H |
| F4 | Visual fidelity | bun scripts/runtime-bench/fidelity.mjs (PlaybleEngine) and bun scripts/port-asset-lint.mjs both pass; zero fidelity FAIL | references/visual-fidelity.md | MUST for any PR touching rendering, assets, mesh simplification, textures, view/DPR or quality settings | M |
| F5 | Release hygiene | release-hygiene-scan.cjs exits 0: no overlay flag on, no webp-requested-but-missing or dedupe-off, no object default on an asset param, no literal CSS url() background, no “unmeasured” perf claim | bun ../t1k-playablelabs-optimize-release-hygiene/scripts/release-hygiene-scan.cjs --report pack-report.json --dir <src> --dir <out> | SHOULD (one exit code mixes rules verified on real PLAs with rules that have no real positive yet; promote to MUST once object-default and dedupe-off each catch a real case) | M (see t1k-playablelabs-optimize-release-hygiene) |
Review gate
Section titled “Review gate”When: before every playable PR is marked ready, and again before every release/tag build; also after
any change to textures, audio, meshes, the engine module set, --optimize* flags or hot-path code.
A reviewer or the author runs it, and a reviewer re-checks one load-bearing FAIL or waiver.
Output (paste in the PR, one row per check ID, none skipped):
| ID | Check | Result | Evidence | Sev | Waiver ||----|-------|--------|----------|-----|--------|| A1 | Largest texture side | PASS | max 1024 (hero.png) | MUST | - || E2 | p95 frame ms @x4 | FAIL | 41.2 ms vs base 35.0 (+17.7%) | MUST | - || F2 | Real device | N/A | no lab device yet (evidence.md Q3) | SHOULD | studio, until device bought |Verdict: BLOCKED (1 MUST FAIL) <- PASS only when every MUST is PASS or N/A with a stated reasonN/A needs a one-line reason (a web-only check on a Cocos game, a tool absent). A check that was not
run (tool absent, a band too wide to decide) is NOT-RUN, which counts as FAIL for a MUST. Never turn a FAIL into PASS by editing the threshold
in the same PR. Record the numbers (bytes, first-scene ms, p95, decoded MB, device) so the next run diffs.
Hard rule: no device-driven visual degradation
Section titled “Hard rule: no device-driven visual degradation”Performance comes from visual-neutral work only. A device-class-driven quality governor (resolution below
the reference engine’s rule, fewer particles, shadows off, LOD pops) FAILS F4 whatever the frame time.
One exception, approved 2026-10-12 (TimelineUp #46/#47): a geometry LOD / simplification that is
identical on EVERY device (no DPR/canvas/device signal read to pick a level) is allowed after the
owner reviews before/after shots, with the differing-pixel count and max channel delta recorded.
Check list, fidelity-gate contract and the regressions behind it: references/visual-fidelity.md.
Step 0 as a gate input: read the device probes, not a desktop profile
Section titled “Step 0 as a gate input: read the device probes, not a desktop profile”E9 needs the phone verdict, not a desktop one. A &sync=1 sync wait >= 2x JS ms (and >= 4 ms) is
GPU-bound; &dpr=1 barely moving the fps means not fill-bound (likely vertex-bound — read vertices
per frame per kind); an isolation toggle that moves the fps names the culprit draw. Three CPU-side
PRs measured well on a desktop and gave no phone gain. Decision table and probe parameters:
t1k-playablelabs-optimize-mass-populations/references/device-probe-workflow.md.
Phase D, pack (short, details live in base-pack and base-networks)
Section titled “Phase D, pack (short, details live in base-pack and base-networks)”bun dist/cli.js --build <dir> --out out --network all --deflate --json > pack-report.json # exit 1 = a row over budgetjq '.allPass, [.emitted[] | {id: .network, s: .verdict.status, b: .verdict.actualBytes, max: .verdict.budgetBytes}]' pack-report.json--budget-kb defaults to 5120 and overrides vendor ceilings, so D1 alone can pass a build a network
bounces (Meta, Google, Snapchat sit at 4882 KB in the packer): also read emitted[].sizeVerified and
compare against the ceiling in base-networks. The Meta 2 MB vs 5 MB conflict is an open studio question
(references/evidence.md Q1): until decided, treat Meta single-HTML above 2 MB as a SHOULD-FAIL needing a waiver.
Hard rules
Section titled “Hard rules”- Smoke green says nothing about frame time or memory (it measures boot, CTA, MRAID): never use F1 as evidence for phase E.
runtime-benchaborts with exit 3 on a software rasteriser: run it on a GPU workstation, not a CI pod. A plain headless Chromium launch on Linux silently uses SwiftShader; the bench passes--enable-gpu --ignore-gpu-blocklistitself, any other script must too (measure-properly.md§0).- Interleaved A/B only: a shared machine drifts +-30% between minutes.
texture-downscale,mesh-simplify,anim-extractionare Cocos-only packer passes today; on a web game do the work at authoring time.- Open studio questions (Meta ceiling, target device, SSIM floors) sit in
references/evidence.md. - Unverified claims are tagged in each reference; do not promote one to a rule without one measurement.
Sources
Section titled “Sources”Distilled evidence and open questions: references/evidence.md (the 2026-10-07 research report lives only in a local clone, so what the gate needs is inlined there). Packer references
.claude/skills/playable-engine/references/web-perf-playbook.md and web-port-guide.md; URLs with
retrieval dates are in each reference file. Verified against PlaybleEngine@4ee4272 for CLI/report fields
(the verdict shape comes from t1k-playablelabs-base-pack).
Executed by
Section titled “Executed by”Running scripts/measure-*.mjs and the noise-floor/ page, and tabulating their JSON, is mechanical; deciding a PASS, a
floor-adjusted PASS, a waiver or a threshold is not. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
| Run the measuring scripts, fill the PASS/FAIL table from their output | t1k-tester (read-only build-verification lane), or the calling agent itself |
| Watch a triggered pack or CI job to a verdict (status only) | t1k-ci-watcher |
| Judge a FAIL, a waiver or a floor-adjusted PASS | t1k-playablelabs-base-packer-engineer (sonnet, native) |