Behavior Tree Editor - Overview

The Behavior Tree Editor is a visual tool for creating and editing AI behavior trees in the Olympe Engine. It provides a node-based interface for designing complex AI decision-making systems without writing code.

What is a Behavior Tree?

A Behavior Tree (BT) is a hierarchical structure used to control AI decision-making. Unlike Finite State Machines (FSM), behavior trees offer:

Modular design: Reusable sub-trees and nodes
Clear hierarchy: Parent-child relationships define execution flow
Easy to understand: Visual representation of AI logic
Scalable: From simple to complex behaviors
Reactive: Re-evaluates decisions each frame

Why Use Behavior Trees?

Behavior Trees are ideal for:

NPC AI: Enemies, companions, civilians
Boss behaviors: Complex multi-phase attacks
Patrol systems: Guards, wandering NPCs
Combat AI: Decision-making during fights
Interactive objects: Door logic, traps, puzzles

Editor Interface

The Behavior Tree Editor consists of several main areas:

1. Node Graph (Center)

The main canvas where you build your behavior tree by placing and connecting nodes.

Features:

Visual node connections
Pan and zoom controls
Node selection and editing
Real-time validation

Quick access to common operations:

New: Create a new behavior tree
Open: Load existing tree
Save: Save current tree
Validate: Check for errors
Test: Run in debugger

3. Node Palette (Left)

All available node types organized by category:

Composite Nodes: Selector, Sequence
Decorator Nodes: Inverter, Repeater
Condition Nodes: Target checks, health checks
Action Nodes: Movement, combat, patrol

4. Properties Panel (Right)

Edit properties of the selected node:

Node name (for clarity)
Node-specific parameters
Connection validation
Documentation/help

Key Concepts

Tree Structure

Every behavior tree has:

Root Node: The entry point (usually a Selector or Sequence)
Branch Nodes: Composite nodes that have children
Leaf Nodes: Conditions and Actions (no children)

Execution Flow

Behavior trees execute from top to bottom (or left to right in horizontal layout):

Start at root: Execution begins at the root node
Evaluate children: Nodes evaluate their children in order
Return status: Each node returns Success, Failure, or Running
Re-evaluate: Tree is re-evaluated each frame

Node Status

Every node returns one of three statuses:

Status	Icon	Meaning
Running	🔵	Node is still executing (next frame continues)
Success	✅	Node completed successfully
Failure	❌	Node failed

Blueprint Format

Behavior trees are saved as JSON files in the Blueprints/AI/ directory.

File format:

{
  "schema_version": 2,
  "blueprintType": "BehaviorTree",
  "name": "MyAI",
  "data": {
    "rootNodeId": 1,
    "nodes": [...]
  }
}

Schema Version

The editor uses schema version 2, which includes:

Standardized blueprint type field
Metadata (author, creation date, tags)
Editor state (zoom, scroll position)
Improved validation

Integration with ECS

Behavior trees integrate with the Entity Component System:

Required Components

To use a behavior tree, an entity needs:

AIBehaviorTree_data: Links entity to tree file
AIBlackboard_data: Stores runtime state (target, goals, timers)
AIRuntime_data: Tracks current node and execution state

Prefab Integration

Attach a behavior tree to an entity in the prefab JSON:

{
  "components": [
    {
      "type": "AIBehaviorTree_data",
      "treeFile": "Blueprints/AI/guard_ai.json"
    },
    {
      "type": "AIBlackboard_data"
    }
  ]
}

Runtime Debugger

The BT Debugger provides real-time visualization of AI execution:

Entity List: View all entities with behavior trees
Node Graph: See which nodes are currently executing
Execution Log: Track decision history
Blackboard Inspector: View runtime state variables
Performance Metrics: Monitor execution time

See BT Debugger Guide for details.

Best Practices

1. Start Simple

Begin with a simple tree structure (3-5 nodes) before adding complexity.

Example: Basic idle behavior

Root (Action)
 └─ Idle

2. Use Meaningful Names

Give nodes descriptive names that explain what they do:

✅ "Check if target in attack range"
❌ "Condition 1"

3. Keep Trees Shallow

Aim for 2-4 levels of depth. Deep trees are hard to understand:

✅ Root → Category → Action (3 levels)
❌ Root → Cat1 → Cat2 → Cat3 → Cat4 → Action (6 levels)

4. Test Incrementally

Test your tree after adding each branch:

Add patrol behavior → Test
Add combat behavior → Test
Add investigation → Test

5. Reuse Sub-trees

Create separate tree files for reusable behaviors:

guard_patrol.json - Patrol logic (reusable)
guard_combat.json - Combat logic (reusable)
guard_ai.json - Main tree that uses both

6. Document Complex Logic

Use node names and comments to explain:

Why certain conditions exist
What parameters mean
Expected behavior flow

Common Patterns

Pattern 1: Priority Selector

Handle behaviors by priority (first success wins):

Selector (Root)
 ├─ Combat (high priority)
 ├─ Investigate (medium priority)
 └─ Patrol (low priority)

Pattern 2: Sequence with Guards

Check conditions before executing actions:

Sequence
 ├─ Condition: Target in Range
 └─ Action: Attack Target

Pattern 3: Repeating Action

Execute action multiple times:

Repeater (count=3)
 └─ Action: Fire Projectile

File Organization

Organize your behavior trees logically:

Blueprints/
└── AI/
    ├── Common/
    │   ├── patrol.json       (reusable patrol)
    │   ├── combat.json       (reusable combat)
    │   └── investigate.json  (reusable search)
    ├── Enemies/
    │   ├── guard_ai.json
    │   ├── zombie_ai.json
    │   └── boss_ai.json
    └── NPCs/
        ├── merchant_ai.json
        └── villager_ai.json

Performance Considerations

CPU Cost

Each entity evaluates its tree every frame
Complex trees (30+ nodes) may impact performance with 100+ entities
Use conditions to early-exit expensive branches

Memory Usage

Trees are loaded once and shared across entities
Runtime state stored per-entity in AIRuntime_data (~100 bytes)
Blackboard stores entity-specific data (~200 bytes)

Optimization Tips

Limit depth: Shallow trees execute faster
Early exit: Put likely-to-fail conditions first
Caching: Store expensive calculations in blackboard
Tree reuse: Share tree files across entity types

Next Steps

Ready to start building? Continue with:

Node Types - Learn about all available nodes
Connection Rules - Understand how to connect nodes
Keyboard Shortcuts - Work more efficiently
First BT Tutorial - Create your first behavior tree

Additional Resources

Technical Reference - Deep architecture details
Custom Nodes - Extend the system with code
BT Debugger - Runtime debugging guide
Behavior Tree Basics Tutorial - Comprehensive tutorial

Troubleshooting

Tree not loading

✅ Check file path in prefab matches actual file
✅ Validate JSON syntax
✅ Ensure schema_version: 2 is set

AI not executing

✅ Entity has AIBehaviorTree_data component
✅ Entity has AIBlackboard_data component
✅ Tree file loaded successfully (check console)

Nodes always failing

✅ Check condition parameters (range values, thresholds)
✅ Verify entity has required components (Navigation, Combat, etc.)
✅ Use debugger to see which node fails

What is a Behavior Tree?​

Why Use Behavior Trees?​

Editor Interface​

1. Node Graph (Center)​

2. Toolbar (Top)​

3. Node Palette (Left)​

4. Properties Panel (Right)​

Key Concepts​

Tree Structure​

Execution Flow​

Node Status​

Blueprint Format​

Schema Version​

Integration with ECS​

Required Components​

Prefab Integration​

Runtime Debugger​

Best Practices​

1. Start Simple​

2. Use Meaningful Names​

3. Keep Trees Shallow​

4. Test Incrementally​

5. Reuse Sub-trees​

6. Document Complex Logic​

Common Patterns​

Pattern 1: Priority Selector​

Pattern 2: Sequence with Guards​

Pattern 3: Repeating Action​

File Organization​

Performance Considerations​

CPU Cost​

Memory Usage​

Optimization Tips​

Next Steps​

Additional Resources​

Troubleshooting​

Tree not loading​

AI not executing​

Nodes always failing​