| name | game-optimization-performance |
| description | Project-specific optimization and performance skill. Covers audio smoothing patterns, frame budget testing, Performance singleton benchmarks, Server API usage, profiling workflow, and known performance pitfalls. Use when diagnosing glitches, optimizing frame times, writing performance tests, or fixing audio/visual artifacts. |
Game Optimization & Performance
Project-specific optimization patterns, benchmarking, and known pitfalls.
Architecture
| Component | Location | Role |
|---|
| AudioManager | scripts/autoloads/audio_manager.gd | Bus hierarchy, sidechain compressor, volume API |
| CarAudio | scripts/audio/car_audio.gd | Engine/wind/servo/landing audio (sample-based) |
| TireAudio | scripts/audio/tire_audio.gd | Per-wheel tire squeak with envelope smoothing |
| ImpactAudio | scripts/audio/impact_audio.gd | Collision/scrape audio (sample-based, pooled) |
| GraphicsManager | scripts/autoloads/graphics_manager.gd | Tier switching, DOF, config persistence |
| Debug overlays | scripts/debug/ | F3-F8 visual profiling overlays |
| EffectLOD | Various effect scripts | WorldScale-aware distance culling |
Optimization Principles
The Hierarchy (Most to Least Impact)
- Design-level -- Choose the right algorithm/architecture (physics engine, sample-based audio vs synthesis)
- Algorithm-level -- Fix math that produces bad output (audio envelope smoothing, parameter clamping)
- Data-level -- Cache locality, compact storage, precalculation
- Low-level/Server API -- Direct RenderingServer/PhysicsServer/AudioServer calls (only when node overhead is the bottleneck)
When to Use Server APIs
Server APIs (RenderingServer, PhysicsServer3D, AudioServer) bypass the scene tree for maximum performance. Use them ONLY when dealing with thousands of instances where node overhead is measurable.
| System | Current Approach | Server API Needed? |
|---|
| Vehicles (8-12 max) | Full Vehicle nodes | No -- node count is fine |
| Tire marks/decals | Node-based decals | Maybe at 500+ marks |
| Dust/particles | GPUParticles3D | No -- already GPU-side |
| Spectator crowd (future) | N/A | Yes -- RenderingServer.instance_create() |
| Foliage instances | MultiMesh | Already optimal |
Critical rule: Never poll Server APIs per-frame. They run asynchronously; calling functions that return values stalls them. Write-only access (setting transforms, volumes) is fine.
# GOOD: Write-only, per-frame is fine
RenderingServer.instance_set_transform(instance, xform)
# BAD: Stalls the server, kills performance
var current_xform = RenderingServer.instance_get_transform(instance) # DON'T
Bottleneck Identification
- Profile first -- Use Godot Profiler (Debug > Profiler), F3-F8 debug overlays,
Performance singleton. Known bug: Time spent waiting for built-in servers (rendering, physics, audio) may not appear in profiler results -- if a function seems fast but frame time is high, suspect server-side stalls.
- Hypothesis test -- Add/remove instances, measure impact
- Binary search -- Comment out half the frame work, narrow down
- Check GPU vs CPU -- If CPU optimization doesn't improve frame time, you're GPU-bound
# Quick bottleneck check
var cpu_time := Performance.get_monitor(Performance.TIME_PROCESS)
var physics_time := Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS)
var draw_calls := Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME)
var fps := Performance.get_monitor(Performance.TIME_FPS)
Manual Function Timing
When profiler identifies a bottleneck area, use manual timing to measure specific functions precisely:
# Time a specific function with microsecond precision
var time_start := Time.get_ticks_usec()
update_enemies()
var time_end := Time.get_ticks_usec()
print("update_enemies() took %d microseconds" % (time_end - time_start))
Key rules for manual timing:
- Run the function 1000+ times and average -- single measurements are unreliable due to timer precision and CPU scheduling
- CPU cache effects: First run is always slower (cache miss). Second+ runs benefit from cached data. Always use averages.
- Re-time after every optimization attempt to verify it actually helped
CPU Cache Awareness
- CPUs load data from small, fast cache -- not directly from system RAM
- Cache miss = data not in cache, CPU stalls waiting for main memory fetch
- Sequential/linear memory access patterns = cache-friendly = fast
- Random/scattered memory access = cache misses = slow
- Godot's Server APIs already optimize for cache locality (rendering, physics)
- Most relevant when writing GDExtensions or processing large custom data arrays
Language Performance Tiers
| Language | Speed | Use Case |
|---|
| GDScript | Slowest (ease-of-use optimized) | Gameplay logic, UI, orchestration -- fine for most game code |
| C# | Medium (watch for GC pauses) | Heavy calculations; use object pooling to avoid GC stalls |
| C++ (GDExtension) | Fastest | Hot inner loops, thousands of instances, custom physics |
Rule: If GDScript profiling shows a function is the bottleneck, consider moving just that function to C++ via GDExtension. Don't rewrite entire systems.
Threading
- Use threads for parallelizable heavy work (pathfinding batches, procedural generation)
- Danger: Race conditions when multiple threads access shared data. Use mutexes or message queues.
- Godot's scene tree is NOT thread-safe -- never modify nodes from worker threads
- Debug threaded code is significantly harder; prefer single-threaded until profiling proves it's needed
SceneTree Node Cost
- Every node has overhead:
_process(), _physics_process(), _notification() propagation through the tree
- Thousands of nodes are fine; tens of thousands may bottleneck (platform-dependent -- profile on target hardware)
- Fewer nodes with more content each outperforms many tiny nodes
- Detach instead of hide/pause:
remove_child(node) is cheaper than visible = false or process_mode = DISABLED -- the node exits the tree entirely. Re-attach with add_child() when needed. Keep a reference to avoid GC.
- For truly massive instance counts, bypass the SceneTree entirely with Server APIs
Physics Optimization
- Simplified collision shapes: Use approximate geometry (convex hulls, boxes) instead of trimesh for moving objects
- Remove off-screen physics objects: Detach or disable physics bodies outside the active area
- Physics tick rate: Default 60Hz is correct for real-time vehicle games. Reducing to 30Hz saves CPU but adds input lag and jitter.
- Fixed timestep interpolation: Godot's built-in
physics/common/physics_interpolation smooths rendered positions between physics ticks. Orders of magnitude cheaper than running more physics ticks. Eliminates jitter if tick rate is reduced.
GPU Optimization
Draw Calls & State Changes
- Every API command (Vulkan/OpenGL) has validation overhead
- Goal: Minimize draw calls and group similar objects to reduce state changes
- Godot automatically batches 2D items; 3D requires more manual attention
Material & Shader Reuse
- Reuse materials aggressively: 20,000 objects with 100 shared materials >> 20,000 objects with 20,000 unique materials
- Shader reuse is automatic for StandardMaterial3D with same feature flags (even with different parameters)
- Use texture atlases to reduce texture switches when many unique materials are unavoidable
- For custom shaders: share the same Shader resource across materials, vary only uniforms
Vertex vs Pixel Cost
- On desktop/console: vertex cost is low -- GPUs handle millions of triangles efficiently
- On mobile: tile-based rendering makes vertex processing more expensive; avoid geometry concentration in small screen areas
- LOD is critical: Use lower-detail meshes for distant objects. Avoid sub-pixel triangles even on desktop.
- Additional vertex cost from: skeletal animation (skinning), shape keys (morphs), vertex lighting
Fill Rate & Fragment Shaders
- Fragment shading cost has grown massively with resolution (4K = 27x more pixels than 640x480)
- Fill rate test: Disable V-Sync, compare FPS at large vs tiny window. Big FPS increase = fill rate-limited.
- Reduce fill rate cost: Simplify shaders, reduce texture count/size, disable expensive StandardMaterial3D options
- Variable rate shading: On supported hardware, reduces fragment shading resolution in less-important screen areas without affecting edge sharpness. Good for reducing fill rate cost with minimal visual impact.
- For particles: force vertex shading in material to reduce fragment cost
Texture Best Practices
- VRAM compression: Always enabled for 3D textures (reduces GPU memory bandwidth). Artifacts are invisible on 3D geometry.
- Disable VRAM compression only for pixel art textures
- Minimize texture reads per fragment shader -- each read is expensive (especially with trilinear/mipmap filtering)
- Most Android devices don't support VRAM compression for transparent textures
Transparency & Blending
- Depth prepass: Enabled by default in Forward+ and Compatibility. Writes to Z-buffer first, then only runs fragment shaders on the "winning" (frontmost) pixel. This makes opaque rendering efficient -- but transparent objects can't benefit from it.
- Transparent objects are expensive: Cannot use Z-buffer optimization, must render back-to-front (sorted by material, not depth -- can cause visual artifacts with overlapping transparent objects), every fragment is shaded even if occluded
- Overlapping transparent objects multiply fill rate cost
- Prefer opaque geometry over transparency cheats when possible
- Keep transparent areas small to minimize fill rate impact
- Separate transparent surfaces: If a mesh has a small transparent section, split it into a separate surface with its own material. This lets the opaque parts benefit from depth prepass while limiting the transparent area.
Shadows & Post-Processing
- Shadows are expensive for both writing and reading shadowmaps
- Reduce shadowmap size for distant/small lights
- Disable shadows on OmniLights/SpotLights that are small, distant, or visually unimportant
- Always profile post-processing effects on target hardware
MultiMesh for Mass Instances
Use MultiMesh when rendering hundreds to millions of identical objects (foliage, debris, crowd):
# MultiMesh setup for thousands of instances (single draw call)
extends MultiMeshInstance3D
func _ready() -> void:
multimesh = MultiMesh.new()
multimesh.transform_format = MultiMesh.TRANSFORM_3D
multimesh.instance_count = 10000
multimesh.visible_instance_count = 1000 # Only show what's needed
for i in multimesh.visible_instance_count:
multimesh.set_instance_transform(i, Transform3D(Basis(), Vector3(i * 20, 0, 0)))
MultiMesh key rules:
- No per-instance culling -- entire MultiMesh is drawn or not. Split into spatial chunks for large worlds. Set a custom visibility AABB (
MultiMesh.custom_aabb) to control culling bounds when instances spread beyond the auto-calculated AABB.
- Control visible count dynamically with
visible_instance_count (allocate max, show only what's needed)
- Per-instance logic possible via vertex shader (
INSTANCE_ID, INSTANCE_CUSTOM) + data textures (use Image.FORMAT_RGBAF floating-point format for encoding per-instance data into textures the shader can sample)
- For C++ GDExtension:
RenderingServer.multimesh_set_buffer() sets all transforms in one call (linear memory, cache-friendly, multi-threadable)
| Instance Count | Recommended Approach |
|---|
| < 100 | Individual nodes |
| 100 - 1,000 | Nodes with LOD, or MultiMesh |
| 1,000 - 100,000 | MultiMesh |
| 100,000+ | MultiMesh + GDExtension for data |
Multi-Platform Performance
- Design for lowest common denominator, add enhancements for powerful hardware
- Test on all target platforms early and often (especially mobile)
- Mobile tile-based renderers: post-processing, viewport textures, and cross-tile effects are expensive
- Consider Compatibility rendering method when targeting both desktop and mobile
Pipeline Compilation & Shader Stutter
Pipeline compilation (GPU driver converting shader intermediate format to GPU-native code) causes "shader stutter" on first playthrough. Godot 4.4+ mitigates this:
Ubershaders: Godot uses specialization constants to optimize shader pipelines for specific rendering configurations. Ubershaders are a generic version that can change these constants at runtime, allowing Godot to precompile just one pipeline at load time and compile optimized specializations in the background during gameplay. This eliminates most first-encounter stutters.
Pipeline precompilation: Pipelines are precompiled when meshes load or nodes are added to scene. Works with background threading during loading screens.
Shader baker (4.5+): Bakes compiled shader code into PCK at export time, skipping the compilation step entirely. Enable in Export > Shader Baker > Enabled. Especially beneficial for D3D12/Metal (slower initial compilation than Vulkan). Platform limitations: The editor can only bake shaders for drivers supported on the current OS (Windows: Vulkan + D3D12, macOS: Vulkan + Metal, Linux/Android: Vulkan only). Only works for Forward+ and Mobile renderers (not Compatibility). Baked shaders match the rendering/rendering_device/driver project setting for the target platform.
Avoiding pipeline stutters:
- Load meshes/shaders during loading screens, not during gameplay
- Ensure rendering features are active in an early scene before loading main assets. Full feature list that triggers pipeline compilation: MSAA level, ReflectionProbes, separate specular (SSS), motion vectors (TAA/FSR2/motion blur), normal+roughness buffer (SDFGI/VoxelGI/SSR/SSAO/SSIL), LightmapGI, VoxelGI, SDFGI, multiview (XR), 16/32-bit shadow depth, omni shadow mode (dual paraboloid vs cubemap)
- For dynamically-spawned effects (explosions, dust, particles): attach a hidden instance of each effect type as a child of a persistent, always-present node (e.g., the player). Enable "Editable Children" on the instance and disable its script + hide visual nodes. The engine precompiles pipelines when the node enters the scene tree, even if invisible. This prevents first-use stutters during gameplay.
- Never change MSAA level, GI settings, or shadow precision during gameplay -- triggers immediate recompilation stutters. If these must be configurable, apply changes from an options screen behind a loading screen.
- Use Godot debugger's pipeline compilation monitors to identify stutter sources (Canvas/Mesh/Surface/Draw/Specialization)
Monitor categories:
| Monitor | Meaning | Stutter Risk |
|---|
| Canvas | 2D node drawn first time | Yes (no 2D precompilation yet) |
| Mesh | 3D mesh loaded, pipelines identified | Only if loaded during gameplay |
| Surface | Node added to scene tree first time | Only on first frame after add |
| Draw | Ubershader wasn't precompiled (bug) | Yes -- report to Godot devs |
| Specialization | Background optimization | No (async) |
3D Rendering Optimization
Occlusion culling: Enable OccluderInstance3D nodes to prevent rendering objects behind walls/buildings. May require level design changes (add walls to block long sightlines).
Level of detail (LOD):
- Automatic mesh LOD on import (Mesh LOD)
- Manual visibility ranges (HLOD) for node-level control
- Decals/lights have Distance Fade properties
- Use billboard impostors for distant objects (trees, foliage)
- Combine multiple distant objects into single impostor groups
- Re-rendered imposters: For distant scenery (track buildings, tree lines), periodically re-render the object group onto a texture from the current viewing angle rather than using a static billboard. Only needed when the viewer moves far enough for the angle to change significantly. Complex to implement but effective for detailed distant environments in racing tracks.
Static mesh joining: Combine static meshes that are near each other into a single mesh (done by artists in Blender or programmatically via addons). Reduces draw calls significantly for large groups of small objects. Tradeoff: joined meshes can't be individually culled -- an off-screen city joined to one on-screen blade of grass renders the entire city. Best for distant or clustered low-poly objects.
Automatic instancing (Forward+ only): MeshInstance3D nodes with same mesh + opaque/alpha-scissor material are automatically batched. No setup needed. Alpha-blended materials must use MultiMesh instead.
Baked lighting:
- Use LightmapGI for static scenes -- dramatically cheaper than realtime
- Set lights to
Static bake mode for best performance
- Keep DirectionalLight3D as
Dynamic, set omni/spot to Static for good balance
- Static lights can't cast shadows on lightmapped meshes
Animation optimization:
- Skeletal animation (skinning) is CPU-expensive -- lower polycount for animated models
- Reduce animation rate for distant/occluded meshes
- Use VisibleOnScreenEnabler3D to pause animations off-screen
Large worlds:
- Tile-based loading to limit memory and processing
- Enable large world coordinates for worlds >~5km from origin
- Or periodically re-center the world around the player to avoid floating point precision loss
Threading in Godot
Thread creation is slow (especially on Windows). Create threads during loading, not just-in-time.
Thread safety rules:
| System | Thread-Safe? | Notes |
|---|
| Global scope singletons | Yes | Ideal for Server API access from threads |
| Scene tree | No | Use call_deferred() / set_deferred() for node operations |
| Building scene chunks | Partial | Create node trees off-tree in thread, add_child.call_deferred() on main thread |
| RenderingServer | Yes (with setting) | Enable Rendering > Driver > Thread Model = Separate. Warning: has known bugs, may not be stable in all scenarios. |
| PhysicsServer3D | Yes (with setting) | Enable Physics > 3D > Run on Separate Thread. Note: physics callbacks fire on the physics thread, not main thread -- code assuming main-thread execution will break. |
| NavigationServer3D | Yes | Queries run in true parallel |
| Resource loading | Partial | One thread loading is safe; multiple threads risk crashes. Use ResourceLoader.load_threaded_request() for safe background loading. |
| GDScript arrays/dicts | Partial | Read/write elements OK; resize/add/remove requires mutex |
Mutex best practices:
- Lock as briefly as possible -- long locks defeat threading benefits
- Avoid locking too frequently (lock/unlock is expensive)
- Never access GPU directly from threads (texture creation, image data retrieval)
- Always call
Thread.wait_to_finish() in _exit_tree() -- mandatory for portability, even if the thread has already returned
# Thread + Mutex pattern
var _mutex := Mutex.new()
var _thread := Thread.new()
var _data := 0
func _ready() -> void:
_thread.start(_worker)
func _worker() -> void:
_mutex.lock()
_data += 1
_mutex.unlock()
func _exit_tree() -> void:
_thread.wait_to_finish()
Semaphore pattern for on-demand thread work:
# Thread sleeps until semaphore.post() wakes it
var _semaphore := Semaphore.new()
func _thread_function() -> void:
while true:
_semaphore.wait() # Suspends until post()
# ... do work ...
func request_work() -> void:
_semaphore.post() # Wake the thread
Vertex Animation via Shader (MultiMesh + Fish Pattern)
For animating thousands of identical objects (fish, birds, crowd), use vertex shaders instead of skeletal animation:
- Define motion as
cos(TIME + offset) functions in vertex shader
- Pass per-instance phase/speed via
INSTANCE_CUSTOM (set via set_instance_custom_data())
- Four composable motions: side-to-side, pivot, wave (panning cos along spine), twist (panning roll)
- Use
smoothstep mask to limit motion to specific body regions
- Entirely GPU-side -- zero CPU cost per instance
// Per-instance animation offset via INSTANCE_CUSTOM
float time = (TIME * (0.5 + INSTANCE_CUSTOM.y) * time_scale) + (6.28318 * INSTANCE_CUSTOM.x);
float body = (VERTEX.z + 1.0) / 2.0;
float mask = smoothstep(mask_black, mask_white, 1.0 - body);
VERTEX.x += cos(time + body) * mask * wave;
Audio Performance & Smoothing
The Envelope Smoothing Pattern
Audio parameter changes (volume, pitch) MUST be smoothed to avoid audible discontinuities (pops, clicks, stuttering). TireAudio implements this correctly:
# CORRECT: Attack/release envelope (TireAudio pattern)
const VOLUME_ATTACK: float = 12.0 # per-second rise rate
const VOLUME_RELEASE: float = 6.0 # per-second fall rate (slower = no clicks)
var _smooth_volume: float = 0.0
func _update_volume(target: float, delta: float) -> void:
if target > _smooth_volume:
_smooth_volume = minf(_smooth_volume + VOLUME_ATTACK * delta, target)
else:
_smooth_volume = maxf(_smooth_volume - VOLUME_RELEASE * delta, target)
# WRONG: Direct assignment causes discontinuities
player.volume_db = linear_to_db(vol) # jumps instantly, causes pops
player.pitch_scale = new_pitch # pitch discontinuity = audible click
Audio Constants Reference
| System | Constant | Value | Purpose |
|---|
| CarAudio | SAMPLE_RPM | 4000.0 | Engine pitch reference RPM |
| CarAudio | ENGINE_FREE_SPIN | 1.5 | Airborne motor multiplier |
| CarAudio | Engine RPM lerp | 8.0 | Per-second smoothing rate |
| TireAudio | VOLUME_ATTACK | 12.0/s | Fast slip onset |
| TireAudio | VOLUME_RELEASE | 6.0/s | Slow silence fade |
| TireAudio | SLIP_THRESHOLD | 0.15 | Below this: silent |
| TireAudio | SILENCE_DB | -80.0 dB | Silence floor |
| TireAudio | MAX_VOLUME_DB | -6.0 dB | Peak tire volume |
| AudioManager | Compressor threshold | -20.0 dB | Music ducking starts |
| AudioManager | Compressor ratio | 3.0 | 3:1 gentle compression |
| AudioManager | Compressor attack | 20000.0 us | 20ms impact response |
| AudioManager | Compressor release | 200.0 ms | Smooth musical return |
Known Audio Pitfalls
- Compressor attack_us is microseconds --
20.0 = 0.02ms (< 1 audio sample at 44.1kHz). Must be 20000.0 for 20ms.
- Engine/wind/servo have no envelope smoothing -- Direct
volume_db assignment per frame causes pops. Apply attack/release pattern.
- Servo steer_speed spikes at low delta --
absf(steer - prev) / maxf(delta, 0.001) amplifies at high framerates. Smooth the output.
- Landing min intensity = 0.2 -- Soft landings (<6 kmh) still play at -14dB. Lower floor or add speed gate.
- ImpactAudio methods never called --
play_collision() and play_scrape() have no call sites. Need Vehicle collision wiring.
- AudioStreamGenerator requires explicit play() --
autoplay=true unreliable on programmatic nodes. Only affects ui_audio.gd and ambient_soundscape.gd.
Audio Bus Rules
- Never query AudioServer per-frame (stalls audio thread)
- Write-only access to bus volumes is fine
- All volume changes go through
AudioManager.set_bus_volume()
- Bus hierarchy: Master -> Music / SFX -> Engine / Tires / Impact / Ambient / UI
Benchmarking & Performance Testing
GUT Frame Timing Tests
## Assert that N frames stay under budget (60fps = 16.67ms)
func test_frame_budget() -> void:
var start := Time.get_ticks_usec()
for i in 100:
await get_tree().process_frame
var elapsed := Time.get_ticks_usec() - start
var avg_ms := elapsed / 100.0 / 1000.0
assert_lt(avg_ms, 16.67, "Average frame should be under 16.67ms (60fps)")
Performance Monitor Snapshots
## Capture performance baseline for regression detection
func capture_perf_snapshot() -> Dictionary:
return {
"fps": Performance.get_monitor(Performance.TIME_FPS),
"process_ms": Performance.get_monitor(Performance.TIME_PROCESS) * 1000.0,
"physics_ms": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS) * 1000.0,
"draw_calls": Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME),
"objects": Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME),
"memory_static": Performance.get_monitor(Performance.MEMORY_STATIC),
}
Audio Parameter Sweep Tests
Test that audio calculations produce sane values at edge cases:
## Parameterized test: engine pitch stays in valid range at all RPMs
func test_engine_pitch_range(rpm: float, min_pitch: float, max_pitch: float,
test_parameters := [
[0.0, 0.01, 0.5], # idle
[1200.0, 0.2, 0.4], # low RPM
[4000.0, 0.9, 1.1], # sample RPM (should be ~1.0)
[8000.0, 1.8, 2.2], # high RPM
[12000.0, 2.5, 4.0], # free-spin overshoot
]) -> void:
var pitch := maxf(rpm / CarAudio.SAMPLE_RPM, 0.01)
assert_between(pitch, min_pitch, max_pitch,
"Engine pitch at %d RPM should be in [%.2f, %.2f]" % [rpm, min_pitch, max_pitch])
Audio Discontinuity Detection
Test that consecutive frames don't produce parameter jumps exceeding a threshold:
## Assert that audio parameter doesn't jump more than max_delta per frame
func assert_smooth_transition(values: Array[float], max_delta: float, label: String) -> void:
for i in range(1, values.size()):
var delta := absf(values[i] - values[i - 1])
assert_lt(delta, max_delta,
"%s jumped %.3f between frames %d-%d (max: %.3f)" % [label, delta, i - 1, i, max_delta])
Memory Leak Detection
## Check that a scene doesn't leak resources after cleanup
func test_no_memory_leak() -> void:
var mem_before := Performance.get_monitor(Performance.MEMORY_STATIC)
# ... run test scenario ...
# Force cleanup
await get_tree().process_frame
var mem_after := Performance.get_monitor(Performance.MEMORY_STATIC)
var leaked_kb := (mem_after - mem_before) / 1024.0
assert_lt(leaked_kb, 100.0, "Scene leaked %.1f KB" % leaked_kb)
Draw Call Budget
## Assert draw calls stay within budget for a standard scene
func test_draw_call_budget() -> void:
# Load a representative scene
var runner := scene_runner("res://scenes/main.tscn")
await get_tree().process_frame
await get_tree().process_frame # let scene stabilize
var draws := Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME)
assert_lt(draws, 500, "Draw calls should be under 500 for standard track")
Custom Benchmark Script Pattern
## Standalone benchmark: spawn N vehicles, measure frame times over M seconds
extends Node
var _frame_times: Array[float] = []
func _ready() -> void:
# Spawn vehicles, set up scene...
pass
func _process(delta: float) -> void:
_frame_times.append(delta * 1000.0)
if _frame_times.size() >= 600: # 10 seconds at 60fps
_report_and_quit()
func _report_and_quit() -> void:
_frame_times.sort()
var avg := _frame_times.reduce(func(a, b): return a + b) / _frame_times.size()
var p99 := _frame_times[int(_frame_times.size() * 0.99)]
var worst := _frame_times[-1]
print("Benchmark: avg=%.2fms p99=%.2fms worst=%.2fms" % [avg, p99, worst])
get_tree().quit()
GDScript Performance Patterns
Cache Node References
# GOOD: Cached at init
@onready var _player := $Player
# BAD: Tree traversal every frame
func _process(_delta):
var player = get_node("Player") # 60x/sec tree walk
Move Calculations Outside Loops
# GOOD: Precalculate
var inv_count := 1.0 / items.size()
for item in items:
item.weight = item.mass * inv_count
# BAD: Division every iteration
for item in items:
item.weight = item.mass / items.size()
Use Typed Arrays
# GOOD: Typed = faster iteration, less memory
var positions: Array[Vector3] = []
# BAD: Variant array
var positions = []
Avoid Allocations in Hot Paths
# GOOD: Reuse pre-allocated object
var _temp_transform := Transform3D()
func _physics_process(_delta):
_temp_transform.origin = new_position
RenderingServer.instance_set_transform(rid, _temp_transform)
# BAD: New allocation every frame
func _physics_process(_delta):
var xform := Transform3D(Basis(), new_position) # allocates
Project-Specific Optimization Notes
Vehicle Count Scaling
- 8-12 vehicles is the target. Each Vehicle has ~20 child nodes (wheels, effects, audio)
- Total node budget per vehicle: ~200 nodes including effects
- At 12 vehicles: ~2400 nodes. Well within Godot's comfort zone.
- If more vehicles needed: disable non-visible effects via EffectLOD
Effect LOD System
Effects use WorldScale-aware distance culling:
- Close: Full detail (particles, tire marks, dust)
- Medium: Reduced particles, no tire marks
- Far: Minimal (no particles, simplified audio)
Terrain3D Performance
- Terrain3D handles its own LOD internally
- Don't fight it -- let the addon manage mesh detail
- Texture count is the main GPU cost: keep terrain material slots reasonable
Physics (Jolt)
- Jolt is already highly optimized
- Main cost: collision detection between vehicles
- Layer masks keep costs low: vehicles only collide with terrain (1) and vehicles (2)
- Don't enable
contact_monitor on vehicles unless needed (adds overhead)
Profiling Workflow
- F8 -- Toggle verbose debug logging (Debug autoload)
- F3/F5/F6/F7 -- Visual physics overlays (suspension, traction, chassis, air)
- Debug > Profiler -- Godot's built-in profiler
- Performance singleton -- Programmatic monitoring in tests
- External GPU profilers -- NVIDIA Nsight, RenderDoc for draw call analysis
- External CPU profilers -- Callgrind (Valgrind) for C++ engine/driver profiling. Relevant for profiling GDExtensions. Compile with debug symbols, run via
valgrind --tool=callgrind ./godot, view results in KCachegrind. Shows Inclusive (function + children) vs Self (function only) time, call counts per function. Can reveal time spent in graphics driver vs engine code (e.g., identifying that 50% of CPU time is in libglapi/i965_dri = driver bottleneck, not engine code)
What to Profile First
| Symptom | Likely Cause | Tool |
|---|
| Low FPS (constant) | GPU-bound: too many draw calls, overdraw | Godot Profiler + GPU profiler |
| Spikes/stutter | GC, allocations in hot path, physics spikes | Profiler + Performance.TIME_PROCESS |
| Audio pops/clicks | Unsmoothed parameter changes | Audio parameter sweep tests |
| Memory growth | Resource leaks, undisposed nodes | Performance.MEMORY_STATIC |
| Physics jitter | Too many contacts, tunneling | Performance.PHYSICS_3D_ACTIVE_OBJECTS |
Related Skills
.agents/skills/debug-system/SKILL.md -- Debug overlays, F-key map, logging.agents/skills/godot-audio-systems/SKILL.md -- Bus management, spatial audio.agents/skills/godot-performance-optimization/SKILL.md -- Generic Godot optimization (community)
