### Single-File State Machine Setup with Chained Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/hierarchical-state-machines/create-hsm.md This example shows how to set up a LimboHSM in a single file using chained methods for state creation and configuration. It includes defining states, transitions, and update functions for character movement. ```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") ``` -------------------------------- ### Initialize LimboHSM Source: https://github.com/limbonaut/limboai/blob/master/doc/source/hierarchical-state-machines/create-hsm.md Set up the state machine and define transitions within the _ready function. ```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) ``` -------------------------------- ### Get Root State in LimboState Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_limbostate.md Returns the root LimboState of the state machine hierarchy. ```gdscript get_root() -> LimboState ``` -------------------------------- ### Blackboard Variable Management Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboard.md Methods for setting, getting, checking, and removing variables within the Blackboard scope. ```APIDOC ## set_var(var_name: StringName, value: Variant) ### Description Assigns a value to a variable in the current Blackboard scope. If the variable doesn't exist, it will be created. If the variable exists in the parent scope, the parent scope value remains unchanged. ## get_var(var_name: StringName, default: Variant = null, complain: bool = true) ### Description Returns the variable value or the default if it doesn't exist. Searches parent scopes if not found in the current scope. ## has_var(var_name: StringName) ### Description Returns true if the variable exists, including in parent scopes. ## erase_var(var_name: StringName) ### Description Removes a variable by its name. ``` -------------------------------- ### BTInstance Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btinstance.md Lists and describes the methods available for interacting with BTInstance objects. ```APIDOC ## Methods | `Node` | [get_agent](#class-btinstance-method-get-agent)() | |----------------------------------------------------|---------------------------------------------------------------------------------| | [Blackboard](class_blackboard.md#class-blackboard) | [get_blackboard](#class-btinstance-method-get-blackboard)() | | [Status](class_bt.md#enum-bt-status) | [get_last_status](#class-btinstance-method-get-last-status)() | | `Node` | [get_owner_node](#class-btinstance-method-get-owner-node)() | | [BTTask](class_bttask.md#class-bttask) | [get_root_task](#class-btinstance-method-get-root-task)() | | `String` | [get_source_bt_path](#class-btinstance-method-get-source-bt-path)() | | `bool` | [is_instance_valid](#class-btinstance-method-is-instance-valid)() | | | [register_with_debugger](#class-btinstance-method-register-with-debugger)() | | | [unregister_with_debugger](#class-btinstance-method-unregister-with-debugger)() | | [Status](class_bt.md#enum-bt-status) | [update](#class-btinstance-method-update)(delta: `float`) | ``` -------------------------------- ### BTInstance Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btinstance.md Provides an overview of the BTInstance class, its inheritance, and its primary purpose. ```APIDOC ## BTInstance **Inherits:** Represents a runtime instance of a [BehaviorTree](class_behaviortree.md#class-behaviortree) resource. Can be created using the [BehaviorTree.instantiate](class_behaviortree.md#class-behaviortree-method-instantiate) method. ``` -------------------------------- ### BTInstance Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btinstance.md Methods for retrieving instance properties and managing the behavior tree lifecycle. ```APIDOC ## GET get_agent ### Description Returns the agent of the behavior tree instance. ### Method GET ### Endpoint get_agent() ### Response - **Node** - The agent node. ## GET get_blackboard ### Description Returns the blackboard of the behavior tree instance. ### Method GET ### Endpoint get_blackboard() ### Response - **Blackboard** - The instance blackboard. ## GET get_last_status ### Description Returns the execution status of the last update. ### Method GET ### Endpoint get_last_status() ### Response - **Status** - The last execution status. ## GET get_owner_node ### Description Returns the scene Node that owns this behavior tree instance. ### Method GET ### Endpoint get_owner_node() ### Response - **Node** - The owner node. ## GET get_root_task ### Description Returns the root task of the behavior tree instance. ### Method GET ### Endpoint get_root_task() ### Response - **BTTask** - The root task. ## GET get_source_bt_path ### Description Returns the file path to the behavior tree resource that was used to create this instance. ### Method GET ### Endpoint get_source_bt_path() ### Response - **String** - The file path. ## GET is_instance_valid ### Description Returns true if the behavior tree instance is properly initialized and can be used. ### Method GET ### Endpoint is_instance_valid() ### Response - **bool** - Validity status. ## POST register_with_debugger ### Description Registers the behavior tree instance with the debugger. ### Method POST ### Endpoint register_with_debugger() ## POST unregister_with_debugger ### Description Unregisters the behavior tree instance from the debugger. ### Method POST ### Endpoint unregister_with_debugger() ## POST update ### Description Ticks the behavior tree instance and returns its status. ### Method POST ### Endpoint update(delta: float) ### Parameters #### Request Body - **delta** (float) - Required - The time delta for the update. ### Response - **Status** - The status after the update. ``` -------------------------------- ### LimboState Lifecycle Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_limbostate.md Core lifecycle methods for LimboState: _setup for initialization, _enter when entering the state, _update for behavior during updates, and _exit when leaving the state. ```gdscript _setup() ``` ```gdscript _enter() ``` ```gdscript _update(delta: float) ``` ```gdscript _exit() ``` -------------------------------- ### Create and Configure BTState in LimboHSM Source: https://github.com/limbonaut/limboai/blob/master/doc/source/hierarchical-state-machines/create-hsm.md This snippet demonstrates how to create a BTState, assign a BehaviorTree to it, and integrate it into a LimboHSM. Ensure the BehaviorTree resource is correctly assigned and the scene root hint is set. ```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) ``` -------------------------------- ### BlackboardPlan Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboardplan.md Methods for interacting with and managing BlackboardPlan instances. ```APIDOC ## Method: create_blackboard ### Description Creates a new [Blackboard](class_blackboard.md#class-blackboard) instance based on this plan. ### Parameters - **prefetch_root** (`Node`) - Required - The root node for prefetching. - **parent_scope** ([Blackboard](class_blackboard.md#class-blackboard)) - Optional - The parent scope for the new blackboard. - **prefetch_root_for_base_plan** (`Node`) - Optional - The root node for prefetching for the base plan. ### Returns - [Blackboard](class_blackboard.md#class-blackboard) - The newly created Blackboard instance. ``` ```APIDOC ## Method: get_base_plan ### Description Retrieves the base [BlackboardPlan](class_blackboardplan.md#class-blackboardplan) associated with this plan. ### Returns - [BlackboardPlan](class_blackboardplan.md#class-blackboardplan) - The base plan. ``` ```APIDOC ## Method: get_parent_scope_plan_provider ### Description Retrieves the callable provider for the parent scope's plan. ### Returns - `Callable` - The callable provider for the parent scope's plan. ``` ```APIDOC ## Method: is_derived ### Description Checks if this [BlackboardPlan](class_blackboardplan.md#class-blackboardplan) is derived from another plan. ### Returns - `bool` - `true` if derived, `false` otherwise. ``` ```APIDOC ## Method: populate_blackboard ### Description Populates an existing [Blackboard](class_blackboard.md#class-blackboard) instance with variables from this plan. ### Parameters - **blackboard** ([Blackboard](class_blackboard.md#class-blackboard)) - Required - The blackboard instance to populate. - **overwrite** (`bool`) - Required - Whether to overwrite existing variables. - **prefetch_root** (`Node`) - Required - The root node for prefetching. - **prefetch_root_for_base_plan** (`Node`) - Optional - The root node for prefetching for the base plan. ``` ```APIDOC ## Method: set_base_plan ### Description Sets the base [BlackboardPlan](class_blackboardplan.md#class-blackboardplan) for this plan. ### Parameters - **blackboard_plan** ([BlackboardPlan](class_blackboardplan.md#class-blackboardplan)) - Required - The base plan to set. ``` ```APIDOC ## Method: set_parent_scope_plan_provider ### Description Sets the callable provider for the parent scope's plan. ### Parameters - **callable** (`Callable`) - Required - The callable provider for the parent scope's plan. ``` ```APIDOC ## Method: sync_with_base_plan ### Description Synchronizes this plan with its base plan. ``` -------------------------------- ### BlackboardPlan Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboardplan.md This section covers various methods for managing BlackboardPlan instances. ```APIDOC ## BlackboardPlan Methods ### create_blackboard 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. ### get_base_plan Returns the base plan. ### get_parent_scope_plan_provider Returns the parent scope plan provider - a callable that returns a BlackboardPlan. ### is_derived Returns true if this plan is derived from another, i.e., the base plan is not null. A derived plan can only contain variables that are present in the base plan, and only variable values can be different. ### populate_blackboard 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. ### set_base_plan 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. ### set_parent_scope_plan_provider Sets the parent scope plan provider - a callable that returns a BlackboardPlan. Used to provide hints in the inspector. When set, mapping feature becomes available. ### sync_with_base_plan 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. ``` -------------------------------- ### BTForEach Node Configuration Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btforeach.md Configure the BTForEach node to iterate over an array and store elements in a Blackboard variable. ```APIDOC ## BTForEach ### Description BT decorator that executes its child task for each element of an `Array`. BTForEach executes its child task for each element of an `Array`. During each iteration, the next element is stored in the specified [Blackboard](class_blackboard.md#class-blackboard) variable. Returns `RUNNING` if the child task results in `RUNNING` or if the child task results in `SUCCESS` on a non-last iteration. Returns `FAILURE` if the child task results in `FAILURE`. Returns `SUCCESS` if the child task results in `SUCCESS` on the last iteration. ### Method N/A (This is a node configuration, not an API endpoint) ### Endpoint N/A ### Properties #### Blackboard Variables - **array_var** (StringName) - Required - The name of the Blackboard variable holding the array to iterate over. - **save_var** (StringName) - Required - The name of the Blackboard variable to store the current array element in during iteration. ### Request Example N/A ### Response N/A ``` -------------------------------- ### LimboState Configuration and Utility Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_limbostate.md Methods for configuring state behavior, chaining calls, and retrieving state information. ```APIDOC ## call_on_enter(callable: Callable) -> LimboState ### Description A chained method that connects the `entered` signal to a `callable`. ### Method public ### Endpoint N/A ### Parameters - **callable** (Callable) - The function to call when the state is entered. ### Request Example None ### Response - **return value** (LimboState) - The current LimboState instance for chaining. ## call_on_exit(callable: Callable) -> LimboState ### Description A chained method that connects the `exited` signal to a `callable`. ### Method public ### Endpoint N/A ### Parameters - **callable** (Callable) - The function to call when the state is exited. ### Request Example None ### Response - **return value** (LimboState) - The current LimboState instance for chaining. ## call_on_update(callable: Callable) -> LimboState ### Description A chained method that connects the `updated` signal to a `callable`. ### Method public ### Endpoint N/A ### Parameters - **callable** (Callable) - The function to call during the update. ### Request Example None ### Response - **return value** (LimboState) - The current LimboState instance for chaining. ## clear_guard() ### Description Clears the guard function, removing the `Callable` previously set by `set_guard`. ### Method public ### Endpoint N/A ### Parameters None ### Request Example None ### Response None ## get_root() -> LimboState ### Description Returns the root **LimboState**. ### Method public ### Endpoint N/A ### Parameters None ### Request Example None ### Response - **return value** (LimboState) - The root LimboState. ## is_active() -> bool ### Description Returns `true` if it is currently active, meaning it is the active substate of the parent [LimboHSM](class_limbohsm.md#class-limbohsm). ### Method public ### Endpoint N/A ### Parameters None ### Request Example None ### Response - **return value** (bool) - `true` if the state is active, `false` otherwise. ## named(name: String) -> LimboState ### Description A chained method for setting the name of this state. ### Method public ### Endpoint N/A ### Parameters - **name** (String) - The desired name for the state. ### Request Example None ### Response - **return value** (LimboState) - The current LimboState instance for chaining. ## set_guard(guard_callable: Callable) ### Description Sets the guard function, which is a function called each time a transition to this state is considered. If the function returns `false`, the transition will be disallowed. ### Method public ### Endpoint N/A ### Parameters - **guard_callable** (Callable) - The function to use as a guard. ### Request Example None ### Response None ``` -------------------------------- ### Add Local NuGet Source for LimboAI Source: https://github.com/limbonaut/limboai/blob/master/doc/source/getting-started/c-sharp.md Use this command in your terminal to add the local LimboAI NuGet package directory as a source for your .NET project. Replace 'path/to/limboai/nupkgs' with the actual path to your NuGet packages. ```shell dotnet nuget add source path/to/limboai/nupkgs --name LimboNugetSource ``` -------------------------------- ### BTTask Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_bttask.md Provides an overview of the BTTask class, its inheritance, and its role in the Behavior Tree system. ```APIDOC ## BTTask **Inherits:** [BT](class_bt.md#class-bt) **Inherited By:** [BTAction](class_btaction.md#class-btaction), [BTComment](class_btcomment.md#class-btcomment), [BTComposite](class_btcomposite.md#class-btcomposite), [BTCondition](class_btcondition.md#class-btcondition), [BTDecorator](class_btdecorator.md#class-btdecorator) ### Description Base class for all [BehaviorTree](class_behaviortree.md#class-behaviortree) tasks. A task is a basic building block in a [BehaviorTree](class_behaviortree.md#class-behaviortree) that represents a specific behavior or control flow. Tasks are used to create complex behaviors by combining and nesting them in a hierarchy. A task can be one of the following types: action, condition, composite, or decorator. Each type of task has its own corresponding subclass: [BTAction](class_btaction.md#class-btaction), [BTCondition](class_btcondition.md#class-btcondition), [BTDecorator](class_btdecorator.md#class-btdecorator), [BTComposite](class_btcomposite.md#class-btcomposite). Tasks perform their work and return their status using the [\_tick](#class-bttask-private-method-tick) method. Status values are defined in [Status](class_bt.md#enum-bt-status). Tasks can be initialized using the [\_setup](#class-bttask-private-method-setup) method. See also [\_enter](#class-bttask-private-method-enter) & [\_exit](#class-bttask-private-method-exit). **Note:** Do not extend **BTTask** directly for your own tasks. Instead, extend one of the subtypes mentioned above. ### Properties | `Node` | [agent](#class-bttask-property-agent) | | |----------------------------------------------------|-----------------------------------------------------|------| | [Blackboard](class_blackboard.md#class-blackboard) | [blackboard](#class-bttask-property-blackboard) | | | `String` | [custom_name](#class-bttask-property-custom-name) | `""` | | `float` | [elapsed_time](#class-bttask-property-elapsed-time) | | | `Node` | [scene_root](#class-bttask-property-scene-root) | | | [Status](class_bt.md#enum-bt-status) | [status](#class-bttask-property-status) | | ``` -------------------------------- ### BTStopAnimation Class Reference Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btstopanimation.md Documentation for the BTStopAnimation behavior tree task, including properties for controlling animation playback. ```APIDOC ## BTStopAnimation ### Description BTStopAnimation is a BT action that stops the playback of an animation on a specified AnimationPlayer node. It returns SUCCESS upon completion or FAILURE if the AnimationPlayer node cannot be accessed. ### Properties - **animation_name** (StringName) - The key of the animation within the AnimationPlayer. If provided, the action only stops the animation if it is currently playing. - **animation_player** (BBNode) - The target AnimationPlayer node to control. - **keep_state** (bool) - If true, the animation state is not updated visually when stopped. ### Methods - **set_animation_name(value: StringName)**: Sets the animation name to target. - **get_animation_name() -> StringName**: Returns the currently set animation name. - **set_animation_player(value: BBNode)**: Sets the target AnimationPlayer node. - **get_animation_player() -> BBNode**: Returns the target AnimationPlayer node. - **set_keep_state(value: bool)**: Sets whether to keep the animation state visually. - **get_keep_state() -> bool**: Returns the current keep_state setting. ``` -------------------------------- ### LimboHSM Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_limbohsm.md API methods for controlling state machine transitions, initialization, and state queries. ```APIDOC ## add_transition ### Description Establishes a transition from one state to another when an event is dispatched. ### Parameters - **from_state** (LimboState) - Required - The source state. - **to_state** (LimboState) - Required - The destination state. - **event** (StringName) - Required - The event triggering the transition. - **guard** (Callable) - Optional - A function returning a boolean to validate the transition. --- ## change_active_state ### Description Changes the currently active substate to the specified state. ### Parameters - **state** (LimboState) - Required - The state to activate. --- ## get_active_state ### Description Returns the currently active substate. --- ## get_leaf_state ### Description Returns the currently active leaf state within the state machine. --- ## get_previous_active_state ### Description Returns the previously active substate. --- ## has_transition ### Description Returns true if there is a transition from a state for a given event. ### Parameters - **from_state** (LimboState) - Required - The source state. - **event** (StringName) - Required - The event to check. --- ## initialize ### Description Initiates the state and calls _setup for itself and all substates. ### Parameters - **agent** (Node) - Required - The agent node. - **parent_scope** (Blackboard) - Optional - The blackboard scope. --- ## remove_transition ### Description Removes a transition from a state associated with a specific event. ### Parameters - **from_state** (LimboState) - Required - The source state. - **event** (StringName) - Required - The event to remove. --- ## set_active ### Description Switches the state to the initial state and activates processing. ### Parameters - **active** (bool) - Required - Whether to activate the state machine. --- ## update ### Description Calls _update on itself and the active substate. ### Parameters - **delta** (float) - Required - Time elapsed since the last frame. ``` -------------------------------- ### Build GDExtension Library with SCons Source: https://github.com/limbonaut/limboai/blob/master/doc/source/getting-started/contributing.md Compile the LimboAI plugin library for your current platform using SCons. SCons will automatically handle cloning the godot-cpp repository if necessary. ```bash scons target=editor ``` -------------------------------- ### Access Node Using Blackboard Plan Source: https://github.com/limbonaut/limboai/blob/master/doc/source/behavior-trees/accessing-nodes.md Retrieve a node instance from the blackboard using a StringName variable. Ensure the blackboard variable is of type NodePath and that `BTPlayer.prefetch_nodepath_vars` is set to true. ```gdscript extends BTCondition @export var shape_var: StringName = &"shape_cast" func _tick(delta) -> Status: var shape_cast: ShapeCast3D = blackboard.get_var(shape_var) ``` -------------------------------- ### create_from_bt_instance Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_behaviortreedata.md Creates a BehaviorTreeData object from a given BTInstance. ```APIDOC ## create_from_bt_instance ### Description Returns the current state of the provided bt_instance encoded as a BehaviorTreeData object, which is suitable for use with BehaviorTreeView. ### Parameters - **bt_instance** (BTInstance) - Required - The behavior tree instance to capture, typically acquired via BTPlayer.get_bt_instance. ### Response - **BehaviorTreeData** - The captured state of the behavior tree instance. ``` -------------------------------- ### BTTask Properties and Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_bttask.md Overview of the core properties and utility methods available for BTTask instances. ```APIDOC ## BTTask API ### Properties - **agent** (Node) - The contextual object for the BehaviorTree instance. - **blackboard** (Blackboard) - Provides access to the Blackboard for sharing data among tasks. - **custom_name** (String) - User-provided name for the task used by the editor. - **elapsed_time** (float) - Elapsed time since the task was entered; returns 0 if not RUNNING. - **scene_root** (Node) - Root node of the scene where the behavior tree is used. - **status** (Status) - The last execution status returned by the task. ### Methods - **is_root()** -> bool: Returns true if the task is the root of the tree. - **next_sibling()** -> BTTask: Returns the next sibling task. - **print_tree(initial_tabs: int = 0)**: Prints the task tree structure. - **remove_child(task: BTTask)**: Removes a specific child task. - **remove_child_at_index(idx: int)**: Removes a child task at the specified index. ``` -------------------------------- ### BTState Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btstate.md Methods available for interacting with the BTState node and its behavior tree instance. ```APIDOC ## BTState Methods ### get_bt_instance - **Returns**: [BTInstance](class_btinstance.md#class-btinstance) - **Description**: Returns the behavior tree instance managed by this state. ### set_scene_root_hint - **Parameters**: - **scene_root** (`Node`) - The node to be used as the scene root for the behavior tree instance. - **Description**: Sets the `Node` that will be used as the scene root for the newly instantiated behavior tree. Should be called before the state machine is initialized. This is typically useful when creating **BTState** nodes dynamically from code. ``` -------------------------------- ### BTInstance Properties Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btinstance.md Details the properties available for BTInstance objects. ```APIDOC ## Properties | `bool` | [monitor_performance](#class-btinstance-property-monitor-performance) | `false` | |----------|-------------------------------------------------------------------------|-----------| ### Property Descriptions `bool` **monitor_performance** = `false` [🔗](#class-btinstance-property-monitor-performance) - **set_monitor_performance**(value: `bool`) - `bool` **get_monitor_performance**() If `true`, adds a performance monitor for this instance to “Debugger->Monitors” in the editor. ``` -------------------------------- ### BehaviorTreeView Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_behaviortreeview.md Provides an overview of the BehaviorTreeView class, its inheritance, and its primary function. ```APIDOC ## BehaviorTreeView **Inherits:** Visualizes the current state of a [BehaviorTree](class_behaviortree.md#class-behaviortree) instance. ### Description Visualizes the current state of a [BehaviorTree](class_behaviortree.md#class-behaviortree) instance. See also [BehaviorTreeData](class_behaviortreedata.md#class-behaviortreedata). ``` -------------------------------- ### Blackboard Utility Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboard.md Methods for bulk operations and debugging the Blackboard state. ```APIDOC ## get_vars_as_dict() ### Description Returns all variables in the current scope as a dictionary. ## populate_from_dict(dictionary: Dictionary) ### Description Fills the Blackboard with multiple variables from a provided dictionary. ## clear() ### Description Removes all variables from the current Blackboard scope. ``` -------------------------------- ### BTConsolePrint - Output Text to Console Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btconsoleprint.md The BTConsolePrint action task prints a specified text to the console. It supports format arguments similar to GDScript's % operator. ```APIDOC ## BTConsolePrint ### Description BT action task that outputs text to the console. BTConsolePrint action outputs text to the console and returns `SUCCESS`. It can include placeholders for format arguments similar to GDScript’s % operator. ### Properties - **text** (String) - The text to be printed, which can include multiple placeholders to be substituted with format arguments. These placeholders follow the same format as GDScript’s % operator and typically start with ‘%’ followed by a format specifier. For instance: %s for string, %d for integer, %f for real. - **bb_format_parameters** (PackedStringArray) - The values of format parameters are used as format arguments for the text that will be printed. ### Example Usage ```gdscript var print_task = BTConsolePrint.new() print_task.text = "Processing item: %s with ID: %d" print_task.bb_format_parameters = ["Apple", 123] # The console will output: Processing item: Apple with ID: 123 ``` ``` -------------------------------- ### BTPlayer Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btplayer.md Methods available on the BTPlayer node for controlling and interacting with the behavior tree. ```APIDOC ## BTPlayer Methods ### get_bt_instance - **Description**: Returns the current BTInstance associated with this player. - **Returns**: `BTInstance` ### restart - **Description**: Restarts the behavior tree execution. ### set_bt_instance - **Description**: Sets a custom BTInstance for this player. - **Parameters**: - **bt_instance** (`BTInstance`) - The BTInstance to set. ### set_scene_root_hint - **Description**: Provides a hint for the scene root node, which can be used by the behavior tree. - **Parameters**: - **scene_root** (`Node`) - The scene root node. ``` -------------------------------- ### BTDynamicSequence Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btdynamicsequence.md Details regarding the BTDynamicSequence behavior tree task, its inheritance, and execution logic. ```APIDOC ## BTDynamicSequence ### Description BT composite that executes tasks from scratch every tick as long as they return SUCCESS. Unlike BTSequence, it re-evaluates preceding tasks on every tick, making it useful for rechecking conditions during long-running actions. ### Inheritance - BTComposite - BTTask - BT ### Execution Logic - Returns RUNNING if a child task results in RUNNING. - Returns FAILURE if a child task results in FAILURE. - Returns SUCCESS if all child tasks result in SUCCESS. - On each tick, it re-executes tasks from the beginning. If a preceding task fails, it aborts the previously remembered RUNNING task. ``` -------------------------------- ### BTTask Tree Navigation and Querying Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_bttask.md Methods for retrieving task hierarchy information and tree structure status. ```APIDOC ## get_index ### Description Returns the task’s position in the behavior tree branch. Returns -1 if the task doesn’t belong to a task tree. ### Method GET ### Endpoint get_index() ### Response - **return** (int) - The index of the task. ## get_parent ### Description Returns the task’s parent. ### Method GET ### Endpoint get_parent() ### Response - **return** (BTTask) - The parent task. ## get_root ### Description Returns the root task of the behavior tree. ### Method GET ### Endpoint get_root() ### Response - **return** (BTTask) - The root task. ## is_root ### Description Returns true if this task is the root task of its behavior tree. ### Method GET ### Endpoint is_root() ### Response - **return** (bool) - True if root, false otherwise. ``` -------------------------------- ### BTInstance Signals Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_btinstance.md Details the signals emitted by BTInstance objects. ```APIDOC --- ## Signals **freed**() [🔗](#class-btinstance-signal-freed) Emitted when the behavior tree instance is freed. Used by debugger to unregister. --- **updated**(status: `int`) [🔗](#class-btinstance-signal-updated) Emitted when the behavior tree instance has finished updating. ``` -------------------------------- ### Register State Transitions Source: https://github.com/limbonaut/limboai/blob/master/doc/source/hierarchical-state-machines/create-hsm.md Configure transitions between states using specific events or the ANYSTATE wildcard. ```gdscript hsm.add_transition(idle_state, move_state, &"movement_started") ``` ```gdscript hsm.add_transition(hsm.ANYSTATE, move_state, &"movement_started") ``` -------------------------------- ### Blackboard Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboard.md Provides a general overview of the Blackboard's functionality and its role in the LimboAI system. ```APIDOC ## Blackboard ### Description A key/value storage for sharing among [LimboHSM](class_limbohsm.md#class-limbohsm) states and [BehaviorTree](class_behaviortree.md#class-behaviortree) tasks. Blackboard is where data is stored and shared between states in the [LimboHSM](class_limbohsm.md#class-limbohsm) system and tasks in a [BehaviorTree](class_behaviortree.md#class-behaviortree). Each state and task in the [BehaviorTree](class_behaviortree.md#class-behaviortree) can access this Blackboard, allowing them to read and write data. This makes it easy to share information between different actions and behaviors. Blackboard can also act as a parent scope for another Blackboard. If a specific variable is not found in the active scope, it looks in the parent Blackboard to find it. A parent Blackboard can itself have its own parent scope, forming what we call a “blackboard scope chain.” Importantly, there is no limit to how many Blackboards can be in this chain, and the Blackboard doesn’t modify values in the parent scopes. New scopes can be created using the [BTNewScope](class_btnewscope.md#class-btnewscope) and [BTSubtree](class_btsubtree.md#class-btsubtree) decorators. Additionally, a new scope is automatically created for any [LimboState](class_limbostate.md#class-limbostate) that has defined non-empty Blackboard data or for any root-level [LimboHSM](class_limbohsm.md#class-limbohsm) node. ``` -------------------------------- ### Clone Godot and LimboAI Repositories Source: https://github.com/limbonaut/limboai/blob/master/doc/source/getting-started/contributing.md Clone the Godot Engine and LimboAI repositories to set up the project for building as a Godot Engine module. Ensure you checkout the correct stable tag for Godot. ```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 ``` -------------------------------- ### BehaviorTree Class Overview Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_behaviortree.md Provides an overview of the BehaviorTree class, its purpose, and core concepts. ```APIDOC ## BehaviorTree **Inherits:** Contains Behavior Tree data. ### Description Behavior Trees are hierarchical structures used to model and control the behavior of agents in a game (e.g., characters, enemies, entities). They are designed to make it easier to create complex and highly modular behaviors for your games. Behavior Trees are composed of tasks that represent specific actions or decision-making rules. Tasks can be broadly categorized into two main types: control tasks and leaf tasks. Control tasks determine the execution flow within the tree. They include [BTSequence](class_btsequence.md#class-btsequence), [BTSelector](class_btselector.md#class-btselector), and [BTInvert](class_btinvert.md#class-btinvert). Leaf tasks represent specific actions to perform, like moving or attacking, or conditions that need to be checked. The [BTTask](class_bttask.md#class-bttask) class provides the foundation for various building blocks of the Behavior Trees. BT tasks can share data with the help of [Blackboard](class_blackboard.md#class-blackboard). See [BTTask.blackboard](class_bttask.md#class-bttask-property-blackboard) and [Blackboard](class_blackboard.md#class-blackboard). **Note:** To create your own actions, extend the [BTAction](class_btaction.md#class-btaction) class. The BehaviorTree is executed from the root task and follows the rules specified by the control tasks, all the way down to the leaf tasks, which represent the actual actions that the agent should perform or conditions that should be checked. Each task returns a status when it is executed. It can be `SUCCESS`, `RUNNING`, or `FAILURE`. These statuses determine how the tree progresses. They are defined in [Status](class_bt.md#enum-bt-status). Behavior Trees handle conditional logic using condition tasks. These tasks check for specific conditions and return either `SUCCESS` or `FAILURE` based on the state of the agent or its environment (e.g., “IsLowOnHealth”, “IsTargetInSight”). Conditions can be used together with [BTSequence](class_btsequence.md#class-btsequence) and [BTSelector](class_btselector.md#class-btselector) to craft your decision-making logic. **Note**: To create your own conditions, extend the [BTCondition](class_btcondition.md#class-btcondition) class. Check out the [BTTask](class_bttask.md#class-bttask) class, which provides the foundation for various building blocks of Behavior Trees. ``` -------------------------------- ### BTTask Class Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_bttask.md This section outlines the available methods for interacting with and managing BTTask instances within a Behavior Tree. ```APIDOC ## BTTask Class Methods ### Description Provides a comprehensive list of methods for managing Behavior Tree tasks, including initialization, execution, child management, and state checking. ### Methods - **`_enter()`**: Private method for entering a task. - **`_exit()`**: Private method for exiting a task. - **`_generate_name()`**: Private method to generate a task name. - **`_get_configuration_warnings()`**: Private method to retrieve configuration warnings. - **`_setup(agent: Node, blackboard: Blackboard, scene_root: Node)`**: Private method for task setup. - **`_tick(delta: float)`**: Private method to tick the task, returning its status. - **`abort()`**: Aborts the current task. - **`add_child(task: BTTask)`**: Adds a child task to the current task. - **`add_child_at_index(task: BTTask, idx: int)`**: Adds a child task at a specific index. - **`clone()`**: Creates a clone of the current task. - **`editor_get_behavior_tree()`**: Retrieves the Behavior Tree associated with this task (editor-only). - **`execute(delta: float)`**: Executes the task's logic for a given delta time, returning its status. - **`get_child(idx: int)`**: Retrieves a child task by its index. - **`get_child_count()`**: Gets the total number of child tasks. - **`get_child_count_excluding_comments()`**: Gets the number of child tasks, excluding comments. - **`get_index()`**: Gets the index of the current task within its parent. - **`get_parent()`**: Retrieves the parent task of the current task. - **`get_root()`**: Retrieves the root task of the Behavior Tree. - **`get_task_name()`**: Gets the name of the task. - **`has_child(task: BTTask)`**: Checks if the task has a specific child task. - **`initialize(agent: Node, blackboard: Blackboard, scene_root: Node)`**: Initializes the task with agent, blackboard, and scene root. - **`is_descendant_of(task: BTTask)`**: Checks if the current task is a descendant of another task. ### Return Types - `_generate_name()`: `String` - `_get_configuration_warnings()`: `PackedStringArray` - `_tick(delta: float)`: `Status` (enum BTStatus) - `clone()`: `BTTask` - `editor_get_behavior_tree()`: `BehaviorTree` - `execute(delta: float)`: `Status` (enum BTStatus) - `get_child(idx: int)`: `BTTask` - `get_child_count()`: `int` - `get_child_count_excluding_comments()`: `int` - `get_index()`: `int` - `get_parent()`: `BTTask` - `get_root()`: `BTTask` - `get_task_name()`: `String` - `has_child(task: BTTask)`: `bool` - `is_descendant_of(task: BTTask)`: `bool` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) Responses vary based on the method called. Refer to the 'Return Types' section for details. #### Response Example None ``` -------------------------------- ### Blackboard Methods Source: https://github.com/limbonaut/limboai/blob/master/doc/source/classes/class_blackboard.md This section covers the core methods for managing variables within the Blackboard. ```APIDOC ## Blackboard Methods ### bind_var_to_property Binds a variable to an object's property. ### Method `bind_var_to_property(var_name: StringName, object: Object, property: StringName, create: bool = false)` ### Parameters - **var_name** (StringName) - The name of the variable to bind. - **object** (Object) - The object whose property will be bound. - **property** (StringName) - The name of the property to bind to. - **create** (bool, optional) - If true, creates the property if it doesn't exist. Defaults to false. ### set_var Sets the value of a variable in the Blackboard. ### Method `set_var(var_name: StringName, value: Variant)` ### Parameters - **var_name** (StringName) - The name of the variable to set. - **value** (Variant) - The value to assign to the variable. ### get_var Retrieves the value of a variable from the Blackboard. ### Method `get_var(var_name: StringName, default: Variant = null, complain: bool = true) -> Variant` ### Parameters - **var_name** (StringName) - The name of the variable to retrieve. - **default** (Variant, optional) - The default value to return if the variable is not found. Defaults to null. - **complain** (bool, optional) - If true, will print an error if the variable is not found. Defaults to true. ### has_var Checks if a variable exists in the Blackboard. ### Method `has_var(var_name: StringName) -> bool` ### Parameters - **var_name** (StringName) - The name of the variable to check. ### erase_var Removes a variable from the Blackboard. ### Method `erase_var(var_name: StringName)` ### Parameters - **var_name** (StringName) - The name of the variable to erase. ### list_vars Returns a list of all variable names currently in the Blackboard. ### Method `list_vars() -> Array[StringName]` ### get_vars_as_dict Returns all variables in the Blackboard as a Dictionary. ### Method `get_vars_as_dict() -> Dictionary` ### populate_from_dict Populates the Blackboard with variables from a Dictionary. ### Method `populate_from_dict(dictionary: Dictionary)` ### Parameters - **dictionary** (Dictionary) - The dictionary containing variables to add. ### clear Removes all variables from the Blackboard. ### Method `clear()` ### link_var Links a variable to another variable in a different Blackboard. ### Method `link_var(var_name: StringName, target_blackboard: Blackboard, target_var: StringName, create: bool = false)` ### Parameters - **var_name** (StringName) - The name of the variable to link. - **target_blackboard** (Blackboard) - The Blackboard containing the target variable. - **target_var** (StringName) - The name of the target variable. - **create** (bool, optional) - If true, creates the target variable if it doesn't exist. Defaults to false. ### unbind_var Unbinds a variable that was previously bound to a property. ### Method `unbind_var(var_name: StringName)` ### Parameters - **var_name** (StringName) - The name of the variable to unbind. ### get_parent Returns the parent Blackboard. ### Method `get_parent() -> Blackboard` ### set_parent Sets the parent Blackboard. ### Method `set_parent(blackboard: Blackboard)` ### Parameters - **blackboard** (Blackboard) - The Blackboard to set as the parent. ### top Returns the top-most Blackboard in the hierarchy. ### Method `top() -> Blackboard` ### print_state Prints the current state of the Blackboard to the console. ### Method `print_state()` ```