BehaviorTree.CPP v4 XML reference for the Beehave parser¶
This document is the reference for Beehave's BT.CPP v4 parser, flattener and walker. It plays the same role for v4 that btcpp-v3-xml.md plays for v3, and it assumes you have read that document and btcpp-v3-vs-v4.md. It lists every node type that BehaviorTreeFactory registers in the latest release, gives each one a walk rule with a third, "skipped", continuation, and specifies pre- and post-conditions, the scripting language, v4 subtree remapping and the document structure.
Versions checked. Everything here was read from the C++ source of tag 4.10.0 (commit 879522c, 2026-07-24, the latest 4.x release) and of master at commit 03ec870 (2026-10-10). The node registrations are identical in both (bt_factory.cpp L118-L173). The differences between the two that matter to a parser are noted where they occur. Behaviour that changed during 4.x carries the first release that has it, found with git tag --contains. Where the documentation and the code disagree, the code wins and the disagreement is noted. Lines marked (run) were also confirmed by running small trees on a local build of 4.10.0, not only by reading the source.
Notation.
S,FandKare the success, failure and skipped continuations passed tocompile(n, S, F, K).Kis where execution goes whennreturns SKIPPED.Branch(c, A, B)is a guard: go toAifcholds, else toB(the walk's_Branch).ERRmeans BT.CPP throws at runtime. Beehave should report a diagnostic and draw no edge.WAIT(c)means the node returns RUNNING and checkscagain on the next tick. A single pass draws only the edge taken oncecholds.- "Exact" means the rule reproduces every success, failure and skipped path of one activation of the node. "Approximated" means Beehave draws the single-pass edges and reports the node as approximated.
1. Summary table¶
Every row also accepts the pre- and post-condition attributes of §3, which wrap the rule given here. "Since" is given for nodes added after 4.0.1 (see btcpp-v3-vs-v4.md §2.3).
| XML name | Beehave kind | Children | Walk rule: compile(n, S, F, K) |
Single pass | Notes |
|---|---|---|---|---|---|
Sequence |
control | ≥ 1 | two-track chain (§2.3): ci -S-> c(i+1), ci -F-> F, ci -K-> c(i+1); after cn: S, or K if every child was skipped |
exact | Restarts at c1 after a failure. |
SequenceWithMemory |
control | ≥ 1 | same as Sequence |
approximated (memory) | v3 SequenceStar. After a FAILURE it resumes at the failed child. |
AsyncSequence (4.2.0) |
control | ≥ 1 | same as Sequence |
exact | Returns RUNNING after each successful child so the tree can be interrupted. Same edges. |
ReactiveSequence |
control | ≥ 1 | same as Sequence |
approximated (preemption) | Re-ticks earlier children every tick. When one child is RUNNING, all others are halted. |
Fallback |
control | ≥ 1 | mirror chain: ci -F-> c(i+1), ci -S-> S, ci -K-> c(i+1); after cn: F, or K if every child was skipped |
exact | |
AsyncFallback (4.2.0) |
control | ≥ 1 | same as Fallback |
exact | Yields after each failed child. |
ReactiveFallback |
control | ≥ 1 | same as Fallback |
approximated (preemption) | |
Parallel |
control | ≥ 1 | fork into every child, join on counts (§2.3) | approximated | success_count (default -1 = all), failure_count (default 1). Negative M means max(N+M+1, 0). Skipped children count as successes only when success_count < 0. |
ParallelAll (4.3.2) |
control | ≥ 1 | fork, join when every child has finished or skipped: F if failures ≥ max_failures, else S; K if all skipped |
approximated | max_failures (default 1, negative as above). The port description says "exceeds", the code uses ≥. |
IfThenElse |
control | 2 or 3 | compile(c1, compile(c2,S,F,K), n=3 ? compile(c3,S,F,K) : F, ERR) |
exact | A skipped c1 throws "Something unexpected happened" (run). |
WhileDoElse |
control | 2 or 3 (2 since 4.3.5) | same as IfThenElse |
approximated (re-check) | c1 is ticked on every tick. A skipped c1 makes the node return IDLE, which throws (run). |
TryCatch (4.9.0) |
control | ≥ 2 | try block c1..c(n-1) as a Sequence with exits S/K; every try child -F-> C, where C = compile(cn, F, F, F) |
exact | The catch child's result is ignored: the node returns FAILURE, also when cn is skipped (run). catch_on_halt (bool, default false) runs cn on halt. |
Switch2 … Switch6 |
control | N+1 | Branch(variable == case_1, compile(c1,S,F,K), Branch(variable == case_2, …, compile(default,S,F,K))) |
exact for one pass | Missing variable: default child. A selected child that skips makes the node SKIPPED (run). |
Inverter |
decorator | 1 | compile(c, F, S, K) |
exact | |
ForceSuccess |
decorator | 1 | compile(c, S, S, K) |
exact | SKIPPED passes through (run). |
ForceFailure |
decorator | 1 | compile(c, F, F, K) |
exact | SKIPPED passes through (run). |
Repeat |
decorator | 1 | e = compile(c, LOOP, F, K), LOOP = Branch([k<N], e, S); N=-1: LOOP = e; N=0: entry is S |
exact (loop edge) | num_cycles required. A skipped child makes the node SKIPPED even after earlier cycles ran (run). |
RetryUntilSuccessful |
decorator | 1 | e = compile(c, S, RETRY, K), RETRY = Branch([k<N], e, F); N=-1: RETRY = e; N=0: entry is F |
exact (loop edge) | num_attempts required, read again after each failure. SKIPPED after a failed attempt also gives K (run). |
KeepRunningUntilFailure |
decorator | 1 | e = compile(c, e, F, e) |
exact (loop edge) | Never SUCCESS, never SKIPPED. A skipped child keeps it RUNNING (run). |
Timeout |
decorator | 1 | compile(c, S, F, K) plus timeout edges to F from RUNNING-capable actions |
approximated | msec required (0 disables the timer). |
Delay |
decorator | 1 | compile(c, S, F, K) |
exact | delay_msec required. Waits first, then ticks the child. |
RunOnce (4.2.0) |
decorator | 1 | Branch(first activation, compile(c,S,F,K), LATER); LATER = K |
approximated (state across activations) | then_skip (default true). With then_skip="false", later activations return the first result without ticking. |
Precondition |
decorator | 1 | Branch(if, compile(c,S,F,K), ELSE); ELSE is F (default), S, K, or WAIT(if) for else="RUNNING" |
exact for one pass | Since 4.7.0 checked once per activation (§2.4). |
LoopInt, LoopBool, LoopDouble, LoopString (4.2.0, 4.3.5) |
decorator | 1 | e = Branch([queue not empty], compile(c, e, F, e), EMPTY); EMPTY is S, F or K from if_empty |
exact (loop edge) | Pops one element into value per tick. if_empty default SUCCESS. A skipped child continues the loop (run). |
SkipUnlessUpdated (4.6.0) |
decorator | 1 | Branch(updated(entry), compile(c,S,F,K), K) |
exact for one pass | Stateful guard (§2.4). A missing entry counts as "not updated" (run). |
WaitValueUpdate (4.6.0) |
decorator | 1 | WAIT(updated(entry)), then compile(c, S, F, K) |
exact for one pass | Same class as SkipUnlessUpdated, with RUNNING instead of SKIPPED. |
SubTree |
subtree | 0 | inline the body: compile(body, S, F, K) |
exact | Remapping in §5. Pre-conditions on the <SubTree> element read the parent blackboard. |
AlwaysSuccess |
action (constant) | 0 | S |
exact | |
AlwaysFailure |
action (constant) | 0 | F |
exact | |
Script |
action (effect) | 0 | S, carrying the script as an effect |
exact | code required. Always SUCCESS. A failing script throws. |
ScriptCondition (4.3.1) |
condition | 0 | Branch(code, S, F) |
exact | A pure expression is a guard label (§4.5). |
SetBlackboard |
action (effect) | 0 | S |
exact for literal values | value, output_key. Since 4.7.0 it returns FAILURE when value="{k}" names an entry that holds no value. |
UnsetBlackboard (4.4.3) |
action (effect) | 0 | S |
exact | key. |
Sleep (4.3.0) |
action | 0 | an action vertex with a single -S-> S edge |
exact | msec. Never fails. |
WasEntryUpdated (4.6.0) |
condition (registered as an action) | 0 | Branch(updated(entry), S, F) |
exact for one pass | Stateful: each node instance remembers the last version it saw. |
SequenceStar |
control | ≥ 1 | as SequenceWithMemory |
approximated | Registered only when BT.CPP is built with USE_BTCPP3_OLD_NAMES. Warn. |
user Action / Condition |
action / condition | 0 | as v3: vertex with S/F edges, or Branch(cond, S, F) |
exact | Assumed never to return SKIPPED, although BT.CPP allows it. |
user Control / Decorator |
control / decorator | ≥ 1 / 1 | unknown | approximated | As in v3 (Nav2 RecoveryNode, PipelineSequence, RoundRobin, RateController, …). |
The C++ class behind WasEntryUpdated is EntryUpdatedAction. SkipUnlessUpdated and WaitValueUpdate are both EntryUpdatedDecorator, registered with NodeStatus::SKIPPED and NodeStatus::RUNNING as the "not updated" status (bt_factory.cpp L171-L173). The XML only ever uses the registration names.
Classes that exist but are not registered¶
| Name | Status in v4 | Where |
|---|---|---|
ManualSelector |
class ManualSelectorNode still exists, not registered since 4.1.1 |
controls/manual_node.h |
ConsumeQueue, PopFromQueue, QueueSize |
header-only templates, never registered | decorators/consume_queue.h, actions/pop_from_queue.hpp |
TestNode |
used by substitution rules for mocking, not registered | actions/test_node.h |
SubTreePlus, BlackboardCheckInt/Double/String/Bool, Switch, Loop |
do not exist in v4 | — |
A v4 file that uses any of these names refers to a user-registered node, or is invalid.
2. The SKIPPED status¶
2.1 Where SKIPPED comes from¶
A node returns SKIPPED in exactly these cases:
- A pre-condition fires:
_skipIfis true, or_whileis false (§3). Preconditionwithelse="SKIPPED"and a falseif.SkipUnlessUpdatedwith an entry that has not changed.RunOnce(then_skip="true") on every activation after the first.- A
Loop*decorator with an empty queue andif_empty="SKIPPED". - A control node whose children were all skipped (§2.3), or a decorator whose child was skipped (§2.4).
- A user node whose
tick()returns SKIPPED. Nothing in BT.CPP forbids this (action_node.cpp). Beehave assumes that user nodes never do it, unless the config says otherwise.
SKIPPED is never stored. Since 4.3.4, executeTick returns SKIPPED to the parent but does not store it as the node's status (tree_node.cpp L151-L156). A node skipped by a pre-condition stays IDLE, so it evaluates its pre-conditions again the next time it is ticked. In 4.0.1 to 4.3.3 the SKIPPED status was stored.
2.2 may_skip: when K matters¶
Most nodes can never return SKIPPED. For them K is irrelevant and the walk can pass None. Compute this bottom-up:
may_skip(n) =
true if n has _skipIf or _while
true for SkipUnlessUpdated, RunOnce (then_skip true),
Precondition else="SKIPPED", Loop* if_empty="SKIPPED"
all(may_skip(c) for c in children) for Sequence, SequenceWithMemory, AsyncSequence,
ReactiveSequence, Fallback, AsyncFallback,
ReactiveFallback, ParallelAll, and the try block of TryCatch
success_count > 0 and all(may_skip) for Parallel (the literal port value; the default -1 never skips)
may_skip(c2) or may_skip(c3) for IfThenElse, WhileDoElse (a skipped c1 is ERR, report it)
any(may_skip(c) for c in children) for Switch2..Switch6
may_skip(child) for Inverter, ForceSuccess, ForceFailure, Repeat,
RetryUntilSuccessful, Timeout, Delay, Precondition,
WaitValueUpdate, SubTree (its body)
false for KeepRunningUntilFailure, Loop* (unless if_empty),
every leaf, and user nodes
The root of the tree is compiled with K = SKIPPED, a new terminal vertex that is drawn only when it is reachable. tickOnce() on a tree whose root skipped returns SKIPPED.
2.3 Control nodes¶
Every control node treats a skipped child as "not executed, move on". The node itself returns SKIPPED only when every child it ticked in this activation was skipped.
| Node | Child returns SKIPPED | Node result when every child is skipped | Source |
|---|---|---|---|
Sequence, AsyncSequence |
move to the next child, count it | SKIPPED; otherwise SUCCESS (run) | sequence_node.cpp L81-L103 |
SequenceWithMemory |
move on, count it | SKIPPED (run) | sequence_with_memory_node.cpp L68-L90 |
ReactiveSequence |
halt (reset) that child, move on | SKIPPED (run). Counted per tick. | reactive_sequence.cpp L75-L90 |
Fallback, AsyncFallback |
move to the next child, like a failure | SKIPPED; otherwise FAILURE. Fallback(fail, skip) is FAILURE (run) |
fallback_node.cpp L71-L93 |
ReactiveFallback |
reset that child, move on | SKIPPED; otherwise FAILURE (run) | reactive_fallback.cpp L75-L90 |
Parallel |
count it for this tick. It is not marked completed, so it is ticked again next tick. | success_count < 0 (default): SUCCESS, because skipped children count toward success (run). success_count > 0: SKIPPED (run). success_count="0" succeeds after the first child. |
parallel_node.cpp L69-L131 |
ParallelAll |
counts as finished | SKIPPED (run) | parallel_all_node.cpp L75-L99 |
IfThenElse |
c1: throws. c2/c3: the node returns SKIPPED (run) |
— | if_then_else_node.cpp L40-L77 |
WhileDoElse |
c1: returns IDLE, which throws. c2/c3: SKIPPED (run) |
— | while_do_else_node.cpp L39-L74 |
SwitchN |
the node returns SKIPPED. The source comment says "jump to default"; the code does not. | — | switch_node.h L148-L166 |
TryCatch |
try child: move on, count it. Catch child: the node returns FAILURE (run) | SKIPPED when every try child skipped (run) | try_catch_node.cpp L74-L131 |
The two-track chain. "SKIPPED only if all skipped" needs one bit of state: "has some child returned a non-skipped status yet?". In continuation-passing style, a Sequence with children c1 … cn compiles two entries per child:
T(n+1) = S # some earlier child succeeded: the remaining skips lead to SUCCESS
U(n+1) = K # every earlier child skipped: if the rest skip too, the Sequence skips
T(i) = compile(ci, S = T(i+1), F = F, K = T(i+1))
U(i) = compile(ci, S = T(i+1), F = F, K = U(i+1))
entry = U(1)
Fallback is the mirror image (T(n+1) = F, U(n+1) = K, children's F go to T(i+1), their S to S). For a child with may_skip(ci) = false, U(i) and T(i) are identical, so only the leading run of skippable children needs two versions. If no child may skip, the chain is the v3 chain.
The two versions of a child differ only in their K. When K is reached only through branch points at the child's entry (the common case: _skipIf on a leaf), the action vertices inside are the same in both tracks and the walk can share them. K can also be reached after an action has run: through a Repeat or RetryUntilSuccessful loop over a skippable body (the second cycle skips), and through a _while that turns false while an action is RUNNING. In those cases the same action needs different edges in the two tracks. The walk must then either duplicate the action vertices, or keep the T track only and report the node as approximated ("SKIPPED after a child ran is drawn as SUCCESS/FAILURE").
Parallel in detail (parallel_node.cpp L40-L131, parallel_node.h L48-L56). With N children, required = success_count < 0 ? max(N + success_count + 1, 0) : success_count, and the same for failure_count. After each child it checks: SUCCESS if successes ≥ required, or if success_count < 0 and successes + skipped ≥ required. FAILURE if N − failures < required or failures == failure_threshold. If the loop ends without a decision, the result is SKIPPED when every child skipped in this tick, else RUNNING. It throws when N is below either threshold. Consequences: failure_count="0" fails after the first child. With a positive success_count, a child that keeps skipping can leave the node RUNNING forever, which BT.CPP itself shows (run), so Beehave should warn.
2.4 Decorators¶
| Decorator | Child returns SKIPPED | K wiring |
|---|---|---|
Inverter, ForceSuccess, ForceFailure |
returns SKIPPED (run) | child K = K |
Repeat, RetryUntilSuccessful |
resets the child and returns SKIPPED, keeping the cycle counter (run) | child K = K, also from the loop's later cycles |
KeepRunningUntilFailure |
returns RUNNING, ticks the child again next tick (run) | child K = entry of the child (loop) |
Timeout |
returns SKIPPED | child K = K |
Delay |
returns SKIPPED after the delay (run) | child K = K |
RunOnce |
returns SKIPPED and does not mark itself as run | child K = K |
Precondition |
returns SKIPPED (run). Quirk: the "child running" flag is not cleared, so on the next activation the child is ticked without checking if (run). |
child K = K |
Loop* |
returns RUNNING and pops the next element, as after a success (run) | child K = loop entry |
SkipUnlessUpdated, WaitValueUpdate |
returns SKIPPED | child K = K |
SubTree |
returns SKIPPED (run) | body K = K |
The Precondition quirk affects later activations only, so a single static pass is not affected. It is worth a lint warning for a Precondition over a skippable child.
Precondition changed in 4.7.0 (commit 5f3f675). Before 4.7.0, if was evaluated on every tick, and a false value while the child was RUNNING returned else without halting the child. Since 4.7.0 it is evaluated once per activation (script_precondition.h L63-L90). With else="RUNNING" and a false if, the node keeps returning RUNNING and re-checks if on each tick until it holds (run). else="IDLE" makes the node return IDLE, which throws. The website's pre/post-conditions guide still says that else="RUNNING" re-evaluates "on every tick" while the child runs. The code, and BT.CPP's own docs/pre_postconditions.md on master, say it does not.
SkipUnlessUpdated, WaitValueUpdate and WasEntryUpdated compare the entry's sequence_id (incremented on every write) with the value the node instance saw last, then store the new value (updated_decorator.cpp L42-L72, updated_action.cpp L40-L68). The first check of an entry that has been written is "updated". The guard is therefore stateful: two different nodes watching the same key are independent conditions. Key them by node path, not by their text.
3. Pre-conditions and post-conditions¶
Sources: TreeNode::executeTick L71-L157, checkPreConditions L204-L259, checkPostConditions L261-L281, haltNode L159-L169, the enums in tree_node.h L47-L94, and their attachment to every node in createNodeFromXML L885-L902 and instantiateTreeNode L404-L419.
- Any node can carry them: leaves, controls, decorators, and
<SubTree>elements (run). - They are XML attributes, not ports. Their names are reserved, so they are never checked against the node's port list.
- The scripts are parsed when the tree is created. A syntax error makes the whole tree fail to load.
- They are evaluated in the blackboard of the node that carries them. For a
<SubTree>element that is the parent's blackboard, because the SubTree node is created before its child scope.
3.1 Pre-conditions¶
Evaluated in this fixed order, and the first that fires wins (run):
| Order | Attribute | Evaluated when | Fires if | Result | tick() called? |
|---|---|---|---|---|---|
| 1 | _failureIf |
node is IDLE | script is true | FAILURE | no |
| 2 | _successIf |
node is IDLE | script is true | SUCCESS | no |
| 3 | _skipIf |
node is IDLE | script is true | SKIPPED | no |
| 4 | _while |
node is IDLE | script is false | SKIPPED | no |
| 4 | _while |
node is RUNNING | script is false | halts the node (runs _onHalted), then SKIPPED |
no |
"IDLE" is "IDLE or SKIPPED" in the code. Since SKIPPED is not stored (§2.1), this means "the node is starting a new activation". _failureIf, _successIf and _skipIf are not checked again while the node is RUNNING. _while is the only pre-condition checked on every tick. When none fires, tick() runs and its result is the node's result.
Walk rule. Absent attributes drop their level:
compile(n, S, F, K) =
Branch(failureIf, F,
Branch(successIf, S,
Branch(skipIf, K,
Branch(while, body(n, S, F, K), K))))
body is the rule of §1. This is exact for a single pass. _while also needs "interrupt" edges from each RUNNING-capable action inside n to K, guarded by !(while) and carrying the _onHalted effect. That part is approximated, like reactive preemption, and should be reported.
3.2 Post-conditions¶
| Attribute | Runs when | Changes the status? |
|---|---|---|
_onSuccess |
the node returned SUCCESS | no |
_onFailure |
the node returned FAILURE | no |
_post |
the node returned SUCCESS or FAILURE, after _onSuccess / _onFailure |
no |
_onHalted |
a RUNNING node was halted, by its parent or by its own _while |
no |
- They also run when the status came from
_successIfor_failureIf.<AlwaysFailure _successIf="true" _onSuccess="a := 1" _post="b := 2"/>returns SUCCESS and sets both keys (run). - They do not run on SKIPPED (run) or on RUNNING.
- Before 4.5.2,
checkPostConditionsran after every tick, so_postalso ran on RUNNING and SKIPPED.
Walk rule. Post-conditions never change control flow. They are effects attached to the edges that leave n: _onSuccess; _post on every edge into S, _onFailure; _post on every edge into F, _onHalted on interrupt edges. For an action they are its outgoing edges. For a control node they are the edges from its inner actions that leave the node. Phase 1 can show them as edge notes or ignore them. Phase 2 needs them, because an assignment changes what later guards mean (§7.3).
3.3 Worked example¶
Both children may skip, so the two-track chain is needed: U2 = Branch(!ready, K, Patrol), T2 = Branch(!ready, S, Patrol), and entry = Branch(battery > 80, U2, Charge) with Charge -S-> T2.
flowchart LR
start((START)) -- "battery > 80 ∧ !ready" --> SK((SKIPPED))
start -- "battery > 80 ∧ ready" --> Patrol[Patrol]
start -- "!(battery > 80)" --> Charge[Charge]
Charge -- "SUCCESS ∧ !ready" --> OK((SUCCESS))
Charge -- "SUCCESS ∧ ready" --> Patrol
Charge -- FAILURE --> FAIL((FAILURE))
Patrol -- SUCCESS --> OK
Patrol -- FAILURE --> FAIL
When both are skipped the Sequence returns SKIPPED, not SUCCESS. A parent Fallback would then move on to its next child instead of stopping.
4. The scripting language¶
Used by Script (code), ScriptCondition (code), Precondition (if) and all eight pre- and post-condition attributes. Since 4.9.0 the parser is hand-written: a tokenizer (script_tokenizer.cpp) and a Pratt parser (script_parser.cpp), commit d198332. Up to 4.8.x it was a lexy grammar in scripting/operators.hpp. The differences are listed in §4.3. Evaluation is in scripting/operators.hpp.
4.1 Lexical structure (4.9.0+)¶
| Token | Form |
|---|---|
| identifier | [A-Za-z_@][A-Za-z0-9_]*. A leading @ names the root blackboard (4.6.0+). No {} braces: in scripts a blackboard key is a bare name. Keys containing ., / or - cannot be written. |
| integer | decimal 42, or hex 0x7F. Stored as int64. Out of range is an error (master). |
| real | 3.14, 1e3, 2.5E-2 |
| string | 'single quoted', no escapes. Double quotes are an error (run). |
| boolean | true, false (lower case only), stored as 1.0 and 0.0 |
| statement separator | ;. Optional: p := 1 q := 2 is two statements (run). Newlines are whitespace. |
In XML attributes, <, > and & are written <, > and &. The XML parser decodes them before the script parser sees the text.
4.2 Grammar and precedence (4.9.0+)¶
From loosest to tightest binding (leftBP, script_parser.cpp L104-L160):
| Level | Operators | Associativity | AST node |
|---|---|---|---|
| 1 | := = += -= *= /= |
right; the left side must be an identifier | ExprAssignment |
| 2 | c ? a : b |
right (a ternary may follow :) |
ExprIf |
| 3 | || |
left | ExprBinaryArithmetic |
| 4 | && |
left | ExprBinaryArithmetic |
| 5 | == != < > <= >= |
chainable: 0 < x <= 4 means 0 < x && x <= 4 (run) |
ExprComparison |
| 6 | | ^ |
left | bitwise |
| 7 | & |
left | bitwise |
| 8 | + - .. |
left | .. concatenates strings |
| 9 | * / |
left | |
| 10 | prefix - ~ ! |
prefix, binds tighter than every infix operator | ExprUnaryArithmetic |
| atoms | literals, identifiers, ( expr ) |
script := statement ( ';'* statement )* ';'*
statement := expr
expr := name ASSIGN_OP expr | ternary
ternary := or ( '?' expr ':' ternary )?
or := and ( '||' and )*
and := cmp ( '&&' cmp )*
cmp := bitor ( CMP_OP bitor )*
bitor := bitand ( ('|' | '^') bitand )*
bitand := sum ( '&' sum )*
sum := product ( ('+' | '-' | '..') product )*
product := unary ( ('*' | '/') unary )*
unary := ('-' | '~' | '!') unary | atom
atom := INTEGER | REAL | STRING | BOOLEAN | IDENT | '(' expr ')'
The value of a multi-statement script is the value of its last statement. ScriptCondition code="false; true" succeeds (run).
4.3 Differences up to 4.8.x (lexy grammar)¶
Files written for 4.0 to 4.8 can parse differently:
&&and||had the same precedence, left-associative:a || b && cmeant(a || b) && c. Since 4.9.0 it meansa || (b && c)(run). Beehave should parse with the 4.9+ rules, warn when an expression mixes&&and||without parentheses, and show such guards with explicit parentheses.- Strings could be single- or double-quoted.
- Identifiers could contain Unicode letters.
- Arithmetic, bitwise and string operators could not be mixed without parentheses (
dsl::groups). Prefix-,!and~applied to an atom only.
4.4 Evaluation¶
- Names. Identifiers are looked up first in the enums registered in C++ (
registerScriptingEnum,registerScriptingEnums<E>()), then in the blackboard. An enum shadows a key with the same name. A missing variable throws "Variable not found" (ExprNameL80-L106). Beehave cannot see C++ enums, so the config should be able to declare them. Unknown identifiers default to blackboard keys. - Numbers. Every arithmetic result is a
double. Booleans are1.0and0.0. &&and||do not short-circuit. Both sides are always evaluated:false && (x := 5) > 0setsx(run) (L214-L230).- Comparisons. Number with number. String with string (lexicographic). String with number: the string is converted, and enums are accepted. Anything else throws.
==and!=on doubles use a tolerance of thefloatepsilon.<,<=,>,>=are exact (IsSameL315-L326). - Assignment.
:=creates the entry if needed.=(and+=, …) throw if the entry does not exist (run). An assignment increments the entry'ssequence_id, whichWasEntryUpdatedand friends observe. - Unary
!on a string accepts"true"/"false"/"1"/"0"on master only (after 4.10.0).
4.5 Which expressions are side-effect free¶
A script is pure if no statement contains an assignment operator (:=, =, +=, -=, *=, /=) anywhere, including inside parentheses and ternary branches. Decide this on the token stream (= vs ==, <= vs <), never with a regular expression. A pure script reads the blackboard only, so its value can be a guard label.
| Use | Pure script | Impure script |
|---|---|---|
ScriptCondition, Precondition if, _failureIf, _successIf, _skipIf, _while |
guard on the expression | still a branch, on the value of the last statement. Report "guard with side effects" and record the assignments as an effect on both branches (they run either way). |
Script, _onSuccess, _onFailure, _post, _onHalted |
a no-op (allowed) | effect on the edge (§3.2) |
Evaluation can also throw: a missing variable, = on a missing key, or a type mix. A static walk ignores these runtime errors. A lint pass can flag reads of keys that no earlier node writes.
4.6 Displaying guards and their negation¶
- Label = the script text with whitespace collapsed and XML entities already decoded, for example
battery < 20. Condition key = a canonical print of the AST plus the blackboard scope it is evaluated in (§5.2). Thena>banda > bin the same scope are the same condition, but the same text inside two subtree instances is not. - Negated label, used on the false edge:
xwherexis a single name or literal:!x. And!xnegated isx. Remove double negation.- Anything else:
!(expr), for example!(battery < 20). Never write!exprwithout parentheses.!binds tighter than every binary operator, so!battery < 20would mean(!battery) < 20. - Optional simplification, for Phase 2: one non-chained comparison may be flipped (
==↔!=,<↔>=,>↔<=). This is exact in BT.CPP, apart from NaN, because==and!=share the same tolerance and the ordering operators are exact complements. Do not apply De Morgan in Phase 1. - When the 4.8.x and 4.9.x parses differ (§4.3), print explicit parentheses.
5. SubTree in v4¶
Sources: recursivelyCreateSubtree L1062-L1271 (the remapping loop is L1100-L1229), Blackboard::getEntry L146-L177, createEntryImpl L394-L460, loadSubtreeModel L316-L334, subtree_node.h.
<SubTree ID="T" …/> always creates a new blackboard, child of the caller's. Attributes are read in document order:
| Attribute | Effect | Since |
|---|---|---|
a="{k}" |
remap: inside key a is an alias of parent key k. Spaces around the braces are trimmed. |
4.0.1 |
a="{@k}" |
remap to the root blackboard's k, from any depth |
4.6.0 |
a="{=}" |
shorthand for a="{a}" |
4.6.0 for subtree attributes (4.5.2 for node ports) |
a="literal" |
sets local key a to the literal. Since 4.9.1 it is stored as int (or int64) when the whole string is an integer, as double when it parses as a real, else as a string (run). Before that, always a string. |
4.0.1 |
a="${k}" |
a literal string since 4.3.4. Before that, same as {k}. |
— |
a="=" |
the literal string =. = is the same-name shorthand only for node ports. |
— |
_autoremap="true" |
any key that is neither local nor remapped falls through to the same key in the parent, except private keys that start with _ (4.4.3+) (run). Literals are always written locally, whatever the attribute order (the 3.8.4 quirk is gone). |
4.0.1 |
name="x" |
the instance path becomes parent/x, else T::<uid>. Two SubTrees with the same name in one tree are an error (4.8.4) (run). |
4.0.1 |
pre- and post-conditions, _description, other _… attributes |
not remappings. Conditions apply to the SubTree node and read the parent blackboard. | — |
Subtree port models (4.4.0+). If <TreeNodesModel> has <SubTree ID="T"> with ports, then for each declared port not given in the XML, and only when _autoremap is off: a default is used as if it had been written ({x} → remap, otherwise a literal) (run), and a port with no default makes loading fail with "mandatory port … but you are not remapping it" (run). With _autoremap on, the model is not consulted. A model port whose name is not an allowed port name (for example _myPort) and that is used in the XML is an error on master.
Recursion. A tree that includes itself, directly or indirectly, is rejected at creation since 4.9.0 (run). Earlier releases had no such check.
5.1 Differences from v3 SubTreePlus¶
| Topic | v3.8 SubTreePlus |
v4 SubTree |
|---|---|---|
| auto-remap attribute | __autoremap (two underscores) |
_autoremap |
private _keys under auto-remap |
forwarded | local (4.4.3+) |
| literal after auto-remap | written to the parent (3.8.4+ quirk) | always local |
| literal type | string | int, int64 or double when numeric (4.9.1+) |
${k} |
remap | literal (4.3.4+) |
{=} |
literal {=} |
same-name remap (4.6.0+) |
{@k} |
key literally named @k |
root blackboard |
TreeNodesModel subtree ports |
ignored | defaults applied, mandatory ports checked |
name |
ignored | used for the path, must be unique |
__shared_blackboard |
on classic SubTree |
removed |
5.2 Flattening rule for v4¶
The v3 rule (btcpp-v3-xml.md §5.3) becomes:
resolve(k, scope):
if k starts with "@": return Key(k[1:]) # root blackboard
if k in scope.literals: return Literal(scope.literals[k]) # typed (4.9.1+)
if k in scope.remap: return resolve(scope.remap[k], scope.parent)
if scope.autoremap and not k.startswith("_"): return resolve(k, scope.parent)
return Key(scope.path + "/" + k) # local to the instance
root scope: resolve(k) = Key(k)
scope.remap and scope.literals come from the <SubTree> attributes in document order,
after rewriting {=} to {a} and, when _autoremap is off, adding the model defaults.
Apply resolve to every {key} port value inside the subtree and to every identifier in its scripts. A script identifier is a key, unless it is a declared enum.
6. Document structure¶
Primary sources: xml_parsing.cpp (loadDocImpl L336-L469, VerifyXML L471-L698, instantiateTree L700-L736, createNodeFromXML L740-L1060), bt_factory.cpp createTreeFromText/createTreeFromFile L440-L486, basic_types.cpp L547-L614, and BT.CPP's docs/name_validation_rules.md.
6.1 <root>¶
- The document element must be
root. BTCPP_format: when it is missing, v4 prints a warning to stdout and carries on. Its value is never checked (L352-L359). Version detection stays Beehave's job (btcpp-v3-vs-v4.md§3). Two v4 fixtures have no marker:v4/btcpp/examples/test_files/Check.xmlandv4/nav2-jazzy/nav2_docking/…/application_example.xml.main_tree_to_execute:createTreeFromTextandcreateTreeFromFileresolve the tree to run in this order: (1)main_tree_to_executeof that document; (2) the only<BehaviorTree>with anIDin that document, ignoring included files; (3) the only tree newly registered by loading it; (4) the parser default:main_tree_to_executeof the first document ever loaded, else the only registered tree, else the error "[main_tree_to_execute] was not specified correctly" (run).factory.createTree("ID")names the tree explicitly, which is what most v4 code does.
6.2 <BehaviorTree ID="…">¶
- Exactly one child element.
IDmay be omitted only when<root>has exactly one child element of any kind: a<TreeNodesModel>or<include>next to it makes the missingIDan error (run). An ID-less tree is registered asBehaviorTree_<n>.IDmust not be the name of a registered node (4.6.2), and must pass the model-name rules (§6.6, 4.8.4).- Duplicate IDs: the last definition wins (
tree_roots[name] = …), the opposite of v3 (run). Includes are loaded before the including file's own trees, so a local tree overrides an included one with the same ID. Later files loaded into the same factory override earlier ones. Beehave should warn, and the v4 parser must keep the last definition, not the first.
6.3 <include path="…" [ros_pkg="…"]/>¶
pathis mandatory: a missing one is an error ("Invalid \<include> tag"). In v3 it crashed.- A relative path is resolved against the directory of the including file, which becomes the current directory for nested includes. Same as v3. Fixture:
v4/btcpp/tests/trees/(sibling, child and parent includes). ros_pkgresolves throughament_indexin ROS 2 builds only. Otherwise it throws. With an absolutepath,ros_pkgis ignored with a warning.- There is no include-cycle detection and no de-duplication. Beehave must detect cycles itself.
- Third-party loaders add their own include attributes (AutoAPMS uses
<include autoapms="…"/>, seev4/auto-apms/…/include_e2e.xml). Report unknown include attributes as unresolved, as forros_pkg.
6.4 <TreeNodesModel>¶
- At most one per file. The check that every model has an
IDiterates over the children of<root>instead of the model's children, the same bug as in v3 (L501-L534). - Elements
Action,Condition,Control,DecoratorandSubTreewithID. Ports areinput_port,output_portandinout_portwithname,typeanddefault, and the description as text.writeTreeNodesModelXMLcan add<MetadataFields><Metadata key="value"/></MetadataFields>(L1306-L1360). Groot2 adds attributes such aseditable="true". An empty<TreeNodesModel/>is common (v4/auto-apms/…/my_behavior_tree.xml). - The runtime reads only the
<SubTree>models (§5, since 4.4.0). The other entries are for Groot2, and for Beehave they are the main source of node kinds, as in v3. - Models-only files (
<root BTCPP_format="4"><TreeNodesModel>…), like Nav2'snav2_tree_nodes.xml, are valid inputs. - v4 can also write an XSD of the registered nodes (
writeTreeXSD). It supports only the compact form.
6.5 Node elements¶
- Compact
<Name …/>or explicit<Action|Condition|Control|Decorator ID="Name" …/>, as in v3. The explicit tag is not checked against the registered kind:<Action ID="Sequence">with a child works (run). Use it only as a hint. IDon a compact element is an error ("Attribute [ID] is not allowed") (run).- Compact subtree references
<T/>are rejected ("Node not recognized") (run). They were rejected in v3 too. BT.CPP's ownexamples/test_files/subtree_test.xmlstill uses them (fixturev4/btcpp/examples/test_files/subtree_test.xml). No code loads that file any more, so Beehave can keep its "accept with a warning" behaviour. VerifyXMLarity checks: a decorator has exactly 1 child, a control ≥ 1 (TryCatch≥ 2, 4.9.0), an action or condition 0, a<SubTree>0. AReactiveSequencemay not have more than oneAsyncSequencechild. A<BehaviorTree>or<SubTree>ID must not be a registered node name. Not checked statically:IfThenElse/WhileDoElsearity (2 or 3) andSwitchN(N+1), which throw at the first tick, andParallelthresholds. Beehave should check all of them.- Upstream bug (4.7.0+): the
ReactiveSequencecheck above looks up each child's element name, so a child written in explicit form (<Action ID="…">,<Condition ID="…">) fails to load with "Unknown node type: Action" (run). The same child under aSequenceloads. Beehave should accept such trees and warn. - Nesting deeper than 256 levels is rejected (both in
VerifyXMLand at creation).
6.6 Attributes, ports and names¶
| Rule | Detail |
|---|---|
| Reserved attributes (never ports) | ID, name, _autoremap, _failureIf, _successIf, _skipIf, _while, _onSuccess, _onFailure, _post, _onHalted (IsReservedAttribute L567-L584) |
Other _… attributes |
silently ignored (_description, _uid, …) (run). Anything that is not an allowed port name goes to other_attributes. |
| Allowed port name | starts with a letter, contains no forbidden character, is not reserved |
| Unknown port on a registered node | error: "a port with name [x] is found in the XML … but not in the providedPorts()" (run). For example a v3 Parallel success_threshold is a hard error in v4. |
| Literal for a strongly typed port | converted when the tree is created. A failing conversion is a load error. |
| Forbidden characters in model and port names (4.8.4) | space, tab, CR, LF, < > & " ' / \ : * ? | ., ASCII 0-31 and 127. UTF-8 is allowed. |
| Model names | non-empty, not Root or root. On master also checked for the explicit ID form. |
| Port names | also must not start with a digit |
Instance names (name) |
anything except control characters |
Port values on ordinary nodes:
| Value | Meaning |
|---|---|
{key} (spaces around trimmed) |
blackboard entry key |
{@key} |
entry key of the root blackboard (4.6.0) |
{=} or = |
entry with the same name as the port ({=} 4.5.2+, = kept from v3) |
${key} |
literal string (since 4.3.4) |
| anything else | literal |
| absent | the manifest default for input ports, else getInput fails at runtime |
6.7 Checklist for the v4 parser¶
- Accept
<root>, with or withoutBTCPP_format. Warn about a missing marker or a value other than4. - Resolve
<include>relative to the including file and detect cycles. Keep the last definition of a duplicate tree ID and warn. - Load every
<TreeNodesModel>, including models-only files and the config. Read<SubTree>port models for §5. - Classify with the table of §1: the built-ins, then models, then config, then shape.
WasEntryUpdatedandScriptConditionare conditions. - Separate the reserved condition attributes from ports. Ignore other
_…attributes. Reject or warn on unknown ports of built-ins. - Parse every script with the §4 grammar. Classify each as pure or impure.
- Check arities statically, including
IfThenElse,WhileDoElse,SwitchN,TryCatchandParallelthresholds. - Pick the main tree with the order of §6.1, or a CLI flag.
- Flatten with §5.2. Detect recursion. Warn about duplicate SubTree
names and mandatory model ports that are not remapped. - Walk with
compile(n, S, F, K): §1 for the node, §3.1 around it,may_skip(§2.2) to skip the unneededKwork, and report every approximated construct.
7. Mapping onto Beehave's model¶
7.1 Node types and Semantics¶
| v4 XML name | Semantics |
Status | Single pass |
|---|---|---|---|
Sequence, AsyncSequence |
SEQUENCE |
existing (the async yield does not change the edges) | exact |
SequenceWithMemory (and SequenceStar) |
SEQUENCE_WITH_MEMORY |
existing | approximated |
ReactiveSequence |
REACTIVE_SEQUENCE |
existing | approximated |
Fallback, AsyncFallback |
FALLBACK |
existing | exact |
ReactiveFallback |
REACTIVE_FALLBACK |
existing | approximated |
Parallel |
PARALLEL |
existing; new port names and skip rule | approximated |
ParallelAll |
PARALLEL_ALL |
new | approximated |
IfThenElse |
IF_THEN_ELSE |
existing | exact |
WhileDoElse |
WHILE_DO_ELSE |
existing; arity 2..3 | approximated |
TryCatch |
TRY_CATCH |
new | exact |
Switch2..Switch6 |
SWITCH |
existing; numeric and enum equality | exact |
Inverter, ForceSuccess, ForceFailure |
existing members | existing | exact |
Repeat, RetryUntilSuccessful, KeepRunningUntilFailure |
REPEAT, RETRY, KEEP_RUNNING_UNTIL_FAILURE |
existing | exact with loop edges (approximated today) |
Timeout, Delay |
TIMEOUT, DELAY |
existing | approximated / exact |
RunOnce |
RUN_ONCE |
new | approximated |
Precondition |
PRECONDITION |
new (guard decorator with else) |
exact |
LoopInt, LoopBool, LoopDouble, LoopString |
LOOP_QUEUE |
new | exact with a loop edge |
SkipUnlessUpdated |
SKIP_UNLESS_UPDATED |
new | exact |
WaitValueUpdate |
WAIT_VALUE_UPDATE |
new | exact (waits) |
WasEntryUpdated |
WAS_ENTRY_UPDATED |
new; NodeKind.CONDITION |
exact |
AlwaysSuccess, AlwaysFailure |
existing | existing | exact |
SetBlackboard |
SET_BLACKBOARD |
existing | exact |
UnsetBlackboard |
UNSET_BLACKBOARD |
new (or a shared "blackboard write") | exact |
Script |
SCRIPT |
new; entry S plus an effect |
exact |
ScriptCondition |
SCRIPT_CONDITION |
new; NodeKind.CONDITION |
exact |
Sleep |
SLEEP |
new; action vertex with only a success edge | exact |
SubTree |
SUBTREE_V4 |
new: v4 remapping (§5.2) differs from both SUBTREE and SUBTREE_PLUS |
exact |
BLACKBOARD_CHECK, MANUAL_SELECTOR and SUBTREE_PLUS are never produced by the v4 parser.
7.2 Model changes the v4 walk needs¶
- A third continuation.
compile(node, path, s, f, k, subtrees), withk = Nonewhenmay_skipis false, and aSKIPPEDterminal vertex next toSUCCESSandFAILUREfor the root. - Conditions as attributes.
Node.portstoday holds every attribute exceptIDandname. The four pre-conditions and four post-conditions should go into a separate mapping (for exampleNode.conditions), so they are not treated as ports and so the v3 parser can keep rejecting them. - Script conditions.
Condition(key, label, negated_label)with the key built from the canonical AST and the scope (§4.6). Stateful guards (WasEntryUpdated,SkipUnlessUpdated,RunOnce's "first activation") are keyed by node path. - Effects on edges.
_onSuccess,_onFailure,_post,_onHaltedandScriptgive edges an optional list of assignments. Phase 1 can show them as notes. - Error sinks. A skippable first child of
IfThenElseorWhileDoElseandelse="IDLE"produce a diagnostic, not an edge.
7.3 What is exact in a single static pass¶
Exact: Sequence, AsyncSequence, Fallback, AsyncFallback, IfThenElse, TryCatch, SwitchN, Inverter, ForceSuccess, ForceFailure, Delay, Precondition, SkipUnlessUpdated, WaitValueUpdate, WasEntryUpdated, Script, ScriptCondition, SetBlackboard, UnsetBlackboard, Sleep, SubTree, and _failureIf, _successIf, _skipIf and _while at activation. Repeat, RetryUntilSuccessful, KeepRunningUntilFailure and Loop* are exact once loop edges exist.
Approximated: SequenceWithMemory (resume point), ReactiveSequence and ReactiveFallback (preemption), Parallel and ParallelAll (concurrency), WhileDoElse (re-check), Timeout (time), RunOnce (history across activations), _while while RUNNING (interrupt edges), a skipped child after an action has run (§2.3), user controls and decorators.
A caveat for guard reasoning. _expand in walk.py drops contradictory paths and merges a condition seen twice on one path. That assumes a condition keeps its value along a path. In v4 a Script, a post-condition, SetBlackboard, UnsetBlackboard or an output port can write a key between two evaluations of a guard that reads it. The walk should forget the literals over a key once a write to that key lies on the path, or at least not merge across such a write.
Sources¶
- BehaviorTree.CPP tag
4.10.0(commit879522c75cce5e67f3dd7b5591bcb96eb3557a42) andmasterat commit03ec870a07b384f0766bbfe81f77c64a9f994a2b(2026-10-10). Line numbers below are formaster. Version boundaries were found withgit tag --containson the commits that introduced each behaviour. Behaviour marked (run) was checked with a small C++ program linked against a local4.10.0build. - Website: pre- and post-conditions guide, scripting guide (btcpp_website commit
9cc7aad). - Independent check: the LiteBT differential corpus, whose trees run on BT.CPP 4.10.0 and are fixtures in
tests/fixtures/public/v4/litebt/. Itsa7-precond-order.xml,f1-ifthenelse-stale.xmlandf2-whiledoelse-strand.xmlagree with §2 and §3.