Beehave: behavior tree AI for Godot, built from scene nodes

The problem Beehave solves for Godot NPCs

Game AI written directly in _process tends to grow into nested conditionals: check distance, check line of sight, check cooldown, then pick an action. That structure is hard to read once an enemy has more than a handful of states, and it is harder to reuse across enemy types. Beehave addresses that by making the decision logic a tree of Godot nodes. The README describes it as an addon that "enables you to create robust AI systems using behavior trees" and lists the intended targets as complex NPC behaviors, boss battles, and "other advanced setups".

The audience is Godot developers working in GDScript who want AI logic to live in the scene tree rather than in a single script. The node-based approach means a designer can open a scene and see the structure of an enemy's behavior, and the same subtree can be instanced under several enemies. The README is explicit that this is not for everyone: "For simple AI, behavior trees are definitely overkill, however, for more complex AI interactions, behavior trees can help you to better manage changes and re-use logic across all NPCs." That sentence is the honest boundary of the project, and it is worth taking at face value.

How Beehave's node-based tree actually runs

Beehave does not use a separate editor or a text format for trees. The tree is the scene tree. The README's feature list puts it as "Node based - build behavior trees within your scene tree", and the screenshot shows a tree composed of condition and action nodes arranged under a root, with the note that you can "attach them to any node of your choice". The repository layout matches that claim: examples/actions/ and examples/conditions/ hold example leaf nodes, and examples/random_tree_example/ holds a complete tree, while examples/beehave_test_scene.tscn is the scene that wires them together.

Because the tree is a scene, instancing, inheritance and the Godot editor's own scene tools apply to behavior logic. That is the main architectural difference from libraries that parse a separate behavior tree asset at load time. The trade-off is that large trees become large scenes, and the README does not describe any facility for composing a tree from a data file or for editing one outside the editor.

Two runtime tools are documented. The first is a "dedicated debug view inside the Godot editor" that lets you "better understand what the behavior is doing under the hood". The second is a performance monitor, described as "built-in monitors to track performance of your behavior trees", aimed at investigating frame rate problems. Both are editor features; the README does not state whether the debug view works in an exported build.

Installing Beehave and attaching a first tree

The README gives a four-step install. Download the latest release from the GitHub releases page, unpack the addons/beehave folder into your project's /addons folder, enable the plugin under Project > Project Settings > Plugins, and move script_templates into your project folder. That last step is easy to skip and it is listed as part of the install, not as an optional extra.

If you prefer to pull a branch rather than a release, the README links archives for the Godot 3.x and Godot 4.x branches. Before you pick one, check the compatibility table: Godot 3.x maps to branch 3.x and Beehave 1.x, Godot 4.0.x maps to branch 4.x and Beehave 2.7.x, Godot 4.1.x maps to 2.9.x, and Godot 4.5+ needs Beehave 2.10+. Installing the wrong pair is the most likely first-run failure, and the README points to a separate compatibility guide at bitbra.in/blog/godot-addon-compatibility for the reasoning behind the split.

There is no command-line install and no package manager step. The addon arrives as files you copy:

# from the unpacked release archive, with your Godot project as the working directory
cp -r addons/beehave ./addons/

After copying, the addons/beehave directory should sit next to your other addons. Then enable it in the editor:

Project > Project Settings > Plugins > Beehave > Enable

With the plugin on, build a tree the way the README describes: create a scene, add a Beehave root node, and attach condition and action nodes beneath it as children. The examples/ directory in the repository is the working reference for how those nodes are assembled, since the README itself hands off to the wiki for the actual usage manual. The README's own pointer is: "Learn how to beehave on the official wiki!" at bitbra.in/beehave/#/manual/. Expect to read that manual before your first tree runs, because the README documents installation and features but not node semantics.

Where Beehave stops being the right tool

The first limitation is stated by the project itself. If your enemy has two states, a behavior tree adds a scene, a plugin dependency and a node hierarchy to express what a single script would express in a few lines. The README's own wording is that behavior trees are "definitely overkill" for simple AI. That is not a flaw, but it is the case where you should not install this.

The second is documentation depth. The README covers features and installation, then hands off to the wiki. Node types, composite semantics, how a running branch is resumed, and what the debug view shows are not in the README. You are depending on the wiki and on the examples/ directory to learn the API.

The third is version coupling. The compatibility table shows a project where the addon version must track the engine version, with 4.5+ requiring Beehave 2.10+ and 4.0.x pinned to 2.7.x. In practice that means an engine upgrade can force an addon upgrade, and the README does not describe a migration path between Beehave versions. The repository does carry a test suite, run through GdUnitRunner.cfg with runtest.sh and runtest.cmd, and the README claims unit test coverage for features, which is evidence of a maintained codebase rather than a guarantee about your upgrade.

Finally, the README does not document rollback or downgrade behaviour. If a new Beehave version breaks a tree, the README gives no stated procedure for going back beyond installing an older release.

Beehave compared with LimboAI

LimboAI is the comparison Godot developers actually search for, and the two take different routes to the same goal. Beehave's README describes trees built inside the scene tree from nodes you attach to any node you choose. That means the tree is a Godot scene, and everything the engine does with scenes, including instancing and editor inspection, applies directly.

LimboAI is not described in this article's sources, so the honest statement is narrower: the choice between them is a choice about where the tree lives and what edits it. Beehave's answer is the Godot scene tree and the Godot editor. If you want your AI structure to be a scene you can open, diff and instance alongside the rest of your game objects, Beehave's design is aimed at exactly that. If you want tree authoring decoupled from scene files, Beehave's README does not offer that, and you should evaluate the alternative on its own documentation rather than on this one.

There is also a plain engine-level alternative: hand-written state machines in GDScript, which is what Beehave is meant to replace once the state count grows. That comparison is fairer than any library comparison, because it costs nothing to try and its limits are your own code.

Maintenance, licence and upgrade cost

The repository is not archived. The last push was on 2026-08-18, the same day as the v2.9.3 release, so the project has shipped recently. The release history shows v2.9.2 on 2025-12-02 and v2.9.1 on 2025-05-03, which is a cadence of a few releases a year rather than continuous churn. Treat it as a project that moves in steps, and expect the compatibility table to be the thing that forces your hand.

Beehave is MIT licensed. That is a permissive licence, and for most Godot projects it means you can ship it inside a commercial game. This is not legal advice; if your project has unusual distribution or attribution requirements, read the LICENSE file in the repository rather than relying on a summary.

The upgrade cost is real but bounded. Because the addon is copied into addons/beehave rather than resolved by a package manager, upgrading means replacing that directory with the contents of a newer release, then re-enabling the plugin and re-checking your trees in the debug view. The README does not document a migration procedure, so budget time for opening each tree scene after an upgrade. The test suite in test/, driven by GdUnitRunner.cfg and runtest.sh, is the project's own safety net, not yours.

Editorial conclusion

Adopt Beehave if your Godot project already has NPCs whose logic is spreading across nested if statements and you want that logic visible in the scene tree and debuggable at runtime. Do not adopt it for one or two simple enemies, since the README itself calls behavior trees overkill for simple AI. Before committing, verify three things: that your Godot version maps to the right branch in the compatibility table (4.5+ needs Beehave 2.10+, 4.1.x needs 2.9.x, 4.0.x needs 2.7.x), that you are willing to move script_templates into your project folder as step 4 of the install instructions requires, and that you have read the wiki manual at bitbra.in/beehave, because the README stops at installation and does not document the node types or the debug view's controls.

Frequently asked questions

Official sources

1. bitbrain/beehave on GitHub
2. License: MIT
3. Project website
4. README
5. Releases