t1k:cocos:playable:gpu-perf
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: backbuffer, cc-dpr-cap, devicePixelRatio, dpr, fill rate, fragment bound, gpu, graphics performance, mobile heat, overdraw, render resolution, thermal
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:gpu-perf<symptom: heat | low fps on DPR 2-3 phone | 3D scene | fill-rate suspect>Cocos Playable GPU / Fill-Rate Measures
Section titled “Cocos Playable GPU / Fill-Rate Measures”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.
Triggers
Section titled “Triggers”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”| Symptom | Measure first (references/measure-gpu.md) | Choose |
|---|---|---|
| Slow frame, many draw calls or long script/update time | CPU-throttled Chrome trace, engine draw-call counter | NOT this skill: t1k-cocos-playable-runtime-perf |
| Slow only on high-DPR phones, fine on a DPR-1 desktop window | Same scenario at DPR 1 vs the phone’s DPR on a real device; compare frame time | Fill-rate suspect: try cc-dpr-cap (below), then re-measure |
| Hot phone, frame rate holds | Thermal/battery observation on a real device, A/B with and without the measure | cc-dpr-cap is a candidate; unproven until the A/B shows a gain |
| Shadows suspected | GPU 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 number | none | Stop. 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.
Option 1: @playablelabs/cc-dpr-cap
Section titled “Option 1: @playablelabs/cc-dpr-cap”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,playableSyncregistered per itsskills/t1k-cocos-playable-stdlib-adopt/references/mechanics.md), never a hand copy. - Expose the cap as a dashboard
RangeParameter(min 1, max 2) viat1k-cocos-playable-parameter-implement, so the value is tuned per network by measurement, not guessed.
When NOT to use it
Section titled “When NOT to use it”- 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.
Workflow
Section titled “Workflow”- Name the symptom and the scenario; take the baseline (
references/measure-gpu.md). - Walk the table; pick the matching row only.
- Apply one measure, re-measure the same scenario on the same device, pixel-check the look.
- Commit with before -> after numbers and the device/scenario, or
unmeasuredplus why. - Record kept/rejected measures in the project’s docs/system-design.md.
Executed by
Section titled “Executed by”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).