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.
| 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. Feature demos live in the reference project; see Demos and tests |
docs/ |
This documentation. docs/README.md is the same table of contents, for browsing inside the folder |