0013. Let the config give a custom node a preset¶
- Status: Accepted
- Date: 2026-11-12
Context¶
Custom controls and decorators are the largest source of approximations on
real trees: Beehave walks an unknown control like a Sequence and an unknown
decorator as transparent, and reports both
(ADR 0004). Many of them behave exactly like
a node Beehave knows (Nav2's PipelineSequence, a project's own Fallback
with logging), or follow a handful of generic patterns: run the child until
it succeeds, poll a check until it holds, loop until a blackboard flag is set,
run children in parallel until one succeeds (roadmap F4a).
A project's own node may also share a name with a node of another BT.CPP
version (a v3 project with its own ParallelAll), which today makes the file
read as v4.
Decision¶
beehave.yamlgets anodes:mapping from node type to a preset:Name: preset, orName: {behaves_like: preset, <options>}. Presets live inbeehave.presets; each fixes the node's kind, how many children it may have, and its walk rule. Options are checked against the preset.- The model records it:
Node.behaves_likeandNode.options, and newSemanticsmembers for behaviours no built-in has:PIPELINE_SEQUENCE,ROUND_ROBIN,PARALLEL_FIRST_SUCCESS,UNTIL_SUCCESSandLOOP_UNTIL_FLAG. Diagnostics name the preset:KeepTrying (until_success): …. - A node type under
nodesis declared, like one underconditionsoractions: never evidence of BT.CPP v4 or of py_trees XML. A preset for a built-in of the file's version is ignored with apreset-ignoredwarning. - Loops are walked up to the point where the child starts again, and no
further: an
until_successchild that fails has no failure edge, and aloop_until_flagchild that succeeds leads to the exit only when the flag is set. The edge back to the child needs cycles (FD5); when the child can run an action, that missing edge is reported. A loop whose child only checks something is exact. - Concurrent presets (
parallel_first_success) keep the existing parallel approximation, as one-after-another children, and are reported.
Consequences¶
- Exact presets are checked against the reference interpreter on random trees, loops included: with every condition and action keeping its value, a loop ends in its first pass or never, and the graph has no edge exactly where the interpreter would spin.
- The graph never shows an edge a loop cannot take, at the cost of missing the edges back to the child until FD5.
- Nav2's per-distro presets and its bounded loops (
RecoveryNode) are left for later; they need counted loops.