AI crowds and director

Scale AI with significance and crowd tiers, pace threats with the AI director, and build ambient behavior with cover, smart objects, schedules and situations.

Last updated Oct 26, 2026Edit this pageVersion 1.0.0

These systems take AI from a handful of enemies to a living level: hundreds of ambient characters at three levels of detail, a director that paces threats, and data-driven cover, smart objects, daily schedules and world events that witnesses react to and gossip about.

Significance

The significance system scores entities that carry a Significance component, from 0 to 1, against the main camera: a falloff to maxDistance (150 m), plus frustumBonus (0.25) when on screen. forcedSignificance of 0 or more overrides the score, for cutscene principals. SignificanceComponent

The score lowers the cost of unimportant characters:

ConsumerEffect
AnimationUpdate rate drops with the score
PerceptionLow-score perceivers run every ai.SignificancePerceptionInterval frames (4)
Behavior treesTick no faster than ai.SignificanceBTMidInterval (0.2 s) or ai.SignificanceBTLowInterval (0.6 s)
AudioVoice priority scales down, so distant barks lose the voice budget first

ai.SignificanceBudget (128) entities are re-scored per frame, round-robin. FSignificanceSystem

Crowds

Crowd members carry a CrowdMember component and are ranked by significance into three tiers. Changing tier swaps only the brain; the entity keeps its identity and position. FCrowdSystem

TierCapSimulation
Fullai.Crowd.MaxFull (24)A real AI: nav agent with avoidance, perception, optional behavior tree
Bulkai.Crowd.MaxBulk (128)A shared idle, walk and flee state machine with avoidance; no perception
ParticleUnboundedFlow steering with neighbor separation; no nav agent

Promotions wait ai.Crowd.TierDwell (1 s) and incumbents get a small score bonus, so camera jitter does not make members flicker between tiers.

Populate with a CrowdSpawner component: count members in a disc of radius, with archetypeCount variants, a walkSpeed and a seed. Spawning ramps up at ai.Crowd.SpawnPerFrame per frame, and members despawn with the spawner. CrowdSpawnerComponent

MCrowdStatics::BroadcastCrowdReaction(position, radius, type) panics members in the radius; full-tier AIs hear it as a noise. GetCrowdFullCount, GetCrowdBulkCount and GetCrowdParticleCount report the tiers. MCrowdStatics

The AI director

The director paces threats the way Left 4 Dead does. It measures each player's stress from damage taken and dealt, deaths, enemy sightings, nearby enemies, low health and low ammo, takes the team's intensity as the highest player's, and cycles through four phases: FAIDirectorSystem

  1. BuildUp
  2. Peak
  3. PeakFade
  4. Relax
Relax is a guaranteed quiet window: the director never spawns during it.

Each phase has a wanted population. The director spawns threats in a ring around a random player, on the navmesh and out of every player's sight, and despawns them when far away or insignificant.

Enable it in World Settings (director_enabled) and assign a .director profile (director_profile) holding the intensity weights, pacing thresholds and durations, populations and spawn settings.

From C++, RegisterPlayer adds co-op pawns, ReportStress(player, amount) adds custom stress such as a scripted scare, and SetSpawner installs your own spawner. From Visual Scripting, MDirectorStatics reads the phase and intensity and offers ForceDirectorPhase and SetDirectorPaused. MDirectorStatics A music score can follow the director's phase; see Music and mixing.

Cover

The cover system generates cover points from the level's static collision at the start of play, spread over several frames, and classifies each as Low (crouch) or High (full) cover. Place an ACoverPointActor, or add a CoverPoint component, for hand-placed points. FCoverSystem

Behavior trees use four native tasks: FindCover reserves the best point away from the threat in the blackboard, MoveToCover walks there, InCover checks the agent is still covered and not flanked, and LeaveCover releases the reservation.

Smart objects

A smart object is something an agent can claim and use: a bench, a terminal, a window. The SmartObject component sets its activity, slotCount, slotSpacing, useDuration and cooldown. Each agent holds at most one claim, and a claim dies with either end, so a despawned NPC never keeps a seat. SmartObjectComponent

Use them from a behavior tree with the FindSmartObject and UseSmartObject native tasks, or from Visual Scripting with MSmartObjectStatics::ClaimNearestSmartObject(actor, activity, radius), ReleaseSmartObject and GetSmartObjectSlotLocation. MSmartObjectStatics

Schedules

NPCs can follow a daily routine. Mark activity spots with ASmartPointActor or a SmartPoint component (activityTag, optional pointName, capacity, useFacing), and give the NPC a Schedule component naming a .schedule asset. SmartPointComponent

Content/AI/TownWorker.schedule
Schedule "TownWorker" {
    schema_version: 1

    Act "work" {
        start_hour: 8.0
        end_hour: 12.0
        activity: "work"
        behavior: GoToAndIdle
    }
    Act "sleep" {
        start_hour: 20.0
        end_hour: 8.0
        activity: "sleep"
        behavior: Wander
    }
}

Hours follow the day-night clock and wrap across midnight; the first matching act wins. Behaviors are GoToAndIdle, GoToAndLoop, Patrol and Wander. ai.Schedule.HourOverride forces an hour for testing. ScheduleAsset

Situations

A situation is a world event that witnesses learn about: Gunshot, Explosion, BodyFound, Trespass, Vandalism, Suspicious or Custom. FSituationSystem

  • Full AIs within earshot learn it, through the same walls-and-portals hearing the player's voice uses, and get blackboard keys such as KnowsAboutSituation, SituationType and SituationPosition. Crowd members in range panic.
  • Two AIs that stay within ai.Situation.ConversationRange for ai.Situation.ConversationTime pass what they know to each other.
  • BodyFound starts dormant and activates only when someone sees the body. Deaths raise one automatically (ai.AutoBodyFound).
  • A TrespassVolume component raises Trespass for anyone inside whose team is not authorized.
  • Situations decay after a per-type lifetime (ai.Situation.GunshotLifetime and so on).

Raise and resolve them with MSituationStatics::RaiseSituation(type, position, radius, severity), ResolveSituation(id) and ResolveSituationsAt(position, radius). MSituationStatics

Engine sources

This page describes behavior implemented in these files of the engine repository, checked against commit 5922e6e5e.

  • Engine/Source/Runtime/Game/Public/Gameplay/SignificanceSystem.h
  • Engine/Source/Runtime/Game/Public/Game/Components/SignificanceComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/CrowdSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/CrowdMemberComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/CrowdSpawnerComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/MCrowdStatics.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/AIDirectorSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/MDirectorStatics.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/CoverSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/CoverPointComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/ACoverPointActor.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/SmartObjectComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/SmartObjectSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/MSmartObjectStatics.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/ScheduleAsset.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/ScheduleComponent.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/ScheduleSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/SituationSystem.h
  • Engine/Source/Runtime/AINavigation/Public/AINavigation/MSituationStatics.h
  • Engine/Source/Runtime/Game/Public/Game/Components/SmartPointComponent.h
  • Engine/Source/Runtime/Game/Public/Game/Components/TrespassVolumeComponent.h

Page feedback

Was this page helpful?