Civil System (Pedestrian AI & Roaming NPCs)

Civil Waypoint System

The Civil Waypoint System is a graph-based navigation layer designed for non-combatant NPCs (civilians). Unlike standard NavMeshAgents that just pathfind from A to B, the Civil System allows you to define traffic lanes, activity spots, and spawn/despawn points to create realistic city life.

Overview

The system consists of two main components:

1. Civil Waypoint Manager: The central brain that maintains the graph and handles lookups.

2. Civil Waypoint Node: Individual points in the world that define where agents go and what they do.

---

Waypoint Manager

The Waypoint Manager is a singleton-like component that must exist in your scene if you are using Civil Crowds.

Setup

1. Create an empty GameObject named CivilManager.

2. Add the CivilWaypointManager component.

3. (Optional) Adjust settings, though defaults are usually fine.

Key Features

• Auto-Discovery: Automatically finds all CivilWaypointNode objects in the scene (or just its children) on Start.

• Validation: Checks if waypoints are on the NavMesh and warns about broken connections.

• Spatial Hashing: Optimizes performance by organizing waypoints into a grid, allowing for ultra-fast "Find Nearest Waypoint" queries even with thousands of nodes.

• Bidirectional Linking: Can automatically create return paths (A->B becomes A<->B) to save setup time.

---

Civil Waypoint Node

The CivilWaypointNode is the building block of your traffic system. You place these at intersections, doorways, parks, and spawn points.

Waypoint Types

The behavior of a node is defined by its Type:

Type	Description
Path	A standard navigation point. Agents walk here and then choose a connected node to continue to. Used for sidewalks and corridors.
Explore	A "wander zone". Agents arriving here will pick random points within the Explore Radius for a set duration before moving on. Good for parks or plazas.
Activity	A specific interaction spot (e.g., a bench, a vending machine, a conversation partner). Agents play an animation here.
Spawn	A generator node. Spawns new agents into the world based on defined intervals and limits.
Despawn	A sink node. Agents arriving here are removed from the world. Used for subway entrances or "off-screen" exits.

Common Settings

• Connections: A list of other nodes this one connects to. Agents can only travel along these lines.

  • Free Roam Note: If your agents are set to Free Roam mode in their EnemyCrowd settings (under Civil Settings), you do not need to manually connect nodes. Agents will automatically scan for nearby valid nodes and travel to them without predefined links.

• Arrival Radius: How close an agent needs to get to "hit" the waypoint.

• Allowed Factions: Filter which specific crowds can use this node (e.g., "Guards Only" path).

Spawn Settings (Spawn Type Only)

• Spawn Entries: A list of rules defining who spawns and how often.

  • Faction Index: Which crowd to spawn.

  • Interval: Time between spawns (Fixed or Random range).

  • Count: How many to spawn at once.

• Spawn Mode:

  • Fixed Radius: Spawns in a circle around the node.

  • Camera Frustum Edge: Spawns just off-screen (useful for endless city crowds).

• Max Total Spawned Alive: Limits the total population generated by this specific node.

Activity Settings (Activity Type Only)

• Activity Position/Facing: Exact Transform for the interaction (e.g., where to sit).

• Max Concurrent: How many agents can use this spot at once (e.g., a bench might hold 2).

• Available Activities: List of animation definitions (e.g., "Sit_Read", "Sit_Phone").

---

Workflow: Building a City Street

1. Place Nodes:

   • Place Spawn nodes at the ends of the street (e.g., subway exits).

   • Place Despawn nodes near the Spawn nodes (so agents have somewhere to go).

   • Place Path nodes along the sidewalks.

   • Place Activity nodes near benches or shop windows.

2. Connect Nodes:

   • Select a node.

   • In the Inspector, drag other nodes into the Connections list.

   • Tip: Enable Draw Network Gizmo on the Manager to see lines connecting your nodes.

3. Configure Spawning:

   • Select your Spawn nodes.

   • Add a Spawn Entry for your "Citizens" faction.

   • Set the Interval (e.g., every 2-5 seconds).

4. Run:

   • Press Play. The Manager will auto-link everything.

   • Agents will spawn, walk along the path nodes, stop at activities, and eventually leave via despawn nodes.

Runtime Civil Mode Switching

A powerful feature of Enemy Masses is the ability to toggle a faction between "Combat Mode" and "Civil Mode" instantly at runtime.

• Combat Mode: Agents use formations, chase enemies, and fight.

• Civil Mode: Agents ignore combat, break formation, and start following the nearest Civil Waypoints.

Use Cases

• Panic: When a battle starts, switch your "Villager" faction from Civil to Combat (with a Flee behavior) or vice versa.

• Patrols: Have soldiers march in formation (Combat Mode), then switch them to Civil Mode to have them disperse and guard individual spots (Activity Nodes).

• Day/Night Cycle: During the day, agents work (Civil Mode). At night, they form up to defend the city (Combat Mode).

To do this, simply toggle the boolean on the EnemyCrowd asset:

// Switch to Civil Mode
myEnemyCrowd.civilSettings.enableCivilMode = true;

// Switch back to Combat Mode
myEnemyCrowd.civilSettings.enableCivilMode = false;

Scripting API

// Get the singleton
var manager = CivilWaypointManager.Instance;

// Find nearest sidewalk node to a position
var node = manager.FindNearestWaypoint(transform.position, CivilWaypointType.Path);

// Register a new node created at runtime
manager.RegisterWaypoint(myNewNode);