BehaviorTree

A behavior tree library for Simba/Lape with blackboard data sharing, parallel execution, and debugging tools.

Quick Start

{$INCLUDE_ONCE behaviortree.simba}

var
  Tree: TBehaviorTree;

function CheckHealth(): Boolean;
begin
  Result := Tree.Blackboard.Get('Health', -1) > 50;
end;

function Heal(): EBTStatus;
begin
  Tree.Blackboard.Put('Health', 99);
  Result := EBTStatus.Success;
end;

function Attack(): EBTStatus;
begin
  Result := EBTStatus.Success;
end;

begin
  Tree.Setup('Combat AI');
  Tree.SetDebugLevel(EBTDebugLevel.Normal);
  Tree.Blackboard.Put('Health', 30);

  Tree.Root := Tree.CreateSelector('Combat', [
    Tree.CreateSequence('Heal When Low', [
      Tree.CreateInverter('Health Not OK', Tree.CreateCondition('Health OK', @CheckHealth)),
      Tree.CreateAction('Heal', @Heal)
    ]),
    Tree.CreateAction('Attack', @Attack)
  ]);

  Tree.Tick(); // Executes heal since health is low
  Tree.Tick(); // Executes attack since health is now good

  Tree.Free();
end.

Output

--> Combat
  --> Heal When Low
    --> Health Not OK
      --> Health OK
      <-- Health OK [FAIL]
    <-- Health Not OK [OK]
    --> Heal
    <-- Heal [OK]
  <-- Heal When Low [OK]
<-- Combat [OK]
--> Combat
  --> Heal When Low
    --> Health Not OK
      --> Health OK
      <-- Health OK [OK]
    <-- Health Not OK [FAIL]
  <-- Heal When Low [FAIL]
  --> Attack
  <-- Attack [OK]
<-- Combat [OK]   

Core Concepts

• Actions: Execute functions and return success/failure/running
• Conditions: Evaluate boolean expressions
• Selectors: Try children until one succeeds (OR logic)
• Sequences: Execute children until one fails (AND logic)
• Decorators: Modify child behavior (invert, retry, cooldown, etc.)
• Blackboard: Shared data storage for all nodes
• Reactive Nodes: Interrupt on data changes

Node Types

Composites

• CreateSelector - OR logic
• CreateSequence - AND logic
• CreateParallelSelector/Sequence - Concurrent execution

Decorators

• CreateInverter - Flip success/failure
• CreateRetry - Repeat on failure
• CreateCooldown - Limit execution frequency

Utilities

• CreateDelay - Wait for specified time
• CreateProbability - Random success chance
• CreateSuccess/Failure - Static results

Documentation

All functions include inline documentation with examples. See the source files:

• src/actions.simba - Actions and conditions
• src/composites.simba - Selectors and sequences
• src/decorators.simba - Behavior modifiers
• src/reactive.simba - Reactive nodes
• src/features.simba - Events and debugging
• src/blackboard.simba - Shared data storage

Testing

Run tests/test_runner.simba to execute all tests and see usage examples.