Skip to content

t1k:playablelabs:optimize:gate

FieldValue
Moduleoptimize
Version1.16.2
Efforthigh
Tools—

Keywords: pla size cpu memory budget, playable code complexity, playable optimization gate, playable perf checklist, playable review gate

/t1k:playablelabs:optimize:gate
<packed out dir | pack-report.json> [--phase A|B|C|D|E|F]

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).

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 in PlaybleEngine master or in the 2026-10-07 baseline (n = 6 builds, one desktop; numbers inlined in references/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 is max(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 is PASS (floor-adjusted). There is no NOT-RUN (noise): a loaded box widens the limit, it never skips a row. A named quiet runner (references/evidence.md Q11) 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.
PhaseGate topicDetail file
AAsset authoring: textures, meshes, audio, fonts, Blender exportreferences/assets.md, references/blender.md
BScene and engine: graph size, draw calls, modules, lazy initreferences/engine-scene.md
CCode technique and complexity: hot paths, big-O, leaks, bundlereferences/code-technique.md
DPack: per-network verdicts, size shares, banned APIsbelow (this file)
ERuntime: CPU, frame budget, long tasks, memoryreferences/runtime-cpu-memory.md
FVerify: smoke, A/B bench, real device, visual diffreferences/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)”
IDCheckThreshold / ruleVerifySevBasis
A1Largest texture side<= 2048 px (sample max 2000, 0 of 226 over); hero 1024, bg 256-512 stay Htexture-audit list (see assets.md)MUSTM (n=226 textures, 6 builds) for 2048; H for 1024/256-512
A3Decoded texture RAM, whole buildreport 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.mjsMUST report / SHOULD capM distribution (n=6 builds); H for the 30 MiB cap (sample max + 5%, a regression guard, not a device limit)
A9Audiomono, BGM 48 kbps, SFX 64 kbps, trimmedffprobe per fileSHOULDM+H
B1Live scene graph sizeno growth without a reason; prune inert subtreesnode count at first-scene-frameSHOULDM
B2Draw calls per framewithin +10% of the base build, per-scene baseline (sample: 4.6-224/frame, n=1 each, no spread yet)runtime-bench --shimMUSTH (n=1)
C1Cyclomatic complexityMUST <= 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 ruleMUST (20) / SHOULD (10/15)S (20); M descriptive only (10/15: n=6 repos, 3 share template code, so ~4 independent codebases)
C2Steady-state allocation in update0 B/frame after warm-upruntime-bench --profile heapMUSTH
C21Unused code and depszero unused files/exports/deps, or each justifiedbunx --no-install knipSHOULDS (tool), H (zero rule)
D1Pack verdict per networkevery emitted[].verdict.status == "pass", allPass == truepack-report.jsonMUSTM
D2Headroompacked 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 budgetBytesSHOULDH (context, n=11)
D3Engine vs asset sharelist top 20 assets by raw bytes in the PRclassAttributionSHOULDM
D4Banned APIs per networknetlint clean (XHR, JS redirect, mraid.js presence)bun scripts/netlint.cjs --out out --report pack-report.jsonMUSTS (ceilings come from vendor-sourced adapter rows)
E1Long tasks after first scene frame, x4floor-adjusted: quiet floor (0 tasks) = none > 50 ms; else count <= floor + 5 and max <= floor max + 50 ms; never above baseboot-heap probe (runtime-cpu-memory.md)MUSTS (definition) + H (limits; not calibrated on a quiet box)
E2p95 frame time at CPU x4<= max(33.3 ms, floor p95 + 5 ms); no regress > 10% vs baseruntime-bench --cpu 4MUSTH (not calibrated on a quiet box)
E3First scene frame at CPU x4median <= base + max(10%, 2 x CV of base reps), interleaved; 2 x CV >= 100% = not measured, re-run n >= 9bench-first-frame.cjsSHOULD (MUST once Q11 names a quiet runner)H (rep spread 4-114% at n=3 under load)
E4JS heap after N play loopsratio 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 loopruntime-cpu-memory.md leak recipeMUST (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)
E9Perf-PR evidencea 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 outputreferences/runtime-cpu-memory.md § E9MUST for perf-claim PRs, else N/AM (method), H (thresholds)
F1Smokeevery network row boots, CTA fires, zero console errorssmoke.cjsMUSTM
F2Real low-end Androidone run on the lab device, recordedreferences/verify-gates.mdSHOULD until a device existsH
F3Visual diffSSIM floor per asset class vs reference shotsreferences/assets.mdMUST for any L2/L3 passH
F4Visual fidelitybun scripts/runtime-bench/fidelity.mjs (PlaybleEngine) and bun scripts/port-asset-lint.mjs both pass; zero fidelity FAILreferences/visual-fidelity.mdMUST for any PR touching rendering, assets, mesh simplification, textures, view/DPR or quality settingsM
F5Release hygienerelease-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 claimbun ../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)

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 reason

N/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)”
Terminal window
bun dist/cli.js --build <dir> --out out --network all --deflate --json > pack-report.json # exit 1 = a row over budget
jq '.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.

  • Smoke green says nothing about frame time or memory (it measures boot, CTA, MRAID): never use F1 as evidence for phase E.
  • runtime-bench aborts 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-blocklist itself, 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-extraction are 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.

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).

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”.

StepAgent
Run the measuring scripts, fill the PASS/FAIL table from their outputt1k-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 PASSt1k-playablelabs-base-packer-engineer (sonnet, native)