LimboAI

https://limboai.readthedocs.io/en/stable/
Admin
LimboAI is an open-source C++ module for Godot Engine 4 providing a combination of Behavior Trees...
Tokens:21,709
Snippets:340
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Clone and Setup LimboAI Module

Source: https://limboai.readthedocs.io/en/stable/_sources/getting-started/contributing.rst.txt

Commands to clone the Godot Engine repository and integrate LimboAI as a module.

```bash
git clone https://github.com/godotengine/godot.git
git checkout 4.3-stable  # Replace "4.3-stable" with the latest stable tag
git clone https://github.com/limbonaut/limboai modules/limboai
```

--------------------------------

### Implement a simple action task in GDScript

Source: https://limboai.readthedocs.io/en/stable/behavior-trees/custom-tasks.html

Example of an action task that toggles the visibility of a node based on a provided path.

```GDScript
@tool
extends BTAction

## Shows or hides a node and returns SUCCESS.
## Returns FAILURE if the node is not found.

# Task parameters.
@export var node_path: NodePath
@export var visible := true


# Called to generate a display name for the task (requires @tool).
func _generate_name() -> String:
    return "SetVisible  %s  node_path: \"%s\"" % [visible, node_path]


# Called each time this task is ticked (aka executed).
func _tick(p_delta: float) -> Status:
    var n: CanvasItem = scene_root.get_node_or_null(node_path)
    if is_instance_valid(n):
        n.visible = visible
        return SUCCESS
    return FAILURE
```

--------------------------------

### create_blackboard

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboardplan.html

Constructs a new instance of a Blackboard using this plan. If NodePath prefetching is enabled, the provided prefetch_root is used to resolve node instances.

```APIDOC
## Blackboard create_blackboard(prefetch_root: Node, parent_scope: Blackboard = null, prefetch_root_for_base_plan: Node = null)

### Description
Constructs a new instance of a Blackboard using this plan. If NodePath prefetching is enabled, `prefetch_root` will be used to retrieve node instances for `NodePath` variables and substitute their values.
```

--------------------------------

### Integrating a Behavior Tree into a State Machine

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Demonstrates how to host a behavior tree within a LimboHSM state machine using BTState.

```gdscript
extends CharacterBody2D

var hsm: LimboHSM

@export var behavior_tree: BehaviorTree


func _ready():
    hsm = LimboHSM.new()
    add_child(hsm)

    var bt_state := BTState().new()
    bt_state.named("Supplied BT")

    # Set the behavior tree, or use a load("res://ai/trees/...") call
    bt_state.behavior_tree = behavior_tree
    bt_state.set_scene_root_hint(self)

    hsm.add_child(bt_state)
    hsm.initial_state = bt_state

    hsm.initialize(self)
    hsm.set_active(true)
```

--------------------------------

### populate_blackboard

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboardplan.html

Populates an existing blackboard with variables from this plan.

```APIDOC
## void populate_blackboard(blackboard: Blackboard, overwrite: bool, prefetch_root: Node, prefetch_root_for_base_plan: Node = null)

### Description
Populates `blackboard` with the variables from this plan. If `overwrite` is `true`, existing variables with the same names will be overwritten. If `NodePath` prefetching is enabled, `prefetch_root` will be used to retrieve node instances for `NodePath` variables and substitute their values.
```

--------------------------------

### BTInstance Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btinstance.html

Methods available for interacting with a BTInstance object.

```APIDOC
## Node get_agent()
Returns the agent of the behavior tree instance.

## Blackboard get_blackboard()
Returns the blackboard of the behavior tree instance.

## Status get_last_status()
Returns the execution status of the last update.

## Node get_owner_node()
Returns the scene Node that owns this behavior tree instance.

## BTTask get_root_task()
Returns the root task of the behavior tree instance.

## String get_source_bt_path()
Returns the file path to the behavior tree resource that was used to create this instance.

## bool is_instance_valid()
Returns true if the behavior tree instance is properly initialized and can be used.

## void register_with_debugger()
Registers the behavior tree instance with the debugger.

## void unregister_with_debugger()
Unregisters the behavior tree instance from the debugger.

## Status update(delta: float)
Ticks the behavior tree instance and returns its status.
```

--------------------------------

### Using BBFloat for Task Parameters

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Demonstrates using a BBFloat parameter to allow a task to accept either a direct value or a blackboard variable reference.

```gdscript
extends BTAction

@export var speed: BBFloat

func _tick(delta: float) -> Status:
    var current_speed: float = speed.get_value(scene_root, blackboard, 0.0)
    ...
```

--------------------------------

### Chained Configuration Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_limbostate.html

Methods that allow for fluent configuration of the LimboState instance.

```APIDOC
### call_on_enter(callable: Callable) -> LimboState
Connects the entered signal to a callable.

### call_on_exit(callable: Callable) -> LimboState
Connects the exited signal to a callable.

### call_on_update(callable: Callable) -> LimboState
Connects the updated signal to a callable.

### named(name: String) -> LimboState
Sets the name of the state.
```

--------------------------------

### set_bt_instance

Source: https://limboai.readthedocs.io/en/stable/classes/class_btplayer.html

Sets the BTInstance to play.

```APIDOC
## void set_bt_instance(bt_instance: BTInstance)

### Description
Sets the BTInstance to play. This method is useful when you want to switch to a different behavior tree instance at runtime.
```

--------------------------------

### get_bt_instance

Source: https://limboai.readthedocs.io/en/stable/classes/class_btplayer.html

Returns the current behavior tree instance.

```APIDOC
## BTInstance get_bt_instance()

### Description
Returns the behavior tree instance currently being used by the BTPlayer.
```

--------------------------------

### Initialize LimboHSM in GDScript

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Typically performed in the _ready function to define states and establish transitions before activating the state machine.

```gdscript
@onready var hsm: LimboHSM = $LimboHSM
@onready var idle_state: LimboState = $LimboHSM/IdleState
@onready var move_state: LimboState = $LimboHSM/MoveState


func _ready() -> void:
    _init_state_machine()


func _init_state_machine() -> void:
    hsm.add_transition(idle_state, move_state, idle_state.EVENT_FINISHED)
    hsm.add_transition(move_state, idle_state, move_state.EVENT_FINISHED)

    hsm.initialize(self)
    hsm.set_active(true)
```

--------------------------------

### Retrieving object instances from Blackboard

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Shows how to safely retrieve and validate object instances from the Blackboard to avoid errors when instances are freed.

```gdscript
@export var object_var: StringName = &"object"

func _tick(delta: float) -> Status:
    # Get object instance stored in the "object" variable.
    # - Important: Avoid specifying a type for "obj" in GDScript
    #   to prevent errors when the instance is freed.
    var obj = blackboard.get_var(object_var)
    if is_instance_valid(obj):
        # ...
```

--------------------------------

### create_from_bt_instance

Source: https://limboai.readthedocs.io/en/stable/classes/class_behaviortreedata.html

Creates a BehaviorTreeData object from a given BTInstance, suitable for visualization or serialization.

```APIDOC
## static BehaviorTreeData create_from_bt_instance(bt_instance: BTInstance)

### Description
Returns the current state of the provided `bt_instance` encoded as a BehaviorTreeData object. This is intended for use with BehaviorTreeView or for custom serialization tasks.

### Parameters
- **bt_instance** (BTInstance) - Required - The behavior tree instance to capture. Can be acquired via BTPlayer.get_bt_instance().

### Returns
- **BehaviorTreeData** - An object representing the serialized state of the behavior tree instance.
```

--------------------------------

### Sharing Data Between Agents via Blackboard

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Demonstrates how to use blackboard.top() to access the root scope for sharing variables across multiple agents.

```gdscript
extends BTAction

@export var group_target_var: StringName = &"group_target"

func _tick(delta: float) -> Status:
    if not blackboard.has_var(group_target_var):
        var new_target: Node = acquire_target()
        # Set common target shared between agents in a group:
        blackboard.top().set_var(group_target_var, new_target)

    # Access common target shared between agents in a group:
    var target: Node = blackboard.get_var(group_target_var)
```

--------------------------------

### Add local NuGet source for LimboAI

Source: https://limboai.readthedocs.io/en/stable/_sources/getting-started/c-sharp.rst.txt

Register the directory containing LimboAI NuGet packages as a source for the dotnet CLI.

```shell
dotnet nuget add source path/to/limboai/nupkgs --name LimboNugetSource
```

--------------------------------

### Implementing a Single-File State Machine

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Uses chained methods and delegation to define states and transitions within a single script.

```gdscript
extends CharacterBody2D

var hsm: LimboHSM

@onready var animation_player: AnimationPlayer = $AnimationPlayer


func _ready() -> void:
    _init_state_machine()


func _init_state_machine() -> void:
    hsm = LimboHSM.new()
    add_child(hsm)

    # Use chained methods and delegation to set up states:
    var idle_state := LimboState.new().named("Idle") \
        .call_on_enter(func(): animation_player.play("idle")) \
        .call_on_update(_idle_update)
    var move_state := LimboState.new().named("Move") \
        .call_on_enter(func(): animation_player.play("walk")) \
        .call_on_update(_move_update)

    hsm.add_child(idle_state)
    hsm.add_child(move_state)

    hsm.add_transition(idle_state, move_state, &"movement_started")
    hsm.add_transition(move_state, idle_state, &"movement_ended")

    hsm.initialize(self)
    hsm.set_active(true)


func _idle_update(delta: float) -> void:
    var dir: Vector2 = Input.get_vector(
        &"ui_left", &"ui_right", &"ui_up", &"ui_down")
    if not dir.is_zero_approx():
        hsm.dispatch(&"movement_started")


func _move_update(delta: float) -> void:
    var dir: Vector2 = Input.get_vector(
        &"ui_left", &"ui_right", &"ui_up", &"ui_down")
    var desired_velocity: Vector2 = dir * 200.0
    velocity = desired_velocity
    move_and_slide()
    if desired_velocity.is_zero_approx():
        hsm.dispatch(&"movement_ended")
```

--------------------------------

### Linking Blackboard Variables Programmatically

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Shows how to link variables between two different blackboard instances using the link_var method.

```gdscript
# Example: programmatically link a BT blackboard variable to an HSM blackboard variable
# Assume `hsm` is a LimboHSM instance and `bt_state` is a BTState instance
var hsm_bb := hsm.get_blackboard()
var bt_bb := bt_state.get_blackboard()

# NOTE: variable names do not need to match
bt_bb.link_var("target_pos", hsm_bb, "target_pos")
```

--------------------------------

### BTAwaitAnimation Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btawaitanimation.html

Methods to configure the BTAwaitAnimation behavior tree task.

```APIDOC
## BTAwaitAnimation

### Description
BTAwaitAnimation is a behavior tree action that waits for a specified animation on an AnimationPlayer node to finish. It returns SUCCESS upon completion or timeout, and FAILURE if the animation or node cannot be found.

### Properties
- **animation_name** (StringName) - The key of the animation within the AnimationPlayer node.
- **animation_player** (BBNode) - The reference to the AnimationPlayer node.
- **max_time** (float) - The maximum duration in seconds to wait for the animation to complete.

### Methods
- **set_animation_name(value: StringName)**: Sets the animation name to monitor.
- **get_animation_name() -> StringName**: Returns the current animation name.
- **set_animation_player(value: BBNode)**: Sets the AnimationPlayer node reference.
- **get_animation_player() -> BBNode**: Returns the current AnimationPlayer node.
- **set_max_time(value: float)**: Sets the maximum wait time in seconds.
- **get_max_time() -> float**: Returns the current maximum wait time.
```

--------------------------------

### get_base_plan

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboardplan.html

Returns the base plan if this plan is derived.

```APIDOC
## BlackboardPlan get_base_plan() const

### Description
Returns the base plan. See is_derived.
```

--------------------------------

### BTSetAgentProperty Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btsetagentproperty.html

Methods for configuring the operation, property name, and value for the BTSetAgentProperty task.

```APIDOC
## set_operation(value: Operation)
Sets the operation to be performed before assignment (property = property OPERATION value).

## get_operation() -> Operation
Returns the current operation setting.

## set_property(value: StringName)
Sets the name of the agent's property to be modified.

## get_property() -> StringName
Returns the name of the agent's property.

## set_value(value: BBVariant)
Sets the value to be assigned to the agent's property.

## get_value() -> BBVariant
Returns the value currently set for assignment.
```

--------------------------------

### BTPlayAnimation Class Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btplayanimation.html

Methods for configuring the BTPlayAnimation action properties.

```APIDOC
## void set_animation_name(value: StringName)
### Description
Sets the animation's key within the AnimationPlayer node.

## StringName get_animation_name()
### Description
Returns the current animation name key.

## void set_animation_player(value: BBNode)
### Description
Sets the AnimationPlayer node to be used by this action.

## BBNode get_animation_player()
### Description
Returns the currently assigned AnimationPlayer node.

## void set_await_completion(value: float)
### Description
Sets the maximum duration (in seconds) to wait for the animation to complete.

## float get_await_completion()
### Description
Returns the current await_completion duration.

## void set_blend(value: float)
### Description
Sets the custom blend time in seconds.

## float get_blend()
### Description
Returns the current blend time.

## void set_from_end(value: bool)
### Description
Sets whether to play the animation from the end.

## bool get_from_end()
### Description
Returns the current from_end status.

## void set_speed(value: float)
### Description
Sets the playback speed scaling ratio.

## float get_speed()
### Description
Returns the current playback speed.
```

--------------------------------

### set_base_plan

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboardplan.html

Sets the base plan for this instance.

```APIDOC
## void set_base_plan(blackboard_plan: BlackboardPlan)

### Description
Sets the base plan. If assigned, this plan will be derived from the base plan. Use with caution, as it will remove variables not present in the base plan. Only use this for custom tooling.
```

--------------------------------

### Accessing Blackboard variables in GDScript

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Demonstrates setting, retrieving, and checking for the existence of variables within a BTTask.

```gdscript
@export var speed_var: StringName = &"speed"

func _tick(delta: float) -> Status:
    # Set the value of the "speed" variable:
    blackboard.set_var(speed_var, 200.0)

    # Get the value of the "speed" variable, with a default value of 100.0 if not found:
    var speed: float = blackboard.get_var(speed_var, 100.0)

    # Check if the "speed" variable exists:
    if blackboard.has_var(speed_var):
        # ...
```

--------------------------------

### Managing Shared Blackboard for Agent Groups

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/using-blackboard.rst.txt

Shows how to assign a shared blackboard scope to multiple agents by setting the parent of their individual blackboards.

```gdscript
class_name AgentGroup
extends Node2D
## AgentGroup node: Manages the shared Blackboard for agents in a group.
## Children of this node are assumed to be agents that belong to a common group.
## This implementation assumes that each agent has a "BTPlayer" node for AI.

@export var blackboard_plan: BlackboardPlan

var shared_scope: Blackboard

func _ready() -> void:
    if blackboard_plan == null:
        shared_scope = Blackboard.new()
    else:
        shared_scope = blackboard_plan.create_blackboard()

    for child in get_children():
        var bt_player: BTPlayer = child.find_child("BTPlayer")
        if is_instance_valid(bt_player):
            bt_player.blackboard.set_parent(shared_scope)
```

--------------------------------

### Implement a Custom Subtree Decorator

Source: https://limboai.readthedocs.io/en/stable/classes/class_btsubtree.html

Use this pattern to create a custom decorator for loading and executing a BehaviorTree at runtime, which provides more flexibility than the standard BTSubtree.

```gdscript
extends BTDecorator
## MyCustomBranch

func _setup() -> void:
    var bt: BehaviorTree = load("res://...")
    var my_branch: BTTask = bt.get_root_task().clone()
    my_branch.initialize(agent, blackboard)
    add_child(my_branch)

func _tick(delta) -> Status:
    var child: BTTask = get_child(0)
    return child.execute(delta)
```

--------------------------------

### sync_with_base_plan

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboardplan.html

Synchronizes the current plan with its base plan.

```APIDOC
## void sync_with_base_plan()

### Description
Synchronizes this plan with the base plan: removes variables not present in the base plan, and updates type information. Only use this for custom tooling.
```

--------------------------------

### BTTimeLimit Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_bttimelimit.html

Methods for managing the time limit property of the BTTimeLimit decorator.

```APIDOC
## void set_time_limit(value: float)

### Description
Sets the time limit for the child task's execution.

### Parameters
- **value** (float) - Required - The duration in seconds to allocate for the child task.

---

## float get_time_limit()

### Description
Retrieves the current time limit set for the child task.

### Returns
- (float) - The current time limit in seconds.
```

--------------------------------

### BTDelay API

Source: https://limboai.readthedocs.io/en/stable/classes/class_btdelay.html

Methods for configuring the delay duration of the BTDelay decorator.

```APIDOC
## BTDelay

### Description
BTDelay is a decorator that introduces a delay of a specified number of seconds before executing its child task. It returns a RUNNING status during the delay period.

### Properties
- **seconds** (float) - The duration of the delay in seconds. Default is 1.0.

### Methods
- **set_seconds(value: float)** - Sets the delay duration in seconds.
- **get_seconds() -> float** - Returns the current delay duration in seconds.
```

--------------------------------

### BTCheckAgentProperty Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btcheckagentproperty.html

Methods for configuring the property check, including setting the check type, the property name, and the comparison value.

```APIDOC
## set_check_type(value: CheckType)
Sets the type of check to be performed.

## get_check_type() -> CheckType
Returns the current check type.

## set_property(value: StringName)
Sets the agent's property name to be compared.

## get_property() -> StringName
Returns the name of the property being checked.

## set_value(value: BBVariant)
Sets the value to compare against the agent's property.

## get_value() -> BBVariant
Returns the comparison value.
```

--------------------------------

### BTNewScope Properties

Source: https://limboai.readthedocs.io/en/stable/classes/class_btnewscope.html

Methods for managing the BlackboardPlan associated with the BTNewScope.

```APIDOC
## Property: blackboard_plan

### Description
Stores and manages variables that will be used in constructing new Blackboard instances.

### Methods
- **void set_blackboard_plan(value: BlackboardPlan)**: Sets the BlackboardPlan for this scope.
- **BlackboardPlan get_blackboard_plan()**: Returns the current BlackboardPlan.
```

--------------------------------

### link_var

Source: https://limboai.readthedocs.io/en/stable/classes/class_blackboard.html

Links a variable to another Blackboard variable so their states remain identical.

```APIDOC
## void link_var(var_name: StringName, target_blackboard: Blackboard, target_var: StringName, create: bool = false)

### Description
Links a variable to another Blackboard variable. Any change to one will be reflected in the other.
```

--------------------------------

### update

Source: https://limboai.readthedocs.io/en/stable/classes/class_btplayer.html

Executes the root task of the behavior tree.

```APIDOC
## void update(delta: float)

### Description
Executes the root task of the behavior tree instance if active is true. Call this method when update_mode is set to MANUAL.
```

--------------------------------

### BTTask Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_bttask.html

Methods available for interacting with BTTask instances in the behavior tree.

```APIDOC
## BTTask::get_child(idx: int)
Returns a child task by specifying its index.

## BTTask::get_child_count()
Returns the number of child tasks.

## BTTask::get_child_count_excluding_comments()
Returns the number of child tasks not counting BTComment tasks.

## BTTask::get_index()
Returns the task’s position in the behavior tree branch. Returns -1 if the task doesn’t belong to a task tree.

## BTTask::get_parent()
Returns the task’s parent.

## BTTask::get_root()
Returns the root task of the behavior tree.

## BTTask::get_task_name()
Returns the string used to represent the task in the editor.

## BTTask::has_child(task: BTTask)
Returns true if task is a child of this task.

## BTTask::initialize(agent: Node, blackboard: Blackboard, scene_root: Node)
Initializes the task, assigns agent and blackboard, and calls _setup for the task and its children.

## BTTask::is_descendant_of(task: BTTask)
Returns true if this task is a descendant of task.

## BTTask::is_root()
Returns true if this task is the root task of its behavior tree.

## BTTask::next_sibling()
Returns the next task after this task in the parent’s children list.

## BTTask::print_tree(initial_tabs: int = 0)
Prints the subtree that starts with this task to the console.

## BTTask::remove_child(task: BTTask)
Removes task from children.

## BTTask::remove_child_at_index(idx: int)
Removes a child task at a specified index from children.
```

--------------------------------

### Define a custom task in C#

Source: https://limboai.readthedocs.io/en/stable/behavior-trees/custom-tasks.html

Boilerplate template for creating custom behavior tree tasks using C#.

```C#
using Godot;
using System;

[Tool]
public partial class _CLASS_ : _BASE_
{
    public override string _GenerateName()
    {
        return "_CLASS_";
    }

    public override void _Setup()
    {
    }

    public override void _Enter()
    {
    }

    public override void _Exit()
    {
    }

    public override Status _Tick(double delta)
    {
        return Status.Success;
    }

    public override string[] _GetConfigurationWarnings()
    {
        return Array.Empty<string>();
    }
}
```

--------------------------------

### BTForEach Properties

Source: https://limboai.readthedocs.io/en/stable/classes/class_btforeach.html

Methods to manage the array and save variables used by the BTForEach decorator.

```APIDOC
## BTForEach Properties

### array_var
- **Type**: StringName
- **Description**: A variable within the Blackboard that holds an Array, which is used for the iteration process.
- **Methods**:
  - `void set_array_var(value: StringName)`
  - `StringName get_array_var()`

### save_var
- **Type**: StringName
- **Description**: A Blackboard variable used to store an element of the array referenced by array_var.
- **Methods**:
  - `void set_save_var(value: StringName)`
  - `StringName get_save_var()`
```

--------------------------------

### restart

Source: https://limboai.readthedocs.io/en/stable/classes/class_btplayer.html

Resets the behavior tree's execution.

```APIDOC
## void restart()

### Description
Resets the behavior tree's execution. Each running task will be aborted and the next tree execution will start anew. This method does not reset the Blackboard.
```

--------------------------------

### Define Custom State Behavior

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Extends LimboState to implement logic like playing animations and dispatching events upon completion.

```gdscript
extends LimboState
## PlayAnimation: Play an animation on AnimationPlayer, and wait for it to finish.

@export var animation_player: AnimationPlayer
@export var animation_name: StringName

func _enter() -> void:
    animation_player.play(animation_name)

func _update(_delta: float) -> void:
    if not animation_player.is_playing() \
            or animation_player.assigned_animation != animation_name:
        dispatch(EVENT_FINISHED)
```

--------------------------------

### BehaviorTree Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_behaviortree.html

Methods available for interacting with and managing BehaviorTree resources.

```APIDOC
## BehaviorTree::clone()

### Description
Makes a copy of the BehaviorTree resource.

## BehaviorTree::copy_other(other: BehaviorTree)

### Description
Become a copy of another behavior tree.

## BehaviorTree::get_root_task()

### Description
Returns the root task of the BehaviorTree resource.

## BehaviorTree::instantiate(agent: Node, blackboard: Blackboard, instance_owner: Node, custom_scene_root: Node = null)

### Description
Instantiates the behavior tree and returns a BTInstance. The instance_owner should be the scene node that will own the behavior tree instance.

## BehaviorTree::set_root_task(task: BTTask)

### Description
Assigns a new root task to the BehaviorTree resource.
```

--------------------------------

### BTConsolePrint Properties

Source: https://limboai.readthedocs.io/en/stable/classes/class_btconsoleprint.html

Methods for managing the text and format parameters of the BTConsolePrint action.

```APIDOC
## BTConsolePrint Methods

### set_text(value: String)
Sets the text to be printed, which can include placeholders (e.g., %s, %d, %f).

### get_text() -> String
Returns the current text string.

### set_bb_format_parameters(value: PackedStringArray)
Sets the values used as format arguments for the text placeholders.

### get_bb_format_parameters() -> PackedStringArray
Returns a copy of the current format parameters.
```

--------------------------------

### get_value(scene_root: Node, blackboard: Blackboard, default: Variant = null)

Source: https://limboai.readthedocs.io/en/stable/classes/class_bbparam.html

Retrieves the value of the parameter based on the configured value_source.

```APIDOC
## get_value

### Description
Returns the value of the parameter. Depending on the `value_source` property, this will either return the `saved_value` or look up the value in the provided `blackboard` using the `variable` name.

### Parameters
- **scene_root** (Node) - Required - The root node of the scene.
- **blackboard** (Blackboard) - Required - The Blackboard instance to retrieve variables from.
- **default** (Variant) - Optional - A default value to return if the variable is not found or if the source is invalid.

### Returns
- **Variant** - The resolved value of the parameter.
```

--------------------------------

### Accessing nodes using blackboard plan

Source: https://limboai.readthedocs.io/en/stable/_sources/behavior-trees/accessing-nodes.rst.txt

Retrieves a node reference from the blackboard that was automatically resolved from a NodePath variable.

```gdscript
extends BTCondition

@export var shape_var: StringName = &"shape_cast"

func _tick(delta) -> Status:
    var shape_cast: ShapeCast3D = blackboard.get_var(shape_var)
```

--------------------------------

### BTWaitTicks Class Reference

Source: https://limboai.readthedocs.io/en/stable/classes/class_btwaitticks.html

Methods for configuring the tick count for the BTWaitTicks action.

```APIDOC
## BTWaitTicks

### Description
A behavior tree action that waits for a specified number of ticks to elapse and then returns `SUCCESS`.

### Properties
- **num_ticks** (int) - The number of ticks to wait before returning `SUCCESS`. Default is 1.

### Methods
- **set_num_ticks(value: int)**: Sets the number of ticks to wait.
- **get_num_ticks() -> int**: Returns the current number of ticks configured for the wait.
```

--------------------------------

### BTProbabilitySelector API

Source: https://limboai.readthedocs.io/en/stable/classes/class_btprobabilityselector.html

Methods and properties for configuring and interacting with the BTProbabilitySelector behavior tree node.

```APIDOC
## Properties
- **abort_on_failure** (bool) - Determines if the selector returns FAILURE immediately when a child task fails.

## Methods
- **get_probability(child_idx: int) -> float** - Returns the selection probability for a specific child task.
- **get_total_weight() -> float** - Returns the sum of all weights assigned to child tasks.
- **get_weight(child_idx: int) -> float** - Returns the weight of a specific child task.
- **has_probability(child_idx: int) -> bool** - Checks if a child task participates in the probability selection.
- **set_probability(child_idx: int, probability: float) -> void** - Sets the weight of a child task based on a probability value.
- **set_weight(child_idx: int, weight: float) -> void** - Sets the weight of a child task for the selection algorithm.
- **set_abort_on_failure(value: bool) -> void** - Sets the abort_on_failure property.
- **get_abort_on_failure() -> bool** - Gets the current abort_on_failure property value.
```

--------------------------------

### BTRepeat Class Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_btrepeat.html

Methods for configuring the repetition behavior of the BTRepeat decorator.

```APIDOC
## void set_abort_on_failure(value: bool)

### Description
Sets whether the decorator should abort if the child task returns FAILURE.

### Parameters
- **value** (bool) - If false, a FAILURE status from the child is treated as a successful execution.

---

## bool get_abort_on_failure()

### Description
Returns the current abort_on_failure configuration.

---

## void set_forever(value: bool)

### Description
Sets whether the child task should be repeated indefinitely.

### Parameters
- **value** (bool) - If true, the task repeats indefinitely and returns RUNNING.

---

## bool get_forever()

### Description
Returns the current forever configuration.

---

## void set_times(value: int)

### Description
Sets the number of times to repeat the child task.

### Parameters
- **value** (int) - The number of iterations.

---

## int get_times()

### Description
Returns the configured number of repetitions.
```

--------------------------------

### State Anatomy Template

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Standard lifecycle methods available for overriding in a custom LimboState script.

```gdscript
extends LimboState

## Called once, when state is initialized.
func _setup() -> void:
    pass

## Called when state is entered.
func _enter() -> void:
    pass

## Called when state is exited.
func _exit() -> void:
    pass

## Called each frame when this state is active.
func _update(delta: float) -> void:
    pass
```

--------------------------------

### Retrieve a node using scene_root

Source: https://limboai.readthedocs.io/en/stable/classes/class_bttask.html

Demonstrates how to use the scene_root property to access a node within the scene tree using a NodePath.

```gdscript
extends BTAction

@export var node_path: NodePath

func _setup():
    var node: Node = scene_root.get_node(node_path)
```

--------------------------------

### Define a custom task structure in GDScript

Source: https://limboai.readthedocs.io/en/stable/behavior-trees/custom-tasks.html

Template showing the anatomy of a custom task, including optional lifecycle methods and configuration warnings.

```GDScript
@tool
extends BTAction

# Task parameters.
@export var parameter1: float
@export var parameter2: Vector2

## Note: Each method declaration is optional.
## At minimum, you only need to define the "_tick" method.


# Called to generate a display name for the task (requires @tool).
func _generate_name() -> String:
    return "MyTask"


# Called to initialize the task.
func _setup() -> void:
    pass


# Called when the task is entered.
func _enter() -> void:
    pass


# Called when the task is exited.
func _exit() -> void:
    pass


# Called each time this task is ticked (aka executed).
func _tick(delta: float) -> Status:
    return SUCCESS


# Strings returned from this method are displayed as warnings in the editor.
func _get_configuration_warnings() -> PackedStringArray:
    var warnings := PackedStringArray()
    return warnings
```

--------------------------------

### BehaviorTreeView API

Source: https://limboai.readthedocs.io/en/stable/classes/class_behaviortreeview.html

Methods and properties for interacting with the BehaviorTreeView component.

```APIDOC
## Properties

### update_interval_msec (int)
Minimum delay between two updates (in milliseconds). Set to higher values for a lower CPU load.

## Methods

### clear()
Clears the tree view.

### update_tree(behavior_tree_data: BehaviorTreeData)
Updates the representation of a BehaviorTree instance.

## Signals

### task_selected(type_name: String, script_path: String)
Emitted when a task item is selected in BehaviorTreeView.
```

--------------------------------

### LimboUtility Methods

Source: https://limboai.readthedocs.io/en/stable/classes/class_limboutility.html

Methods available in the LimboUtility class for formatting, status retrieval, and operations.

```APIDOC
## String decorate_output_var(variable: String)
Produces a string with a Blackboard variable name formatted for display, including an additional symbol to indicate it is an output variable.

## String decorate_var(variable: String)
Produces a string with a Blackboard variable name formatted for display or console output.

## String get_check_operator_string(check: CheckType)
Returns an operator string (e.g., "==") for a given CheckType enum value.

## String get_operation_string(operation: Operation)
Returns a string representation of a given Operation enum value.

## String get_status_name(status: int)
Returns the name associated with a BTTask status code.

## Texture2D get_task_icon(class_or_script_path: String)
Returns the icon texture associated with a task based on its class name or script resource path.

## bool perform_check(check: CheckType, a: Variant, b: Variant)
Performs a check on two values and returns true if the condition passes.

## Variant perform_operation(operation: Operation, a: Variant, b: Variant)
Performs an arithmetic or bitwise operation on two values and returns the result.
```

--------------------------------

### Register Transitions with Events

Source: https://limboai.readthedocs.io/en/stable/_sources/hierarchical-state-machines/create-hsm.rst.txt

Associates transitions with specific events, including support for global ANYSTATE transitions.

```gdscript
hsm.add_transition(idle_state, move_state, &"movement_started")
```

```gdscript
hsm.add_transition(hsm.ANYSTATE, move_state, &"movement_started")
```
Tokens:
Raw