RTS UI Components

RTS UI Components

Enemy Masses provides specialized UI components for displaying agent health bars, status effects, and integrating with the crowd system's health events. These components are designed for RTS and strategy games where you need to visualize the state of selected units or all units on the battlefield.

---

EnemyMassesRTSHealthBarUI

The EnemyMassesRTSHealthBarUI component displays health bars for Enemy Masses agents, supporting both individual unit displays and aggregated averages. It automatically reacts to selection changes and health events for optimal performance.

Quick Setup

1. Create a Canvas in your scene (if you don't have one)

2. Create an empty GameObject as a child of the Canvas

3. Add the EnemyMassesRTSHealthBarUI component

4. Create a UI Slider to use as the health bar template

5. Assign the Slider to the Health Bar Prefab field

Canvas
└── HealthBarPanel (with EnemyMassesRTSHealthBarUI)
    └── HealthBarTemplate (Slider - will be cloned)

The component automatically finds the EnemyMassesRTSController and EnemyMassesCrowdController in your scene if not explicitly assigned.

Display Modes

Display Scope

Mode	Description
Selected Agents Only	Show health bars only for currently selected agents
Always	Show health bars for all agents (respects faction filter)

Display Mode

Mode	Description
Individual Agents	One health bar per agent
Average	Aggregated health bars based on grouping

Average Grouping

When using Average display mode:

Grouping	Description
Combined	Single bar showing average of all visible agents
EnemyCrowd	One bar per faction/type (EnemyCrowd asset)
SpawnGroup	One bar per spawn group

Settings Reference

References

Setting	Description
RTS Controller	Reference to selection controller (auto-resolved)
Crowd Controller	Reference to crowd controller (auto-resolved)
Health Bar Prefab	UI Slider template to clone for each bar
Health Bar Container	Parent transform for spawned bars

Display Settings

Setting	Description	Default
Display Scope	When to show bars	Selected Agents Only
Display Mode	Individual or averaged	Individual Agents
Average Grouping	How to group averages	Combined
Include Dead Agents	Show bars for dead agents	false
Include Dead Agents In Average	Include 0-health agents in calculations	true
Preserve Dead Selection In Average	Keep dead agents in average so it doesn't jump up	true
Faction Filter	Filter by player-controlled factions	All
Max Bars	Limit number of bars (0 = unlimited)	50

Update & Performance

Setting	Description	Default
Update Interval	Seconds between UI refreshes	0.1
Use Aggregate Cache	Event-driven health tracking for averages	true
Aggregate Resync Interval	Seconds between full cache rebuilds	1.0
Hide Template At Runtime	Disable the template Slider in scene	true

Colors

Setting	Description	Default
Full Health Color	Color at 100% health	Green
Mid Health Color	Color at mid health	Yellow
Low Health Color	Color at low health	Red
Mid Health Threshold	Percent to switch to mid color	0.6
Low Health Threshold	Percent to switch to low color	0.3

Labels

Setting	Description	Default
Show Labels	Display text labels on bars	false
Label Child Path	Path to find Text component in slider	"Label"
Combined Label	Label for combined averages	"Combined"
Selected Label	Label for selection averages	"Selected"
Enemy Crowd Label Format	Format for faction bars	"{faction} {type} ({index})"
Spawn Group Label Format	Format for spawn group bars	"Spawn Group {group}"
Agent Label Format	Format for individual bars	"Agent {index}"

Label Tokens:

• {faction} - Faction name from EnemyCrowd

• {type} - Enemy type name from EnemyCrowd

• {index} - Agent index

• {group} - Spawn group ID

Creating the Health Bar Template

Your health bar Slider should have:

1. Background - The unfilled portion

2. Fill Area > Fill - The filled portion (colored by component)

3. Label (optional) - A Text component for labels

HealthBarSlider (Slider)
├── Background (Image)
├── Fill Area
│   └── Fill (Image) ← Component controls this color
└── Label (Text) ← Optional, for labels

Set the Slider's Interactable to false since it's display-only. The component will control the value and fill color automatically.

Faction Filtering

Filter which agents' health is displayed:

Filter	Description
All	Show all agents
Player Controlled Only	Only show agents from player-controlled factions
Non Player Only	Only show enemy/neutral agents

Faction filtering requires your EnemyMassesRTSController to have Player Controlled Factions configured.

---

EnemyMassesRTSStatusEffectUI

The EnemyMassesRTSStatusEffectUI component displays active status effects (buffs, debuffs, DoTs, crowd control) on agents. Perfect for showing what's affecting your selected units.

Quick Setup

1. Create a UI container (Panel or empty GameObject under Canvas)

2. Add the EnemyMassesRTSStatusEffectUI component

3. Create a status effect entry prefab with an Image and optional Text

4. Assign the prefab to Status Effect Prefab

Canvas
└── StatusEffectPanel (with EnemyMassesRTSStatusEffectUI)
    └── StatusEffectEntry (prefab template)
        ├── Icon (Image)
        └── Label (Text, optional)

Settings Reference

References

Setting	Description
RTS Controller	Reference to selection controller (auto-resolved)
Crowd Controller	Reference to crowd controller (auto-resolved)
Status Effect Prefab	Template GameObject to clone per effect
Status Effect Container	Parent transform for spawned entries

Display Settings

Setting	Description	Default
Display Scope	When to show effects	Selected Agents Only
Faction Filter	Filter by player-controlled factions	All
Include Dead Agents	Show effects on dead agents	false
Max Items	Limit number of entries (0 = unlimited)	100

Category Filters

Setting	Description	Default
Show Crowd Control	Display stuns, slows, roots, etc.	true
Show Damage Over Time	Display poison, burn, bleed, etc.	true
Show Debuffs	Display armor break, weaken, etc.	true
Show Buffs	Display regeneration, damage buff, etc.	true

Icons

Setting	Description	Default
Icon Child Path	Path to find Image in entry prefab	"Icon"
Fallback To Any Image	Use first Image if path not found	true
Icon Overrides	Per-effect-type custom icons	(empty list)
Default Buff Icon	Fallback icon for buffs	-
Default Debuff Icon	Fallback icon for debuffs	-
Default Dot Icon	Fallback icon for DoTs	-
Default Crowd Control Icon	Fallback icon for CC effects	-

Colors

Setting	Description	Default
Colorize Icons	Tint icons by category	true
Colorize Labels	Tint labels by category	false
Buff Color	Color for buff effects	Green
Debuff Color	Color for debuff effects	Red
Dot Color	Color for DoT effects	Orange
Crowd Control Color	Color for CC effects	Yellow

Labels

Setting	Description	Default
Show Labels	Display text labels	true
Label Child Path	Path to find Text in entry prefab	"Label"
Label Format	Format string for labels	"{effect} {remaining}"
Show Stacks	Show stack count in label	true
Show Stacks Only When Stacked	Hide "x1" stacks	true
Show Remaining Time	Show time remaining	true
Remaining Time Format	Numeric format	"0.#"
Remaining Time Suffix	Suffix after time	"s"
Permanent Label	Text for permanent effects	"Permanent"

Label Tokens:

• {effect} - Effect name (e.g., "Poison", "Stun")

• {category} - Category name (e.g., "DamageOverTime")

• {stacks} - Stack count

• {remaining} - Time remaining with suffix

• {agent} - Agent index

• {faction} - Faction name

• {type} - Enemy type name

Status Effect Categories

The system organizes effects into four categories:

Category	Examples	Description
Crowd Control	Stun, Freeze, Sleep, Fear, Slow, Root	Disable or impair actions
Damage Over Time	Poison, Burn, Bleed, Curse	Periodic damage
Debuff	Armor Break, Weaken, Vulnerable	Stat reductions
Buff	Regeneration, Damage Buff, Shield	Stat increases

Creating Custom Icon Overrides

To use custom icons for specific effects:

1. In the Inspector, expand Icon Overrides

2. Click + to add an entry

3. Select the Effect Type (e.g., Poison, Stun)

4. Assign your custom Sprite

[System.Serializable]
public class StatusEffectIconOverride
{
    public StatusEffectType effectType;
    public Sprite icon;
}

---

RTSSelectionCommandPanel

The RTSSelectionCommandPanel is a command interface that appears when player-controlled units are selected. It provides buttons for combat stances (Offensive, Defensive, Hold Position) and a Stop command, with support for strict/non-strict modes.

Quick Setup

1. Create a UI Panel under your Canvas

2. Add the RTSSelectionCommandPanel component

3. Create buttons for each command (Offensive, Defensive, Hold, Stop)

4. Optionally add a Toggle for Strict Mode

5. Wire up the references in the Inspector

Canvas
└── CommandPanel (with RTSSelectionCommandPanel)
    ├── StrictModeToggle (Toggle)
    ├── OffensiveButton (Button)
    ├── DefensiveButton (Button)
    ├── HoldButton (Button)
    └── StopButton (Button)

The panel automatically shows/hides based on whether player-controlled units are selected (configurable via Auto Hide When No Player Selection).

Combat Stances Explained

Stance	Non-Strict Behavior	Strict Behavior
Offensive	Actively seeks enemies, helps allies under attack	Actively seeks enemies, ignores ally calls for help
Defensive	Only attacks when attacked, helps allies	Only attacks when attacked, ignores allies
Hold Position	Stays in place, attacks nearby enemies, helps allies	Stays in place, attacks nearby enemies, ignores allies

Strict Mode is useful when you want precise control over unit behavior. Non-strict mode creates more realistic "army" behavior where units support each other.

Settings Reference

References

Setting	Description
RTS Controller	The RTS controller to receive commands
Panel Root	Root GameObject to show/hide

UI Elements

Setting	Description
Strict Mode Toggle	Toggle for strict/non-strict stance mode
Offensive Strict Button	Button for Offensive stance
Defensive Strict Button	Button for Defensive stance
Hold Strict Button	Button for Hold Position stance
Stop Button	Button to cancel current actions

Visual Customization

Setting	Description	Default
Button Normal Color	Default button color	Dark blue-gray
Button Hover Color	Color when hovering	Lighter blue-gray
Button Pressed Color	Color when clicked	Bright blue
Button Selected Color	Color for active stance	Cyan
Button Disabled Color	Color when disabled	Very dark

Audio

Setting	Description
Offensive Click Sfx	Sound when clicking Offensive
Defensive Click Sfx	Sound when clicking Defensive
Hold Click Sfx	Sound when clicking Hold Position
Stop Click Sfx	Sound when clicking Stop
Strict On Sfx	Sound when enabling Strict Mode
Strict Off Sfx	Sound when disabling Strict Mode
Command Audio Source	Optional AudioSource for playback
Command Sfx Pitch Variation	Random pitch variation (0-0.5)

Behavior

Setting	Description	Default
Auto Hide When No Player Selection	Hide panel when no player units selected	true
Stop Resets To Offensive	Stop also resets units to Offensive stance	true

How It Works

1. Selection Detection: The panel subscribes to SelectionChanged events from the RTS controller

2. Filtering: Only responds to player-controlled units (based on playerControlledFactions)

3. Visual Feedback: Highlights the button matching the majority stance of selected units

4. Command Dispatch: Button clicks call the appropriate method on the RTS controller

Post-Combat Reformation

When switching stances during combat, the panel automatically enables post-combat reformation:

• Units that break formation to chase enemies will return to formation after combat

• Switching from Strict to Non-Strict mode triggers reformation tracking

• This creates realistic "units regroup after a skirmish" behavior

Scripting the Command Panel

// Get reference to the panel
RTSSelectionCommandPanel panel = FindObjectOfType<RTSSelectionCommandPanel>();

// Show/hide programmatically
panel.gameObject.SetActive(true);

// The panel automatically updates when selection changes
// You can also directly call RTS controller methods:
rtsController.SetSelectedAgentsOffensive();
rtsController.SetSelectedAgentsDefensive();
rtsController.SetSelectedAgentsHoldPosition();
rtsController.SetSelectedAgentsOffensiveStrict();
rtsController.SetSelectedAgentsDefensiveStrict();
rtsController.SetSelectedAgentsHoldPositionStrict();
rtsController.StopSelectedAgents();

Creating Custom Command Buttons

To add your own command buttons:

public class CustomCommandButton : MonoBehaviour
{
    public EnemyMassesRTSController rtsController;
    public Button retreatButton;

    private void Start()
    {
        retreatButton.onClick.AddListener(OnRetreatClicked);
    }

    private void OnRetreatClicked()
    {
        // Custom command: move selected units to a retreat point
        Vector3 retreatPoint = GetRetreatPoint();
        rtsController.MoveSelectedToPosition(retreatPoint);
        rtsController.SetSelectedAgentsDefensive(); // Switch to defensive while retreating
    }
}

---

Health-Driven UI Events

The EnemyMassesCrowdController exposes events that fire when agent health changes, enabling you to build custom UI or trigger game logic.

Available Events

// Fired when any agent's health changes
public event Action<int, float, float> EventAgentHealthChanged;
// Parameters: (agentIndex, newHealth, maxHealth)

// Fired when an agent is killed
public event Action<GPUICrowdInstance> EventAgentKilled;
// Parameters: (crowdInstance)

// Fired when an agent hits the player target
public event Action<CrowdAgent, Vector3, Transform, float, Vector3, bool> EventPlayerTargetHit;
// Parameters: (attacker, attackerPosition, target, damage, hitPoint, isMelee)

Subscribing to Health Events

using Arawn.EnemyMasses.Runtime;
using UnityEngine;

public class CustomHealthUI : MonoBehaviour
{
    public EnemyMassesCrowdController crowdController;

    private void OnEnable()
    {
        if (crowdController != null)
        {
            crowdController.EventAgentHealthChanged += OnAgentHealthChanged;
            crowdController.EventAgentKilled += OnAgentKilled;
        }
    }

    private void OnDisable()
    {
        if (crowdController != null)
        {
            crowdController.EventAgentHealthChanged -= OnAgentHealthChanged;
            crowdController.EventAgentKilled -= OnAgentKilled;
        }
    }

    private void OnAgentHealthChanged(int agentIndex, float newHealth, float maxHealth)
    {
        float healthPercent = newHealth / maxHealth;
        Debug.Log($"Agent {agentIndex} health: {healthPercent:P0}");
        
        // Example: Spawn damage numbers
        // Example: Update world-space health bar
        // Example: Trigger low-health warning
    }

    private void OnAgentKilled(GPUICrowdInstance instance)
    {
        Debug.Log($"Agent killed: {instance}");
        
        // Example: Update kill counter
        // Example: Award XP
        // Example: Spawn loot
    }
}

Performance Considerations

The EventAgentHealthChanged event fires every time any agent's health changes. With thousands of agents, this can fire very frequently. Use the event for:

• UI updates (with rate limiting)

• Tracking specific agents

• Spawning effects on health thresholds

For aggregate statistics, use EnemyMassesRTSHealthBarUI's built-in Aggregate Cache which batches updates efficiently.

Example: Damage Numbers

public class DamageNumberSpawner : MonoBehaviour
{
    public EnemyMassesCrowdController crowdController;
    public GameObject damageNumberPrefab;

    private Dictionary<int, float> _lastHealth = new Dictionary<int, float>();

    private void OnEnable()
    {
        crowdController.EventAgentHealthChanged += OnHealthChanged;
    }

    private void OnDisable()
    {
        crowdController.EventAgentHealthChanged -= OnHealthChanged;
    }

    private void OnHealthChanged(int agentIndex, float newHealth, float maxHealth)
    {
        // Calculate damage dealt
        if (!_lastHealth.TryGetValue(agentIndex, out float lastHealth))
        {
            lastHealth = maxHealth;
        }

        float damage = lastHealth - newHealth;
        _lastHealth[agentIndex] = newHealth;

        if (damage > 0)
        {
            // Spawn damage number
            var agents = crowdController.GetAgents();
            if (agentIndex < agents.Count)
            {
                Vector3 position = agents[agentIndex].position + Vector3.up * 2f;
                SpawnDamageNumber(position, damage);
            }
        }
    }

    private void SpawnDamageNumber(Vector3 position, float damage)
    {
        var instance = Instantiate(damageNumberPrefab, position, Quaternion.identity);
        // Configure damage number display...
    }
}

Example: Kill Counter

public class KillTracker : MonoBehaviour
{
    public EnemyMassesCrowdController crowdController;
    public TMPro.TextMeshProUGUI killCountText;

    private int _killCount = 0;

    private void OnEnable()
    {
        crowdController.EventAgentKilled += OnAgentKilled;
        UpdateUI();
    }

    private void OnDisable()
    {
        crowdController.EventAgentKilled -= OnAgentKilled;
    }

    private void OnAgentKilled(GPUICrowdInstance instance)
    {
        _killCount++;
        UpdateUI();
    }

    private void UpdateUI()
    {
        killCountText.text = $"Kills: {_killCount}";
    }
}

---

Best Practices

Health Bar UI

1. Use Aggregate Cache - Enable Use Aggregate Cache for average mode to avoid per-frame calculations

2. Limit Max Bars - Set Max Bars to prevent performance issues with large selections

3. Tune Update Interval - Increase Update Interval (e.g., 0.2s) if UI updates feel expensive

4. Preserve Dead Selection - Enable to prevent average jumping when agents die

Status Effect UI

1. Filter Categories - Disable categories you don't use to reduce noise

2. Use Icon Overrides - Custom icons improve readability over color-coding alone

3. Show Remaining Time - Helps players plan around effect durations

4. Limit Max Items - Large battles can have hundreds of effects; limit display

Event Subscriptions

1. Always Unsubscribe - Remove event handlers in OnDisable() to prevent memory leaks

2. Rate Limit Updates - Don't update UI on every health change; batch updates

3. Cache Agent Data - Store previous health values to calculate damage deltas

4. Null Check Controllers - Events fire during cleanup; check references aren't null

---

Related Components

• EnemyMassesRTSController - Unit selection and commands

• RTSCameraController - Camera controls

• Status Effect System - Applying and managing status effects