Skip to content

t1k:cocos:playable:runtime-perf

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: baked animation, draw calls, frame time, hitch, instancing, joint texture, prewarm, runtime performance, shader link, shadows, stall, texture memory, weak device

/t1k:cocos:playable:runtime-perf
<scenario: level start | first drag | level N gameplay | memory>

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×).

SymptomRead
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 highreferences/memory-and-weak-devices.md § Memory
Fine on desktop, bad on low-end phonesreferences/memory-and-weak-devices.md § Weak-device tier
Not sure where the time goes§ Measure first

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.

  1. 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).
  2. 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).
  3. Log frame-time percentiles, not a mean: median, frames over 40 ms, worst frame. A stall hides inside an average.
  4. 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.
  5. 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.
LeverMeasuredHow
USE_INSTANCING on materials shared by many static renderersfly-over 807 → 221 draw calls, gameplay 222 → 91Shared 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 model700 voxel blocks: frame 52 → 37 ms; 1100 hidden models goneA 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 seeAnimationManager 2 → 0.3 msRenderer 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 msDistance 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 draw3,072 empty triangles per frameDisable 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 renderer4,467 pooled intro voxel nodes: 20-27 s of build at 4× CPU, up to 8,954 instances per frameA 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 code3.4 → 2.7 µs per object per frameIf an offset is always zero / a rotation always identity, write the result directly
  1. Measure the scenario (§ Measure first) and write the baseline numbers down.
  2. Rank: is the frame CPU (component/render-scene update, culling), draw calls, or a one-off stall? Fix the biggest category only.
  3. Apply one lever, rebuild or reload, re-measure the same scenario, pixel-check.
  4. Commit with before → after numbers and the throttle/scenario they were taken under.
  5. Repeat until the budget holds; record what was left (and why) in the project’s docs/system-design.md.