Beehave for Godot

The Blackboard is a centralized repository used to store and share data between multiple nodes in a behavior tree. It prevents the need to pass variables directly to nodes and ensures data consistency across different game characters or objects.

By default, every BeehaveTree manages its own private blackboard instance. However, you can assign a custom Blackboard node from your scene tree to the blackboard property of a BeehaveTree to allow multiple trees to share the same data source.

Leaf nodes are the terminal nodes in a Beehave behavior tree. They have no children and represent the actual execution of logic. Unlike composite nodes or decorators that manage flow, leaf nodes interact directly with the game world.

There are two primary types of leaf nodes:

• Action Nodes: Perform actions that change the game state (e.g., moving, playing animations).
• Condition Nodes: Check conditions in the game state (e.g., checking health levels or visibility).

All leaf nodes must return one of three statuses: SUCCESS, FAILURE, or RUNNING.

Beehave uses a hierarchical tree structure composed of different node types to organize AI logic:

• Root: The entry point of the tree.
• Composite Nodes: Manage the flow between multiple child nodes (e.g., deciding which branch to follow).
• Decorator Nodes: Modify the behavior or result of their single child node (e.g., inverting a result or repeating an action).
• Leaf Nodes: The terminal nodes that perform actual game actions (e.g., Move to position) or check specific conditions (e.g., Is health low?).

Every node in a Beehave behavior tree returns one of three status codes that determine how the tree progresses:

• SUCCESS: The node completed its task successfully.
• FAILURE: The node failed its task or its conditions were not met.
• RUNNING: The node is still performing its task and requires more time. When a node returns RUNNING, it will be revisited on the next tick until it returns SUCCESS or FAILURE.

You can monitor Beehave's performance directly within the Godot editor. Navigate to the Debugger panel at the bottom of the editor, select the Monitors tab, and scroll down to the beehave section.

Available global metrics include:

• beehave/tree_id-process_time: The total process time per frame tick for the whole behavior tree.
• beehave/total_trees: The total number of Beehave nodes in the scene.
• beehave/total_enabled_trees: The number of active behavior trees in the scene.

Use the Delayer decorator to create a delay between a trigger event and the subsequent reaction, allowing for anticipation or telegraphing in gameplay.

Structure:

Sequence
├── TriggerEvent
└── Delayer (seconds)
    └── ReactToEvent

The Memory Pattern uses the Blackboard to store information between ticks, allowing nodes to make decisions based on past events (e.g., remembering a player's last seen position).

Structure:

Sequence
├── Condition (Stores result in blackboard)
└── Action (Uses stored result)

// SpotAndRememberPlayer.gd
class_name SpotAndRememberPlayer extends ConditionLeaf

func tick(actor: Node, blackboard: Blackboard) -> int:
    var player = get_tree().get_first_node_in_group("player")
    if player and actor.can_see(player):
        // Remember where we saw the player
        blackboard.set_value("last_seen_position", player.global_position)
        blackboard.set_value("last_seen_time", Time.get_ticks_msec())
        return SUCCESS
    return FAILURE

Use UntilFail to repeat a behavior continuously until it returns a failure status. This is ideal for automating repetitive tasks like resource gathering.

Structure:

UntilFail
└── BehaviorToRepeat