godot-performance-optimization

NEVER Do in Performance Optimization

• NEVER optimize without profiling first — "I think physics is slow" without data? Premature optimization. ALWAYS use Debug → Profiler (F3) to identify actual bottleneck [20].
• NEVER use print() in release builds — print() every frame = file I/O bottleneck + log spam. Use @warningignore or conditional if OS.isdebug_build(): [21].
• NEVER ignore VisibleOnScreenNotifier2D for off-screen entities — Enemies processing logic off-screen = wasted CPU. Disable setprocess(false) when screenexited [22].
• NEVER instantiate nodes in hot loops — for i in 1000: var bullet = Bullet.new() = 1000 allocations. Use object pools, reuse instances [23].
• NEVER use getnode() in process() — Calling get_node("Player") 60x/sec = tree traversal spam. Cache in @onready var player := $Player [24].
• NEVER forget to batch draw calls — 1000 unique sprites = 1000 draw calls. Use TextureAtlas (sprite sheets) + MultiMesh for instanced rendering [25].
• NEVER block the main thread for heavy operations — Avoid OS.delay_msec() or long synchronous data processing. Use WorkerThreadPool to keep framerates steady.
• NEVER use complex collision shapes for physics queries — High-poly convex shapes are expensive to resolve. Prefer simplified primitives (Circle, Rectangle, Box).
• NEVER forget to disconnect local lambda signals — Anonymous lambdas connected to global signals can cause memory leaks if the capturing object is freed.
• NEVER use large textures without VRAM compression — VRAM is limited. Use S3TC/BPTC for desktop (DirectX/Vulkan) and ETC2 for mobile. Note: Disable compression for Pixel Art to avoid artifacts [13].
• NEVER perform tree modifications during physics steps — Adding/removing nodes during interray or physicsprocess can lock the physics server. Use call_deferred.
• NEVER skip shader pre-warming in the Compatibility renderer — Unlike Forward+, OpenGL lacks Ubershaders. Pre-instantiate every mesh/VFX in front of the camera for 1 frame behind a loading screen to avoid hitches [21].

Debug → Profiler (F3)

Tabs:

• Time: Function call times
• Memory: RAM usage
• Network: RPCs, bandwidth
• Physics: Collision checks

Profiler-Tab Decision Tree

Open Debug → Profiler first. MANDATORY load only the script for the hot tab/symptom.

Do NOT Load every perf script for a single hitch.

Available Scripts

[objectpoolsystem.gd](scripts/objectpoolsystem.gd)

MANDATORY for hot-path spawn/despawn — reuse, do not invent Array pop pools inline.

[manualcullinglogic.gd](scripts/manualcullinglogic.gd)

VisibilityNotifier-driven process disable for CPU-heavy off-screen entities.

[renderingserverdirect.gd](scripts/renderingserverdirect.gd)

RenderingServer canvas/mesh path when SceneTree overhead dominates.

[lowlevelphysicsquery.gd](scripts/lowlevelphysicsquery.gd)

Direct space-state queries vs hundreds of RayCast nodes.

[workerthreadpoolmanager.gd](scripts/workerthreadpoolmanager.gd)

WorkerThreadPool offload for heavy jobs.

[multimeshoptimizer.gd](scripts/multimeshoptimizer.gd) / [multimeshfoliagemanager.gd](scripts/multimeshfoliagemanager.gd)

Hardware instancing for dense meshes/foliage.

[texturearraybatching.gd](scripts/texturearraybatching.gd)

Texture2DArray batching to cut material switches.

[sharedresourcestrategy.gd](scripts/sharedresourcestrategy.gd)

Shared vs local-to-scene memory tradeoffs.

[navigationagentoptimization.gd](scripts/navigationagentoptimization.gd)

Staggered path updates for crowds.

[custommonitorprofiler.gd](scripts/custommonitorprofiler.gd) / [customperformancemonitor.gd](scripts/customperformancemonitor.gd)

Performance.get_monitor / custom monitors for game-specific spikes.

Expert Pointers (keep short)

• Compatibility renderer: pre-warm pipelines (hidden camera + unique meshes/materials one frame). Forward+/Mobile: Ubershaders still need instantiate-once detection.
• VRAM: S3TC/BPTC desktop, ETC2 mobile; skip compression for pixel art.
• AStar/path budgets belong in [navigationagentoptimization.gd](scripts/navigationagentoptimization.gd) — do not paste thrashy queue snippets as the golden path.

Deep dives (on demand)

• Path time-slicing, Compatibility shader pre-warm, VRAM codec table → [profiler-budgets-and-prewarm.md](references/profiler-budgets-and-prewarm.md)

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• General optimization — profiler-first workflow so you measure Time/Memory/Physics before changing code.
• CPU optimization — process cost, node lookups, allocations, and why hot-path patterns dominate frame time.
• GPU optimization — draw calls, overdraw, and VRAM compression choices that cut render cost.
• Using MultiMesh — hardware instancing for thousands of meshes and why spatial splits restore culling.
• Using Servers and Resources — RenderingServer/PhysicsServer direct APIs when SceneTree overhead is the bottleneck.
• Using multiple threads — WorkerThreadPool task model for heavy work off the main thread.
• Thread-safe APIs — which engine APIs are safe from worker tasks versus SceneTree-only calls.
• Pipeline compilations — shader/pipeline hitch causes and pre-warm strategies per renderer.
• Optimizing 3D performance — LOD, cull distances, and mesh complexity budgets for 3D scenes.
• Occlusion culling — OccluderInstance3D tradeoffs when frustum culling alone is not enough.
• Performance — built-in monitors plus custom metrics for game-specific bottleneck dashboards.
• Optimizing Navigation Performance — agent update budgets and bake costs for large crowds.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, resources, and import basics required before profiling or pooling patterns make sense.
• godot-gdscript-mastery — typed hot paths, callables, and @onready caching that keep optimization scripts correct.
• godot-resource-data-patterns — shared vs local-to-scene resource ownership that drives memory and unique-instance tradeoffs.

Complements

• godot-2d-physics — collision layers, queries, and body counts that show up as Physics profiler spikes.
• godot-physics-3d — 3D shape cost and RigidBody budgets when optimizing simulation-heavy scenes.
• godot-raycasting-queries — direct space-state query patterns that replace heavy RayCast node stacks.
• godot-shaders-basics — material/shader complexity and Texture2DArray batching that reduce GPU state changes.
• godot-scene-management — threaded loads and scene packing that prevent hitch spikes during streaming.
• godot-navigation-pathfinding — agent path budgets and async bake that pair with staggered AI updates.
• godot-3d-world-building — GridMap/LOD/occlusion level layout that sets the ceiling for draw-call budgets.

Downstream / consumers

• godot-adapt-desktop-to-mobile — resolution/shader fallbacks and battery modes that apply these budgets on weaker GPUs.
• godot-export-builds — export presets and renderer choices where compression and Compatibility pre-warm matter.
• godot-genre-open-world — chunk streaming and HLOD systems that consume MultiMesh, culling, and thread-pool patterns at scale.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.