BTTask

Inherits: BT

Inherited By: BTAction, BTComment, BTComposite, BTCondition, BTDecorator

Base class for all BehaviorTree tasks.

Description

Base class for all BehaviorTree tasks. A task is a basic building block in a 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, BTCondition, BTDecorator, BTComposite.

Tasks perform their work and return their status using the _tick method. Status values are defined in Status. Tasks can be initialized using the _setup method. See also _enter & _exit.

Note: Do not extend BTTask directly for your own tasks. Instead, extend one of the subtypes mentioned above.

Properties

Node	agent
Blackboard	blackboard
String	custom_name	""
float	elapsed_time
Node	scene_root
Status	status

Methods

void	_enter ( ) virtual
void	_exit ( ) virtual
String	_generate_name ( ) virtual const
PackedStringArray	_get_configuration_warnings ( ) virtual const
void	_setup ( ) virtual
Status	_tick ( float delta ) virtual
void	abort ( )
void	add_child ( BTTask task )
void	add_child_at_index ( BTTask task, int idx )
BTTask	clone ( ) const
BehaviorTree	editor_get_behavior_tree ( )
Status	execute ( float delta )
BTTask	get_child ( int idx ) const
int	get_child_count ( ) const
int	get_child_count_excluding_comments ( ) const
int	get_index ( ) const
BTTask	get_parent ( ) const
BTTask	get_root ( ) const
String	get_task_name ( )
bool	has_child ( BTTask task ) const
void	initialize ( Node agent, Blackboard blackboard, Node scene_root )
bool	is_descendant_of ( BTTask task ) const
bool	is_root ( ) const
BTTask	next_sibling ( ) const
void	print_tree ( int initial_tabs=0 )
void	remove_child ( BTTask task )
void	remove_child_at_index ( int idx )

---

Property Descriptions

Node agent

• void set_agent ( Node value )

• Node get_agent ( )

The agent is the contextual object for the BehaviorTree instance. This is usually the parent of the BTPlayer node that utilizes the BehaviorTree resource.

---

Blackboard blackboard

• Blackboard get_blackboard ( )

Provides access to the Blackboard. Blackboard is used to share data among tasks of the associated BehaviorTree.

See Blackboard for additional info.

---

String custom_name = ""

• void set_custom_name ( String value )

• String get_custom_name ( )

User-provided name for the task. If not empty, it is used by the editor to represent the task. See get_task_name.

---

float elapsed_time

• float get_elapsed_time ( )

Elapsed time since the task was “entered”. See _enter.

Returns 0 when task is not RUNNING.

---

Node scene_root

• Node get_scene_root ( )

Root node of the scene the behavior tree is used in (e.g., the owner of the BTPlayer node). Can be uses to retrieve NodePath references.

Example:

extends BTAction

@export var node_path: NodePath

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

---

Status status

• Status get_status ( )

Last execution Status returned by _tick.

---

Method Descriptions

void _enter ( ) virtual

Called when task is “entered”, i.e. when task is executed while not having a RUNNING status.

It is called before _tick in the execution order. This method is used when preparation is needed before main work begins, usually when it takes more than one tick to finish the task. See also execute.

---

void _exit ( ) virtual

Called when task is “exited”, i.e. after _tick returns SUCCESS or FAILURE status. See also execute.

---

String _generate_name ( ) virtual const

Called to generate a display name for the task unless custom_name is set. See get_task_name.

---

PackedStringArray _get_configuration_warnings ( ) virtual const

The string returned by this method is shown as a warning message in the behavior tree editor. Any task script that overrides this method must include @tool annotation at the top of the file.

---

void _setup ( ) virtual

Called to initialize a task during initialization step. It is called only once before the task’s first execution tick. This method allows you to set up any necessary state or configurations for the task before it begins executing.

---

Status _tick ( float delta ) virtual

Called when task is “ticked”, i.e. executed by BTPlayer or BTState during an update.

Returns execution status as defined in Status.

Note: Tasks perform their main function by implementing this method.

---

void abort ( )

Resets the task and its children recursively. If a task is in the RUNNING state, it is exited and its status is reset to FRESH.

---

void add_child ( BTTask task )

Adds a child task. The task is placed at the end of the children list.

---

void add_child_at_index ( BTTask task, int idx )

Adds a child task. The task is placed at idx position in the children list.

---

BTTask clone ( ) const

Duplicates the task and its children, copying the exported members. Sub-resources are shared for efficiency, except for BBParam subtypes, which are always copied. Used by the editor to instantiate BehaviorTree and copy-paste tasks.

---

BehaviorTree editor_get_behavior_tree ( )

Returns the behavior tree that owns this task. This is only available in the editor.

---

Status execute ( float delta )

Performs task’s execution. The execution follows a specific sequence:

• If task’s current status is not RUNNING, the _enter method is called first.

• Next, the _tick method is called next to perform the task’s work.

• If the _tick method returns SUCCESS or FAILURE status, the _exit method will be called next as part of the execution cleanup.

---

BTTask get_child ( int idx ) const

Returns a child task by specifying its index.

---

int get_child_count ( ) const

Returns the number of child tasks.

---

int get_child_count_excluding_comments ( ) const

Returns the number of child tasks not counting BTComment tasks.

---

int get_index ( ) const

Returns the task’s position in the behavior tree branch. Returns -1 if the task doesn’t belong to a task tree, i.e. doesn’t have a parent.

---

BTTask get_parent ( ) const

Returns the task’s parent.

---

BTTask get_root ( ) const

Returns the root task of the behavior tree.

---

String get_task_name ( )

The string returned by this method is used to represent the task in the editor.

Method _generate_name is called to generate a display name for the task unless custom_name is set.

---

bool has_child ( BTTask task ) const

Returns true if task is a child of this task.

---

void initialize ( Node agent, Blackboard blackboard, Node scene_root )

Initilizes the task. Assigns agent and blackboard, and calls _setup for the task and its children.

The method is called recursively for each child task. scene_root should be the root node of the scene the behavior tree is used in (e.g., the owner of the node that contains the behavior tree).

---

bool is_descendant_of ( BTTask task ) const

Returns true if this task is a descendant of task. In other words, this task must be a child of task or one of its children or grandchildren.

---

bool is_root ( ) const

Returns true if this task is the root task of its behavior tree. A behavior tree can have only one root task.

---

BTTask next_sibling ( ) const

Returns the next task after this task in the parent’s children list.

Returns null if this task has no parent or it is the last child in the parent’s children list.

---

void print_tree ( int initial_tabs=0 )

Prints the subtree that starts with this task to the console.

---

void remove_child ( BTTask task )

Removes task from children.

---

void remove_child_at_index ( int idx )

Removes a child task at a specified index from children.