t1k:playablelabs:web:perf
| Field | Value |
|---|---|
| Module | web |
| Version | 1.18.2 |
| Effort | medium |
| Tools | — |
Keywords: cpu bound playable port, draw calls too high playable, low-end phone playable, shader warm-up hitch, three.js playable low fps, updateMatrixWorld hot, web host frame time, web playable performance
How to invoke
Section titled “How to invoke”/t1k:playablelabs:web:perf[symptom | measure | cpu | gpu | load | compare]Web-host performance playbook (a Cocos game ported to three.js)
Section titled “Web-host performance playbook (a Cocos game ported to three.js)”Scope: measured patterns for a Cocos Creator 3.8 game ported to the web engine host, and the cases
where each one did not help. Evidence is one completed port on one desktop GPU; every figure
carries its basis (config, n) or is marked unverified. Re-measure on your own game and device before
promising a frame rate.
Not here, linked instead (single source of truth):
- Typed-array populations, one instanced draw, GPU motion, the per-item measured checklist and proof
table:
t1k-playablelabs-optimize-mass-populations(itscpu-first-checklist.md,device-probe-workflow.md,profiling-and-proof.md,cpu-alloc-closeout.md). - The per-PR review gate, how to measure properly, the no-device-class-degradation rule:
t1k-playablelabs-optimize-gate(measure-properly.md,visual-fidelity.md,runtime-cpu-memory.md). - Probe switches the game must ship (
?perf=1,&sync=1):t1k-playablelabs-web-host-contract. - Port-vs-keep, the
dist/contract, lighting/DPR port gotchas:t1k-playablelabs-web-port. - Packer optimize passes and size ceilings:
t1k-playablelabs-optimize-passes,t1k-playablelabs-base-networks. - Deferring assets out of the boot payload (two-phase loading,
playable-lazy.json):t1k-playablelabs-web-lazy-load.
State your host first
Section titled “State your host first”Say which engine host the game targets (web) in the first message of the task. Packing is performed
by CI; to reproduce a size number, the command it runs is shaped like
pla-pack --build <dist dir> --out <out dir> --engine-host web --json. Never rely on a default host.
Rules that held across every measurement
Section titled “Rules that held across every measurement”- Decide CPU-bound or GPU-bound before changing anything. In the measured port JS was 85-95 % of
frame time and GPU 1-10 ms (desktop RX 580, CPU-throttle stand-in), so every win was a CPU win.
GPU-side fixes were exact (0 px) but did not move a phone. Method:
references/measurement.md. - Profile, fix the largest self-time, re-profile. Scene-graph walks, bone objects and per-unit skinning were 65 % of the original frame (n = 1).
- Never trade visuals for fps. Same pixel ratio (
min(devicePixelRatio, 2)), same particle counts, same shadows on every device. A governor keyed on device class was shipped, measured at zero fps gain on a CPU-bound frame, and removed after a low-end phone report. Details:references/gpu-and-draw.md. - Uncapped fps is a cost proxy, not a player number. A player sees the vsync-capped rows.
- A phone pass is a gate. No real phone was measured in the source; treat desktop throttling as a ranking tool, never a bound.
Which reference for which signature
Section titled “Which reference for which signature”| The profile or counter shows | Try | Read |
|---|---|---|
updateMatrixWorld / multiplyMatrices high; 10 k+ Object3Ds | dirty-flag transforms, one world pass, then pruning | frame-cpu.md |
| A second (UI) camera costs ms for a few quads | per-camera layer culling | frame-cpu.md |
| Reachable objects far above live objects; pooled units still walked | unlink dead, skip inert, drop unread bones | frame-cpu.md |
Allocation MB/s far above the original; sort/slice in the allocation profile | scheduler without per-frame sort or allocation | frame-cpu.md |
| Hundreds of skinned meshes, bone objects | baked vertex-animation texture plus instancing | gpu-and-draw.md |
| Hundreds of identical small draws | instanced rigid props, opt-in transparent batching | gpu-and-draw.md |
Draw calls high; choosing between InstancedMesh, BatchedMesh, merged geometry | decision guide, feature detect, device gate | draw-call-batching.md |
| Which pass or material costs draws (array materials, double-sided transparent, transmission, shadow lights) | runtime cost-driver audit (scripts/draw-call-probe.js); raw rAF hosts, reset-owning hosts, labelled windows, visibleOnly | draw-call-batching.md section 6 |
| Authored GLB has many small meshes or materials | build-time reduction (scripts/glb-reduce-draws.cjs; check mesh names after join) | draw-call-batching.md section 4 |
| Sprites, a HUD second pass, canvas or troika text, many 2D or UI draws | atlas plus InstancedMesh, HUD pass cost, text update rules (evidence labelled, gaps listed) | draw-call-batching.md section 7 |
getProgram high on an idle frame; needsUpdate written per frame | single-pass DoubleSide, one material per draw kind | gpu-and-draw.md |
| More triangles than the Cocos build; GPU ms is the limit | mesh simplification (position-only error metric) | gpu-and-draw.md |
| Hitch on first use of an effect; worst one-second window far under the average | shader warm-up behind the loading view | load-and-hitches.md |
| Game speed drifts below 20 fps | pass the real frame delta | load-and-hitches.md |
| Invisible pooled debris/confetti, empty pooled meshes | build the pool after its geometry | runtime-recipes.md |
| Idle screens still tick tweens; HUD DOM writes every frame; dt after a tab resume; shadow pass cost | live-only scheduler, dirty-checked writes, dt clamp, paced shadow redraw | runtime-recipes.md |
| Quality tier / DPR cap / weak-device memory questions; blur-backdrop UI layer cost | opt-in tier (conflicts with rule 3), software-GL-only figures labelled | runtime-recipes.md |
| Hundreds of per-entity nodes or per-shot spawns | typed-array population (linked skill) | mass-populations |
What did not help (do not spend a day before the profile points at it)
Section titled “What did not help (do not spend a day before the profile points at it)”Quality governor / DPR drop on a CPU-bound frame; mesh simplification for CPU time; the scheduler rewrite
for frame time; batching tracers on a slow CPU (x6 frame 83 to 80 ms, n = 3, noise); single-pass
materials as the main lever (about 0.5 ms at most); a hit-detection grid (the hit code was about 1 ms per
frame); pooling audits where spawns already instantiate at load; cheaper shadows (planar shadows were
about 15 instanced draws); a lower DPR cap. Evidence per item: references/failure-signatures.md.
Hard rules
Section titled “Hard rules”- Fix looks big in uncapped fps, nothing changes on a throttled or real phone. The frame is native GL submission plus live nodes, not draw count; check the throttled capped row.
- Two measurements disagree (a profile share vs an A/B what-if). Treat the allocation effect as real and the frame-time effect as modest until an interleaved run says otherwise.
- A cross-build A/B shows pixel diffs on a scene with randomness. Compare the same build with the optimisation on and off, and run a deliberately broken variant: a diff of 0 from a blind check proves nothing.
- Pruning breaks a later lookup. A subtree skipped as inert is stale if game code reads its matrix or adds a component below it later; compute on demand and register nodes the game looks up by name.
matrixWorldAutoUpdate = falsestill walked (r180). Parking a subtree takes detaching it from the graph, not the flag; measured inframe-cpu.mdsection 3.- Transparent
DoubleSidewithoutforceSinglePass: truedraws two passes and relinks its program every frame; measured ingpu-and-draw.mdsection 3. - Warm-up black UI. Never hide an enabled UI drawable while prewarming; warm up per camera with the same layer culling as the render pass (the light set is part of the program key).
- Baked animation drops blends. A baked unit’s cross-fade becomes an immediate switch, and a model with a non-skinned mesh cannot be baked without losing it.
- Crowd-scaling wins vanish at low entity count. Sweep entity count; the quiet-subtree skip was 55.2 to 57.9 fps at 2 troops and 37.0 to 42.2 at 41 (CPU x4, interleaved, n = 2-3). One point lies.
- Stock splash art flashes, then the customer’s art swaps in. The page splash inlines the stock art, so
it paints at first paint, but the dashboard params are readable only after the document parsed and the
SDK bridge’s macrotask ran. Fix: start the splash with a
holdclass that hides its images, release it in afinallyright afteradaptSplashToParams(a missing bridge or a throwing plan still shows the stock art), and add a ~2.5 s safety release in the splash script. Proof: a capture with a distinctive bridge logo shows no stock frame, plus a negative control with hold removed that must show stock frames. - A second loading screen flashes after the splash. The scene’s loading view must stay hidden while a
page splash exists; see rule
playablelabs-zero-black-first-load.mditem 6.
Draw-call reduction status (P1, web and none only)
Section titled “Draw-call reduction status (P1, web and none only)”references/draw-call-batching.md carries the draw-call guide. Its evidence labels are the source of truth:
InstancedMesh for one geometry and one material is verified (three.js source). BatchedMesh on mobile
WebViews is unverified (WEBGL_multi_draw support not checked on the target), so feature-detect it and gate
it on a device run. The per-instance morph API is a building block with no measured gain. The GLB reduction
and the cost-driver audit have no verified impact figures. The 2D and UI section (draw-call-batching.md 7)
lists what has no verified evidence, and says so. No draw-call budget is stated in this skill. A
threshold comes from an A/B run on the target devices.
Honest status
Section titled “Honest status”Numbers are from the unpacked host build, mouse input, one scripted run, n of 2 to 5, a shared and
drifting machine. The Cocos baseline and the port came from different sessions, so compare shapes and
large ratios, not decimals. See references/measurement.md section “Caveats”.
Executed by
Section titled “Executed by”Running scripts/glb-reduce-draws.cjs on a GLB and tabulating its before/after JSON is mechanical. Choosing whether a
count change is acceptable for the asset (join can grow vertex count) stays with the main session. Routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run glb-reduce-draws.cjs <in.glb> <out.glb> --json and tabulate before/after counts | t1k-playablelabs-base-packer-engineer (sonnet, native: the kit’s agent that runs packer CLIs and reads their reports, with Bash; no haiku-tier agent in this kit has a role that runs scripts) |
| Judge whether the counts are acceptable for the asset | main session |