/limboai

name: limboai
description: Use when using the LimboAI addon — behavior trees and hierarchical state machines (C++ GDExtension) with a visual editor, BTTask subclassing, and a blackboard

LimboAI

> **Related skills:** **ai-navigation** for movement the tasks drive, **state-machine** for core-engine FSM (when you don't need an addon), **godot-brainstorming** for choosing an AI approach.

> **Addon:** LimboAI · version `v1.8.1` · Godot 4.6+ (GDExtension) · MIT · source: https://github.com/limbonaut/limboai · written in C++ (GDExtension; engine-module build also available). GDExtension exposes GDScript; **C# requires the module build** (not GDExtension in v1.8.1), and the v1.8.1 module build targets **Godot 4.7** (4.7.2-stable builds).

> **Godot 4.8:** not yet confirmed by the addon. Issue [#477](https://github.com/limbonaut/limboai/issues/477) (open) reports that v1.8 does not work with 4.8's new dock system and leaves the editor unusable; the open draft PR [#474](https://github.com/limbonaut/limboai/pull/474) "Support Godot 4.8" targets it. Keep LimboAI projects on 4.7 until a release states 4.8 support (checked 2026-11-12).

---

1. When to use LimboAI

| Approach | Best for | |---|---| | Core-engine FSM (`state-machine` skill) | Simple agents, < 5 states, no addon | | **Beehave** (GDScript addon) | Lightweight BT, GDScript-only projects | | **LimboAI** | BT **and** HSM together, visual editor, C++ performance, C# support (module build) |

Choose LimboAI when you need a behavior tree with a polished visual debugger, want to combine it with a hierarchical state machine (`BTState` bridges them), or need C++ task execution speed. Note: LimboAI v1.8.x requires **Godot 4.6+**. On 4.4–4.5 the matching lines are 1.4.x–1.6.x, and on 4.3 it is 1.2.0–1.3.x; this skill covers neither. For a simpler GDScript-only behavior tree, Beehave is a lighter alternative. For plain state machines without a BT, use the built-in `state-machine` skill instead.

---

2. Install & setup

GDExtension (recommended — no custom engine)

1. **Godot AssetLib** → search "LimboAI" → Download → Reload project. Or download from GitHub Releases and place `addons/limboai/` in `res://addons/limboai/`. 2. No plugin toggle: there is no `plugin.cfg` — the extension registers its editor plugin itself once the project reloads. 3. The `.gdextension` manifest ships at `res://addons/limboai/bin/`:

[configuration]
entry_symbol = "limboai_init"
compatibility_minimum = "4.2"

[libraries]
windows.debug.x86_64   = "res://addons/limboai/bin/liblimboai.windows.editor.x86_64.dll"
windows.release.x86_64 = "res://addons/limboai/bin/liblimboai.windows.template_release.x86_64.dll"
linux.debug.x86_64     = "res://addons/limboai/bin/liblimboai.linux.editor.x86_64.so"
linux.release.x86_64   = "res://addons/limboai/bin/liblimboai.linux.template_release.x86_64.so"
macos.debug            = "res://addons/limboai/bin/liblimboai.macos.editor.framework"
macos.release          = "res://addons/limboai/bin/liblimboai.macos.template_release.framework"
# ... (additional platform entries for linux arm64/rv64, android, iOS, web)

**GDExtension limitations:** the LimboAI task palette shows no documentation tooltips (module-only in v1.8.1). The `BBParam` property editor was ported to GDExtension in 2025, although the docs still list it as missing. C# needs the module build (below).

Module version (C# or full editor integration)

Download pre-compiled editor + export templates from [GitHub Releases](https://github.com/limbonaut/limboai/releases). Requires the custom engine for export. v1.8.1 module builds are based on **Godot 4.7** (4.7.2-stable) (GDExtension supports 4.6+). The module build ships a NuGet package for C#:

# Add local NuGet source to your project:
# dotnet nuget add source path/to/nupkgs --name LimboNugetSource

---

3. Behavior trees

A `BehaviorTree` resource holds the task tree. `BTPlayer` runs it each physics frame (or idle/manual). Add `BTPlayer` as a child of the agent node and assign a `BehaviorTree` resource.

GDScript

# EnemyAI.gd — assign behavior_tree in the Inspector or here
extends CharacterBody2D

@onready var bt_player: BTPlayer = $BTPlayer

func _ready() -> void:
    # BTPlayer starts executing automatically (active = true by default).
    # updated(status) fires after every update, not only when the tree finishes.
    bt_player.updated.connect(_on_bt_updated)

func _on_bt_updated(status: int) -> void:
    if status == BT.SUCCESS:
        # A tree that returned SUCCESS/FAILURE re-enters from the root on the next
        # update, so it loops on its own; stopping it here makes it run once.
        # (restart() is for aborting a tree that is still running.)
        bt_player.active = false

C#

// EnemyAI.cs
using Godot;

public partial class EnemyAI : CharacterBody2D
{
    [Export] private BTPlayer _btPlayer;

    public override void _Ready()
    {
        _btPlayer.Updated += OnBtUpdated;
    }

    private void OnBtUpdated(long status) // int signal args are long in C#
    {
        if (status == (long)BT.Status.Success)
            _btPlayer.Active = false; // without this the finished tree loops on its own; Restart() aborts a running one
    }
}

`BTPlayer.UpdateMode` controls when the tree ticks: `IDLE` (every `_process`), `PHYSICS` (every `_physics_process`, default), or `MANUAL` (call `bt_player.update(delta)` yourself).

---

4. Custom tasks

Subclass `BTAction` (multi-tick work) or `BTCondition` (immediate check). Annotate with `@tool` so `_generate_name()` and `_get_configuration_warnings()` work in the editor. Place scripts under `res://ai/tasks/`; subfolders become task categories.

GDScript

@tool
extends BTAction
## Moves the agent toward a blackboard position each tick.

@export var target_pos_var: StringName = &"target_pos"
@export var speed: float = 200.0

func _generate_name() -> String:
    return "MoveT