t1k:cocos:playable:runtime-perf
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: baked animation, draw calls, frame time, hitch, instancing, joint texture, prewarm, runtime performance, shader link, shadows, stall, texture memory, weak device
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:runtime-perf<scenario: level start | first drag | level N gameplay | memory>Cocos Playable Runtime Performance
Section titled “Cocos Playable Runtime Performance”Make a Cocos Creator 3.8.7 3D playable run smoothly on weak phones: fewer draw calls, no stalls
on first use, smaller texture/GPU/joint memory, a lighter tier for slow devices. Build SIZE is
t1k-cocos-playable-build-size; the engine-agnostic measure-fix-remeasure loop is the
one t1k-cocos-base-optimizer follows (this skill is its Cocos 3D-runtime delta). Distilled from a 3D playable
(UFOPLA) where level-start frames went 104–118 → 44–60 ms, level-3 frames 52 → 37 ms and texture
memory 81.6 → 33.4 MB (Chrome, CPU throttled 4×).
Decision Tree
Section titled “Decision Tree”| Symptom | Read |
|---|---|
| Steady frame too slow; many draw calls | § Draw calls and per-object cost |
| One long frame the first time something happens (first drag, first hit, first effect) | references/first-use-stalls.md |
| Texture / GPU / joint-texture memory too high | references/memory-and-weak-devices.md § Memory |
| Fine on desktop, bad on low-end phones | references/memory-and-weak-devices.md § Weak-device tier |
| Not sure where the time goes | § Measure first |
Executed by
Section titled “Executed by”Profiling, reading the numbers, and choosing which lever to pull are judgment and stay on a
reasoning tier (t1k-cocos-base-optimizer, or inline). Tabulating before/after numbers a script
already printed is t1k-metrics-reporter. Headless captures are
t1k-gamedev-playable-runtime-verifier. Scene/prefab edits follow t1k-cocos-base-editor-mcp-truth.
Measure first
Section titled “Measure first”- Pick a scenario that repeats: level start, the first drag, N seconds of a named level. Run it in the editor preview or a built page with Chrome’s CPU throttled 4× (a desktop GPU is rarely the limit, so throttling the CPU is what exposes the phone-like cost).
- Read the engine’s own counters: the Cocos profiler stats (draw calls, triangles) and a Chrome Performance trace for where the frame goes (component update, render-scene update, forward stage, shader program links).
- Log frame-time percentiles, not a mean: median, frames over 40 ms, worst frame. A stall hides inside an average.
- A/B one change at a time, interleaved (A, B, A, B) on the same page loads; machine noise is large. A change whose effect sits inside the noise is not a win; say so in the commit.
- Pixel-check the look: freeze the scene (stop the camera rig’s tick) and compare a frozen view before and after; only moving things may differ.
Draw calls and per-object cost
Section titled “Draw calls and per-object cost”| Lever | Measured | How |
|---|---|---|
USE_INSTANCING on materials shared by many static renderers | fly-over 807 → 221 draw calls, gameplay 222 → 91 | Shared material only; see t1k-cocos-playable-tooling-gotchas skills/t1k-cocos-playable-tooling-gotchas/references/instancing-shared-material-drawcalls.md. Keep anything needing its own draw order (a depth pre-pass ghost) un-instanced: the instanced queue ignores priorities |
| Thousands of identical small moving objects → ONE model | 700 voxel blocks: frame 52 → 37 ms; 1100 hidden models gone | A mesh of N unit cubes tagged by slot; the vertex shader reads each slot’s pose/colour from a data texture (RGBA32F, or the float bytes in RGBA8 where float textures cannot be sampled). Instancing still culls, transforms and batches each model one by one |
| Sleep what the camera cannot see | AnimationManager 2 → 0.3 ms | Renderer off + animation paused when outside the view frustum; wake on entry |
| Stop far or tiny objects casting during a wide fly-in | ~730 casters → 6, frame 35 → 26 ms | Distance cut for shadow casting; hide pieces under ~1.5% of screen height via the render model’s enabled |
| An inactive camera still costs | — | A camera that draws nothing visible still culls the scene and re-renders the shadow map: deactivate its node |
| A disabled renderer can still draw | 3,072 empty triangles per frame | Disable the renderer BEFORE assigning a mesh: a mesh set on an enabled renderer adds its model, and disabling a renderer whose onEnable never ran does not remove it |
| Re-assigning the same mesh rebuilds it | — | MeshRenderer.mesh is a SETTER, not a lazy field: assigning it tears down and rebuilds the renderer’s sub-models even when the value is the identical mesh instance. A pool, a bind step or an update loop that reassigns mesh every spawn or every frame pays that rebuild for nothing. Read renderer.mesh and return early when it is already the value you were about to set |
| Scale 0 does not hide a renderer | 4,467 pooled intro voxel nodes: 20-27 s of build at 4× CPU, up to 8,954 instances per frame | A scale-0 MeshRenderer is still culled-in and drawn, instanced and in the shadow-caster pass. Hide with node.active = false or disable the model, or never create the node |
| Per-voxel pop/reveal inside merged chunk meshes | — | Run it in the vertex shader: bake a per-vertex pivot attribute (voxel centre + reveal row) under an opt-in effect define, drive a uniform clock. Pad the chunk bounds for the overshoot so it is not frustum-culled; declare the uniform in the shadow-caster pass too |
| Skip identity math in hot per-object code | 3.4 → 2.7 µs per object per frame | If an offset is always zero / a rotation always identity, write the result directly |
Workflow
Section titled “Workflow”- Measure the scenario (§ Measure first) and write the baseline numbers down.
- Rank: is the frame CPU (component/render-scene update, culling), draw calls, or a one-off stall? Fix the biggest category only.
- Apply one lever, rebuild or reload, re-measure the same scenario, pixel-check.
- Commit with before → after numbers and the throttle/scenario they were taken under.
- Repeat until the budget holds; record what was left (and why) in the project’s docs/system-design.md.