Godot Genre Rts

NEVER Do (Expert Anti-Patterns)

Unit Logic & Pathfinding

• NEVER allow pathfinding "Jitter" when moving group units; strictly stagger path queries and enable RVO Avoidance only when units are in motion to save CPU cycles.
• NEVER update RVO avoidance every frame for all units; strictly use Avoidance Threading (Project Settings) and replace static units with NavigationObstacle.
• NEVER let units get stuck in infinite path loops; strictly implement a timeout and IDLE state if a destination is unreachable.
• NEVER use _process() on hundreds of individual units; strictly use a central UnitManager or _physics_process only when required.
• NEVER calculate unit visibility manually for Fog of War; strictly use a Shader-based mask (SubViewport + ColorRect) for GPU efficiency.
• NEVER process unit AI or pathfinding synchronously for mass groups; strictly offload to WorkerThreadPool and stagger path updates.
• NEVER use high-poly visual meshes as NavMesh source geometry; strictly use simplified Collision Shapes for baking.

Interaction & Commands

• NEVER forget Command Queuing (Shift-Click); strictly store an Array[Command] and implement a "Force Move/Attack" bypass.
• NEVER create excessive micromanagement; strictly automate low-level tasks like auto-aggro range and auto-return for resource gathering.
• NEVER use exact floating-point equality (==) for grid or timers; strictly use is_equal_approx() for deterministic triggers.
• NEVER rely on the visual SceneTree for selection data; strictly maintain a Typed Selection Set of RefCounted or Resource objects for deterministic serialization and netcode.
• NEVER forget Command Queuing; strictly implement a Command Pattern using serializable Dictionary or JSON states for save-game and multiplayer playback.
• NEVER forget to duplicate_deep() globally shared Resources; otherwise, modifying one unit's data (e.g., stats) affects all.

Performance & Simulation

• NEVER render thousands of units using separate MeshInstance3D nodes; strictly use MultiMeshInstance with INSTANCE_CUSTOM data to drive unique GPU-side state animations (walking/attacking/color).
• NEVER calculate transforms for mass units on the main thread; strictly use WorkerThreadPool to push buffers to RenderingServer.multimesh_set_buffer().
• NEVER update every unit's navigation path in the same frame; strictly use random timers to stagger updates.
• NEVER use standard Strings for high-frequency AI state identifiers; strictly use StringName (&"harvesting") for pointer-speed comparisons.
• NEVER allow simulation coordinates to exceed 8192 units without float-precision management; strictly use world-origin shifts.
• NEVER use CSGShape3D for building placement ghosts; strictly use optimized static ArrayMesh geometry.

---

🛠 Expert Components (scripts/)

MANDATORY: Read the script for the workflow you are implementing — do not re-inline selection/fog recipes in the agent body.

Selection / commands

• selection_manager_marquee_2d.gd — MANDATORY for 2D drag-box, filter, shift-add.
• selection_manager_raycast_3d.gd — MANDATORY for 3D PhysicsServer picks.
• rts_selection_overlay.gd — Selection visuals / box overlay.
• rts_group_commander.gd — SceneTree group broadcast for mass orders.
• rts_targeting_logic.gd — Distance-squared enemy filtering.

Units / navigation / army

• rts_unit.gd — MANDATORY unit controller (states + NavigationAgent).
• crowd_navigation_unit.gd — RVO / crowd agent wiring.
• rts_path_query_pool.gd — Pooled Navigation path queries.
• navigation_mask_helper.gd — Nav layers / avoidance bitmasks.
• rts_army_manager.gd — WorkerThreadPool army AI batches.
• rts_unit_stat_duplicator.gd — duplicate_deep() isolation for unit Resources.

Economy / build / fog / ghosts

• global_economy_manager.gd — Gather/spend bank Autoload pattern.
• building_grid_astar.gd — Grid placement pathing.
• fog_of_war_tile_mask.gd — MANDATORY TileMapLayer fog clear (2D/grid).
• rendering_ghost_spawner.gd — Placement ghosts via RenderingServer RIDs.
• rts_formation_manager.gd — Center-of-mass group path + per-unit formation offsets.
• rts_massive_unit_renderer.gd — MultiMeshInstance3D army renderer synced from unit transforms.

---

Core Loop

1. Gather: Units collect resources (Gold, Wood, etc.).
2. Build: Construct base buildings to unlock tech/units.
3. Train: Produce an army of diverse units.
4. Command: Micromanage units in real-time battles.
5. Expand: Secure map control and resources.

Skill Chain

Decision Tree: NavigationAgent+RVO vs MultiMesh+server sim

Rule: Keep NavigationAgent+RVO while units need individual collision avoidance and micromanage feel. Switch to MultiMesh + server-side transforms when draw-call/node cost dominates — path as squads, not as thousands of agents.

Architecture Overview

1. Selection Manager

MANDATORY: selection_manager_marquee_2d.gd (2D) or selection_manager_raycast_3d.gd (3D). Maintain a typed selection set (not SceneTree-only) for netcode/save. Overlay: rts_selection_overlay.gd.

2. Unit Controller (State Machine)

MANDATORY: rts_unit.gd for Idle/Move/Attack/Hold + NavigationAgent. Deep state graphs → godot-state-machine-advanced. Always duplicate_deep() shared stat Resources (rts_unit_stat_duplicator.gd).

3. Group Movement & Formations

Avoid clumping on one click target: compute center of mass, apply relative offsets, issue per-unit destinations. For hundreds of units, use one NavigationServer path for the COM (Batch 09) plus rts_group_commander.gd / rts_path_query_pool.gd.

4. Fog of War

MANDATORY for tile/grid fog: fog_of_war_tile_mask.gd. SubViewport mask + shader overlay is valid for soft vision — implement via docs (Using Viewports) + godot-shaders-basics; Do NOT paste long fog shaders into this skill body when the tile-mask script covers the grid path.

Key Mechanics Implementation

Command Queue

Shift-click chains: store Array of serializable commands; pop on finish; draw queued path lines. Pair with selection scripts' issue-command hooks.

Resource Gathering

ResourceNode → work timer → DropoffPoint → bank update. Wire bank through global_economy_manager.gd / godot-economy-system.