LimboAI Documentation

LimboAI is an open-source C++ plugin for Godot Engine 4 that provides Behavior Trees (BT) and Hierarchical State Machines (HSM). It is designed to help developers create complex, modular AI behaviors.

Key features include:

• Behavior Trees: Visual editor, BTPlayer node for execution, a Blackboard system for data sharing, and a visual debugger.
• Hierarchical State Machines: LimboHSM node for managing LimboState instances, supporting event-based transitions and nesting.
• Extensibility: Full support for creating custom tasks and states using GDScript.
• Integration: Can be used as a C++ module or as a GDExtension (which does not require custom engine builds).

The BTProbabilitySelector is a behavior tree composite that selects a child task to execute based on assigned weights. It is useful for implementing stochastic decision-making logic.

Execution Logic

• Returns SUCCESS if a child task succeeds.
• Returns RUNNING if a child task is running.
• Failure Handling (controlled by abort_on_failure):
  • If abort_on_failure is false (default): When a child fails, the selector normalizes the probabilities of the remaining children and picks a new one. If all children fail, it returns FAILURE.
  • If abort_on_failure is true: When a child fails, the selector immediately returns FAILURE without trying other children.

The BehaviorTree class contains Behavior Tree data and serves as a hierarchical structure to model and control agent behaviors (e.g., characters or enemies).

Behavior Trees consist of:

• Control Tasks: Determine execution flow (e.g., BTSequence, BTSelector, BTInvert).
• Leaf Tasks: Represent specific actions or conditions. To create custom actions, extend the BTAction class. To create custom conditions, extend the BTCondition class.
• Statuses: Every task returns a status: SUCCESS, RUNNING, or FAILURE (defined in BT_Status).
• Blackboard: Tasks can share data using a Blackboard.

BBParam is the base class for all LimboAI typed parameters. It allows a parameter to either hold a raw value or reference a variable from a Blackboard.

Important: Do not instantiate BBParam directly. Instead, use its specific subtypes (e.g., BBInt, BBFloat, BBString, BBVector3, etc.) based on the data type you need.

Value Sources

You can configure how a parameter retrieves its value using the value_source property:

• SAVED_VALUE (0): The value is stored directly within the parameter resource.
• BLACKBOARD_VAR (1): The value is retrieved from a Blackboard using the name provided in the variable property.

The BehaviorTreeData class represents the current state of a BehaviorTree instance. It is primarily used for:

1. Serialization/Deserialization: Used by the LimboAI debugger to capture and restore tree states.
2. Visualization: Can be passed to a BehaviorTreeView to visualize the real-time state of a behavior tree.
3. Custom In-Game Tools: Intended for developers building their own custom debugging or monitoring tools within Godot.

To capture the state of a running tree, use the create_from_bt_instance static method.

LimboAI provides several key classes for implementing Behavior Trees and Hierarchical State Machines (HSM) in Godot 4:

Behavior Trees

• BTTask: The base class for all behavior tree tasks.
• BTPlayer: A Godot node used to execute BehaviorTree resources.
• Blackboard: A mechanism for sharing data between different tasks.
• BBParam: A helper class used for the parametrization of tasks.

Hierarchical State Machines (HSM)

• LimboHSM: An event-based hierarchical state machine.
• LimboState: A state node used within a hierarchical state machine.
• BTState: A specialized state node for LimboHSM that hosts a BehaviorTree.

LimboAI Behavior Trees are composed of four main types of tasks that dictate agent behavior:

• Actions: Leaf tasks that perform actual work (e.g., BTPlayAnimation, BTWait).
• Conditions: Leaf tasks that conduct checks and return SUCCESS or FAILURE (e.g., BTCheckVar, InRange).
• Composites: Tasks with one or more children that dictate execution flow (e.g., BTSequence, BTSelector, BTParallel).
• Decorators: Tasks with a single child that modify the child's behavior (e.g., BTAlwaysSucceed, BTInvert, BTTimeLimit).

Tasks return one of three statuses: SUCCESS, FAILURE, or RUNNING.

The BehaviorTreeView class is used to visualize the current state of a BehaviorTree instance in Godot. It provides a visual representation of the tree's execution flow and task status.

To use it, you typically provide it with BehaviorTreeData via the update_tree method.