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(delta: float) virtual
void	abort()
void	add_child(task: BTTask)
void	add_child_at_index(task: BTTask, idx: int)
BTTask	clone() const
BehaviorTree	editor_get_behavior_tree()
Status	execute(delta: float)
BTTask	get_child(idx: int) 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(task: BTTask) const
void	initialize(agent: Node, blackboard: Blackboard, scene_root: Node)
bool	is_descendant_of(task: BTTask) const
bool	is_root() const
BTTask	next_sibling() const
void	print_tree(initial_tabs: int = 0)
void	remove_child(task: BTTask)
void	remove_child_at_index(idx: int)

---

Property Descriptions

Node agent 🔗

• void set_agent(value: Node)

• 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(value: String)

• 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(delta: float) 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(task: BTTask) 🔗

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

---

void add_child_at_index(task: BTTask, idx: int) 🔗

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(delta: float) 🔗

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(idx: int) 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(task: BTTask) const 🔗

Returns true if task is a child of this task.

---

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

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(task: BTTask) 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(initial_tabs: int = 0) 🔗

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

---

void remove_child(task: BTTask) 🔗

Removes task from children.

---

void remove_child_at_index(idx: int) 🔗

Removes a child task at a specified index from children.