Godot Genre Moba

NEVER Do (Expert Anti-Patterns)

Networking & Authority

• NEVER trust the client for damage calculation or resource costs; strictly validate mana, ranges, and hit detection on the authoritative server using multiplayer.is_server().
• NEVER use TRANSFER_MODE_RELIABLE for continuous movement; strictly use UNRELIABLE or UNRELIABLE_ORDERED for position/velocity to prevent network congestion.
• NEVER sync units at 60Hz; strictly use a lower tick rate (10-20Hz) via MultiplayerSynchronizer and implement Interp/Client-Side Prediction for visual smoothness.
• NEVER attach individual synchronizers to hundreds of minions; strictly batch state updates into compressed byte arrays via a central manager.
• NEVER synchronize complex Engine objects directly; strictly serialize state into primitive properties or Dictionaries for reliable peer-to-peer sync.

AI & Pathfinding

• NEVER use expensive pathfinding for all minions every frame; strictly use Time Slicing to spread get_next_path_position() calls across multiple frames.
• NEVER query NavigationAgent paths inside _process(); strictly use _physics_process() to interact with the navigation server and avoidance systems.
• NEVER use complex visual geometry for NavMesh baking; parse simple primitives to avoid stalling the RenderingServer or crashing the engine.
• NEVER set path_search_max_polygons too low in large maps; agents will stop or walk incorrectly if the limit is reached before the destination.
• NEVER use Area2D for high-performance Fog of War LOS; strictly use nodeless physics queries (intersect_ray) to bypass node overhead.

Gameplay & Balancing

• NEVER forget Tower "Dive" protection; towers MUST switch targets immediately if an enemy Hero damages an allied Hero within range (Priority: Hero attacking Ally > Minion > Hero).
• NEVER allow "Snowballing" without counter-play; strictly implement Comeback Mechanisms (Kill Bounties, Catch-up XP) to maintain competitive tension.
• NEVER manage hero stats as standard Node variables; strictly use custom Resource scripts for data separation and memory efficiency.
• NEVER forget to call duplicate(true) on shared ability Resources; modifying a buff on a shared resource will affect all heroes globally.

Technical & Performance

• NEVER use standard strings for status checks (e.g., "stunned"); strictly use StringName (&"stunned") for pointer-speed comparisons.
• NEVER loop over massive Fog of War grids with floats; strictly use Vector2i and TileMapLayer to prevent precision jitter.
• NEVER execute heavy world/minimap logic on the main thread; strictly offload complex array math to WorkerThreadPool to maintain 60+ FPS.
• NEVER rigidly couple UI cooldowns to Hero scripts; strictly use a Signal Bus or Callable bindings for decoupled architecture.
• NEVER evaluate exact floating-point equality (==); strictly use is_equal_approx() for range, cooldown, and mana validations.

Decision Tree: Solo prototype vs authoritative 5v5

🛠 Expert Components (scripts/)

Original Expert Patterns

• skill_shot_indicator.gd - Mouse-driven targeting system for range, width, and direction visualization.
• tower_priority_aggro.gd - Advanced AI for defensive towers following competitive priority rules. MANDATORY for tower dive/priority.

Modular Components

• server_minion_sync.gd - Authoritative sync for high-count units using compressed byte arrays. MANDATORY for 5v5 waves (not one synchronizer per minion).
• fog_visibility_check.gd - Physics raycasting for high-performance Line-of-Sight checks. MANDATORY before fog mask painting.
• fog_grid_mask.gd - TileMap-driven visibility masking system using Vector2i grid logic.
• minion_worker_pathfinder.gd - When to load: WorkerThreadPool path batches when wave size leaves _physics_process pathfinding. Prefer over per-minion full A* every frame.
• weighted_target_selector.gd - When to load: hero/minion/tower acquisition with group-weighted priority (AA and simple aggro). Pair with tower_priority for dive rules.
• synced_ability_controller.gd - When to load: QWER casts under authority — client predicts cooldown UI, server validates. Skip for offline prototypes.
• status_effect_data.gd - Lightweight Resource container for defining buffs, debuffs, and stuns.
• status_effect_manager.gd - Modular logic for applying and managing unique status effect instances.
• decoupled_ability_damage.gd - Inter-hero combat interaction using safe duck-typing patterns.
• hero_state_machine.gd - Optimized StringName-based state machine for hero logic.
• async_arena_baker.gd - Background thread-safe navigation mesh updates for dynamic arenas.
• ability_ui_binder.gd - Signal-based UI decoupling for ability cooldown tracking.
• minion_flow_calculator.gd - Parallelized pathing and intelligence using WorkerThreadPool.
• replay_manager.gd - Binary var_to_bytes match replay frames (not JSON).
• hero_net_sync.gd - Physics interpolation + MultiplayerSynchronizer hero sync at low tick.
• jungle_creep.gd - Camp leash FSM — invulnerable return home beyond leash_radius.

Core Loop

1. Lane: Player farms minions for gold/XP in a designated lane.
2. Trade: Player exchanges damage with opponent hero.
3. Gank: Player roams to other lanes to surprise enemies.
4. Push: Team destroys towers to open the map.
5. End: Destroy the enemy Core/Nexus.

Skill Chain

Architecture Overview

1. Lane / Minion Waves (authoritative)

Do not invent inline lane_manager / minion_ai samples.

MANDATORY reads: server_minion_sync.gd for batched wave state; minion_worker_pathfinder.gd when agent count needs WorkerThreadPool; weighted_target_selector.gd for march→combat target picks. Spawn cadence stays data/timer-driven on the server; clients render from sync arrays.

2. Tower Aggro Logic

Priority: Hero attacking Ally > unit attacking Ally Hero > closest minion > closest hero.

MANDATORY read: tower_priority_aggro.gd. Compose with weighted_target_selector.gd for group ranks.

3. Fog of War

MANDATORY read: fog_visibility_check.gd for nodeless LoS; paint results into fog_grid_mask.gd. Never use Area2D overlap as the fog oracle.

4. Skill-Shot Ability Cycle

Implementation pattern for "QWER" targeting:

1. Idle: Waiting for input.
2. Telegraphed: Show indicator (skill_shot_indicator.gd) while mouse is held.
3. Active: Spawn hitbox/projectile on release — under multiplayer, route through synced_ability_controller.gd.
4. Recovery: Brief backswing animation where movement/casting is locked.

Key Mechanics Implementation

Click-to-Move (RTS Style)

Raycasting from camera to terrain.

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("move"):
        var result = raycast_from_mouse()
        if result:
            nav_agent.target_position = result.position

Ability System (Data Driven)

Defining "Fireball" or "Hook" without unique scripts for everything.

# ability_data.gd
class_name Ability extends Resource
@export var cooldown: float
@export var mana_cost: float
@export var damage: float
@export var effect_scene: PackedScene

Godot-Specific Tips

• NavigationAgent3D: Use avoidance_enabled for minions so they flow around each other like water, rather than stacking.
• MultiplayerSynchronizer: Sync Health, Mana, and Cooldowns. Do NOT sync position every frame if using Client-Side Prediction (advanced).
• Fog of War: Use a SubViewport with a fog texture. Paint "holes" in the texture where allies are. Project this texture onto the terrain shader.