# luis-l/bonsaibehaviourtree architecture

> Architecture diagram of the GitHub repository luis-l/bonsaibehaviourtree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luis-l/bonsaibehaviourtree
- Repository: https://github.com/luis-l/bonsaibehaviourtree

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Host environments
    subgraph "Unity Editor" 
        direction TB
        EditorHost["Unity Editor Host"]:::host
        subgraph "Editor Module"
            direction TB
            BEW["BonsaiEditor Window"]:::editor
            BC["BonsaiCanvas"]:::editor
            EA["Editor Actions"]:::editor
            INSP["Inspectors"]:::editor
            BS["BonsaiSaver"]:::editor
        end
    end

    subgraph "Assets" 
        direction TB
        BT[(BehaviourTree Asset)]:::asset
        BB[(Blackboard Asset)]:::asset
    end

    subgraph "Play Mode" 
        direction TB
        RuntimeHost["Unity Play Mode"]:::host
        subgraph "Runtime Core"
            direction TB
            BTC["BonsaiTreeComponent"]:::runtime
            BTCore["BehaviourTree"]:::runtime
            BN["BehaviourNode"]:::runtime
            COMP["Composite"]:::runtime
            DEC["Decorator"]:::runtime
            TASK["Task"]:::runtime
            CAb["ConditionalAbort"]:::runtime
            CTask["ConditionalTask"]:::runtime
            SERV["Service"]:::runtime
            TT["TreeTraversal"]:::runtime
            TQ["TreeQuery"]:::runtime
            BI["BehaviourIterator"]:::runtime
            BNA["BonsaiNodeAttribute"]:::runtime
            SARA["ShowAtRuntimeAttribute"]:::runtime
        end
        subgraph "Standard Library"
            direction TB
            STDComp["Composites"]:::standard
            STDCA["ConditionalAborts"]:::standard
            STDCT["ConditionalTasks"]:::standard
            STDDec["Decorators"]:::standard
            STDTask["Tasks"]:::standard
        end
        subgraph "Utility Helpers"
            direction TB
            FS["FixedSizeStack"]:::utility
            TM["Timer"]:::utility
            RV["ReactiveValue"]:::utility
            ME["MathExtensions"]:::utility
            TE["TypeExtensions"]:::utility
        end
    end

    %% Editor to Assets
    BS -->|"Serialize"| BT
    BS -->|"Serialize"| BB
    EA -->|"Modify Asset"| BT
    EA -->|"Modify Asset"| BB

    %% Assets to Runtime
    BT -->|"Reference"| BTC
    BB -->|"Reference"| BTC

    %% Runtime execution flow
    BTC -->|"OnStart builds graph"| BTCore
    BTC -->|"Update per frame"| TT
    TT -->|"Traverse nodes"| BN
    BN -->|"OnEnter/Run/OnExit"| COMP
    BN -->|"OnEnter/Run/OnExit"| DEC
    BN -->|"OnEnter/Run/OnExit"| TASK
    BN -->|"Check abort"| CAb
    BN -->|"Check conditional"| CTask
    BN -->|"Invoke service"| SERV

    %% Core to Utilities (dashed)
    COMP -.-> FS
    DEC -.-> TM
    TASK -.-> RV
    TQ -.-> ME
    BI -.-> TE

    %% Custom node discovery
    BNA -.-> STDComp
    BNA -.-> STDCA
    BNA -.-> STDCT
    BNA -.-> STDDec
    BNA -.-> STDTask

    %% Editor runtime debug
    INSP -->|"Query status"| BTC
    BTC -->|"Status data"| INSP

    %% Click events
    click BEW "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Editor/BonsaiEditor.cs"
    click BC "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Editor/BonsaiCanvas.cs"
    click EA "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Editor/Actions/"
    click INSP "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Editor/Inspectors/"
    click BS "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Editor/BonsaiSaver.cs"
    click BT "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/BehaviourTree.cs"
    click BB "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/Blackboard.cs"
    click BTC "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/BonsaiTreeComponent.cs"
    click BN "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/BehaviourNode.cs"
    click COMP "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/Composite.cs"
    click DEC "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/Decorator.cs"
    click TASK "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/Task.cs"
    click CAb "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/ConditionalAbort.cs"
    click CTask "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/ConditionalTask.cs"
    click SERV "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/Service.cs"
    click TT "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/TreeTraversal.cs"
    click TQ "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/TreeQuery.cs"
    click BI "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/BehaviourIterator.cs"
    click BNA "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/BonsaiNodeAttribute.cs"
    click SARA "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Core/ShowAtRuntimeAttribute.cs"
    click STDComp "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Standard/Composites/"
    click STDCA "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Standard/ConditionalAborts/"
    click STDCT "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Standard/ConditionalTasks/"
    click STDDec "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Standard/Decorators/"
    click STDTask "https://github.com/luis-l/bonsaibehaviourtree/tree/master/Standard/Tasks/"
    click FS "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Utility/FixedSizeStack.cs"
    click TM "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Utility/Timer.cs"
    click RV "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Utility/ReactiveValue.cs"
    click ME "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Utility/MathExtensions.cs"
    click TE "https://github.com/luis-l/bonsaibehaviourtree/blob/master/Utility/TypeExtensions.cs"

    %% Styles
    classDef editor fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef runtime fill:#ccddff,stroke:#333,stroke-width:1px
    classDef standard fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef utility fill:#dddddd,stroke:#333,stroke-width:1px
    classDef asset fill:#ffeeaa,stroke:#333,stroke-width:1px
    classDef host fill:#eeeeff,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
```
