Skip to content

Commit 2613b0e

Browse files
author
Davide Faconti
committed
docs updated
1 parent cacd698 commit 2613b0e

13 files changed

+577
-17
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
*~
22
/CMakeLists.txt.user
33
build*
4+
site

‎docs/BT_basics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ A Sequence works as described next:
7878

7979
??? warning "Exercise: find the bug! Expand to read the answer."
8080
If the action __GrabBeer__ fails, the door of the
81-
fridge would remain opened, since the last action __CloseDoor__ is skipped.
81+
fridge would remain open, since the last action __CloseDoor__ is skipped.
8282

8383

8484
### Decorators

‎docs/DecoratorNode.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Decorators
2+
3+
A decorator is a node that can have only a single child.
4+
5+
It is up to the Decorator to decide if, when and how many times the child should be
6+
ticked.
7+
8+
## InverterNode
9+
10+
Tick the child once and return SUCCESS if the child failed or FAILURE if
11+
the child succeeded.
12+
13+
If the child returns RUNNING, this node returns RUNNING too.
14+
15+
## ForceSuccessNode
16+
17+
If the child returns RUNNING, this node returns RUNNING too.
18+
19+
Otherwise, it returns always SUCCESS.
20+
21+
## ForceFailureNode
22+
23+
If the child returns RUNNING, this node returns RUNNING too.
24+
25+
Otherwise, it returns always FAILURE.
26+
27+
## RepeatNode
28+
29+
Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
30+
as long as the child returns SUCCESS.
31+
32+
Interrupt the loop if the child returns FAILURE and, in that case, return FAILURE too.
33+
34+
If the child returns RUNNING, this node returns RUNNING too.
35+
36+
## RetryNode
37+
38+
Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
39+
as long as the child returns FAILURE.
40+
41+
Interrupt the loop if the child returns SUCCESS and, in that case, return SUCCESS too.
42+
43+
If the child returns RUNNING, this node returns RUNNING too.
44+
45+
## RetryNode
46+
47+
Tick the child up to N times, where N is passed as a [NodeParameter](NodeParameter.md),
48+
as long as the child returns FAILURE.
49+
50+
Interrupt the loop if the child returns SUCCESS and, in that case, return SUCCESS too.
51+
52+
If the child returns RUNNING, this node returns RUNNING too.
53+

‎docs/FallbackNode.md‎

Lines changed: 52 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,64 @@
1-
# ControlNodes
1+
# Fallback
22

3-
ControlNodes can have multiple children. Children are always __ordered__
4-
and it is up to the ControlNode itself to decide if and when a child should
5-
be ticked.
3+
This family of nodes are known as "Selector" or, sometimes, "Priority"
4+
in other frameworks.
65

7-
## SequenceNode
6+
Its purpose is to try different strategies, until we find one that "works".
7+
Currently, there is only a single type of node called "FallbackNode".
8+
9+
10+
## FallbackNode
811

912
The SequenceNode is used to execute the children in a sequence.
1013

11-
It ticks its children __as long as__ they returns SUCCESS.
14+
- Before ticking the first child, Fallback becomes __RUNNING__.
15+
- If a child returns __FAILURE__, it ticks the next child.
16+
- If the __last__ child returns __FAILURE__ too, all the children are halted and
17+
the Sequence returns __FAILURE__.
18+
- If a child returns __RUNNING__, Fallback suspends and returns __RUNNING__.
19+
- If a child returns __SUCCESS__, Fallback stops and returns __SUCCESS__.
20+
21+
__Example__:
1222

13-
- Before ticking the first child, Sequence becomes __RUNNING__.
14-
- If a child return __SUCCESS__, it ticks the next child.
15-
- If the __last__ child returns __SUCCESS__ too, all the children are halted and
16-
the Sequence returns __SUCCESS__.
17-
- If a child returns __RUNNING__, Sequence suspends and returns __RUNNING__.
18-
- If a child returns __FAILURE__, Sequence stops and returns __FAILURE__.
23+
Try different strategies to open the door. Check first if it is open already.
1924

25+
![FallbackNode](images/FallbackSimplified.png)
2026

27+
??? example "See the pseudocode"
28+
``` c++
29+
// At the beginning, start from first child
30+
if( state != RUNNING) {
31+
index = 0;
32+
}
33+
state = RUNNING;
2134

35+
while( index < number_of_children )
36+
{
37+
child_state = child[index]->tick();
38+
39+
if( child_state == RUNNING ) {
40+
// Suspend execution and return RUNNING.
41+
// At the next tick, index will be the same.
42+
state = RUNNING;
43+
return state;
44+
}
45+
else if( child_state == FAILURE ) {
46+
// continue the while loop
47+
index++;
48+
}
49+
else if( child_state == SUCCESS ) {
50+
// Suspend execution and return SUCCESS.
51+
// index is reset and children are halted.
52+
state = SUCCESS;
53+
index = 0;
54+
HaltAllChildren();
55+
return state;
56+
}
57+
}
58+
// all the children returned failure. Return FAILURE too.
59+
state = FAILURE;
60+
HaltAllChildren();
61+
return state;
2262

2363

2464

‎docs/SequenceNode.md‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
A __Sequence__ ticks all it's children, from left to right, as long as
44
they return SUCCESS. If any child returns FAILURE, the sequence is suspended.
55

6-
Here we introduce two kinds of TreeNodes:
6+
Here we introduce different kinds of TreeNodes:
77

88
- SequenceNode
99
- SequenceStarNode
@@ -23,7 +23,7 @@ Use __SequenceStarNode__ if, instead, the answer is:
2323
A: "Try again to execute the failed child.
2424
Do not re-tick children which succeeded already."
2525

26-
__SequenceAllNode__ is used when you want all the children to be ticked at least
26+
Last, use __SequenceAllNode__ when you want all the children to be ticked at least
2727
once. If any of them failed, the SequenceAllNode returns FAILURE.
2828

2929
The shared logic is:
@@ -32,16 +32,25 @@ The shared logic is:
3232
- If a child returns __SUCCESS__, it ticks the next child.
3333
- If the __last__ child returns __SUCCESS__ too, all the children are halted and
3434
the SequenceNode returns __SUCCESS__.
35-
- If a child returns __RUNNING__, Sequence suspends and returns __RUNNING__.
36-
The next time it is ticked, it will use the same index.
35+
- If a child returns __RUNNING__, the sequence suspends and returns __RUNNING__.
36+
The next time it is ticked, it will tick the same child again.
3737

3838
The three Sequences differ in what they do if a child returns FAILURE.
3939

4040
## SequenceNode
41+
4142
If a child returns FAILURE, the sequence returns FAILURE.
4243
Reset the index and halt all the children.
4344
The entire sequence will be executed again at the next tick.
4445

46+
__Example__:
47+
48+
This tree represents the behavior of a sniper in a computer game.
49+
If any of these conditions/actions fails, the entire sequence is executed
50+
again from the beginning.
51+
52+
![SequenceNode](images/SequenceNode.png)
53+
4554
??? example "See the pseudocode"
4655
``` c++
4756
// At the beginning, start from first child
@@ -85,6 +94,15 @@ The entire sequence will be executed again at the next tick.
8594
If a child returns FAILURE, the sequence returns FAILURE. At the next tick,
8695
the failed child is executed again.
8796

97+
__Example__:
98+
99+
This is a patrolling agent/robot that must visit locations A, B and C only once.
100+
If the action __GoTo(B)__ fails, __GoTo(A)__ will not be ticked again.
101+
102+
On the other hand, __isBatteryOK__ is visited at every tick, because its parent is a normal SequenceNode.
103+
104+
![SequenceStar](images/SequenceStar.png)
105+
88106
??? example "See the pseudocode"
89107
``` c++
90108

@@ -125,6 +143,14 @@ All the children are executed at least once.
125143
If __any__ child returned FAILURE,
126144
the sequence is __not__ interrupted but the sequence itself will return FAILURE.
127145

146+
__Example__:
147+
148+
If the door of the fridge was succesfully opened, grab a beer.
149+
__CloseFridge__ is always executed, even when _GrabBeer_ failed.
150+
151+
152+
![SequenceAll](images/SequenceAll.png)
153+
128154
??? example "See the pseudocode"
129155
``` c++
130156
if( state != RUNNING) {

‎docs/images/FallbackSimplified.png‎

5.97 KB
Loading

‎docs/images/SequenceAll.png‎

5.04 KB
Loading

‎docs/images/SequenceNode.png‎

6.76 KB
Loading

‎docs/images/SequenceStar.png‎

7.85 KB
Loading

‎docs/uml/FallbackSimplified.uxf‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
<?xml version="1.0" encoding="UTF-8"?><diagram program="umlet" version="13.3">
2+
<zoom_level>10</zoom_level>
3+
<element>
4+
<id>UMLClass</id>
5+
<coordinates>
6+
<x>260</x>
7+
<y>140</y>
8+
<w>100</w>
9+
<h>30</h>
10+
</coordinates>
11+
<panel_attributes>Fallback
12+
fg=blue</panel_attributes>
13+
<additional_attributes/>
14+
</element>
15+
<element>
16+
<id>UMLClass</id>
17+
<coordinates>
18+
<x>200</x>
19+
<y>210</y>
20+
<w>100</w>
21+
<h>30</h>
22+
</coordinates>
23+
<panel_attributes>OpenDoor</panel_attributes>
24+
<additional_attributes/>
25+
</element>
26+
<element>
27+
<id>Relation</id>
28+
<coordinates>
29+
<x>250</x>
30+
<y>160</y>
31+
<w>80</w>
32+
<h>70</h>
33+
</coordinates>
34+
<panel_attributes>lt=-</panel_attributes>
35+
<additional_attributes>10.0;50.0;60.0;10.0</additional_attributes>
36+
</element>
37+
<element>
38+
<id>UMLClass</id>
39+
<coordinates>
40+
<x>420</x>
41+
<y>210</y>
42+
<w>100</w>
43+
<h>30</h>
44+
</coordinates>
45+
<panel_attributes>SmashDoor</panel_attributes>
46+
<additional_attributes/>
47+
</element>
48+
<element>
49+
<id>Relation</id>
50+
<coordinates>
51+
<x>300</x>
52+
<y>160</y>
53+
<w>80</w>
54+
<h>70</h>
55+
</coordinates>
56+
<panel_attributes>lt=-</panel_attributes>
57+
<additional_attributes>60.0;50.0;10.0;10.0</additional_attributes>
58+
</element>
59+
<element>
60+
<id>Relation</id>
61+
<coordinates>
62+
<x>300</x>
63+
<y>160</y>
64+
<w>200</w>
65+
<h>70</h>
66+
</coordinates>
67+
<panel_attributes>lt=-</panel_attributes>
68+
<additional_attributes>180.0;50.0;10.0;10.0</additional_attributes>
69+
</element>
70+
<element>
71+
<id>UMLClass</id>
72+
<coordinates>
73+
<x>310</x>
74+
<y>210</y>
75+
<w>100</w>
76+
<h>30</h>
77+
</coordinates>
78+
<panel_attributes>UnlockDoor</panel_attributes>
79+
<additional_attributes/>
80+
</element>
81+
<element>
82+
<id>UMLUseCase</id>
83+
<coordinates>
84+
<x>70</x>
85+
<y>210</y>
86+
<w>120</w>
87+
<h>40</h>
88+
</coordinates>
89+
<panel_attributes>isDoorOpen?</panel_attributes>
90+
<additional_attributes/>
91+
</element>
92+
<element>
93+
<id>Relation</id>
94+
<coordinates>
95+
<x>120</x>
96+
<y>160</y>
97+
<w>210</w>
98+
<h>70</h>
99+
</coordinates>
100+
<panel_attributes>lt=-</panel_attributes>
101+
<additional_attributes>10.0;50.0;190.0;10.0</additional_attributes>
102+
</element>
103+
</diagram>

0 commit comments

Comments
 (0)