Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.
Performance Optimization
Profiler-first bottleneck routing to pooling, culling, servers, MultiMesh, and threads โ not generic pool tutorials.
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 @warning_ignore or conditional if OS.is_debug_build(): [21].
NEVER ignore VisibleOnScreenNotifier2D for off-screen entities โ Enemies processing logic off-screen = wasted CPU. Disable set_process(false) when screen_exited [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 get_node() 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 _inter_ray or _physics_process 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.
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.
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.
