0011. Name nodes by a stable path, and compute runtime ids from the tree¶
- Status: Accepted
- Date: 2026-11-12
Context¶
Logs, tests, diffs and editors need to point at one node of a tree, and then at the vertex or the guard that node became (roadmap FD1 and FD2). Three kinds of name are in use:
- BehaviorTree.CPP v4 numbers the nodes of an instantiated tree depth first
from 1, a
SubTreenode before its contents (TreeNode::UID()), and builds a path from instance names, adding::<uid>to unnamed nodes (TreeNode::fullPath(),xml_parsing.cpp). Its loggers record both. - Some runtimes publish their own indices: the same pre-order walk, from 0.
- Display ids (
a1,a2…) number actions in document order. They change whenever an action is added before another one, and conditions have none.
UIDs and runtime paths shift when a node is inserted anywhere before them, so they cannot key a diff. Beehave also stays static: it must compute every id from the tree alone, never from a run.
Decision¶
- Every node of the instantiated tree gets a
NodeRef: a path, Beehave's stable key, and its runtime ids. Action vertices and guard conditions carry theNodeRefof the node they come from.NodeRefs take no part in graph equality, so two trees with the same behaviour still compare equal. - A path segment is the node's
name, else its type (for a subtree node, the ID of the tree it includes). Siblings with the same segment are numbered#2,#3… in document order./,#and%are percent-escaped. The path starts at the root node, not at the tree ID, so renaming the tree keeps the keys. - Runtime ids come in two schemes over the same pre-order walk, chosen with
IdScheme:btcpp-v4from 1 andpreorderfrom 0. Every node that the runtime creates counts, controls and decorators included, soruntime_ids()lists them all, not only actions. - The runtime path is computed the way BT.CPP v4 does, for BT.CPP trees. It is checked against BT.CPP's own observer tutorial.
- A guard that checks one condition twice keeps the first node, as it keeps the first literal.
Consequences¶
- A tool holding an id or a runtime path from a log finds the node, then the action or the guards it became, without running anything.
- Diffs and plans key nodes by path. Renaming a node, or reordering unnamed siblings of one type, changes its path; naming nodes avoids that.
- For BT.CPP v3, which numbers nodes per process, the ids are what v4 would
give the same tree. For py_trees, ids count Beehave's model, where an
EternalGuardbecomes two nodes, and there is no runtime path. - The JSON output gains a
tree_nodeobject on actions and guard terms. Adding fields does not change its version.