A visual, node-based behavior tree system for AI and gameplay logic, built on top of Unity Visual Scripting.
I started BH3 in 2023 and built it by hand for its first three years. It began as a tool for another project, which is still unreleased.
Since 2026 I have used Claude Code as part of my development workflow. It helps me draft and shape features, and sometimes brings them to completion. It also writes tests, fixes bugs and drafts documentation.
I'm stating this up front so you can make your own decision before using BH3.
BH3 brings behavior trees and Visual Scripting together the way Unreal's Behavior Tree does: nodes have ports, and any port can be fed by a Visual Scripting graph. A designer builds node logic without writing code; a programmer writes reusable nodes in C# and wires them the same way.
Three ideas carry most of the weight, and the documentation is built around them:
| Idea | In one sentence | Read |
|---|---|---|
| Ports separate what a node does from where its data comes from | A node reads a port. It never knows whether the value came from a variable, a literal, another node or a whole Visual Scripting graph. | Ports and wiring |
| A branch is a function | Put a branch in its own tree asset, pass it parameters through ports, and run it from any agent. Its variables are private to that call; facts about the agent live on the agent. | Sub-trees |
| Guards decide when a branch may run, and when it must stop | A Reactive Guard watches a condition while its branch runs, aborts the branch when the condition drops, and can take the slot from a lower-priority branch when it rises. | Guards |
When an agent does the wrong thing, BH3 has already recorded what every node, guard and variable did. The Why panel turns that into a sentence, the Timeline lets you scrub back to the moment, and a breakpoint stops the editor when it happens again. See Debugging.
New to BH3? Start with the BH3 introduction and tutorial playlist on YouTube.
Four small games built on BH3, in Samples/ of this repository, for learning how trees
are put together. Each is a scene you press Play in and a README that draws its trees and says what each piece shows.
Read them in this order; Samples/README.md maps each BH3 idea to the place in a
sample that uses it.
| Sample | Teaches |
|---|---|
| Click to move | The smallest complete agent: one guarded branch above an unguarded fallback, a branch as its own asset with parameters, a Function feeding a port |
| Combat | One Engage branch shared by every agent, an attack tree picked at run time from a fact, guards that poll next to guards that wake, a swing that must finish |
| Defense | A tree running a game system, reactive guards on facts that components publish, agents spawned with their tree already set |
| RTS | Numbered orders on three channels, interrupt and resume from tree shape alone, a branch that re-targets itself, a tree on a building |
On the release page the samples are their own BH3.Samples.unitypackage, imported after BH3.unitypackage.
They need com.unity.inputsystem and com.unity.ai.navigation beside BH3.
| Page | Read it when |
|---|---|
| Installation | You are adding BH3 to a project, or checking that a checkout works |
| Your first tree | You have never built a BH3 tree. Fifteen minutes, ends with an agent running |
| Core concepts | You want the whole mental model on one page before going deeper |
| Page | What it covers |
|---|---|
| The graph editor | The window, its panels, creating and connecting nodes, shortcuts |
| Node reference | Every node that ships, by menu category, with the ports you must connect |
| Ports and wiring | How a node gets its data: defaults, literals, conversions, Script Graph Variables |
| Variables and scope | The variable kinds, the Blackboard, what a branch can see and write |
| Execution order | Which child runs first, the priority badge, reordering |
| Guards | Conditional Execution and Reactive Guard: gating, aborting, taking over, triggers |
| Sub-trees | Reusing a branch as its own asset, and passing it parameters |
| Functions | Shared Visual Scripting graphs with a declared contract |
| Checking your tree | Problem badges, one-click repairs, bt_verify, the broken-graph finder |
| Best practices | Patterns that keep trees reusable and designer-friendly |
| Page | What it answers |
|---|---|
| Overview | What is recorded, which panel answers which question, what it costs |
| Timeline | What did the tree look like at tick N? Scrub, play back, save and load recordings |
| Why panel | Why did this node do that, and why not something else? |
| Variable watch | What was this variable at that moment, and who wrote it? |
| Breakpoints | Stop the editor the instant it happens |
| Page | What it covers |
|---|---|
| Custom nodes | Writing actions, conditions, guards and decorators |
| API reference | The runtime types: BehaviorTreeMachine, BTContext, ExecutionStatus, node lifecycle |
| Renaming and deleting node types | What happens to trees when a node class goes away, and how to repair them |
| Authoring from code | Generating trees from C#, and the traps in it |
| Command-line tools | The bt_* and fn_* commands, and every message bt_verify can emit |
| Folder | Contents |
|---|---|
Runtime/ |
Nodes, the machine, variables, the flight recorder |
Editor/ |
The graph window, panels, inspectors, authoring and verification tools |
Test/ |
EditMode/ and PlayMode/ test assemblies, plus the fixture trees the verification test runs over |
Samples/ |
Four small games built on BH3, for learning how trees are put together. Not in the release package; start at Samples/README.md |
docs/ |
This documentation. docs/README.md is the same table of contents, for browsing inside the folder |