modular-behavior-tree

Loading trees from XML files

Modular behavior tree is a JavaScript implementation of modular behavior trees, similar to the behavior trees used in the Lumberyard engine. It was inspired by two existing libraries, BehaviorTree.js and BEHAVIOR3JS. The main feature is loading trees from XML files, which lets you describe a behavior as a tree of nodes and keep that description separate from the code that runs it. A tree file starts with a BehaviorTree root element and contains child nodes such as MemSequence, Wait, and LogMessage. In the example the main tree holds a MemSequence that first waits three thousand milliseconds and then logs a message saying it waited three seconds. A second subtree waits five seconds and logs a different message. The main tree references those subtrees by name, so the XML describes composition while the node classes supply the behavior. To load a file you call BehaviorTree.parseFileXML with the path and a map of any custom node classes the file uses. You then build a BehaviorTree instance with the parsed tree and a blackboard object that holds shared data. Running the tree is a matter of calling bt.tick() on a timer, and the README shows a setInterval loop that ticks every five hundred milliseconds. Because the tree is data, you can edit the structure without touching the action code, and you can mix parsed trees with trees built in code.

The built in node types

The library ships a set of basic nodes so you can build trees without writing much code. The composite nodes Sequence, Selector, MemSequence, and MemSelector hold children and decide which child runs next. The Mem variants remember the last child that returned RUNNING and skip the earlier children on the next tick, which is useful for tasks that span several ticks. Selector runs children until one does not fail, while Sequence runs children until one does not succeed. The decorator Inverter flips SUCCESS to FAILURE and FAILURE to SUCCESS. MaxTime returns FAILURE if its child takes too long and keeps the child in RUNNING while the work is in progress. Wait is a simple action that returns RUNNING until the timer elapses. These are imported from the package alongside the Action, Composite, Decorator, and Condition base classes you extend to write your own nodes. Every node returns one of three constants. SUCCESS means the computation succeeded, FAILURE means it failed, and RUNNING means it is still in progress. The node lifecycle has three methods. start runs before run, but not when a node resumes after ending with RUNNING. run is the main computation. end runs after run finishes with SUCCESS or FAILURE.

Writing your own nodes

To create a custom node you inherit from one of four base classes, Action, Composite, Decorator, or Condition, and most users only need Action. The README shows a LogMessage action that takes a text property and prints it during run, returning SUCCESS. The constructor receives an object with a properties field and passes it to the parent class, so the XML loader can supply values from the file. When you parse the tree you hand the class to parseFileXML in the custom node map, and the loader instantiates it with the properties declared in XML. You can also build trees directly in code and mix them with parsed trees. The example builds a Sequence whose first child is an inline Action that logs a message and returns FAILURE, and whose second child is a parsed subtree. This means a single tree can combine hand written logic with XML described structure. For more complex composites you can extend Composite and implement run to walk the children yourself, as the README demonstrates with Sequence, Selector, MemSequence, and MemSelector. Each of those shows how to execute children, how to stop on a non matching status, and how the Mem variants track the open child index so a resumed tick continues where it left off rather than restarting from the first child.

Editorial conclusion

Modular behavior tree is a JavaScript library installed with npm install --save modular-behavior-tree and licensed under MIT. It loads behavior trees from XML, ships basic node types, and lets you write custom nodes by extending Action, Composite, Decorator, or Condition.