Skip to content

t1k:cocos:playable:gpu-perf

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: backbuffer, cc-dpr-cap, devicePixelRatio, dpr, fill rate, fragment bound, gpu, graphics performance, mobile heat, overdraw, render resolution, thermal

/t1k:cocos:playable:gpu-perf
<symptom: heat | low fps on DPR 2-3 phone | 3D scene | fill-rate suspect>

Decides WHEN a playable should opt into a graphics-cost measure and HOW to wire it. The first optional measure is the stdlib package @playablelabs/cc-dpr-cap (mobile render-DPR cap). Selection is measurement-driven: no measure here comes with a promised speedup, and none is applied before the table below says the frame is GPU-bound. Build SIZE is t1k-cocos-playable-build-size; CPU/draw-call/stall/memory work and the shadow levers are t1k-cocos-playable-runtime-perf, whose measure-fix-remeasure loop t1k-cocos-base-optimizer follows.

A 3D scene · a phone that gets hot · low FPS on DPR 2-3 devices · a frame that stays slow when the CPU is not the limit (fragment-bound suspect). A plain 2D playable that already holds frame rate needs none of this: do not opt in “just in case”.

Decision table: symptom -> measure -> choose

Section titled “Decision table: symptom -> measure -> choose”
SymptomMeasure first (references/measure-gpu.md)Choose
Slow frame, many draw calls or long script/update timeCPU-throttled Chrome trace, engine draw-call counterNOT this skill: t1k-cocos-playable-runtime-perf
Slow only on high-DPR phones, fine on a DPR-1 desktop windowSame scenario at DPR 1 vs the phone’s DPR on a real device; compare frame timeFill-rate suspect: try cc-dpr-cap (below), then re-measure
Hot phone, frame rate holdsThermal/battery observation on a real device, A/B with and without the measurecc-dpr-cap is a candidate; unproven until the A/B shows a gain
Shadows suspectedGPU capture of one frame (per-pass time)Shadow levers in t1k-cocos-playable-runtime-perf skills/t1k-cocos-playable-runtime-perf/references/memory-and-weak-devices.md first; they are the better-grounded lever when the capture says shadows dominate
Cannot get any real-device numbernoneStop. Report unmeasured; do not enable anything on speculation

Reported evidence ordering the table (a data point, not a guarantee): in the VoxelFlow3DPLA playable shadows were about 83% of GPU time. The GPU frame time of cc-dpr-cap itself has not been measured; treat any speedup figure as unknown until your own A/B.

Overrides the window.devicePixelRatio getter with min(real, cap) on mobile only and rebuilds the backbuffer through the public API. Full facts, wiring and caveats: references/cc-dpr-cap.md.

  • Affects: canvas pixel count, so fragment/fill cost. Example: 393x852 CSS px at DPR 3 is 786x1704 at the engine’s own clamp of 2, and 589x1278 at cap 1.5 (about 56% of the DPR-2 pixels).
  • Does not affect: vertices, draw calls, CPU time, game logic, touch mapping, CSS layout.
  • Useful range: 1 to 2 (the engine already clamps DPR to 2).
  • Costs: a softer image, UI text included; page scripts see the capped DPR.
  • Adopt: vendor through t1k-cocos-playable-stdlib-adopt (--packages cc-dpr-cap; CPM install, playableSync registered per its skills/t1k-cocos-playable-stdlib-adopt/references/mechanics.md), never a hand copy.
  • Expose the cap as a dashboard RangeParameter (min 1, max 2) via t1k-cocos-playable-parameter-implement, so the value is tuned per network by measurement, not guessed.
  • The frame is CPU-, draw-call-, stall- or memory-bound (the cap changes none of those).
  • A DPR-1 vs device-DPR A/B shows no frame-time or heat difference.
  • Crisp UI text or fine pixel-diff fidelity is a delivery requirement (the playthrough gate compares against the original) and the softness is visible in the frames.
  • Page code depends on the real devicePixelRatio (it will read the capped value).
  • Desktop-only delivery: the cap is mobile-only.
  1. Name the symptom and the scenario; take the baseline (references/measure-gpu.md).
  2. Walk the table; pick the matching row only.
  3. Apply one measure, re-measure the same scenario on the same device, pixel-check the look.
  4. Commit with before -> after numbers and the device/scenario, or unmeasured plus why.
  5. Record kept/rejected measures in the project’s docs/system-design.md.

Choosing a measure and reading the numbers is judgment (t1k-cocos-base-optimizer, or inline). Vendoring and RangeParameter wiring follow the two skills named above. Headless captures are t1k-gamedev-playable-runtime-verifier; they cannot settle a GPU question (see the reference).