Tutorial: Your First Behavior Tree

This step-by-step tutorial will guide you through creating your first behavior tree from scratch. We'll build a simple Guard AI that patrols an area and attacks when it sees a target.

What you'll learn:

Creating a new behavior tree
Adding and connecting nodes
Configuring node parameters
Testing with the debugger
Attaching AI to an entity

Estimated time: 15-20 minutes

Prerequisites

Before starting, make sure you have:

✅ Olympe Engine installed and running
✅ Basic understanding of the editor interface
✅ A test level loaded (any level with navigable terrain)

If you're new to the engine, complete the Getting Started Guide first.

Step 1: Create a New Behavior Tree

1.1 Open the Blueprint Editor

Launch the Olympe Engine
Click Tools → Blueprint Editor
The editor opens in a new window

1.2 Create New Behavior Tree

Click File → New (or press Ctrl+N)
Select Behavior Tree from the blueprint type menu
Enter name: GuardAI_Tutorial
Click Create

Result: A new behavior tree with a default root node appears on the canvas.

Step 2: Plan Your AI Structure

Before adding nodes, let's plan the behavior:

Guard AI Logic:

IF target visible THEN
    Attack target
ELSE
    Patrol waypoints

As a behavior tree:

Selector (Root) - Try combat first, then patrol
 ├─ Sequence (Combat) - Attack if target visible
 │   ├─ Condition: Target Visible
 │   └─ Action: Attack Melee
 └─ Sequence (Patrol) - Patrol when no target
     ├─ Action: Pick Next Patrol Point
     └─ Action: Move To Goal

Step 3: Build the Root Selector

3.1 Configure Root Node

The default root is already a Selector - perfect for our needs!

Select the root node (click on it)
In the Properties Panel (right side):
- Set Name to: Guard Decision
- Leave Type as: Selector
Press Enter to confirm

Why Selector? We want to try combat first (high priority), then fall back to patrol (low priority).

Step 4: Add Combat Sequence

4.1 Add Combat Sequence Node

Select the root node Guard Decision
Press Shift+Q (Quick Add Sequence)
- Or right-click → Add Child → Sequence
A new Sequence appears connected to the root

4.2 Configure Combat Sequence

Select the new Sequence node
In Properties Panel:
- Name: Combat
- Type: Sequence (already set)

Step 5: Add Combat Condition

5.1 Add Target Check

Select the Combat Sequence node
Press Shift+C (Quick Add Condition)
- Or right-click → Add Child → Condition
A new Condition appears

5.2 Configure Condition

Select the new Condition node
In Properties Panel:
- Name: Target Visible?
- Condition Type: TargetVisible (dropdown)
- Parameters: None needed

What this does: Checks if the entity can see a target entity. Returns Success if target exists, Failure if not.

Step 6: Add Attack Action

6.1 Add Attack Node

Select the Combat Sequence node
Press Shift+X (Quick Add Action)
A new Action appears

6.2 Configure Attack Action

Select the new Action node
In Properties Panel:
- Name: Attack Target
- Action Type: AttackIfClose (dropdown)
- Parameters: None needed

What this does: Performs a melee attack if target is in range. Returns Running during attack, Success when complete.

Current tree:

Selector "Guard Decision"
 └─ Sequence "Combat"
     ├─ Condition "Target Visible?"
     └─ Action "Attack Target"

Step 7: Add Patrol Sequence

7.1 Add Patrol Sequence

Select the root Selector Guard Decision
Press Shift+Q (Quick Add Sequence)
A new Sequence appears as second child

7.2 Configure Patrol Sequence

Select the new Sequence node
In Properties Panel:
- Name: Patrol
- Type: Sequence

Step 8: Add Patrol Actions

8.1 Add Pick Patrol Point

Select Patrol Sequence
Press Shift+X (Quick Add Action)
Configure the Action:
- Name: Pick Next Waypoint
- Action Type: PatrolPickNextPoint

8.2 Add Move Action

Select Patrol Sequence (again)
Press Shift+X (Quick Add Action)
Configure the Action:
- Name: Move to Waypoint
- Action Type: MoveToGoal
- Param1 (acceptance radius): 20.0

Final tree structure:

Selector "Guard Decision"
 ├─ Sequence "Combat"
 │   ├─ Condition "Target Visible?"
 │   └─ Action "Attack Target"
 └─ Sequence "Patrol"
     ├─ Action "Pick Next Waypoint"
     └─ Action "Move to Waypoint"

Step 9: Arrange and Validate

9.1 Auto-Layout

Press Ctrl+L or right-click canvas → Auto Layout
Nodes arrange automatically for clarity
Press Home to frame entire tree

9.2 Validate Tree

Press Ctrl+Shift+V or click Validate button
Check for any errors in the output panel
Should see: ✅ "Validation passed"

Common validation errors:

❌ Disconnected nodes - Connect all nodes to root
❌ Decorator without child - Add exactly 1 child
❌ Missing parameters - Fill required fields

Step 10: Save Your Tree

Press Ctrl+S or click File → Save
Save location: Blueprints/AI/GuardAI_Tutorial.json
Confirm save

File structure:

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

Step 11: Create Guard Entity Prefab

Now let's create an entity that uses this AI.

11.1 Create Prefab File

Create a new file: Blueprints/Prefabs/GuardEntity.json

{
  "schema_version": 2,
  "name": "Guard",
  "components": [
    {
      "type": "Transform_data",
      "position": { "x": 400, "y": 300 }
    },
    {
      "type": "VisualSprite_data",
      "texturePath": "Gamedata/Sprites/guard.png",
      "srcRect": { "x": 0, "y": 0, "w": 32, "h": 32 }
    },
    {
      "type": "AIBehaviorTree_data",
      "treeFile": "Blueprints/AI/GuardAI_Tutorial.json"
    },
    {
      "type": "AIBlackboard_data"
    },
    {
      "type": "Patrol_data",
      "waypoints": [
        { "x": 200, "y": 300 },
        { "x": 600, "y": 300 },
        { "x": 600, "y": 500 },
        { "x": 200, "y": 500 }
      ],
      "currentIndex": 0
    },
    {
      "type": "Navigation_data",
      "speed": 100.0
    },
    {
      "type": "Combat_data",
      "attackDamage": 10,
      "attackRange": 50,
      "attackCooldown": 1.0
    },
    {
      "type": "Health_data",
      "current": 100,
      "maximum": 100
    }
  ]
}

Key components:

AIBehaviorTree_data - Links to your tree file
AIBlackboard_data - Stores runtime AI state
Patrol_data - Defines patrol waypoints
Navigation_data - Enables movement
Combat_data - Enables attacking

Step 12: Test in Runtime Debugger

12.1 Launch Game with Guard

Add your guard prefab to a test level
Launch the game (F5)
The guard entity spawns and starts patrolling

12.2 Open BT Debugger

Press Ctrl+Shift+B to open BT Debugger
Debugger window opens showing:
- Entity List (left) - Your guard entity
- Node Graph (center) - Your tree structure
- Inspector (right) - Runtime data

12.3 Observe Patrol Behavior

Select the guard entity in the Entity List
Watch the Node Graph:
- Root Selector: 🔵 Running
- Combat Sequence: ❌ Failure (no target)
- Patrol Sequence: 🔵 Running
- Currently executing nodes are highlighted

Observe in the Execution Log:

[0.0s] Guard Decision - Running
[0.0s] Combat - Failure (no target)
[0.1s] Patrol - Running
[0.1s] Pick Next Waypoint - Success
[0.2s] Move to Waypoint - Running
[3.5s] Move to Waypoint - Success
[3.6s] Pick Next Waypoint - Success
...

12.4 Test Combat Behavior

To test the combat branch:

Option A: Use Debug Mode

In the debugger, click the guard entity
In Inspector → Blackboard section
Manually set targetEntity to player entity ID
Watch combat sequence activate

Option B: Natural Detection

Make sure guard has a detection system
Move player close to guard
Guard detects player and engages

Expected behavior:

Combat Sequence: ✅ Success (target visible)
Attack Target: 🔵 Running (attacking)
Patrol Sequence: ⏸️ Not evaluated (combat wins)

Step 13: Understanding Execution Flow

How the Tree Executes

Frame 1:

Selector "Guard Decision" - Evaluates children
  ├─ Sequence "Combat"
  │   └─ Condition "Target Visible?" → Failure (no target)
  └─ (Combat fails, try next child...)

Frame 1 (continued):

Selector "Guard Decision" - Still evaluating
  ├─ Sequence "Combat" - Failed
  └─ Sequence "Patrol" - Tries this
      ├─ Action "Pick Next Waypoint" → Success (waypoint selected)
      └─ Action "Move to Waypoint" → Running (started moving)

Frame 2-N:

Selector "Guard Decision" - Re-evaluates (tree is reactive!)
  ├─ Sequence "Combat"
  │   └─ Condition "Target Visible?" → Failure (still no target)
  └─ Sequence "Patrol"
      └─ Action "Move to Waypoint" → Running (continues from last frame)

When target appears:

Selector "Guard Decision"
  ├─ Sequence "Combat"
  │   ├─ Condition "Target Visible?" → Success (target detected!)
  │   └─ Action "Attack Target" → Running (starts attacking)
  └─ (Patrol not evaluated - combat succeeded)

Key insight: The tree is reactive - it re-evaluates from the root every frame, so the guard can switch from patrol to combat instantly when a target appears.

Step 14: Improving the Tree (Optional)

Enhancement 1: Add Investigation

What if the guard should investigate where it last saw the target?

Add between Combat and Patrol:

Selector "Guard Decision"
 ├─ Sequence "Combat" (existing)
 ├─ Sequence "Investigate" (new!)
 │   ├─ Condition "Has Last Known Position"
 │   └─ Action "Move to Last Known Position"
 └─ Sequence "Patrol" (existing)

Enhancement 2: Add Attack Range Check

Prevent attacking when too far away:

Sequence "Combat"
 ├─ Condition "Target Visible?"
 ├─ Condition "Target in Range" (new! param: 100.0)
 └─ Action "Attack Target"

Enhancement 3: Add Health Check for Flee

Guard flees when health is low:

Selector "Guard Decision"
 ├─ Sequence "Flee" (new - highest priority!)
 │   ├─ Condition "Health Below" (param: 25.0)
 │   └─ Action "Move to Safe Point"
 ├─ Sequence "Combat"
 ├─ Sequence "Patrol"

Step 15: Common Issues and Solutions

Issue: Guard doesn't patrol

Check:

✅ Patrol_data component exists with waypoints
✅ Navigation_data component exists
✅ Tree file path correct in AIBehaviorTree_data
✅ Tree loaded successfully (check console)

Solution:

Add missing components to prefab
Verify file paths
Check console for load errors

Issue: Guard doesn't attack

Check:

✅ Combat_data component exists
✅ Target detection system working
✅ targetEntity set in blackboard

Solution:

Add Combat_data component
Implement detection (e.g., vision cone)
Use debugger to verify target is set

Issue: Nodes always fail

Check:

✅ Required components exist for actions
✅ Parameters are valid (positive ranges, etc.)
✅ Conditions are reachable (not blocked by failing parent)

Solution:

Use debugger to identify which node fails
Check node parameters
Verify entity has required components

Next Steps

Congratulations! You've created your first behavior tree. 🎉

Continue Learning

BT Debugger Guide - Master runtime debugging
Node Types - Explore all available nodes
Advanced Tutorial - Build complex AI

Try These Challenges

Add an idle state: Guard waits a few seconds before moving to next waypoint
Create a boss AI: Multi-phase behavior with health thresholds
Build a merchant: NPC that wanders but stops to talk to player

Additional Resources

Connection Rules - Understand node connections
Keyboard Shortcuts - Work more efficiently
Custom Nodes - Extend with code

Summary

You learned how to:

✅ Create a new behavior tree
✅ Add and connect nodes (Selector, Sequence, Condition, Action)
✅ Configure node parameters
✅ Validate and save trees
✅ Attach AI to entities with prefabs
✅ Test and debug at runtime
✅ Understand execution flow

Next tutorial: Advanced Behavior Trees - Learn decorators, repeaters, and complex patterns!

Prerequisites​

Step 1: Create a New Behavior Tree​

1.1 Open the Blueprint Editor​

1.2 Create New Behavior Tree​

Step 2: Plan Your AI Structure​

Step 3: Build the Root Selector​

3.1 Configure Root Node​

Step 4: Add Combat Sequence​

4.1 Add Combat Sequence Node​

4.2 Configure Combat Sequence​

Step 5: Add Combat Condition​

5.1 Add Target Check​

5.2 Configure Condition​

Step 6: Add Attack Action​

6.1 Add Attack Node​

6.2 Configure Attack Action​

Step 7: Add Patrol Sequence​

7.1 Add Patrol Sequence​

7.2 Configure Patrol Sequence​

Step 8: Add Patrol Actions​

8.1 Add Pick Patrol Point​

8.2 Add Move Action​

Step 9: Arrange and Validate​

9.1 Auto-Layout​

9.2 Validate Tree​

Step 10: Save Your Tree​

Step 11: Create Guard Entity Prefab​

11.1 Create Prefab File​

Step 12: Test in Runtime Debugger​

12.1 Launch Game with Guard​

12.2 Open BT Debugger​

12.3 Observe Patrol Behavior​

12.4 Test Combat Behavior​

Step 13: Understanding Execution Flow​

How the Tree Executes​

Step 14: Improving the Tree (Optional)​

Enhancement 1: Add Investigation​

Enhancement 2: Add Attack Range Check​

Enhancement 3: Add Health Check for Flee​

Step 15: Common Issues and Solutions​

Issue: Guard doesn't patrol​

Issue: Guard doesn't attack​

Issue: Nodes always fail​

Next Steps​

Continue Learning​

Try These Challenges​

Additional Resources​

Summary​

Prerequisites

Step 1: Create a New Behavior Tree

1.1 Open the Blueprint Editor

1.2 Create New Behavior Tree

Step 2: Plan Your AI Structure

Step 3: Build the Root Selector

3.1 Configure Root Node

Step 4: Add Combat Sequence

4.1 Add Combat Sequence Node

4.2 Configure Combat Sequence

Step 5: Add Combat Condition

5.1 Add Target Check

5.2 Configure Condition

Step 6: Add Attack Action

6.1 Add Attack Node

6.2 Configure Attack Action

Step 7: Add Patrol Sequence

7.1 Add Patrol Sequence

7.2 Configure Patrol Sequence

Step 8: Add Patrol Actions

8.1 Add Pick Patrol Point

8.2 Add Move Action

Step 9: Arrange and Validate

9.1 Auto-Layout

9.2 Validate Tree

Step 10: Save Your Tree

Step 11: Create Guard Entity Prefab

11.1 Create Prefab File

Step 12: Test in Runtime Debugger

12.1 Launch Game with Guard

12.2 Open BT Debugger

12.3 Observe Patrol Behavior

12.4 Test Combat Behavior

Step 13: Understanding Execution Flow

How the Tree Executes

Step 14: Improving the Tree (Optional)

Enhancement 1: Add Investigation

Enhancement 2: Add Attack Range Check

Enhancement 3: Add Health Check for Flee

Step 15: Common Issues and Solutions

Issue: Guard doesn't patrol

Issue: Guard doesn't attack

Issue: Nodes always fail

Next Steps

Continue Learning

Try These Challenges

Additional Resources

Summary