Animal Simulation HerdSim

About Animal Simulation HerdSim – Unity Editor Tool & Plugin

Animal Simulation HerdSim Unity Asset Overview

The Animal Simulation HerdSim framework relies on a modified variant of Craig Reynolds' classic Boids flocking algorithm, extended specifically for ground-based and aerial animal traversal within Unity environments. At its core, the system calculates steering vectors for individual entities by combining three primary behaviors—Separation, Alignment, and Cohesion—with specialized secondary behaviors such as terrain alignment, predator avoidance, and waypoint navigation.

Core Architecture & Data Flow

Unlike simple Boids implementations that iterate over all dynamic transforms via direct Transform.position reads, HerdSim utilizes localized manager classes (e.g., HerdSimController) to cache positional data and reduce internal engine calls. The simulation loop processes movement in distinct phases:

• Spatial Query Phase: Evaluates neighboring entities using distance checks or spatial hashing grids rather than standard physics overlays to avoid unnecessary Physics.OverlapSphere overhead.
• Steering Calculation Phase: Combines active force vectors weighted by exposed configuration values (e.g., cohesionWeight, separationWeight, obstacleWeight).
• Movement & Surface Adaptation Phase: Applies calculated translation vectors through character controllers or manual Raycast sampling against terrain layer masks.

To reduce garbage collection allocations, array resizing is constrained at runtime. Agent states are stored in flat, pre-allocated memory structures, minimizing heap allocations during high-count entity processing.

Extending Behavior via C#

Developers looking to inject custom AI states (such as eating, fleeing, or resting) into the simulation loop can interface directly with the agent event system. The following C# code demonstrates how to override the default steering target when a custom environmental threat enters an agent's sensing zone:

using UnityEngine;

namespace HerdSim.Extensions
{
    [RequireComponent(typeof(HerdSimAgent))]
    public class ThreatAvoidanceOverride : MonoBehaviour
    {
        private HerdSimAgent _agent;
        [SerializeField] private LayerMask _threatLayerMask;
        [SerializeField] private float _detectionRadius = 15.0f;
        [SerializeField] private float _fleeForceMultiplier = 2.5f;

        private void Awake()
        {
            _agent = GetComponent<HerdSimAgent>();
        }

        private void Update()
        {
            EvaluateThreats();
        }

        private void EvaluateThreats()
        {
            Collider[] threats = Physics.OverlapSphere(transform.position, _detectionRadius, _threatLayerMask);
            if (threats.Length > 0)
            {
                Vector3 averageThreatPos = Vector3.zero;
                for (int i = 0; i < threats.Length; i++)
                {
                    averageThreatPos += threats[i].transform.position;
                }
                averageThreatPos /= threats.Length;

                Vector3 fleeDirection = (transform.position - averageThreatPos).normalized;
                _agent.SetCustomSteeringVector(fleeDirection * _fleeForceMultiplier);
                _agent.SetState(HerdAgentState.Fleeing);
            }
        }
    }
}

Inspector Configuration & Workflow

The standard editor integration provides custom Inspector inspectors designed to simplify herd composition and behavior tuning without forcing developers to modify underlying codebase defaults. Parameters are logically segmented across global flock controllers and individual agent overrides.

Key Inspector Parameters

When selecting a HerdSimController instance in the Unity Inspector, several critical properties dictate overall crowd density and stability:

• Min/Max Flock Count: Defines the upper bound of active pooled instances instantiated upon runtime initialization.
• Target Spatial Radius: Controls the spatial extent within which agents search for valid target waypoints.
• Terrain Normal Alignment: A floating-point slider balancing upright world orientation against local terrain angle pitch.
• Ground Layer Mask: Restricts downward probing raycasts to designated ground colliders, preventing agents from snapping to non-traversable geometry.

Scene Gizmos and Visual Debugging

Visual debugging features display realtime direction vectors and spatial boundaries inside the Scene View. When selected, agents draw gizmos indicating current velocity vectors, target vectors, ground raycast hit points, and neighbor detection perimeters. This allows for rapid iteration when troubleshooting flock bundling, erratic turning, or terrain clipping.

Performance & Runtime Profile

Simulating dozens to hundreds of concurrent animal models requires strict attention to target platforms, engine runtime settings, and physics configurations.

Profiling Breakdown & CPU Overhead

The primary CPU bottleneck in unoptimized flocking systems is $O(N^2)$ distance checking. HerdSim mitigates this through staggered update loops (allocating steering logic over multiple frames via frame-slice offsets) and internal grid queries.

• Garbage Collection (GC): Zero allocation during baseline update loops once target arrays and transforms are allocated at startup.
• Transform Access Cost: Utilizes local vector processing arrays to avoid repeated call backs through Unity's native C++ transform bridge.
• Mono vs. IL2CPP: Compiling under IL2CPP with high code generation optimizations significantly enhances loop execution speeds, particularly for distance calculations and vector math.

Physics vs. Raycast Steering Performance

Standard Unity rigidbodies with dynamic sphere colliders scale poorly for high agent counts due to continuous solver passes. HerdSim defaults to raycast-based surface probing. Running 100 concurrent agents using raycasts consumes a fraction of the frame time compared to dynamic dynamic body colliders.

Quick-Start Unity Integration Guide

Setting up a functioning animal simulation environment involves configuring manager prefabs, surface layer masks, and target waypoints.

Step 1: Hierarchy and Layer Setup

1. Open Edit > Project Settings > Tags & Layer Mask. Ensure a dedicated layer exists for ground surfaces (e.g., Terrain) and dynamic obstacles (e.g., Obstacles).
2. Assign all ground geometry to the Terrain layer.

Step 2: Instantiating the Manager Prefab

1. Drag the primary HerdSimManager prefab from the project drawer into the scene hierarchy.
2. Configure the manager's Ground Layer Mask field to evaluate only the designated Terrain layer.
3. Assign the animal character prefab into the manager's Agent Prefab array slot.

Step 3: Programmatic Spawner Implementation

To dynamically instantiate and initialize a flock via C# script at runtime, use the following manager setup pattern:

using UnityEngine;

namespace HerdSim.Setup
{
    public class HerdSpawner : MonoBehaviour
    {
        [SerializeField] private GameObject _herdControllerPrefab;
        [SerializeField] private Vector3 _spawnCenter = Vector3.zero;
        [SerializeField] private int _initialAgentCount = 50;

        private void Start()
        {
            GameObject controllerObj = Instantiate(_herdControllerPrefab, _spawnCenter, Quaternion.identity);
            HerdSimController controller = controllerObj.GetComponent<HerdSimController>();

            if (controller != null)
            {
                controller.SetMaxAgents(_initialAgentCount);
                controller.InitializeFlock();
            }
        }
    }
}

Related Unity Tools Assets