AI Behavior Trees

Relevant source files

The following files were used as context for generating this wiki page:

• code/datums/ai/README.md
• code/datums/ai/learn_ai.md
• tools/build_bt.py
• code/modules/buildmode/README.md
• tools/ci/check_grep.sh

AI Behavior Trees provide a modular architecture for managing game AI logic. The system structures AI decision-making into a tree of nodes that run from left to right, prioritizing high-priority behaviors over lower-priority ones. This architecture separates state management, stored in a Blackboard, from actual behavioral logic, stored in AI Controllers and various node types.

Sources: code/datums/ai/learn_ai.md:7-14, code/datums/ai/README.md:5-10

Core Architecture

The AI system is built around three primary components: the AI Controller, the Blackboard, and the Behavior Tree nodes.

AI Controllers

AI Controllers are datums that you can add to any atom in the game. They store decision-making logic and state, preventing the cluttering of standard Life() code in Mobs. While a controller might support a specific subtype (like /mob/living), the design allows applying a single controller type to various atom groups.
Sources: code/datums/ai/README.md:12-16

The Blackboard

The Blackboard acts as the shared memory for an AI Controller. It is an associative list where keys are strings (usually defined as macros) and values are arbitrary data.

• Reading: Nodes read keys to make decisions (e.g., "Is a target present?").
• Writing: Nodes write results to keys for use by subsequent nodes.
  Sources: code/datums/ai/learn_ai.md:18-29, code/datums/ai/README.md:20-24

Node Execution Status

Every node in the behavior tree returns one of three status values upon execution:

1. BT_SUCCESS: The node completed its task successfully.
2. BT_FAILURE: The node failed its task or condition.
3. BT_RUNNING: The node is still performing its action.
   Sources: code/datums/ai/learn_ai.md:46-52

Node Types and Hierarchy

Behavior trees use different node categories to control the flow of logic.

Structural Nodes (Composites)

Composites control how and when their child nodes execute. They do not perform actions themselves.

Composite Type	Logic Description
Selector	Runs children in order until one returns BT_SUCCESS. Stops on the first success.
Sequence	Runs children in order until one returns BT_FAILURE. Stops on the first failure.
Parallel	Runs multiple children concurrently. Can loop secondary children or stop them when the primary finishes.
Subplan	Runs a child branch with a loop policy, allowing retries without replanning the whole tree.

Sources: code/datums/ai/learn_ai.md:88-145, tools/build_bt.py:34-39

Leaf Nodes (ai_behavior)

Leaf nodes represent the actual actions the AI performs. Common examples include finding targets, moving to locations, attacking, or using abilities.
Sources: code/datums/ai/learn_ai.md:54-61

Decorators

Decorators act as gates or conditions for a branch. They serve two functions:

1. Gating: Only execute children if a condition (like a Blackboard key being set) is met.
2. Observing: Monitoring a condition while children run. If the condition changes, the decorator can cancel the running behavior.
   Sources: code/datums/ai/learn_ai.md:65-80

Target Acquisition System

Targeting is handled by a generic leaf configured with specialized helper datums. This prevents the need to write unique targeting code for every AI.

Components of Targeting

1. Target Source: Gathers nearby candidates (e.g., everything in view).
2. Targeting Strategy: A datum that determines if a specific candidate is valid (e.g., /datum/targeting_strategy/anything).
3. Priority Strategy: Chooses the best candidate among all valid ones.
4. Acquisition Leaf: The node (e.g., update_combat_targets) that executes the search and writes to the target_key.
   Sources: code/datums/ai/learn_ai.md:175-200

Data Compilation and Tooling

Behavior trees are stored as .bt.json files and compiled into a runtime-readable format using a Python utility.

Compilation Process

The tools/build_bt.py script performs the following:

• Define Substitution: Parses all .dm files in code/__DEFINES/ to replace string keys with their actual values (e.g., TRUE to 1).
• Time Macros: Converts SECONDS, MINUTES, and HOURS into game ticks (deciseconds).
• Validation: Replaces standard node names with their internal type paths (e.g., selector to /datum/bt_node/composite/selector).
  Sources: tools/build_bt.py:1-40, tools/build_bt.py:84-110

Compiler Logic Flow

Summary

The Behavior Tree system in BandaStation enables the creation of complex, reactive AI through a modular node-based architecture. By utilizing the Blackboard for shared state and specialized targeting strategies, developers can build reusable AI patterns that remain distinct from mob-specific code. The integration of a dedicated JSON compiler allows for the use of standard code defines within the AI configuration files, maintaining consistency across the project.
Sources: code/datums/ai/README.md:1-10, code/datums/ai/learn_ai.md:210-220