Enemy Masses RTS Controller

Enemy Masses RTS Controller

The EnemyMassesRTSController is the core component for player interaction in an RTS game built with Enemy Masses. It handles unit selection, movement commands, formations, attack orders, and waypoint patrol paths. It is designed to work seamlessly with the EnemyMassesCrowdController to manage thousands of units efficiently.

---

Features

Selection System

• Click Selection: Select individual units with a single click

• Double-Click Selection: Select all units of the same type/faction on screen

• Drag Selection: Classic RTS box selection for grouping units

• Additive Selection: Hold Shift to add units to the current selection

Command System

• Move Commands: Right-click to move selected units to a destination

• Attack Commands: Right-click on an enemy unit to order an attack

• Formations: Units automatically arrange themselves in formations at the destination

Advanced Formation Control

• Drag-to-Adjust Spacing: Hold the command button and drag horizontally to adjust formation spacing before issuing the move order

• Formation Rotation: Hold both command and selection buttons to rotate formation facing direction

• Ghost Preview: Visualizes the formation shape and position before committing to the move

• Formation Cycling: Scroll wheel or hotkey to cycle through formation types while previewing

Waypoint Patrol System

• Queue Waypoints: Hold the queue modifier (Shift) while clicking to build patrol paths

• Loop Closing: Click near the first waypoint to create a patrol loop

• Ping-Pong Paths: Non-looped paths automatically reverse when reaching the end

• Combat Awareness: Patrols auto-pause during combat and resume after combat ends

• Visual Feedback: Waypoint markers and connecting lines (blue paths, green loops)

• Formation-Aware: Patrol movement respects formation type and spacing

Additional Features

• Faction Control: Restrict selection and commands to specific player-controlled factions

• Fog of War Integration: Automatically hides non-player units when not visible

• Group Bookmarks: Save and recall unit groups with number keys (0-9)

• Input System Support: Fully supports Unity's New Input System and legacy Input Manager

---

Getting Started

1. Create an empty GameObject or use your existing "GameController" object

2. Add the EnemyMassesRTSController component

3. Assign the Crowd Controller reference (if not automatically found)

4. Assign the Target Camera (usually your Main Camera)

5. (Optional) Assign the Minimap Controller to prevent accidental deselection when clicking on the minimap

The controller automatically finds the EnemyMassesCrowdController and Camera.main if not explicitly assigned.

---

Key Settings

1. Selection Settings

Setting	Description	Default
Enable Click Selection	Toggles single-click selection	true
Enable Double Click Group Selection	Select all same-type units on double-click	true
Enable Drag Selection	Toggles box selection	true
Double Click Time	Time window for double-click detection	0.3s
Min Drag Distance	Pixels before drag selection starts	5
Agent Selection Mask	Layer mask for selectable objects	Everything

2. Command Settings

Setting	Description	Default
Enable Move Commands	Toggles right-click movement	true
Ground Mask	Layer mask for NavMesh/ground raycasts	Everything
Move Formation	Default formation type	Rectangle
Formation Spacing	Distance between units	1.5
Match Formation Speed To Slowest	Sync speed to slowest unit	false

3. Formation Settings

Setting	Description	Default
Enable Formation Cycling	Cycle formations while previewing	true
Use Mouse Scroll Wheel For Formation Cycle	Scroll to change formation	false
Enable Drag To Adjust Spacing	Drag to adjust density	true
Enable Rotation Adjustment	Drag to rotate formation	true

4. Input Settings

The controller supports both input systems:

New Input System:

• Rebind Selection Button (Left Click), Command Button (Right Click), and modifiers directly in the Inspector

• Uses InputAction bindings

Legacy Input:

• Uses standard mouse button indices (0, 1, 2) and KeyCodes

5. Visual Settings

Setting	Description
Selection Rectangle Color	Color of the drag selection box
Selection Rectangle Border Color	Border color of the drag box
Move Indicator Prefab	Visual marker for move commands
Selection Indicator Prefab	Highlight ring under selected units
Ghost Formation Prefab	Preview marker for formation positions

6. Group Bookmarks

• Select your agents, then hold the Control Group Save Modifier key and press 0-9

• Press the group key to recall that selection

• Double-press the group key to focus the camera on the group

---

Waypoint Patrol System

The patrol system allows you to create waypoint paths that units will continuously follow, with automatic combat handling and formation-aware movement.

Creating Patrol Paths

1. Select Units: Click or drag-select the units you want to patrol

2. Start Queuing: Hold the Queue Modifier (default: Left Shift)

3. Add Waypoints: While holding the modifier, click to add waypoints

4. Visualize Path: Blue lines connect waypoints as you add them

5. Complete Path: Either release the modifier (creates ping-pong path) or close the loop

Click near the first waypoint to close the loop and create a continuous patrol circuit. The loop closing distance is configurable via Patrol Loop Close Distance.

Patrol Path Types

Type	Behavior	Visual
Loop	Units patrol in a continuous circuit	Green connecting lines
Ping-Pong	Units patrol back and forth between waypoints	Blue connecting lines

Combat Behavior

When units on patrol enter combat:

1. Pause: The patrol is automatically paused

2. Combat Position: The interrupt position is stored

3. Fight: Units engage enemies normally

4. Resume: After combat ends, units resume patrol from current waypoint

Units resume patrol automatically after clearing enemies. They don't return to the interrupt position—they continue from where they are toward the next waypoint.

Formation-Aware Patrols

Patrol paths store formation data for each agent:

Data	Description
formationIndex	Agent's position in formation (0, 1, 2, ...)
formationTotalCount	Total agents in the patrol group
formationType	Formation type (Rectangle, Line, etc.)
formationSpacing	Spacing between agents

This means units maintain proper formation spacing at each waypoint, not clumping together.

Waypoint Patrol Settings

Setting	Description	Default
Enable Waypoint Patrol	Enable the patrol system	true
Waypoint Queue Modifier	Key to hold for queuing (New Input System)	Left Shift
Waypoint Queue Modifier Key	Key for queuing (Legacy Input)	LeftShift
Patrol Loop Close Distance	Distance to first waypoint to close loop	5
Show Waypoint Markers	Display markers at waypoints	true
Waypoint Marker Prefab	Prefab for waypoint markers	-
Waypoint Marker Offset	World-space offset for markers	(0, 0.1, 0)
Show Waypoint Lines	Draw lines connecting waypoints	true
Waypoint Line Color	Color for path lines	Blue
Waypoint Line Width	Width of path lines	0.15
Patrol Loop Line Color	Color for looped path lines	Green
Max Waypoints Per Path	Maximum waypoints allowed	20

Patrol APIs

// Check if an agent has an active patrol path
bool isPatrolling = rtsController.HasPatrolPath(agentIndex);

// Get the patrol path for an agent (returns null if none)
AgentPatrolPath path = rtsController.GetPatrolPath(agentIndex);
if (path != null)
{
    Debug.Log($"Waypoints: {path.waypoints.Count}");
    Debug.Log($"Is Loop: {path.isLoop}");
    Debug.Log($"Current Waypoint: {path.currentWaypointIndex}");
    Debug.Log($"Formation Index: {path.formationIndex} / {path.formationTotalCount}");
}

// Clear a specific agent's patrol path
rtsController.ClearPatrolPath(agentIndex);

AgentPatrolPath Class

[Serializable]
public class AgentPatrolPath
{
    public List<Vector3> waypoints;      // All waypoint positions
    public int currentWaypointIndex;     // Current target waypoint
    public bool isLoop;                  // True if patrol loops
    public bool isReversing;             // True if ping-ponging backward
    public bool isPaused;                // True if paused for combat
    public Vector3 combatInterruptPosition; // Position when combat started
    
    // Formation data
    public int formationIndex;           // This agent's index in formation
    public int formationTotalCount;      // Total agents in patrol group
    public FormationType formationType;  // Formation type
    public float formationSpacing;       // Spacing between agents
    
    public Vector3 CurrentWaypoint { get; }
    public Vector3 GetNextWaypoint();
    public void Reset();
}

---

Advanced Usage

Formation Dragging

This feature gives players precise control over unit positioning:

1. Select a group of units

2. Hold Right-Click (Command Button) at the target location

3. Drag Mouse Horizontally:

   • Ghost markers appear showing where units will go

   • Dragging expands or contracts formation spacing

4. Release Right-Click: Units move to the previewed positions

Formation Rotation

To face units in a specific direction:

1. Select units

2. Hold Right-Click (Command Button)

3. Hold Left-Click (Selection Button) while holding Right-Click

4. Drag Mouse: The formation rotates around its center

5. Release: Units move and rotate to face the new direction

Attack Targeting

Setting	Description
Attack Target Mask	Ensure this includes layers your enemy units are on
Attack Target Click Radius	Since thousands of units might not have individual colliders, this radius helps detect clicks "near" a unit to register an attack command

---

Scripting Examples

Basic Selection and Commands

using Arawn.EnemyMasses.Runtime;
using UnityEngine;

public class RTSCommandExample : MonoBehaviour
{
    public EnemyMassesRTSController rtsController;

    void Update()
    {
        // Get currently selected agents
        List<int> selected = rtsController.GetSelectedAgentIndices();
        Debug.Log($"Selected: {selected.Count} units");
        
        // Programmatically move selected units
        if (Input.GetKeyDown(KeyCode.M))
        {
            Vector3 targetPosition = GetMouseWorldPosition();
            rtsController.MoveSelectedToPosition(targetPosition);
        }
        
        // Change formation
        if (Input.GetKeyDown(KeyCode.F))
        {
            rtsController.moveFormation = FormationType.Circle;
        }
    }
}

Listening to Selection Events

public class SelectionUI : MonoBehaviour
{
    public EnemyMassesRTSController rtsController;
    public TMPro.TextMeshProUGUI selectionCountText;

    void OnEnable()
    {
        rtsController.SelectionChanged += OnSelectionChanged;
    }

    void OnDisable()
    {
        rtsController.SelectionChanged -= OnSelectionChanged;
    }

    void OnSelectionChanged(SelectionChangedEventData data)
    {
        selectionCountText.text = $"Selected: {data.totalSelected}";
        
        // React to selection changes
        foreach (int index in data.newlySelected)
        {
            Debug.Log($"Newly selected: Agent {index}");
        }
    }
}

Custom Patrol Path Creation

public class PatrolAssigner : MonoBehaviour
{
    public EnemyMassesRTSController rtsController;
    public Transform[] patrolWaypoints;

    public void AssignPatrolToSelection()
    {
        // Note: The RTS Controller handles patrol path creation internally
        // through user input. For scripted patrols, you would use the
        // crowd controller's AI systems directly.
        
        // Check existing patrol paths:
        var selectedAgents = rtsController.GetSelectedAgentIndices();
        foreach (int agentIndex in selectedAgents)
        {
            if (rtsController.HasPatrolPath(agentIndex))
            {
                AgentPatrolPath path = rtsController.GetPatrolPath(agentIndex);
                Debug.Log($"Agent {agentIndex} has {path.waypoints.Count} waypoints");
            }
        }
    }
    
    public void ClearAllPatrols()
    {
        var selectedAgents = rtsController.GetSelectedAgentIndices();
        foreach (int agentIndex in selectedAgents)
        {
            rtsController.ClearPatrolPath(agentIndex);
        }
    }
}

---

Events Reference

Event	Parameters	Description
SelectionChanged	SelectionChangedEventData	Fires when selection changes
onAgentSelected	int agentIndex	Single agent selected
onAgentDeselected	int agentIndex	Single agent deselected
onSelectionCleared	-	All agents deselected
MoveCommandIssued	Vector3 position, List<int> agents	Move command sent
onMoveCommandIssued	Vector3 position, List<int> agents	UnityEvent version

---

Integration Tips

Fog of War

• Enable Render Above Fog to ensure destination indicators display above the fog plane

• Set Indicator Sorting Order for proper layering

Minimap Integration

• Assign your RTSMinimapController to prevent deselection when clicking on the minimap

• The controller automatically detects minimap clicks and ignores them for selection

Performance with Large Selections

• Use Max Indicator Prefabs to limit selection highlights (20-100 for VFX, 500-2000 for lightweight UI)

• Enable Shader Highlight for efficient selection visualization without spawning prefabs

• The waypoint system efficiently handles thousands of agents with formation-aware pathing

---

Related Components

• RTSCameraController - Camera controls for RTS games

• RTS UI Components - Health bars, status effects, and command panels

• EnemyMassesCrowdController - Core crowd management