GoTree

A small Godot addon to easily implement node based behaviour trees.

GoTree provides a set of reusable behavour nodes that can be organized into behaviour trees in the scene tree. It also provides base scripts so you can create custom behaviours by extending GTLeaf, GTLeafCondition, or GTDecorator.

🤔 Why use GoTree?

I made GoTree as light and barebones as possible. Behaviour trees can become large and complex so I decided to make the core nodes should be as simple and readable as possible so that it can be adapted to as many use cases as possible.

Each scripts is comment documented and should be fairly easy to figure out.

✨ What it includes

• GoTreeRoot: the tree root that drives behaviour evaluation.
• GTSequence: ticks children in order and stops on the first non-success.
• GTSelector: ticks children until one succeeds or is running.
• GTRandomSelector: chooses a random child to tick each cycle.
• GTCondition: decorator that only ticks its child when a custom condition returns true.
• GTDelay: decorator that delays child execution for a configured duration.
• GTCooldown: decorator that blocks child execution until a cooldown expires.
• GTStatusInverter: decorator that inverts success/failure states.
• GTStatusOverrider: decorator that forces a fixed result regardless of the child.
• GTDebug: decorator that logs child ticks for development.
• GTLeaf: base leaf node for custom behaviour.
• GTLeafCondition: leaf node that returns success or failure from an overrideable condition.

🧠 How it works

1. Place a GoTreeRoot node under the scene node that owns the behaviour.
2. Set optional shared state using actor and blackboard on the root.
3. Add a single child branch under GoTreeRoot; only the first child is evaluated.
4. Use control flow nodes (GTSequence, GTSelector, GTRandomSelector) to compose the tree.
5. Wrap branches with decorators to gate, delay, cooldown, debug, or alter results.
6. Implement actions by extending GTLeaf or GTLeafCondition.

The root ticks the tree every tick_delay physics frames. That means the tree can run every physics frame or at a slower interval depending on the value of tick_delay.

⚙️ Installation

1. Copy the addons/go_tree folder into your Godot project.
2. Open Project > Project Settings > Plugins.
3. Enable GoTree.

🚀 Getting started

Example scene setup

• Add GoTreeRoot as a child of your agent or owner node.
• Set actor to the agent node (or use the root's parent node in code).
• Add a control flow node as the first child of GoTreeRoot.
• Add leaf and decorator nodes under that control flow node.

Example behaviour tree

GoTreeRoot
 ├─ GTSequence
 │    ├─ GTLeafCondition
 │    ├─ GTDelay (delay = 0.5)
 │    │    └─ GTLeaf
 │    └─ GTDebug (custom_debug_message = "Sequence ticked")
 │         └─ GTLeaf

Example custom leaf

extends GTLeaf

func tick(_delta: float, _actor: Node) -> Status:
    if _actor.is_on_floor():
        return Status.SUCCESS
    return Status.FAILED

Example custom condition leaf

extends GTLeafCondition

func condition(_delta: float, _actor: Node) -> bool:
    return _actor.health > 20

💡 Use cases

• AI decision trees for NPCs and enemies
• Sequencing gameplay actions and abilities
• Cooldown, delay, and gating logic
• Behaviour prototyping and debugging
• Any state-driven logic that benefits from a tree structure

📌 Notes

• GoTreeRoot only evaluates its first child branch.
• GTLeaf nodes should not have child nodes.
• GTDecorator nodes should have exactly one GTNode child.
• Use actor and blackboard on GoTreeRoot to share data across the tree.
• tick_delay is measured in physics frames; 1 means every physics frame.

🤝 Contributing

If you want to add new node types, improve documentation, or suggest enhancements, please open an issue. Feedback is welcome and appreciated!