Crowd System

Overview

This document describes the new crowd system implemented in the GameFramework package. It replaces the original UnrealEngine 3 crowd system described in OldCrowdSystem.

This crowd system is designed to allow level designers to add 'crowds' of animated characters to a map, and control their movement and animations through a network of crowd destinations and kismet interaction. Agent types are defined using archetypes, and a "plug-in" behavior system allows level designers to control the interaction of crowd agents with players and other NPCs.

There are currently no crowd-specific rendering optimizations in the engine. Each member of the crowd has a unique AnimTree and skeletal mesh instance. However, the system does avoid the most expensive part of character simulation which is Unreal walking physics and full AI. After walking physics, the next most expensive part of a crowd of meshes is skinning all the graphics vertices, so you should keep the SkeletalMesh used as low-poly and low-bone as possible (we use around 1000-1500 polys and 20 bones). You should probably also make aggressive use of LOD.

How It Works

As mentioned above, crowd 'agents' are not Pawns, and do not use PHYS_Walking. Instead, they use a movement model that follows a set of simple rules. One important thing to remember is that they do not perform collision against level geometry. Instead they move along the navigation mesh to ensure they don't pass through the geometry of the map. They can however perform a cheaper zero-extent line trace to ensure they conform to uneven surfaces.

All game specific implementations will have at a minimum to include a non-abstract crowd spawner or population manager toggle and crowd agent class. For example, UTGame contains a very basic example implementation of the crowd system with the UT specific crowd spawner class SeqAct_UTCrowdSpawner, and crowd agent class UTGameCrowdAgent which is used as the base class for UT agent archetypes.

Crowd Population Manager Toggle Kismet Action

This Kismet action is used to toggle the crowd population manager on or off. There is only one population manager ever active. It attempts to fill the area around the player with agents by spawning new agents at nearby positions between GameCrowdDestinations not currently visible to the player, taking into account the predicted position of the player in a few seconds, and removing "stale" agents which are no longer visible or relevant to the player to maintain a consistent agent count.

Input Links

Specifying Agents to spawn

A population manager can spawn multiple types of agents with varying frequencies for each agent type. The set of agent types to spawn is specified by a GameCrowd_ListOfAgents archetype, allowing the list to be easily re-used by different spawners or population managers. Within this list, the agent types are specified using archetypes, as described in the Agent Archetype section. The spawn frequency of each archetype is affected by the associated FrequencyModifier. The likelihood of a specific archetype being chosen is equal to his FrequencyModifier divided by the sum of all the FrequencyModifiers.

If an agent archetype entry has GroupMembers specified, agents based on these archetypes will be spawned and grouped with the primary agent. Grouped agents will move together, but will not queue (so destinations they use must have room for the entire group).

Spawning

You spawn agents in a similar manner to a particle system, but you specify the location to spawn agents using one or more actors in the level. These are normally GameCrowdDestinations, but can be any type of actor (must be GameCrowdDestination for agent to move between destinations).

Graphics And Animation

Crowd agents use the normal UE3 animation system. They use a LightEnvironment for lighting (like player Pawns), but by default do not cast dynamic shadows for speed unless overridden by the crowd spawner. The mesh and animations used by agents are defined by their archetype, as described later.

Crowd Spawner Kismet Action

This latent Kismet action is used to spawn crowd agents. It contains the parameters for which agent archetypes to spawn.

Input Links

Output Links

Specifying Agents to spawn

A crowd spawner can spawn multiple types of agents with varying frequencies for each agent type. The set of agent types to spawn is specified by a GameCrowd_ListOfAgents archetype, allowing the list to be easily re-used by different spawners or population managers. Within this list, the agent types are specified using archetypes, as described in the Agent Archetype section. The spawn frequency of each archetype is affected by the associated FrequencyModifier. The likelihood of a specific archetype being chosen is equal to his FrequencyModifier divided by the sum of all the FrequencyModifiers.

If an agent archetype entry has GroupMembers specified, agents based on these archetypes will be spawned and grouped with the primary agent. Grouped agents will move together, but will not queue (so destinations they use must have room for the entire group).

Graphics And Animation

Crowd agents use the normal UE3 animation system. They use a LightEnvironment for lighting (like player Pawns), but by default do not cast dynamic shadows for speed unless overridden by the crowd spawner. The mesh and animations used by agents are defined by their archetype, as described later.

Spawning

You spawn agents in a similar manner to a particle system, but you specify the location to spawn agents using one or more actors in the level. These are normally GameCrowdDestinations, but can be any type of actor (must be GameCrowdDestination for agent to move between destinations).

Move To Destination

Newly spawned agents will pick a GameCrowdDestination to move toward. This destination will chosen from the destination list in the GameCrowdDestination used as a spawn location, or from among the GameCrowdDestinations attached to the Destinations input of the crowd spawner. The crowd spawner can also override the agent archetype's base settings to force (more expensive) navigation mesh pathfinding and obstacle blocking to be used. NOTE: obstacle blocking currently has some issues, so its use is not recommended at this time. Without obstacle blocking, you may occasionally see agents pass through walls or fall off ledges even when using pathfinding.

GameCrowdAgent

This is the base Actor class of crowd agents. Agent archetypes, which can be created by artists and level designers, will be based on a game specific subclass of GameCrowdAgent. Agent archetypes have a number of editable properties.

Graphics And Animation

The visual properties of agents are specified by their archetype. Typical crowd members will used skeletally animated meshes with an archetype based on a GameCrowdAgentSkeletal subclass.

The following properties have an effect on agent animation only if root motion velocity (bUseRootMotionVelocity, described below) is not being used and the agent's AnimTree has a SpeedBlendNode.

The agent animation code makes certain assumptions about how the agent animtree is set up. It expects to find animation nodes with the following names 'SpeedBlendNode', 'ActionBlendNode', 'ActionSeqNode', 'WalkSeqNode', and 'RunSeqNode', as well as a 'bIsPanicked' AnimNodeBlendByProperty node, to implement all supported functionality.

Agent attachments

Agent archetypes can also be specified to spawn with random attachments specified in the Attachments array.

Movement

Here are the rules that a crowd agent will follow, with the settings within the agent archetype that relates to each. Each rule generates a force that is applied to the agent. The current agent movement system treats agents as particles moving in a flock. In the future, agent movement may move to a system using reciprocal velocity obstacles (http://gamma.cs.unc.edu/RVO/icra2008.pdf).

Obstacle avoidance

Agents do not perform normal collision checking, and therefore may pass through level geometry. There is an option for agents to perform obstacle checking using the navigation mesh, which will prevent agents from penetrating geometry or falling off ledges. Even without obstacle checking, agents will typically behave well if they are using navigation mesh pathing.

Velocity clamping

Using root motion velocity will provide the best visual results. It requires the animations to have root motion in them. With this option, the agent's movement will generally match its animation, except in some cases where the agent must move more slowly because of obstacles or sharp turns.

The following properties only have an effect if root motion velocity is not being used.

Avoid Neighbouring Agents

Agents avoid both neighboring agents and pawns. Currently, a simple spring force is used to avoid penetration between agents. Players using a GamePlayerController derived playercontroller with bWarnCrowdMembers set to true will update crowd members with their position every tick for more accurate avoidance by agents.

Move At Speed Of Neighbours

Agents try and move with the average speed of the agents around them.

Stay in Group

Agents which are grouped (see GroupMembers in SeqAct_GameCrowdSpawner) will attempt to stay together, both with the following properties, and through the GroupWaitingBehaviors (see Custom Agent Behavior).

Agent path finding

Because crowd agents do not do collision checks against the level like players do, they rely on the path finding using the navigation mesh to avoid passing through level geometry. Path finding has some performance cost, so for agents that are only travelling between destinations they can reach directly, it will be more efficient to disable path finding.

Agent Rotation

The following properties control agent rotation while travelling.

The following properties control agent rotation when stopped at a GameCrowdDestination.

Conforming To Ground

As mentioned earlier, agents can optionally conform to uneven surfaces using a vertical zero-extent line check. Note that this approach has no concept of 'max step height' and will not correctly handle very steep or vertical surfaces. By default, agents will conform to the surface of the navmesh. For certain special cases, they can be made to conform to BSP or to all world geometry instead.

Crowd Simulation Level of Detail (LOD)

Separately from visual LOD, crowd agents adjust their simulation based on distance from the player and visibility. Currently two properties are exposed to allow simulation LOD tweaking for agent archetypes.

Custom agent behavior

The default agent behavior is to move between GameCrowdDestinations. This default behavior can be overridden using the "plug-in" behavior system. Designers can assign behaviors to trigger based on various game events by creating Behavior Archetypes based on the GameCrowdAgentBehavior class (note that this is an Object sub-class, so uncheck "Actor classes only" in the class browser to find it). Several basic behavior classes are implemented in the base crowd system, and additional game specific behaviors can be created for a game project. These behaviors can then be customized by designers in the behavior archetypes. See the GameCrowdAgentBehavior entry below for more details.

When an agent behavior completes or is stopped and no other behavior is assigned to the agent, the agent will return to the default behavior of moving between GameCrowdDestinations.

Behavior archetypes are assigned to agent archetype BehaviorEntry arrays, or to the GameCrowdDestination ReachedBehavior BehaviorEntry array. When the appropriate game event is triggered, the agent will be assigned a behavior from the list of possible behaviors for that event. Each BehaviorEntry has the following editable properties:

The following editable properties control the behavior of an agent.

In addition agent behavior can be controlled through Kismet (for example triggered by an agent reaching a GameCrowdDestination).

Debugging agent behavior

Assuming your game's PlayerController class is derived from GamePlayerController, the console command 'CrowdDebug 1' will turn on the display of agent information over nearby agents' heads. The console command 'ShowGameDebug' will display stats information about the crowd population manager, and 'stat crowd' will displayer crowd system performance statistics.

Killing Agents

You can use any pain-causing volume to destroy crowd agents, or a GameCrowdDestination can be set to destroy agents which reach it. When killed, a GameCrowdAgentSkeletal will play an animation from its DeathAnimNames array.

GameCrowdAgents can also be damaged, and will die when their health becomes less than zero. To allow weapon collision they use the bEnableLineCheckWithBounds option, which performs line checks against the bounding box of the mesh. This is very approximate, but avoids the cost of an additional CylinderComponent, or doing more expensive per-bone hit tests.

GameCrowdAgentBehavior

This is the base class of agent behaviors. These behavior classes are the basis for creating designer customized behavior archetypes. A small number of basic behaviors are included in the base crowd system, and additional game specific behaviors can easily be created by gameplay programmers.

Behavior archetypes are added to various BehaviorEntry arrays in agent archetypes or in GameCrowdDestinations. A behavior selected from the appropriate array will be applied to an agent when the required game event occurs.

GameCrowdBehavior_PlayAnimation

GameCrowdBehavior_RunFromPanic

This is a very simplistic implementation which causes agents to run from the source of their panic, virally infecting other agents they encountered. Intended as an example implementation for this type of functionality.

GameCrowdBehavior_WaitInQueue

This behavior is not exposed for level designer use, as it is tied to destinations which have queue points.

GameCrowdBehavior_WaitForGroup

This simple behavior is intended as a basis for an archetype to be added to an agent's GroupWaitingBehaviors. Agents using this behavior will idle and turn toward the agent for whom they are waiting, until he gets close enough.

GameCrowdInteractionPoint

All the following crowd interaction point classes can be enabled or disabled.

GameCrowdDestination

GameCrowdDestinations function as destinations for crowd agents, and also can implement customized behavior for agents which reach the destination. GameCrowdDestinations selected in the editor will display lines to connected destinations (in the NextDestinations list). Selecting multiple GameCrowdDestinations and hitting ctrl-shift-L will connect them (adding themselves to each other's NextDestinations array). Selecting multiple GameCrowdDestinations and hitting ctrl-shift-U will disconnect them.

The following arrays can be used to restrict which agents can use a GameCrowdDestination. If none of these arrays have any entries, any agent can use this destination. If there is any entry in SupportedAgentClasses or SupportedAgentArchetypes, then an agent will only use the destination if it matches the requirement. If it passes the "supported" requirement (which it always will if there are no entries in either array), then it must not belong to a class or archetype in the RestrictedAgentClasses and RestrictedArchetypes arrays.

GameCrowdDestination also provides some custom functionality for specifying the spawn position of agents spawned at the destination.

GameCrowdInteractionDestination

GameCrowdInteractionDestinations don't have any unique functionality. They are simply a GameCrowdDestination subclass with the settings typically needed for a custom interaction destination, such as a capacity of one and being ignored by panicked agents.

GameCrowdDestinationQueuePoint

GameCrowdDestinationQueuePoints are used to allow agents to queue at destinations with a limited capacity.

Selecting multiple GameCrowdDestinationQueuePoints and one GameCrowdDestination and hitting ctrl-shift-L will connect them with the queue going from nearest to furthest queue point.

GameCrowdForcePoint

GameCrowdForcePoints attract or repulse crowd agents. Their use is not recommended if agent pathfinding (bUseNavMeshPathing) is enabled. GameCrowdForcePoints are always cylindrical in shape, and their radius is based on their CylinderComponent. Turn on 'collision' view in UnrealEd to see the current radius, and you can use the scale widget to easily adjust it. You can use a Kismet Toggle action to turn them on and off.

There are two types of crowd force points: GameCrowdAttractors and GameCrowdRepulsors.

SeqEvent_CrowdAgentReachedDestination

This kismet event is associated with a specific GameCrowdDestination and fires when that destination is reached by an agent.

SeqAct_PlayAgentAnimation

This kismet action is used to make an agent play a series of animations while stopped. Agents will automatically return to their current behavior (by default, moving between destinations) when they complete this action.

The play agent animation action has the following inputs.

The play agent animation action has the following outputs.

The play agent animation action has the following editable properties.