Skip to content

t1k:playablelabs:web:perf

FieldValue
Moduleweb
Version1.18.2
Effortmedium
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

/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 (its cpu-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.

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.

  1. 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.
  2. 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).
  3. 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.
  4. Uncapped fps is a cost proxy, not a player number. A player sees the vsync-capped rows.
  5. A phone pass is a gate. No real phone was measured in the source; treat desktop throttling as a ranking tool, never a bound.
The profile or counter showsTryRead
updateMatrixWorld / multiplyMatrices high; 10 k+ Object3Dsdirty-flag transforms, one world pass, then pruningframe-cpu.md
A second (UI) camera costs ms for a few quadsper-camera layer cullingframe-cpu.md
Reachable objects far above live objects; pooled units still walkedunlink dead, skip inert, drop unread bonesframe-cpu.md
Allocation MB/s far above the original; sort/slice in the allocation profilescheduler without per-frame sort or allocationframe-cpu.md
Hundreds of skinned meshes, bone objectsbaked vertex-animation texture plus instancinggpu-and-draw.md
Hundreds of identical small drawsinstanced rigid props, opt-in transparent batchinggpu-and-draw.md
Draw calls high; choosing between InstancedMesh, BatchedMesh, merged geometrydecision guide, feature detect, device gatedraw-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, visibleOnlydraw-call-batching.md section 6
Authored GLB has many small meshes or materialsbuild-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 drawsatlas 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 framesingle-pass DoubleSide, one material per draw kindgpu-and-draw.md
More triangles than the Cocos build; GPU ms is the limitmesh simplification (position-only error metric)gpu-and-draw.md
Hitch on first use of an effect; worst one-second window far under the averageshader warm-up behind the loading viewload-and-hitches.md
Game speed drifts below 20 fpspass the real frame deltaload-and-hitches.md
Invisible pooled debris/confetti, empty pooled meshesbuild the pool after its geometryruntime-recipes.md
Idle screens still tick tweens; HUD DOM writes every frame; dt after a tab resume; shadow pass costlive-only scheduler, dirty-checked writes, dt clamp, paced shadow redrawruntime-recipes.md
Quality tier / DPR cap / weak-device memory questions; blur-backdrop UI layer costopt-in tier (conflicts with rule 3), software-GL-only figures labelledruntime-recipes.md
Hundreds of per-entity nodes or per-shot spawnstyped-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.

  • 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 = false still walked (r180). Parking a subtree takes detaching it from the graph, not the flag; measured in frame-cpu.md section 3.
  • Transparent DoubleSide without forceSinglePass: true draws two passes and relinks its program every frame; measured in gpu-and-draw.md section 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 hold class that hides its images, release it in a finally right after adaptSplashToParams (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.md item 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.

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

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

StepAgent
Run glb-reduce-draws.cjs <in.glb> <out.glb> --json and tabulate before/after countst1k-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 assetmain session