User Guide (Version 1.21)

AI System Overview

This section outlines basic concepts related to the AI system.


  • Default navigation system

    • Triangulation

      • 2D terrain-based navigation

      • Uses cylindrical objects (such as trees) and forbidden areas

    • Navigation modifiers

      • Human waypoints – Need to be place manually but connections can be generated automatically

      • Flight – Information about navigable volumes for flying entities

      • Volume – General volume navigation, such as for oceans

  • Multi-layer navigation system

  • Smart object system: allows AI agents to move in special ways

  • AI territories & waves

    • Control number of active AI agents (through flow graph logic)

    • Activate, deactivate, and spawn all AI agents assigned to a territory using a single FG node

    • AI waves can be attached to AI territories and allow independent AI activations

    • AI waves automatically handle entity pool issues for assigned AI agents, such as loading/unloading

In general, a search is time-sliced to use 0.5 ms per AI frame (configured using the console variable ai_PathfinderUpdateTime). Options for pathfinding techniques include high priority, straight, and partial. Updates for human waypoints are heavy but time-sliced. The navigation graph is optimized but needs memory. Navigation data is generated offline in Editor. With multi-layer navigation, the navigation mesh is regenerated when the designer modifies the map.

Decision Making

  • Behavior selection system – Uses behavior trees to select AI behaviors

  • Cover system – Provides AI agents with static and dynamic covers

  • Smart object system – Allows AI agents to interact with their environment

  • Interest system – Allows AI agents to perform intelligent actions when not alerted


  • Tactical point system (TPS) – Allows AI agents to ask intelligent questions about their environment (such as where to hide or where to attack)

  • Faction system – Determines levels of hostility between AI agents

  • Group coordination system – Uses coordination selection trees to select group behaviors

  • Formation system – Allows AI agents to move in formations

  • Cluster detector – detects clusters of points in space and subdivides them into separate groupings that satisfy specific properties (using a modified K-mean algorithm); used with AISquadManager to group different AI agents into dynamic squads


  • Signals – To trigger events and/or change behaviors

  • Perception system

    • Perception handler (legacy, usually per game)

    • Target track system – Uses configurable ADSR envelopes to represent incoming stimuli

  • Communication system – Allows AI agents to play sound/voice/animation events

Development Environment

The design and development environment includes the following components:

  • Game object model – Entity, movement controller, extensions

  • Actor & vehicle system – Health, camera, IK, weapons, animation, etc.

  • Flow graph – Visual definition of game logic

  • AI debug renderer – HUD, geometric primitives, text labels, graphs, etc.

  • Editor

    • AI entities – Properties, flow graphs, scripts

    • Entity archetypes – Templates for properties of individual AI agents

    • AI shapes – AI territories, AI paths, forbidden areas

    • Navigation – Navigation modifiers used instead of triangulation

    • Cover surfaces – CoverSurface anchors to indicate where cover should be

    • Visual AI debugger – Recording AI signals, active behaviors, goals, stimuli, etc.

  • Scripting with Lua

    • Entity definitions (including entity flow graph nodes)

    • AI behavior definitions

    • Group behavior definitions

    • Library or shared Lua code (game rules, basic entities)

    • Blackboards to share information globally or among groups

    • Examples of AI functionality available in Lua:

      • AI.Signal

      • AI.FindObjectOfType

      • AI.GetAttentionTargetType (Visual, Memory, Sound, None)

      • AI.GetAttentionTargetAIType (Actor, Grenade, Car, etc.)

      • AI.GetRefPointPosition

      • AI.DistanceToGenericShape

      • AI.SetBehaviorVariable (to change behavior)

      • AI.CanMelee

      • AI.RecComment (make comment for Visual AI Debugger

  • Scripting with XML

    • Behavior/coordination trees

    • AI communications

    • Items (e.g., weapons)

  • Entity system

    • Spatial queries – GetPhysicalEntitiesInBox()

    • AI agents and vehicles are entities in the Entity system

    • To spawn an entity, its Entity class is required – Can be defined either using the .ent file in Game\Entities OR through a C++ call to RegisterFactory() in game code

    • An entity pool can be used to limit the number of active AI agents per each specified Entity class.

  • AI Debugger and AI Debug Draw

    • Use AI Debugger to track multiple features, including active behavior, signal received, attention target, comments, etc.

    • ai_DebugDraw

      • 1 – Basic info on AI agents (selected by ai_DrawAgentStats)

      • 74 – All of the navigation graph (can be slow)

      • 79 – Parts of the navigation graph around the player

    • ai_statsTarget <AI name> – Detailed info for the specified AI

    • ai_DebugTargetTracksAgent <AI name> – Perception information on the specified AI

    • ai_Recorder_Auto – Record AI activity in Editor game mode for AI Debugger

    • ai_DebugTacticalPoints – Debug TPS queries

    • ai_DrawPath <AI name> – Draw the path of the specified AI (optionally specify "all" for all AI agents)

    • ai_DrawPathFollower – Draw the actual path being followed

    • ai_DrawSmartObjects – Display smart objects and their classes and attributes

    • ai_DebugDrawEnabledActors – List currently enabled AI agents.

Execution Context

  • AI update is called every frame, but are fully updated only at ~10Hz

  • Some AI subsystems use independent time-slicing (pathfinding, tactical point, dynamic waypoints updating, smart object, interest, and dead bodies removal)

  • Some services can be called synchronously from game code (such as tactical point system (TPS) queries)