Behavior Trees

Behavior trees are a hierarchical model used to control the decision-making process of AI agents. They are composed of nodes that return a state of Success, Failure, or Running.

Core Concepts

Nodes

Every node in a behavior tree is a subclass of Node. The tree is traversed from the root node down to leaf nodes.

Leaf Nodes: Perform actions or checks (e.g., ActionNode, ConditionNode).
Composite Nodes: Control the flow of execution by managing child nodes (e.g., SequenceNode, SelectorNode).
Decorator Nodes: Modify the behavior of a single child node (e.g., InverterNode, RepeatNode).

Ticks

The tree is updated via a tick(dt) method, where dt is the delta time since the last update. This propagates down the tree, updating active nodes.

Node States

SUCCESS: The node completed its task successfully.
FAILURE: The node failed to complete its task.
RUNNING: The node is currently executing and needs to be ticked again in the next frame.

Built-in Nodes

Hology Engine provides a set of standard nodes to build your trees.

Composite Nodes

SequenceNode: Runs children in order. Succeeds if all children succeed. Fails immediately if any child fails.
SelectorNode: Runs children in order. Succeeds immediately if any child succeeds. Fails if all children fail.
ParallelSequenceNode: Runs all children simultaneously. Succeeds if all children succeed. Fails if any child fails.
ParallelSelectorNode: Runs all children simultaneously. Succeeds if any child succeeds. Fails if all children fail.
WeightedRandomSelectorNode: Selects one child to run based on assigned weights.

Decorator Nodes

InverterNode: Flips the result of its child (Success becomes Failure, Failure becomes Success).
RepeatNode: Repeats the child node indefinitely.
RepeatTimesNode: Repeats the child a specific number of times.
RepeatUntilNode: Repeats the child until a condition function returns true.
RepeatUntilFailNode: Repeats the child until it returns Failure.
GuardNode: Only runs the child if a condition is met; otherwise returns Failure.
CooldownNode: Prevents the child from running again until a cooldown period has passed.
TimerNode: Runs the child for a specific duration, then returns Failure.
DelayNode: Waits for a specified time before running the child.
ThrottleNode: Limits how often the child node is ticked.

Leaf Nodes

ActionNode: Executes a function that returns a NodeState.
ConditionNode: Checks a condition function. Returns Success if true, Failure if false.
WaitNode: Returns Running for a specified duration, then Success.
SuccessNode: Always returns Success.
FailNode: Always returns Failure.

Creating a Behavior Tree

Behavior trees are typically constructed in your Actor's onBeginPlay method.

import { 
  SelectorNode, SequenceNode, ActionNode, WaitNode, RepeatNode, 
  NodeState 
} from '@hology/core/gameplay';

// ... inside your Actor class

onBeginPlay() {
  // 1. Define leaf behaviors
  const attack = new ActionNode(() => {
    console.log("Attacking!");
    return NodeState.SUCCESS;
  });

  const patrol = new SequenceNode();
  patrol.addChild(new ActionNode(() => {
     console.log("Moving to waypoint");
     return NodeState.SUCCESS; 
  }));
  patrol.addChild(new WaitNode(1000)); // Wait 1 second

  // 2. Compose the tree
  const rootSelector = new SelectorNode();
  
  // Try to attack first, if that fails (e.g. condition not met), patrol.
  rootSelector.addChild(attack); 
  rootSelector.addChild(patrol);

  // 3. Wrap in a repeater to keep the AI active
  this.behaviorTree = new RepeatNode(rootSelector);
}

onUpdate(dt: number) {
  // 4. Update the tree every frame
  this.behaviorTree?.tick(dt);
}

Custom Nodes

You can create custom nodes by extending LeafNode or DecoratorNode for more complex game-specific logic.

import { LeafNode, NodeState } from '@hology/core/gameplay';

class CheckHealthNode extends LeafNode {
  constructor(private character: Character, private threshold: number) {
    super();
  }

  tick(dt: number): NodeState {
    if (this.character.health < this.threshold) {
      return NodeState.SUCCESS;
    }
    return NodeState.FAILURE;
  }
}