Tier 2 · Performance and memory

Performance & memory

Per-frame cost, allocation, logging and silent-zero configs.

Markdown version

Per-frame cost, allocation, logging and silent-zero configs.

Per-frame cost, allocation, and the silent-config family — values that read back as 0 and quietly disable the feature they gate.

  • Routine per-action logs go through a gated logger — raw Debug.Log* is for one-shot lifecycle and real errors only. Every system that logs a routine OUTCOME (item picked up, piece placed, upgrade accepted/rejected, RPC sent/received) adds console flood + a per-call string-interpolation alloc + (in editor) a managed stack-walk per log — and these accumulate silently as systems multiply until the console is unusable and the editor stutters (this is a recurring, real failure here). Route them through a [Conditional("RJ_VERBOSE")] logger (RjLog.Verbose) so the call AND its argument evaluation compile out when the define is off (the default). Keep raw Debug.Log/LogWarning/LogError for genuine one-shot flow (connect/disconnect, world-load, session dispose) and real errors. The tell you got it wrong: a Debug.Log whose enclosing method runs per-action/per-tick/per-frame, or that just confirms a normal outcome. Server RPC-handler rejection logs are hostile-spammable (a client floods the RPC) — always gate those. A one-shot warning that can re-fire must latch behind a _warned bool so it logs once, not every call.

  • Hot paths allocate nothing and scan nothing per frame. Update/LateUpdate/OnGUI (and per-tick system OnUpdate) run every frame, so any garbage there feeds incremental GC and any scan is O(n) every frame. BANNED in a hot path: new-ing a List/HashSet/array (hoist it to a member, Clear and reuse), LINQ/ToArray, string interpolation into a per-frame log or SetText (cache it, rebuild only on change), and GetComponent*/Find*ByType. Special trap: a GetComponentInParent<TInterface> that returns null every frame makes Unity build an internal error string each call (steady ~1KB/frame GC, profiler marker GetComponentNullErrorMessage) — cache the ref at spawn/Awake, restrict the raycast with a LayerMask, or call a concrete TryGetComponent<T> instead of walking a single-implementer interface. Gate the whole hot path on an early-out when nothing changed (pointer didn't move, the set is empty).

  • OBJECT-NAME-READ-ALLOCATES — UnityEngine.Object.name mints a new managed string on every read. material.name, gameObject.name, clip.name inside a per-camera / per-frame path (a shadow-mode decision keyed on "is this the foliage material", a tag test, a log guard) is a hidden allocation per call — the class header can say "a camera pass allocates nothing" and be wrong. Resolve the answer once at registration and cache the bool/int; compare by reference or by a cached id, never by name, in a hot path. (a tower-defense game: ported verbatim from a mobile strategy game, caught by the lane B worker before it landed.)

  • Pre-allocate big buffers/textures/meshes up front — never lazily on the first gameplay frame that needs them. A new Color32[1024*1024], a RenderTexture, or a re-tessellated mesh deferred to first-use surfaces as a multi-MB mid-game hitch (real 4 MB spikes here). Allocate in Awake/OnEnable, or register a ClientWarmup step so the cost lands behind the loading screen; for a buffer rebuilt repeatedly, reuse a static grow-only scratch array instead of new per rebuild.

  • Invalidate a cache on the specific input that changed, never a blanket force-clear wired to a broad event. A Rebuild(force:true) subscribed to a generic SettingsChanged/OnChanged event re-bakes expensive state (a tessellated cursor, a baked texture) when an UNRELATED setting moves (a volume slider clearing the cursor cache). Key the clear to the field that matters; if you must listen to a broad event, diff the relevant value and early-out when it's unchanged.

  • FRAMES-IN-FLIGHT-SERIALIZE-CPU-AND-GPU - QualitySettings.maxQueuedFrames = 1 is a latency trade that only pays when the GPU is the bottleneck. At 1 the main thread waits at the top of every frame for the previous frame's GPU work (GfxDeviceD3D12.WaitForLastPresentation.WaitForGPU in the profiler), so frame time becomes CPU + GPU instead of max(CPU, GPU). CPU-bound, a second queued frame adds no input latency, so 1 is pure loss; in a fixed-tick netcode game the longer frame also buys extra catch-up ticks, which compounds. With vSync on, 1 halves the rate whenever CPU + GPU crosses one refresh: a menu that runs at 94 fps uncapped locked at 30 fps on a 60 Hz display. Measured by flipping the value live in one Play session: 47.2 -> 30.5 ms per frame, main thread 36.7 -> 21.5 ms, server ticks per frame 2.7 -> 1.8. Before setting 1 for aim latency, measure CPU vs GPU per frame (FrameTimingManager) on the real target and A/B the value live; a large WaitForGPU marker on the main thread is the tell.

Zero managed allocation by default is a hard coding standard: see ZERO-ALLOCATION-BY-DEFAULT on the C# style & conventions page.

Audio — world SFX density

  • A voice-pool size is not a loudness cap. Round-robin steal of the oldest AudioSource still plays every attack — 16 overlapping copies of the same swing is a wall of noise. Cap concurrent world/3D voices, new starts per frame, and copies of the same clip. Drop the extra shot; steal only if the new source is meaningfully closer than the farthest playing 3D voice. Never steal a playing 2D/UI voice. Pool size stays larger than the cap so UI still has idle sources. Authored numbers, with <= 0 → default so a newly added serialized field on an existing config asset cannot silently disable the cap.

  • NEAR-FIRST-STREAMING-BUDGET — a per-tick budget walked over a category-major catalog streams the HORIZON first. A linear scan spent the whole budget on the 1,050–3,400 m bands before the first tree at the spawn; prioritise near bands with a second pass. And a budget cap is a shock absorber, not the fix: MaxConvexBuildsPerScan = 256 turned a 99 s frame into a 16 s drain per sim world that held readiness — and the motor — down the whole time. Cover the drain with a gate and DO LESS WORK. (a survival game)

  • RENDER-BENCH-PROVES-PIXELS — an instancing number counts only after emission AND pixels are proven. A path that draws nothing measures FASTER than an empty scene and looks like a win; Camera.Render timing is CPU-side (a flat 4.49 ms at 1M instances while the GPU pushed ~500M verts); a pipeline flag being ON in the asset proves nothing about it working — A/B it before crediting it; and per-frame resubmission hooks bill the ENTIRE editor, so arm / measure / disarm in a finally (one armed hook took the editor to 98 GB). (a survival game)

  • **FORCED-ARM-SHOWS-ITS-COST ** - a bench arm that forces a gated camera back on counts only after it measurably costs something. Two HDRP forcing methods rendered nothing, with CPU and GPU time identical to the gated arm over 240 frames: inserting the disabled camera into the beginContextRendering camera list, and re-enabling it in Application.onBeforeRender. The "every skipped frame reads black" sweep built on them proved nothing. Force it through the code that owns the enabled flag (make its own visibility test pass), and read the forced arm's cost before trusting its pixels.

  • GPU-WARMUP-NEEDS-A-REAL-DRAW — a first-view hitch is shader variants the gameplay path never compiled; enabling culled renderers warms nothing. Warm with an actual draw of the variant (an off-screen camera or a one-frame visible quad), and measure the second entry. (a project docs/pitfalls/globe-morph.md:8,27.)

  • PROFILER-CAPTURE-IS-BOUNDED — a Profiler binary log armed from a bridge call never stops on its own. Profiler.logFile + enableBinaryLog + ProfilerDriver.enabled left on during the developer's live play wrote 77 GB to Temp/Profiles in ~45 min and held the Editor at 17-20 fps; the developer read it as "the game is laggy" and the raw file was unopenable. Capture seconds, disarm in the same call chain (finally), delete the raw once read, and never leave a capture armed across turns or a context compaction. (a space sandbox game.)

  • EDITOR-GC-IS-AN-UPPER-BOUND - an Editor Play allocation census is not the shipped number. Three inflators measured: profiler-gated systems (a NetCode metrics collector showed 1.06 KB/frame; it returns early unless the Profiler is on and is compiled out of players); Collections safety checks (every NativeArray allocation creates managed safety objects, so a vendor call making six arrays reads as fat managed garbage); and Deep Profile itself, which slowed frames enough to trip wall-clock load gates twice. Confirm an allocation in a development player before optimizing it.

  • TEXTURE-DEFAULT-CAP-SHIPS-WHEN-STANDALONE-IS-NOT-OVERRIDDEN . Generated 2048 maps shipped at 1024 DXT: the importer's Default platform size and format applied because Standalone was not overridden. Set the Standalone override in the import script (source size, BC7 colour, BC5 normals, streamed mips), re-apply it after a rebuild that rewrites maxTextureSize in kept metas, and gate it with an import check.

  • PARTICLE-COST-NEEDS-A-REAL-DRAW . maxParticles is a ceiling and Camera.Render time is CPU-side while particle work runs on the GPU; neither measures an effect's cost. Measure a real draw with the effect's pixels on screen (GPU frame time in a capture); see GPU-WARMUP-NEEDS-A-REAL-DRAW.

  • PROFILER-MARKERS-FROM-EVENTS-ARE-INVISIBLE . Profiler.BeginSample markers issued from event handlers or from an injected PlayerLoop delegate never appeared in HierarchyFrameDataView in Editor Play (profileEditor off). Map an event to its frame by stamping ProfilerDriver.lastFrameIndex + 1 when it fires (lag measured as one frame), then read that frame's hierarchy. Editor frame time is padded by EditorLoop to about 16.7 ms, so judge game work by the PlayerLoop total. A hitch on an event edge (level-up, purchase) is often structural work on that frame: destroying and recreating prototype entities with about 30 component adds each, or a managed EntityManager get/set loop over every live unit. Keep the entities for the session and write values in place; for text, see DYNAMIC-FONT-FIRST-GLYPH-SPIKES-THE-FRAME in the HTML/CSS mock to UI Toolkit page.

  • MAIN-THREAD-FILE-IO-STALLS-THE-TICK . Slow dedicated-server frames measured 60-381 ms in Update.ScriptRunBehaviourUpdate while every ECS world summed about 1 ms. The only MonoBehaviour Update was an operator console that wrote a heartbeat file every 2 s, scanned a command inbox with Directory.GetFiles 4x/s and flushed an event log per line, so a busy disk (an Editor build or antivirus on the same machine) stalled the simulation tick. Give each file writer one background thread: the main thread formats and queues, the heartbeat is latest-wins (a hung main thread still leaves it stale). Wrap each section of that Update in a ProfilerMarker so a slow-frame breakdown names it instead of "scripts: not timed".

  • PROFILER-RECORDER-MISSES-LATE-MARKERS . A ProfilerRecorder set built from ProfilerRecorderHandle.GetAvailable never records a marker registered afterwards, and a static readonly ProfilerMarker registers only when its type's statics initialize. Declare the markers on types constructed before the recorders are enumerated, or rebuild the recorder set once they exist.

  • ONE-SAMPLE-SPIKE-IN-AN-IDLE-SYSTEM-IS-STARVATION . A slow-frame breakdown named ExportPhysicsWorld 51 ms and HybridLightBakingDataSystem 29.8 ms in a server's idle local world, while across 26 slow-frame breakdowns the same groups read 0.1-1 ms (median 0.3): the process was descheduled mid-system (the machine also ran an Editor at 3.3 cores idle and two more Unity processes). Before fixing a system, compare its spike with its typical cost across all breakdowns; a single outlier in an otherwise idle system is CPU starvation, and a large untimed share of slow frames is the same signature. Amended: the direct proof is machine versus process CPU for the slow frame (Windows: GetSystemTimes and GetProcessTimes over the frame). An empty dedicated server whose sleep-mode tick warnings climbed from 297 to 3513 in 20 minutes read machine 97-100 % busy and its own process 0-1 %: other programs (patch hashing on every core, compiler and player builds) held the CPU. Print both numbers on every slow frame. Measure capacity on a quiet machine, and tell the developer plainly: the PC was busy with other programs; the server was waiting, not overloaded. Amended: read those counters on a background thread, never per frame on the game thread, and only trust the reading when the slow frame's time is NOT inside the CPU read itself (see CPU-COUNTERS-OFF-THE-GAME-THREAD).

  • CPU-COUNTERS-OFF-THE-GAME-THREAD . Windows GetSystemTimes read once per frame on the main thread cost 0.15-0.2 ms (p99 0.7 ms, max 19 ms in a 60 Hz probe) and held an idle dedicated server's main thread 55-176 ms in 3 of 3 slow frames; GetProcessTimes in the same probe never passed 0.5 ms. A machine/process delta taken across that stall reads "machine 100 % busy, this process 0 %" while 5 s machine samples around it read 17-51 %, so the observer invents starvation. Sample the counters on a background thread (every 50 ms into a small ring), make no syscall on the game thread, and report the span a reading covers. Wrap each call of a per-frame observer in its own profiler marker so a slow frame can name the observer.

  • EDITOR-RENDER-STATS-VIA-PROFILER-RECORDER . UnityEditor.UnityStats.batches and its siblings no longer exist in Unity 6. Read render counters with ProfilerRecorder.StartNew(ProfilerCategory.Render, "SetPass Calls Count") (likewise "Triangles Count") and read LastValue in a LATER call, after frames have rendered. In a URP Editor, "Batches Count" and "Draw Calls Count" read 0, so budget on SetPass and triangles there, and a camera.Render capture in the same call inflates the counters. See PROFILER-RECORDER-MISSES-LATE-MARKERS above.

  • SURFACEFLINGER-LATENCY-IS-EMPTY-ON-ANDROID-16 . adb shell dumpsys SurfaceFlinger --latency <layer> returns only the refresh period for a Unity SurfaceView on Android 16 (BLAST layer names), with no frame rows. Take device fps from the game's own FPS readout or Unity's frame timing and profiler, and never report an empty latency dump as a measurement.

  • SETTING-COST-IS-SWITCHED-IN-PLACE . Measure one render setting's cost by switching it on a static scene, never by comparing two runs or two moments of a live wave; unit counts drift between reads, so the pair mixes the setting's cost with the wave's. Freeze the scene (a results screen with a fixed camera), then switch the value in separate calls: each call reads the counter's LastValue for the value set in the previous call, then sets the next value (see EDITOR-RENDER-STATS-VIA-PROFILER-RECORDER above). End by re-reading the first value; an identical number proves there was no drift. Measured: terrain pixel error 5 / 2 / 3 / 5 read 412,777 / 500,305 / 460,601 / 412,777 (+87.5k for 2), while a cross-run pair had reported +95.7k.

  • BUDGETING-SPREADS-COST-DOES-NOT-REMOVE-IT — a per-frame cap on expensive boot work only moves the total. Why: frame budgeting changes distribution, not work. Check: measure total cost before budgeting; remove or cache the work first, then budget what remains. See also LOADING-WORK-IS-FRAME-BUDGETED (the scene flow page). Status: locked (empirical, seen in shipped/active projects).