Skip to content

Commit 596a80e

Browse files
AglargilAglargil
committed
feat: add behavior tree doc
1 parent 984a595 commit 596a80e

File tree

4 files changed

+206
-52
lines changed

4 files changed

+206
-52
lines changed

‎MissionPlanning/BehaviorTree/behavior_tree.py‎

Lines changed: 81 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -92,15 +92,17 @@ class SequenceNode(ControlNode):
9292
Executes child nodes in sequence until one fails or all succeed.
9393
9494
Returns:
95-
- Returns FAILURE if any child returns FAILURE
96-
- Returns SUCCESS when all children have succeeded
97-
- Returns RUNNING when a child is still running or when moving to the next child
95+
- Returns FAILURE if any child returns FAILURE
96+
- Returns SUCCESS when all children have succeeded
97+
- Returns RUNNING when a child is still running or when moving to the next child
9898
9999
Example:
100-
<Sequence>
101-
<Action1 />
102-
<Action2 />
103-
</Sequence>
100+
.. code-block:: xml
101+
102+
<Sequence>
103+
<Action1 />
104+
<Action2 />
105+
</Sequence>
104106
"""
105107

106108
def __init__(self, name):
@@ -131,15 +133,17 @@ class SelectorNode(ControlNode):
131133
Executes child nodes in sequence until one succeeds or all fail.
132134
133135
Returns:
134-
- Returns SUCCESS if any child returns SUCCESS
135-
- Returns FAILURE when all children have failed
136-
- Returns RUNNING when a child is still running or when moving to the next child
136+
- Returns SUCCESS if any child returns SUCCESS
137+
- Returns FAILURE when all children have failed
138+
- Returns RUNNING when a child is still running or when moving to the next child
137139
138-
Example:
139-
<Selector>
140-
<Action1 />
141-
<Action2 />
142-
</Selector>
140+
Examples:
141+
.. code-block:: xml
142+
143+
<Selector>
144+
<Action1 />
145+
<Action2 />
146+
</Selector>
143147
"""
144148

145149
def __init__(self, name):
@@ -170,17 +174,19 @@ class WhileDoElseNode(ControlNode):
170174
Conditional execution node with three parts: condition, do, and optional else.
171175
172176
Returns:
173-
- First executes the condition node (child[0])
174-
- If condition succeeds, executes do node (child[1]) and returns RUNNING
175-
- If condition fails, executes else node (child[2]) if present and returns result of else node
176-
- If condition fails and there is no else node, returns SUCCESS
177+
First executes the condition node (child[0])
178+
If condition succeeds, executes do node (child[1]) and returns RUNNING
179+
If condition fails, executes else node (child[2]) if present and returns result of else node
180+
If condition fails and there is no else node, returns SUCCESS
177181
178182
Example:
179-
<WhileDoElse>
180-
<Condition />
181-
<Do />
182-
<Else />
183-
</WhileDoElse>
183+
.. code-block:: xml
184+
185+
<WhileDoElse>
186+
<Condition />
187+
<Do />
188+
<Else />
189+
</WhileDoElse>
184190
"""
185191

186192
def __init__(self, name):
@@ -236,11 +242,13 @@ class SleepNode(ActionNode):
236242
Sleep node that sleeps for a specified duration.
237243
238244
Returns:
239-
- Returns SUCCESS after the specified duration has passed
240-
- Returns RUNNING if the duration has not yet passed
245+
Returns SUCCESS after the specified duration has passed
246+
Returns RUNNING if the duration has not yet passed
241247
242248
Example:
243-
<Sleep sec="1.5" />
249+
.. code-block:: xml
250+
251+
<Sleep sec="1.5" />
244252
"""
245253

246254
def __init__(self, name, duration):
@@ -261,10 +269,12 @@ class EchoNode(ActionNode):
261269
Echo node that prints a message to the console.
262270
263271
Returns:
264-
- Returns SUCCESS after the message has been printed
272+
Returns SUCCESS after the message has been printed
265273
266274
Example:
267-
<Echo message="Hello, World!" />
275+
.. code-block:: xml
276+
277+
<Echo message="Hello, World!" />
268278
"""
269279

270280
def __init__(self, name, message):
@@ -302,13 +312,16 @@ class InverterNode(DecoratorNode):
302312
Inverter node that inverts the status of its child node.
303313
304314
Returns:
305-
- Returns SUCCESS if the child returns FAILURE
306-
- Returns FAILURE if the child returns SUCCESS
307-
- Returns RUNNING if the child returns RUNNING
308-
Example:
309-
<Inverter>
310-
<Action />
311-
</Inverter>
315+
- Returns SUCCESS if the child returns FAILURE
316+
- Returns FAILURE if the child returns SUCCESS
317+
- Returns RUNNING if the child returns RUNNING
318+
319+
Examples:
320+
.. code-block:: xml
321+
322+
<Inverter>
323+
<Action />
324+
</Inverter>
312325
"""
313326

314327
def __init__(self, name):
@@ -325,13 +338,15 @@ class TimeoutNode(DecoratorNode):
325338
Timeout node that fails if the child node takes too long to execute
326339
327340
Returns:
328-
- FAILURE: If the timeout duration has been exceeded
329-
- Child's status: Otherwise, passes through the status of the child node
341+
- FAILURE: If the timeout duration has been exceeded
342+
- Child's status: Otherwise, passes through the status of the child node
330343
331344
Example:
332-
<Timeout sec="1.5">
333-
<Action />
334-
</Timeout>
345+
.. code-block:: xml
346+
347+
<Timeout sec="1.5">
348+
<Action />
349+
</Timeout>
335350
"""
336351

337352
def __init__(self, name, timeout):
@@ -354,13 +369,15 @@ class DelayNode(DecoratorNode):
354369
Delay node that delays the execution of its child node for a specified duration.
355370
356371
Returns:
357-
- Returns RUNNING if the duration has not yet passed
358-
- Returns child's status after the duration has passed
372+
- Returns RUNNING if the duration has not yet passed
373+
- Returns child's status after the duration has passed
359374
360375
Example:
361-
<Delay sec="1.5">
362-
<Action />
363-
</Delay>
376+
.. code-block:: xml
377+
378+
<Delay sec="1.5">
379+
<Action />
380+
</Delay>
364381
"""
365382

366383
def __init__(self, name, delay):
@@ -382,8 +399,8 @@ class ForceSuccessNode(DecoratorNode):
382399
ForceSuccess node that always returns SUCCESS.
383400
384401
Returns:
385-
- Returns RUNNING if the child returns RUNNING
386-
- Returns SUCCESS if the child returns SUCCESS or FAILURE
402+
- Returns RUNNING if the child returns RUNNING
403+
- Returns SUCCESS if the child returns SUCCESS or FAILURE
387404
"""
388405

389406
def __init__(self, name):
@@ -402,8 +419,8 @@ class ForceFailureNode(DecoratorNode):
402419
ForceFailure node that always returns FAILURE.
403420
404421
Returns:
405-
- Returns RUNNING if the child returns RUNNING
406-
- Returns FAILURE if the child returns SUCCESS or FAILURE
422+
- Returns RUNNING if the child returns RUNNING
423+
- Returns FAILURE if the child returns SUCCESS or FAILURE
407424
"""
408425

409426
def __init__(self, name):
@@ -484,12 +501,12 @@ def print_tree(self):
484501
"""
485502
Print the behavior tree.
486503
487-
Node types:
504+
Node print format:
488505
Action: <Action>
489506
Decorator: (Decorator)
490507
Control: [Control]
491508
492-
Colors:
509+
Node status colors:
493510
Yellow: RUNNING
494511
Green: SUCCESS
495512
Red: FAILURE
@@ -577,6 +594,18 @@ def register_node_builder(self, node_name, builder):
577594
Args:
578595
node_name (str): The name of the node.
579596
builder (function): The builder function.
597+
598+
Example:
599+
.. code-block:: python
600+
601+
factory = BehaviorTreeFactory()
602+
factory.register_node_builder(
603+
"MyNode",
604+
lambda node: MyNode(
605+
node.attrib.get("name", MyNode.__name__),
606+
node.attrib["my_param"],
607+
),
608+
)
580609
"""
581610
self.node_builders[node_name] = builder
582611

‎docs/modules/13_mission_planning/behavior_tree/behavior_tree_main.rst‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
Behavior Tree
2+
-------------
3+
4+
Behavior Tree is a modular, hierarchical decision model that is widely used in robot control, and game development.
5+
6+
Core Concepts
7+
~~~~~~~~~~~~~
8+
9+
Control Node
10+
++++++++++++
11+
12+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.ControlNode
13+
14+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.SequenceNode
15+
16+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.SelectorNode
17+
18+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.WhileDoElseNode
19+
20+
Action Node
21+
++++++++++++
22+
23+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.ActionNode
24+
25+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.EchoNode
26+
27+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.SleepNode
28+
29+
Decorator Node
30+
++++++++++++++
31+
32+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.DecoratorNode
33+
34+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.InverterNode
35+
36+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.TimeoutNode
37+
38+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.DelayNode
39+
40+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.ForceSuccessNode
41+
42+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.ForceFailureNode
43+
44+
Behavior Tree Factory
45+
+++++++++++++++++++++
46+
47+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.BehaviorTreeFactory
48+
:members:
49+
50+
Behavior Tree
51+
+++++++++++++
52+
53+
.. autoclass:: MissionPlanning.BehaviorTree.behavior_tree.BehaviorTree
54+
:members:
55+
56+
Example
57+
~~~~~~~
58+
59+
Visualize the behavior tree by `xml-tree-visual <https://xml-tree-visual.vercel.app/>`_.
60+
61+
.. image:: ./robot_behavior_case.svg
62+
63+
Print the behavior tree
64+
65+
.. code-block:: text
66+
67+
Behavior Tree
68+
[Robot Main Controller]
69+
[Battery Management]
70+
(Low Battery Detection)
71+
<Check Battery>
72+
<Low Battery Warning>
73+
<Charge Battery>
74+
[Patrol Task]
75+
<Start Task>
76+
[Move to Position A]
77+
<Move to A>
78+
[Obstacle Handling A]
79+
[Obstacle Present]
80+
<Detect Obstacle>
81+
<Avoid Obstacle>
82+
<No Obstacle>
83+
<Position A Task>
84+
[Move to Position B]
85+
(Short Wait)
86+
<Prepare Movement>
87+
<Move to B>
88+
(Limited Time Obstacle Handling)
89+
[Obstacle Present]
90+
<Detect Obstacle>
91+
<Avoid Obstacle>
92+
<Position B Task>
93+
[Conditional Move to C]
94+
<Check Sufficient Battery>
95+
[Perform Position C Task]
96+
<Move to C>
97+
(Ensure Completion)
98+
<Position C Task>
99+
<Skip Position C>
100+
<Complete Patrol>
101+
<Return to Charging Station>
102+
Behavior Tree

0 commit comments

Comments
 (0)