How luis-l/bonsaibehaviourtree works
Project Type and Purpose
• This is a Unity‐specific open‐source behaviour tree solution with two primary facets:
• A runtime “Core” engine that executes behaviour trees in play mode
• A Unity Editor extension (“Editor”) that provides a graphical canvas/UI for building, editing, and debugging tree assets
• It ships with a “Standard” library of compositors, decorators, tasks, plus utility helpers and a test suite.
File Structure Analysis
• Top-level modules:
• Core/ ← engine for tree execution
• Editor/ ← Unity Editor integration (windows, inspectors, actions)
• Standard/ ← built-in node implementations (Composites, Decorators, Tasks)
• Utility/ ← general helpers (stacks, timers, extensions)
• Tests/ ← NUnit test suites targeting Core and Standard
• Key config/build files: .asmdef for Unity assemblies, .meta for asset tracking, README + LICENSE.
Important README Insights
• Behaviour trees are ScriptableObject assets, loaded and saved by the Editor, then bound to GameObjects via BonsaiTreeComponent at runtime.
• Core API: Composite, Decorator, Task base classes with lifecycle hooks (OnStart, Run, OnEnter/Exit, OnAbort, OnChildExit).
• Editor features: Canvas pan/zoom, multi-select/edit, auto-layout, runtime status visualization via Inspector.
Main Components
A. Unity Editor Host
• BonsaiEditor Window
• BonsaiCanvas (graph model + view)
• Editor Actions (node creation, linking, drag/drop)
• Inspectors (node property panels, runtime status overlays)
• BonsaiSaver / Asset pipeline (serialization of ScriptableObjects)
B. ScriptableObject Assets
• BehaviourTree asset (node graph definition)
• Blackboard asset (shared data store)
C. Unity Play Mode / Runtime
• BonsaiTreeComponent (MonoBehaviour on GameObject)
• Core Engine (BehaviourTree, BehaviourNode graph, TreeTraversal, Blackboard)
• Standard Nodes (Parallel, Selector, Wait, Print, Guards, Services, etc.)
• Utility services (FixedSizeStack, Timer, ReactiveValue)
D. External Interfaces
• Unity engine API (Time.deltaTime, GameObject lookup)
• User-defined custom nodes (via [BonsaiNode] attribute)
Relationships & Data Flow
• In Editor Mode:
1. User opens BonsaiEditor → BonsaiCanvas renders existing BehaviourTree assets
2. User edits node graph → Editor Actions modify ScriptableObject asset via BonsaiSaver
3. Saved asset stored in Unity project
• At Runtime:
1. GameObject with BonsaiTreeComponent references the BehaviourTree asset
2. Component.OnStart → Core.BehaviourTree builds internal node graph
3. Each frame: Component.Update calls Core.TreeTraversal.Run()
4. Nodes execute their Run() logic, read/write Blackboard, trigger ConditionalAborts
5. Results propagate back through Composite/Decorator logic
• Editor Runtime Debug:
• Editor Inspector queries active BonsaiTreeComponent, highlights nodes by status
Architectural Patterns & Principles
• Model-View-Controller (Editor UI vs. ScriptableObject model vs. Core engine)
• Component-based (MonoBehaviours + ScriptableObjects)
• Plugin architecture (Runtime vs. Editor assemblies)
• Extensibility via reflection ([BonsaiNodeAttribute] for custom nodes)
Final Recommendations
• Be exhaustive: include all four top-level modules plus asset and Unity host
• Both static structure (modules, assemblies) and dynamic flow (tree execution)