Public API

Enemy Masses Public API Reference

This document provides a reference for the common public methods available in the Enemy Masses system. The primary entry point for most operations is the EnemyMassesCrowdController MonoBehaviour, which exposes a static Instance for convenience when you have a single controller in the scene.

Core Controller Access

Most operations are performed through the EnemyMassesCrowdController instance. The class sets a static Instance in Awake, but this is not a hard-enforced singleton—adding multiple controllers will cause the last one to overwrite the static reference. Recommended: keep exactly one controller in the scene and use the static accessor for convenience.

// Access the singleton instance
EnemyMassesCrowdController controller = EnemyMassesCrowdController.Instance;

Spawning Agents

Methods for spawning agents into the world.

Spawn by Faction Index

/// <summary>
/// Spawns agents from a specific faction index.
/// </summary>
/// <param name="enemyCrowdIndex">Index of the faction in the EnemyCrowds list.</param>
/// <param name="spawnPosition">World position to spawn at.</param>
/// <param name="spawnRotation">Rotation of the spawn group.</param>
/// <param name="count">Number of agents to spawn.</param>
/// <param name="formation">Formation type (Circle, Square, etc.).</param>
/// <returns>List of spawned agent indices.</returns>
public List<int> SpawnEnemyCrowd(
    int enemyCrowdIndex, 
    Vector3 spawnPosition, 
    Quaternion spawnRotation, 
    int count, 
    FormationType formation = FormationType.Random
)

Spawn by Faction Name

/// <summary>
/// Spawns agents from a specific faction by name.
/// </summary>
/// <param name="factionName">Name of the faction (must match EnemyCrowd.factionName).</param>
/// <param name="spawnPosition">World position to spawn at.</param>
/// <param name="count">Number of agents to spawn.</param>
/// <param name="formation">Formation type.</param>
/// <returns>List of spawned agent indices.</returns>
public List<int> SpawnEnemyCrowdByName(
    string factionName, 
    Vector3 spawnPosition, 
    int count, 
    FormationType formation = FormationType.Random
)

Despawning & Killing Agents

Methods for removing agents from the world.

Kill/Despawn Single Agent

/// <summary>
/// Kills or despawns a specific agent.
/// </summary>
/// <param name="agentIndex">Index of the agent to kill.</param>
/// <param name="useRagdoll">If true, plays death animation/ragdoll. If false, instantly removes.</param>
public void KillAgent(int agentIndex, bool useRagdoll = true)

Clear All Agents

/// <summary>
/// Removes all agents from the scene immediately.
/// </summary>
public void ClearAllAgents()

Navigation & Movement

Methods for controlling agent movement.

Set Global Destination

/// <summary>
/// Sets a new destination for all agents.
/// </summary>
/// <param name="targetPosition">World position to move to.</param>
public void SetDestination(Vector3 targetPosition)

Set Faction Destination

/// <summary>
/// Sets a destination for agents from a specific faction.
/// </summary>
/// <param name="factionIndex">Index of the faction.</param>
/// <param name="targetPosition">World position to move to.</param>
/// <param name="useFormation">If true, arrange in formation. If false, all go to point.</param>
public void SetDestinationForFaction(
    int factionIndex, 
    Vector3 targetPosition, 
    bool useFormation = true
)

Healing & Health

Methods for restoring health to agents.

Heal Single Agent

/// <summary>
/// Heals a specific agent.
/// </summary>
/// <param name="agentIndex">Index of the agent to heal.</param>
/// <param name="healAmount">Amount of health to restore.</param>
/// <returns>True if agent was found and healed.</returns>
public bool HealAgent(int agentIndex, float healAmount)

Heal Agents in Radius (AOE)

/// <summary>
/// Heals all agents within a radius.
/// </summary>
/// <param name="center">Center position of the heal area.</param>
/// <param name="radius">Radius of the heal area.</param>
/// <param name="healAmount">Amount of health to restore.</param>
/// <param name="targetFactionIndex">Optional: Only heal agents of this faction.</param>
/// <returns>Number of agents healed.</returns>
public int HealAgentsInRadius(
    Vector3 center, 
    float radius, 
    float healAmount, 
    int? targetFactionIndex = null
)

Status Effects

The Status Effect System allows applying buffs, debuffs, and crowd control effects.

Accessing the System

StatusEffectSystem statusSystem = EnemyMassesCrowdController.Instance.GetStatusEffectSystem();

Apply Effect (Runtime)

/// <summary>
/// Applies a status effect to an agent.
/// </summary>
/// <param name="agent">The target CrowdAgent.</param>
/// <param name="type">Type of effect (e.g., Stun, Slow, Burn).</param>
/// <param name="duration">Duration in seconds.</param>
/// <param name="value">Magnitude of the effect (e.g., damage amount, speed multiplier).</param>
/// <returns>Slot index where effect was applied, or -1 if failed.</returns>
public int ApplyEffect(
    CrowdAgent agent, 
    StatusEffectType type, 
    float duration, 
    float value
)

Remove/Dispel Effects

// Remove specific effect slot
statusSystem.RemoveEffect(agent, slotIndex);

// Dispel all negative effects
statusSystem.DispelNegativeEffects(agent);

// Dispel all positive effects
statusSystem.DispelPositiveEffects(agent);

Civil AI

Methods for toggling agents between Combat and Civil modes.

Enable Civil Mode

/// <summary>
/// Converts an agent to Civil mode, making them follow waypoints.
/// </summary>
/// <param name="agentIndex">Index of the agent.</param>
/// <param name="startWaypoint">Optional: Waypoint to start at.</param>
/// <returns>True if successful.</returns>
public bool EnableAgentCivilMode(int agentIndex, CivilWaypointNode startWaypoint = null)

Disable Civil Mode

/// <summary>
/// Converts an agent back to Combat mode.
/// </summary>
/// <param name="agentIndex">Index of the agent.</param>
/// <returns>True if successful.</returns>
public bool DisableAgentCivilMode(int agentIndex)

Spawn Civil Agent

/// <summary>
/// Spawns a new agent directly into Civil mode at a waypoint.
/// </summary>
/// <param name="agentIndex">Index of an existing agent to convert (or spawn new if integrated).</param>
/// <param name="spawnWaypoint">Waypoint to spawn at.</param>
public void SpawnCivilAgent(int agentIndex, CivilWaypointNode spawnWaypoint)

Despawn Civil Agent

/// <summary>
/// Despawns a civil agent with a fade-out effect.
/// </summary>
/// <param name="agentIndex">Index of the agent.</param>
public void DespawnCivilAgent(int agentIndex)

Other Important Methods

Get Active Agents

/// <summary>
/// Returns the list of all currently managed agents.
/// </summary>
public List<CrowdAgent> GetAgents()

Global Damage Multipliers

// Adjust global incoming damage (e.g., for difficulty settings)
controller.IncomingDamageMultiplier = 1.5f; // Agents take 50% more damage

// Adjust damage from player
controller.PlayerDamageMultiplier = 0.5f; // Player deals 50% less damage

Events

// Event fired when an agent is killed
controller.EventAgentKilled += (gpuInstance) => { ... };

// Event fired when player is hit
controller.EventPlayerTargetHit += (attacker, position, target, damage, hitPoint, isMelee) => { ... };