Improve docs for BTState and LimboState

This commit is contained in:
Serhii Snitsaruk 2023-10-26 15:45:24 +02:00
parent 39971b1e1a
commit 446925adac
2 changed files with 25 additions and 23 deletions

View File

@ -4,20 +4,19 @@
A state node for [LimboHSM] that hosts a [BehaviorTree].
</brief_description>
<description>
This state node instantiates and executes a [BehaviorTree] resource. Dispatches state machine event, when the task tree returns [code]SUCCESS[/code] or [code]FAILURE[/code]. Event names can be specified by [member success_event] and [member failure_event].
For more information about state machine events see [method LimboState.dispatch].
BTState is a [LimboState] node that manages a [BehaviorTree] to provide behavior logic for the state. It instantiates and runs the [BehaviorTree] resource, dispatching a state machine event upon [code]SUCCESS[/code] or [code]FAILURE[/code]. Event names are customizable through [member success_event] and [member failure_event]. For further details on state machine events, see [method LimboState.dispatch].
</description>
<tutorials>
</tutorials>
<members>
<member name="behavior_tree" type="BehaviorTree" setter="set_behavior_tree" getter="get_behavior_tree">
A [BehaviorTree] resource that contains state behavior.
A [BehaviorTree] resource that defines state behavior.
</member>
<member name="failure_event" type="String" setter="set_failure_event" getter="get_failure_event" default="&quot;failure&quot;">
HSM event that will be dispatched when the behavior tree returns [code]FAILURE[/code].
HSM event that will be dispatched when the behavior tree results in [code]FAILURE[/code]. See [method LimboState.dispatch].
</member>
<member name="success_event" type="String" setter="set_success_event" getter="get_success_event" default="&quot;success&quot;">
HSM event that will be dispatched when the behavior tree returns [code]SUCCESS[/code].
HSM event that will be dispatched when the behavior tree results in [code]SUCCESS[/code]. See [method LimboState.dispatch].
</member>
</members>
</class>

View File

@ -1,9 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="LimboState" inherits="Node" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
<brief_description>
A State node for Hierarchical State Machine (HSM).
A state node for Hierarchical State Machines (HSM).
</brief_description>
<description>
A LimboAI state node for Hierarchical State Machines (HSM).
You can create your state behavior by extending this class. To implement your state logic, you can override [method _enter], [method _exit], [method _setup], and [method _update]. Alternatively, you can delegate state implementation to external methods using the [code]call_on_*[/code] methods.
For additional details on state machines, refer to [LimboHSM].
</description>
<tutorials>
</tutorials>
@ -11,26 +14,26 @@
<method name="_enter" qualifiers="virtual">
<return type="void" />
<description>
Called when state is entered.
Called when the state is entered.
</description>
</method>
<method name="_exit" qualifiers="virtual">
<return type="void" />
<description>
Called when state is exited.
Called when the state is exited.
</description>
</method>
<method name="_setup" qualifiers="virtual">
<return type="void" />
<description>
Called once during intialization.
Called once during initialization. Use this method to initialize your state.
</description>
</method>
<method name="_update" qualifiers="virtual">
<return type="void" />
<param index="0" name="p_delta" type="float" />
<description>
Called during update.
Called during the update. Implement your state's behavior with this method.
</description>
</method>
<method name="add_event_handler">
@ -38,34 +41,34 @@
<param index="0" name="p_event" type="String" />
<param index="1" name="p_handler" type="Callable" />
<description>
Register [code]p_method[/code] that will be called when [code]p_event[/code] happens. Method must belong to the state.
Registers a [code]p_method[/code] to be called when [code]p_event[/code] is dispatched. The method must belong to the state.
</description>
</method>
<method name="call_on_enter">
<return type="LimboState" />
<param index="0" name="p_callable" type="Callable" />
<description>
A chained method that connects [signal entered] signal to a [code]p_method[/code] on a [p_object].
A chained method that connects the [signal entered] signal to a [code]p_callable[/code].
</description>
</method>
<method name="call_on_exit">
<return type="LimboState" />
<param index="0" name="p_callable" type="Callable" />
<description>
A chained method that connects [signal exited] signal to a [code]p_method[/code] on a [p_object].
A chained method that connects the [signal exited] signal to a [code]p_callable[/code].
</description>
</method>
<method name="call_on_update">
<return type="LimboState" />
<param index="0" name="p_callable" type="Callable" />
<description>
A chained method that connects [signal updated] signal to a [code]p_method[/code] on a [p_object].
A chained method that connects the [signal updated] signal to a [code]p_callable[/code].
</description>
</method>
<method name="clear_guard">
<return type="void" />
<description>
Removes state's guard function that was set by [method set_guard].
Clears the guard function, removing the [Callable] previously set by [method set_guard].
</description>
</method>
<method name="dispatch">
@ -73,8 +76,8 @@
<param index="0" name="p_event" type="String" />
<param index="1" name="p_cargo" type="Variant" default="null" />
<description>
Dispatches recursively a state machine event named [code]p_event[/code] with an optional argument [code]p_cargo[/code]. Returns [code]true[/code] if event was consumed.
Events propagate from the leaf state to the root. Propagation stops as soon as some state consumes the event. States will consume event if they have a transition associated with it, or an event handler. See also [method add_event_handler].
Recursively dispatches a state machine event named [code]p_event[/code] with an optional argument [code]p_cargo[/code]. Returns [code]true[/code] if the event was consumed.
Events propagate from the leaf state to the root state, and propagation stops as soon as any state consumes the event. States will consume the event if they have a related transition or event handler. For more information on event handlers, see [method add_event_handler].
</description>
</method>
<method name="get_root" qualifiers="const">
@ -86,33 +89,33 @@
<method name="is_active" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if it is currently active, i.e. it is the active substate of the parent [LimboHSM].
Returns [code]true[/code] if it is currently active, meaning it is the active substate of the parent [LimboHSM].
</description>
</method>
<method name="named">
<return type="LimboState" />
<param index="0" name="p_name" type="String" />
<description>
A chained method that sets the name of this state.
A chained method for setting the name of this state.
</description>
</method>
<method name="set_guard">
<return type="void" />
<param index="0" name="p_guard_callable" type="Callable" />
<description>
Sets the guard function. It is a function that will be called each time a transition to this state should happen. If that function returns [code]false[/code], the transition will not be allowed.
Sets the guard function, which is a function called each time a transition to this state is considered. If the function returns [code]false[/code], the transition will be disallowed.
</description>
</method>
</methods>
<members>
<member name="EVENT_FINISHED" type="String" setter="" getter="event_finished">
A commonly used event that signifies that the state has finished work.
A commonly used event that indicates that the state has finished its work.
</member>
<member name="agent" type="Node" setter="set_agent" getter="get_agent">
An agent that is associated with the state. Assinged by initialization.
An agent associated with the state, assigned during initialization.
</member>
<member name="blackboard" type="Blackboard" setter="" getter="get_blackboard">
A key/value data store shared by states of the state machine this state belongs to.
A key/value data store shared by states within the state machine to which this state belongs.
</member>
</members>
<signals>