# limbonaut/limboai architecture

> Architecture diagram of the GitHub repository limbonaut/limboai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/limbonaut/limboai
- Repository: https://github.com/limbonaut/limboai

## Overview

LimboAI is a Godot C++ AI plugin. A game scene runs a BehaviorTree through BTPlayer: the player instantiates a runtime tree, which executes its task hierarchy using shared blackboard data. Separately, LimboHSM manages hierarchical states and event-driven transitions; BTState supports combining state machines with trees. The editor provides tree and blackboard authoring plus live debugging and visualization. The README documents additional task categories and capabilities beyond the sampled excerpts; their wiring is shown only where supported by those excerpts or explicit documentation.

Main entry points: [`bt/bt_player.cpp`](https://github.com/limbonaut/limboai/blob/master/bt/bt_player.cpp) (BTPlayer), [`bt/tasks/bt_task.cpp`](https://github.com/limbonaut/limboai/blob/master/bt/tasks/bt_task.cpp) (Task Hierarchy), [`bt/bt_instance.cpp`](https://github.com/limbonaut/limboai/blob/master/bt/bt_instance.cpp) (BTInstance), [`editor/limbo_ai_editor_plugin.cpp`](https://github.com/limbonaut/limboai/blob/master/editor/limbo_ai_editor_plugin.cpp) (Editor Plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bt_runtime["Behavior Trees"]
  node_bt_player["BTPlayer<br/>[bt_player.cpp]"]
  node_behavior_tree["BehaviorTree<br/>[behavior_tree.cpp]"]
  node_bt_instance["BTInstance<br/>[bt_instance.cpp]"]
  node_task_hierarchy["Task Hierarchy<br/>[bt_task.cpp]"]
  node_task_families["Task Families<br/>[bt_sequence.cpp]"]
  node_scene_tasks["Scene Tasks"]
end

subgraph group_blackboard["Blackboard Data"]
  node_blackboard["Blackboard<br/>[blackboard.cpp]"]
  node_blackboard_plan["Blackboard Plan"]
  node_bb_parameters["BB Parameters<br/>[bb_param.cpp]"]
end

subgraph group_hsm["State Machines"]
  node_hsm["LimboHSM<br/>[limbo_hsm.cpp]"]
  node_limbo_state["LimboState<br/>[limbo_state.cpp]"]
  node_bt_state["BTState<br/>[limbo_state.h]"]
end

subgraph group_editor["Editor and Debugger"]
  node_editor_plugin["Editor Plugin"]
  node_task_tree["Task Tree Editor<br/>[task_tree.cpp]"]
  node_plan_editor["Plan Editor"]
  node_debugger["Visual Debugger"]
  node_tree_view["BehaviorTreeView"]
end

subgraph group_godot["Godot Runtime"]
  node_game_scene["Game Scene"]
  node_engine(("Godot Engine"))
end

node_developer(("Game Developer"))

node_developer -->|"authors AI"| node_editor_plugin
node_editor_plugin -->|"opens editor"| node_task_tree
node_editor_plugin -->|"opens editor"| node_plan_editor
node_task_tree -->|"edits resource"| node_behavior_tree
node_plan_editor -->|"edits variables"| node_blackboard_plan
node_game_scene -->|"runs tree"| node_bt_player
node_bt_player -->|"instantiates"| node_behavior_tree
node_bt_player -->|"populates blackboard"| node_blackboard_plan
node_bt_player -->|"updates"| node_bt_instance
node_behavior_tree -->|"creates instance"| node_bt_instance
node_bt_instance -->|"executes root"| node_task_hierarchy
node_task_hierarchy -->|"composes tasks"| node_task_families
node_task_hierarchy -->|"uses data"| node_blackboard
node_task_hierarchy -->|"resolves parameters"| node_bb_parameters
node_task_hierarchy -->|"includes scene actions"| node_scene_tasks
node_scene_tasks -->|"acts on agent"| node_game_scene
node_game_scene -->|"hosts state machine"| node_hsm
node_hsm -->|"manages states"| node_limbo_state
node_limbo_state -->|"dispatches events"| node_hsm
node_bt_state -.->|"runs behavior tree"| node_bt_instance
node_bt_instance -.->|"registers runtime"| node_debugger
node_debugger -->|"visualizes execution"| node_tree_view
node_editor_plugin -->|"integrates editor"| node_engine
node_bt_player -->|"runs in scene"| node_engine

click node_bt_player "https://github.com/limbonaut/limboai/blob/master/bt/bt_player.cpp"
click node_behavior_tree "https://github.com/limbonaut/limboai/blob/master/bt/behavior_tree.cpp"
click node_bt_instance "https://github.com/limbonaut/limboai/blob/master/bt/bt_instance.cpp"
click node_task_hierarchy "https://github.com/limbonaut/limboai/blob/master/bt/tasks/bt_task.cpp"
click node_task_families "https://github.com/limbonaut/limboai/blob/master/bt/tasks/composites/bt_sequence.cpp"
click node_scene_tasks "https://github.com/limbonaut/limboai/blob/master/bt/tasks/scene/bt_play_animation.cpp"
click node_blackboard "https://github.com/limbonaut/limboai/blob/master/blackboard/blackboard.cpp"
click node_blackboard_plan "https://github.com/limbonaut/limboai/blob/master/blackboard/blackboard_plan.cpp"
click node_bb_parameters "https://github.com/limbonaut/limboai/blob/master/blackboard/bb_param/bb_param.cpp"
click node_hsm "https://github.com/limbonaut/limboai/blob/master/hsm/limbo_hsm.cpp"
click node_limbo_state "https://github.com/limbonaut/limboai/blob/master/hsm/limbo_state.cpp"
click node_bt_state "https://github.com/limbonaut/limboai/blob/master/hsm/limbo_state.h"
click node_editor_plugin "https://github.com/limbonaut/limboai/blob/master/editor/limbo_ai_editor_plugin.cpp"
click node_task_tree "https://github.com/limbonaut/limboai/blob/master/editor/task_tree.cpp"
click node_plan_editor "https://github.com/limbonaut/limboai/blob/master/editor/blackboard_plan_editor.cpp"
click node_debugger "https://github.com/limbonaut/limboai/blob/master/editor/debugger/limbo_debugger_plugin.cpp"
click node_tree_view "https://github.com/limbonaut/limboai/blob/master/editor/debugger/behavior_tree_view.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bt_player,node_behavior_tree,node_bt_instance,node_task_hierarchy,node_task_families,node_scene_tasks toneBlue
class node_blackboard,node_blackboard_plan,node_bb_parameters toneAmber
class node_hsm,node_limbo_state,node_bt_state toneMint
class node_editor_plugin,node_task_tree,node_plan_editor,node_debugger,node_tree_view toneRose
class node_game_scene,node_engine,node_developer toneIndigo
```

## Components

### Behavior Trees

- [BTPlayer](https://github.com/limbonaut/limboai/blob/master/bt/bt_player.cpp): `bt/bt_player.cpp`
- [BehaviorTree](https://github.com/limbonaut/limboai/blob/master/bt/behavior_tree.cpp): `bt/behavior_tree.cpp`
- [BTInstance](https://github.com/limbonaut/limboai/blob/master/bt/bt_instance.cpp): `bt/bt_instance.cpp`
- [Task Hierarchy](https://github.com/limbonaut/limboai/blob/master/bt/tasks/bt_task.cpp): `bt/tasks/bt_task.cpp`
- [Task Families](https://github.com/limbonaut/limboai/blob/master/bt/tasks/composites/bt_sequence.cpp): `bt/tasks/composites/bt_sequence.cpp`
- [Scene Tasks](https://github.com/limbonaut/limboai/blob/master/bt/tasks/scene/bt_play_animation.cpp): `bt/tasks/scene/bt_play_animation.cpp`

### Blackboard Data

- [Blackboard](https://github.com/limbonaut/limboai/blob/master/blackboard/blackboard.cpp): `blackboard/blackboard.cpp`
- [Blackboard Plan](https://github.com/limbonaut/limboai/blob/master/blackboard/blackboard_plan.cpp): `blackboard/blackboard_plan.cpp`
- [BB Parameters](https://github.com/limbonaut/limboai/blob/master/blackboard/bb_param/bb_param.cpp): `blackboard/bb_param/bb_param.cpp`

### State Machines

- [LimboHSM](https://github.com/limbonaut/limboai/blob/master/hsm/limbo_hsm.cpp): `hsm/limbo_hsm.cpp`
- [LimboState](https://github.com/limbonaut/limboai/blob/master/hsm/limbo_state.cpp): `hsm/limbo_state.cpp`
- [BTState](https://github.com/limbonaut/limboai/blob/master/hsm/limbo_state.h): `hsm/limbo_state.h`

### Editor and Debugger

- [Editor Plugin](https://github.com/limbonaut/limboai/blob/master/editor/limbo_ai_editor_plugin.cpp): `editor/limbo_ai_editor_plugin.cpp`
- [Task Tree Editor](https://github.com/limbonaut/limboai/blob/master/editor/task_tree.cpp): `editor/task_tree.cpp`
- [Plan Editor](https://github.com/limbonaut/limboai/blob/master/editor/blackboard_plan_editor.cpp): `editor/blackboard_plan_editor.cpp`
- [Visual Debugger](https://github.com/limbonaut/limboai/blob/master/editor/debugger/limbo_debugger_plugin.cpp): `editor/debugger/limbo_debugger_plugin.cpp`
- [BehaviorTreeView](https://github.com/limbonaut/limboai/blob/master/editor/debugger/behavior_tree_view.cpp): `editor/debugger/behavior_tree_view.cpp`

### Godot Runtime

- **Game Scene**
- **Godot Engine**

### Other components

- **Game Developer**

## Connections

- Game Developer → Editor Plugin: authors AI
- Editor Plugin → Task Tree Editor: opens editor
- Editor Plugin → Plan Editor: opens editor
- Task Tree Editor → BehaviorTree: edits resource
- Plan Editor → Blackboard Plan: edits variables
- Game Scene → BTPlayer: runs tree
- BTPlayer → BehaviorTree: instantiates
- BTPlayer → Blackboard Plan: populates blackboard
- BTPlayer → BTInstance: updates
- BehaviorTree → BTInstance: creates instance
- BTInstance → Task Hierarchy: executes root
- Task Hierarchy → Task Families: composes tasks
- Task Hierarchy → Blackboard: uses data
- Task Hierarchy → BB Parameters: resolves parameters
- Task Hierarchy → Scene Tasks: includes scene actions
- Scene Tasks → Game Scene: acts on agent
- Game Scene → LimboHSM: hosts state machine
- LimboHSM → LimboState: manages states
- LimboState → LimboHSM: dispatches events
- BTState → BTInstance: runs behavior tree
- BTInstance → Visual Debugger: registers runtime
- Visual Debugger → BehaviorTreeView: visualizes execution
- Editor Plugin → Godot Engine: integrates editor
- BTPlayer → Godot Engine: runs in scene