Skip to content

Commit bac6afd

Browse files
facontidavidefacontidavide
committed
add some more details about pre-conditions
1 parent 458bfe2 commit bac6afd

2 files changed

Lines changed: 80 additions & 17 deletions

File tree

‎docs/guides/pre_post_conditions.md‎

Lines changed: 47 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,25 @@ reconsider your decision to use them.
2525

2626
## Pre conditions
2727

28-
| Name | Description |
29-
|-------------|---------|
30-
| **_skipIf** | Skip the execution of this Node, if the condition is true |
31-
| **_failureIf** | Skip and return FAILURE, if the condition is true |
32-
| **_successIf** | Skip and return SUCCESS, if the condition is true |
33-
| **_while** | Same as _skipIf, but may also interrupt a RUNNING Node if the condition becomes false. |
28+
| Name | Description | When Evaluated |
29+
|-------------|---------|----------------|
30+
| **_skipIf** | Skip the execution of this Node, if the condition is true | IDLE only (once) |
31+
| **_failureIf** | Skip and return FAILURE, if the condition is true | IDLE only (once) |
32+
| **_successIf** | Skip and return SUCCESS, if the condition is true | IDLE only (once) |
33+
| **_while** | If false when IDLE, skip. If false when RUNNING, halt the node and return SKIPPED. | IDLE and RUNNING (every tick) |
34+
35+
:::caution Important: One-time vs. Continuous Evaluation
36+
**`_skipIf`, `_failureIf`, and `_successIf` are evaluated only once** when the node
37+
transitions from IDLE to another state. They are **NOT re-evaluated** while the node
38+
is RUNNING.
39+
40+
Only **`_while`** is checked on every tick, including while the node is running.
41+
42+
If you need a condition to be re-evaluated on every tick, use the `<Precondition>`
43+
decorator node with `else="RUNNING"` instead of these attributes.
44+
:::
3445

35-
:::note
46+
:::note Evaluation Order
3647
Pre conditions are evaluated in this order: `_failureIf` -> `_successIf` -> `_skipIf` -> `_while`.
3748
The first condition that is satisfied will determine the result.
3849
:::
@@ -64,6 +75,35 @@ we can store a boolean in an entry called `door_closed`, the XML can be rewritte
6475
<OpenDoor _skipIf="!door_closed"/>
6576
```
6677

78+
### Using `<Precondition>` for Per-Tick Evaluation
79+
80+
When you need a condition to be checked on **every tick** (not just when the node starts),
81+
use the `<Precondition>` decorator node instead of inline attributes.
82+
83+
This is particularly useful in **ReactiveSequence** or **ReactiveFallback** where you want
84+
the condition to be re-evaluated each time the running child is ticked:
85+
86+
``` xml
87+
<!-- This checks the condition on every tick -->
88+
<Precondition if="battery_ok" else="RUNNING">
89+
<MoveToGoal/>
90+
</Precondition>
91+
```
92+
93+
With `else="RUNNING"`, if the condition becomes false while the child is running,
94+
the decorator returns RUNNING (keeping the tree alive) instead of immediately
95+
returning FAILURE or SKIPPED.
96+
97+
Compare this to the inline attribute:
98+
99+
``` xml
100+
<!-- This checks the condition ONLY when MoveToGoal starts -->
101+
<MoveToGoal _successIf="battery_ok"/>
102+
```
103+
104+
The inline `_successIf` is evaluated once when `MoveToGoal` transitions from IDLE.
105+
If `battery_ok` changes while `MoveToGoal` is RUNNING, the change is ignored.
106+
67107
## Post conditions
68108

69109
| Name | Description |

‎docs/nodes-library/DecoratorNode.md‎

Lines changed: 33 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -115,24 +115,47 @@ After that first execution, you can set value of the [Input Port](tutorial-basic
115115
- TRUE (default), the node will be skipped in the future.
116116
- FALSE, return synchronously the same status returned by the child, forever.
117117

118-
## PreCondition
118+
## Precondition
119119

120-
Cf. [Introduction to the Scripting language](../tutorial-basics/tutorial_09_scripting.md#script-and-precondition-nodes)
120+
The Precondition decorator evaluates a script condition before ticking its child.
121121

122-
## SubTree
122+
| Port | Type | Default | Description |
123+
|------|------|---------|-------------|
124+
| `if` | InputPort\<std::string\> | (required) | Script condition to evaluate |
125+
| `else` | InputPort\<NodeStatus\> | FAILURE | Status to return if condition is false |
123126

124-
Cf. [Compose behaviors using Subtrees](../tutorial-basics/tutorial_05_subtrees).
127+
- If the condition is **true**, the child is ticked.
128+
- If the condition is **false**, the node returns the status specified in `else`.
129+
- Once the child starts (returns RUNNING), the condition is **not re-evaluated** until the child completes.
125130

126-
## Other decorators requiring registration in C++
131+
```xml
132+
<Precondition if="battery_level > 20" else="FAILURE">
133+
<MoveToGoal/>
134+
</Precondition>
135+
```
136+
137+
:::tip Per-Tick Evaluation
138+
If you need the condition to be checked on every tick while the child is running
139+
(e.g., to interrupt a running action when a condition changes), use `else="RUNNING"`:
127140

128-
### ConsumeQueue
141+
```xml
142+
<Precondition if="battery_ok" else="RUNNING">
143+
<LongRunningAction/>
144+
</Precondition>
145+
```
129146

130-
:::caution Deprecated
131-
ConsumeQueue is deprecated. Use `LoopNode` instead (see [Tutorial 13](../tutorial-advanced/tutorial_13_blackboard_reference.md)).
147+
With `else="RUNNING"`, if the condition becomes false, the decorator returns RUNNING
148+
instead of FAILURE, allowing the tree to continue ticking and re-check the condition.
132149
:::
133150

134-
Execute the child node as long as the queue is not empty.
135-
At each iteration, an item of type T is popped from the "queue" and inserted in "popped_item".
151+
For more details, see [Pre and Post conditions](../guides/pre_post_conditions.md) and
152+
[Introduction to the Scripting language](../tutorial-basics/tutorial_09_scripting.md#script-and-precondition-nodes).
153+
154+
## SubTree
155+
156+
Cf. [Compose behaviors using Subtrees](../tutorial-basics/tutorial_05_subtrees).
157+
158+
## Other decorators requiring registration in C++
136159

137160
An empty queue will return SUCCESS
138161

0 commit comments

Comments
 (0)