Godot Game Loop Waves

Architectural Thinking: The "Wave-State" Pattern

A Master implementation treats waves as Data-Driven Transitions. Instead of hardcoding spawn counts, use a WaveResource to define "Encounters" that the WaveManager processes sequentially.

Core Responsibilities

• Manager: Orchestrates the timeline. Handles delays between waves and tracks "Victory" conditions (all enemies dead).
• Spawner: Decoupled nodes that provide spatial context for where enemies appear (wave_spawner.gd / wave_weighted_spawner.gd).
• Resource: Immutable data containers that allow designers to rebalance the game without touching code.

Density Decision Tree (pick scale before coding)

wave_manager.gd is the SceneTree golden path (deferred add_child, group/signal clear counts, optional pool). Treat it as prototype→mid-scale — for RID swarms, follow wave_loop_patterns.gd instead of instantiating thousands of nodes.

Composition Golden Path

1. Author a wave_resource.gd composition table.
2. Place wave_spawner.gd Markers (or wave_weighted_spawner.gd when variety weights matter).
3. Point wave_manager.gd spawner at that Marker; manager defers spawn and clears via &"enemies" group + signals.
4. When weights replace fixed counts, call WaveWeightedSpawner.spawn_enemy() from the composition loop (or set manager spawner to the weighted node).

Expert Code Patterns

1. The Async Wave Trigger

Use await timers in wave_manager.gd — MANDATORY read before writing a custom timeline. Spawns use call_deferred(&"add_child", …); clear via signals/groups (not get_children() scans).

2. Composition-Based Spawning

Define variety in wave_resource.gd; place units with wave_spawner.gd / wave_weighted_spawner.gd. Do not hardcode scene paths in the manager.

Master Decision Matrix: Progression

NEVER Do

• NEVER iterate through get_children() to find all enemies — This is extremely slow. Always add enemies to an "enemies" group and use get_tree().get_nodes_in_group(&"enemies") for efficient access.
• NEVER constantly instantiate() and queue_free() hundreds of enemies — This causes garbage collection stutters. Use an object pool to reuse existing enemy instances.
• NEVER spawn thousands of separate MeshInstance3D nodes for swarms — This will tank your draw calls. Use MultiMeshInstance3D to batch thousands of meshes into a single GPU call.
• NEVER calculate pathfinding for hundreds of agents on the main thread — This will freeze your game. Enable use_async_iterations on your navigation regions or use NavigationServer3D.query_path().
• NEVER forget to check is_inside_tree() before adding a child — If the spawner is queued for deletion, adding a child will crash. Always verify the spawner is still active in the tree.
• NEVER assign a preloaded resource (like stats.tres) directly to spawned mobs — They will all share the exact same health/stats. Always call base_stats.duplicate_deep() to give each mob its own unique data.
• NEVER use standard strings for high-frequency group calls — Always use StringName (&"enemies", &"take_damage") for optimal hash performance and to avoid unnecessary string allocations.
• NEVER spawn entities directly inside physics callbacks synchronously — Instantiating nodes during physics steps can corrupt the physics state. Always use call_deferred(&"add_child", enemy).
• NEVER leave CollisionShapes on dead enemies active — Corpses will block towers and navigation. Use set_deferred("disabled", true) immediately upon death.
• NEVER synchronize complex Object types via MultiplayerSynchronizer — It only supports primitive types. For complex data, sync a UID or ID and look up the data locally on the client.
• NEVER auto-start waves without player feedback — Always provide a UI countdown, a visual "Wave Incoming" effect, or a start button to maintain player agency.
• NEVER hardcode spawn positions at (0,0,0) — Use Marker3D nodes in the editor so you can visually adjust spawn points without digging into code.
• NEVER check wave completion by counting children every frame — It's too expensive. Maintain a local counter or use a signal-based system to track active enemy counts.
• NEVER use the same navigation map for every entity type — If you have flying and walking enemies, use separate navigation maps to prevent pathing issues.
• NEVER scale collision shapes non-uniformly for spawners — This breaks the collision detection math. Adjust the shape resource properties instead.

---

Available Scripts

MANDATORY: Read the appropriate script before implementing the corresponding pattern.

wave_loop_patterns.gd

10 Expert patterns: MultiMesh swarms, async pathfinding, background preloading, and server-side physics mobs.

wave_manager.gd

Orchestrates the timeline, delays between waves, and tracks clear via group counts + signals. Uses call_deferred add_child; optional pool via use_pool / recycle_enemy.

wave_resource.gd

Data containers for wave compositions and difficulty settings.

wave_spawner.gd

Marker3D spatial portal — get_spawn_position() with optional radius jitter. Wire as WaveManager.spawner.