Base class for all :ref:`BehaviorTree<class_BehaviorTree>` tasks.
..rst-class:: classref-introduction-group
Description
-----------
Base class for all :ref:`BehaviorTree<class_BehaviorTree>` tasks. A task is a basic building block in a :ref:`BehaviorTree<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: :ref:`BTAction<class_BTAction>`, :ref:`BTCondition<class_BTCondition>`, :ref:`BTDecorator<class_BTDecorator>`, :ref:`BTComposite<class_BTComposite>`.
Tasks perform their work and return their status using the :ref:`_tick<class_BTTask_private_method__tick>` method. Status values are defined in :ref:`Status<enum_BT_Status>`. Tasks can be initialized using the :ref:`_setup<class_BTTask_private_method__setup>` method. See also :ref:`_enter<class_BTTask_private_method__enter>` & :ref:`_exit<class_BTTask_private_method__exit>`.
\ **Note:** Do not extend **BTTask** directly for your own tasks. Instead, extend one of the subtypes mentioned above.
The agent is a contextual object for the task's :ref:`BehaviorTree<class_BehaviorTree>` instance. Usually, agent is the owner of the :ref:`BTPlayer<class_BTPlayer>` node containing the :ref:`BehaviorTree<class_BehaviorTree>` resource.
Provides access to the :ref:`Blackboard<class_Blackboard>`. Blackboard is used to share data among tasks of the associated :ref:`BehaviorTree<class_BehaviorTree>`.
See :ref:`Blackboard<class_Blackboard>` for additional info.
..rst-class:: classref-item-separator
----
.._class_BTTask_property_custom_name:
..rst-class:: classref-property
String **custom_name** = ``""``
..rst-class:: classref-property-setget
- 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 :ref:`get_task_name<class_BTTask_method_get_task_name>`.
..rst-class:: classref-item-separator
----
.._class_BTTask_property_elapsed_time:
..rst-class:: classref-property
float **elapsed_time**
..rst-class:: classref-property-setget
- float **get_elapsed_time****(****)**
Elapsed time since the task was "entered". See :ref:`_enter<class_BTTask_private_method__enter>`.
Last execution :ref:`Status<enum_BT_Status>` returned by :ref:`_tick<class_BTTask_private_method__tick>`.
..rst-class:: classref-section-separator
----
..rst-class:: classref-descriptions-group
Method Descriptions
-------------------
.._class_BTTask_private_method__enter:
..rst-class:: classref-method
void **_enter****(****)** |virtual|
Called when task is "entered", i.e. when task is executed while not having a ``RUNNING``:ref:`status<class_BTTask_property_status>`.
It is called before :ref:`_tick<class_BTTask_private_method__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 :ref:`execute<class_BTTask_method_execute>`.
..rst-class:: classref-item-separator
----
.._class_BTTask_private_method__exit:
..rst-class:: classref-method
void **_exit****(****)** |virtual|
Called when task is "exited", i.e. after :ref:`_tick<class_BTTask_private_method__tick>` returns ``SUCCESS`` or ``FAILURE`` status. See also :ref:`execute<class_BTTask_method_execute>`.
Called to generate a display name for the task unless :ref:`custom_name<class_BTTask_property_custom_name>` is set. See :ref:`get_task_name<class_BTTask_method_get_task_name>`.
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.
..rst-class:: classref-item-separator
----
.._class_BTTask_private_method__setup:
..rst-class:: classref-method
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.
Duplicates the task and its children, copying the exported members. Sub-resources are shared for efficiency, except for :ref:`BBParam<class_BBParam>` subtypes, which are always copied. Used by the editor to instantiate :ref:`BehaviorTree<class_BehaviorTree>` and copy-paste tasks.
Performs task's execution. The execution follows a specific sequence:
- If task's current :ref:`status<class_BTTask_property_status>` is not ``RUNNING``, the :ref:`_enter<class_BTTask_private_method__enter>` method is called first.
- Next, the :ref:`_tick<class_BTTask_private_method__tick>` method is called next to perform the task's work.
- If the :ref:`_tick<class_BTTask_private_method__tick>` method returns ``SUCCESS`` or ``FAILURE`` status, the :ref:`_exit<class_BTTask_private_method__exit>` method will be called next as part of the execution cleanup.
The string returned by this method is used to represent the task in the editor.
Method :ref:`_generate_name<class_BTTask_private_method__generate_name>` is called to generate a display name for the task unless :ref:`custom_name<class_BTTask_property_custom_name>` is set.
Initilizes the task. Assigns :ref:`agent<class_BTTask_property_agent>` and :ref:`blackboard<class_BTTask_property_blackboard>`, and calls :ref:`_setup<class_BTTask_private_method__setup>` for the task and its children.
The method is called recursively for each child task.
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.
