Arbor

Composable, typed behavior trees for Roblox AI.

Releases · API Reference

Install

Wally (Luau)

[dependencies]
arbor = "axp3cter/arbor@2.1.0"

npm (roblox-ts)

npm install @axpecter/arbor

Direct download

Grab the latest .rbxm from Releases.

Quick Start

local bt = require(path.to.bt)

local board = { target = nil :: Player?, health = 100 }
local npc = script.Parent

local root = bt.select {
    bt.sequence {
        bt.check(function(b) return b.health < 30 end),
        bt.action(function(_b, agent)
            agent:runAway()
            return "running"
        end),
    },
    bt.sequence {
        bt.check(function(b) return b.target ~= nil end),
        bt.action(function(_b, agent)
            agent:attack()
            return "success"
        end),
    },
    bt.action(function(_b, agent)
        agent:patrol()
        return "running"
    end),
}

local ctx = bt.run(root, board, npc, 10)

npc.Destroying:Once(function()
    ctx:destroy()
end)

Concepts

Status

Every node returns one of three statuses each tick:

These are the only three values in the system. Composites and decorators make decisions based on which status their children return.

Board

The board is a shared data table that every node callback receives as its first argument. Put anything the AI needs to reason about on here: targets, health, flags, positions. You define the shape.

local board = {
    target    = nil :: Player?,
    health    = 100,
    canSee    = false,
    allies    = 0,
    lastHeard = nil :: Vector3?,
}

Conditions only receive (board). Actions receive (board, agent, dt). If you need agent state in a condition, write it to the board first (a poll is the natural place for that).

Conditions

Conditions read the board and return "success" or "failure". They never return "running". Use them as gates in sequences and selectors.

local hasTarget = bt.check(function(b) return b.target ~= nil end)
local isHurt    = bt.check(function(b) return b.health < 30 end)

Actions

Actions are where the NPC does work. Two forms exist depending on whether the work is instant or spans multiple frames.

Function form runs every tick the action is active. No state is tracked internally. The handler receives (board, agent, dt) and must return a status.

local attack = bt.action(function(_b, agent)
    agent:swingWeapon()
    return "success"
end)

Table form is for work that spans multiple frames. Three optional hooks:

• enter(board, agent, dt) runs once on the first tick after activation. If it returns "running", the action enters the tick phase. If it returns "success" or "failure", the action completes immediately without ever calling tick.
• tick(board, agent, dt) runs every subsequent tick while the action is "running". Return "success" or "failure" to complete.
• halt(board, agent) runs if the action is interrupted while "running" (a parent halts it). Not called on normal completion. Does not receive dt.

At least one of enter or tick must be provided. If enter is omitted, the action skips straight to tick on its first frame. If tick is omitted and enter returns "running", the action stays "running" indefinitely until halted externally. This is a valid fire-and-forget pattern (start an animation, keep running until the branch switches).

local chase = bt.action({
    enter = function(b, agent)
        agent:pathTo(b.target)
        return "running"
    end,
    tick = function(_b, agent)
        return if agent:reachedTarget() then "success" else "running"
    end,
    halt = function(_b, agent)
        agent:stopMoving()
    end,
})

Composites

Composites combine multiple nodes into control flow.

bt.select runs children left to right and succeeds on the first child that succeeds. Re-evaluates from child 1 every tick. This means higher-priority branches automatically take over when their conditions become true. If a lower-priority child was "running", it gets halted. Returns "failure" only if every child fails.

bt.select {
    bt.sequence { isHurt, flee },       -- priority 1
    bt.sequence { hasTarget, attack },  -- priority 2
    patrol,                             -- priority 3
}

bt.sequence runs children left to right and fails on the first child that fails. Unlike select, sequence uses sticky resume. It remembers which child was "running" and picks up there next tick. Earlier children that already succeeded are not re-evaluated. Returns "success" only if every child succeeds.

bt.sequence {
    hasTarget,
    canSee,
    chase,
}

bt.parallel(succeed, fail?) ticks all children every frame. Resolves when enough children have reached a terminal status. succeed is the number of children that must succeed for the parallel to return "success". fail is the number that must fail for "failure", defaulting to the total child count. Both thresholds must be > 0 and ≤ the child count.

When a threshold is met mid-tick, all remaining active children are halted. If all children resolve without either threshold being met (possible when succeed + fail > count), the parallel returns "failure".

bt.parallel(1) {        -- succeed when 1 child succeeds
    chase,
    attackLoop,
}

bt.parallel(2, 1) {     -- succeed when 2 succeed, fail when 1 fails
    taskA,
    taskB,
    taskC,
}

Note the curried API. bt.parallel(succeed) returns a function that takes the children table. This reads naturally in Luau thanks to call sugar: bt.parallel(1) { ... }.

bt.random picks one child at random and sticks with it until it resolves ("success" or "failure"). While the chosen child returns "running", it stays selected. On resolution, the selection is cleared and the next activation picks fresh. Optional weights make some children more likely.

bt.random({
    patrol,
    idleAnimation,
}, { 3, 1 })  -- patrol is 3x more likely

Decorators

Decorators are chained methods on any node. Each returns a new node wrapping the original. Read left to right:

chase:timeout(6):retry(3)
-- "chase, with a 6-second timeout, retried up to 3 times"

Poll Services

Polls run a function on a wall-clock interval (os.clock) and always return "success". The interval is independent of the context's tick rate. A 0.3s poll fires based on real elapsed time, not simulation ticks.

Attach polls to nodes via :serve(). The polls are scoped to the served node's lifecycle: they tick every frame while the served branch is active, and their timers reset when the branch is halted.

local scan = bt.poll(0.3, function(b, agent)
    b.target = agent:findNearestEnemy()
    b.canSee = b.target ~= nil and agent:hasLineOfSight(b.target)
end)

local root = bt.select {
    -- decision tree...
} :serve(scan)

Wait

bt.wait(seconds) returns "running" until the specified duration has elapsed, then returns "success". Duration is tracked by accumulating ctx.dt, so it measures simulation time, not wall-clock time. With a fixed-timestep runner at 10Hz, each tick advances by 0.1s of simulation time.

bt.sequence {
    attack:cooldown(0.8),
    bt.wait(0.2),        -- brief pause after attack
} :loop()

Context

A tree is just a structure, a frozen graph of nodes. To run it, bind it to a board and an agent by creating a context. The context holds all runtime state (which child is running, timers, cooldown timestamps). One tree can be shared across many contexts with independent state.

-- Manual ticking:
local ctx = bt.bind(root, board, npc)
RunService.Heartbeat:Connect(function(dt)
    ctx:tick(dt)
end)

-- Automatic runner at N Hz (fixed timestep):
local ctx = bt.run(root, board, npc, 10)

-- Automatic runner at frame rate (variable dt):
local ctx = bt.run(root, board, npc)

When ticking manually, always pass dt. Omitting it defaults to 0, which means time-based nodes like bt.wait and node:timeout will never make progress.

ctx:stop() disconnects the runner, halts all running nodes (triggering their cleanup), and clears all internal state. After stop, calling tick() or start() begins a completely fresh run. No prior state survives.

ctx:destroy() calls stop() and marks the context as dead. All subsequent tick() calls return "failure". Idempotent.

Always call ctx:destroy() when the NPC is removed. Without it, the Heartbeat connection leaks.

npc.Destroying:Once(function()
    ctx:destroy()
end)

Full Example

local bt = require(path.to.bt)

type Board = {
    target: Player?,
    health: number,
    canSee: boolean,
    allies: number,
    lastHeard: Vector3?,
}

local board: Board = {
    target    = nil,
    health    = 100,
    canSee    = false,
    allies    = 0,
    lastHeard = nil,
}

local npc = script.Parent

-- Conditions

local hasTarget  = bt.check(function(b: Board) return b.target ~= nil end)
local isHurt     = bt.check(function(b: Board) return b.health < 30 end)
local canSee     = bt.check(function(b: Board) return b.canSee end)
local hasAllies  = bt.check(function(b: Board) return b.allies > 0 end)
local heardNoise = bt.check(function(b: Board) return b.lastHeard ~= nil end)

-- Actions

local attack = bt.action(function(_b: Board, agent)
    agent:swingWeapon()
    return "success"
end)

local callForHelp = bt.action(function(_b: Board, agent)
    agent:shout()
    return "success"
end)

local heal = bt.action(function(b: Board, agent)
    agent:playAnimation("Heal")
    b.health = math.min(100, b.health + 30)
    return "success"
end)

local patrol = bt.action(function(_b: Board, agent)
    agent:walkToNextWaypoint()
    return "running"
end)

local chase = bt.action({
    enter = function(b: Board, agent)
        agent:pathTo(b.target)
        return "running"
    end,
    tick = function(_b: Board, agent)
        return if agent:reachedTarget() then "success" else "running"
    end,
    halt = function(_b: Board, agent)
        agent:stopMoving()
    end,
})

local flee = bt.action({
    enter = function(_b: Board, agent)
        agent:runAway()
        return "running"
    end,
    tick = function(_b: Board, agent)
        return if agent:isSafe() then "success" else "running"
    end,
    halt = function(_b: Board, agent)
        agent:stopMoving()
    end,
})

local investigate = bt.action({
    enter = function(b: Board, agent)
        agent:pathTo(b.lastHeard)
        return "running"
    end,
    tick = function(b: Board, agent)
        if agent:reachedTarget() then
            b.lastHeard = nil
            return "success"
        end
        return "running"
    end,
    halt = function(_b: Board, agent)
        agent:stopMoving()
    end,
})

-- Tree

local root = bt.select {
    bt.sequence {
        isHurt,
        bt.select {
            bt.sequence { hasAllies:invert(), flee },
            bt.sequence { callForHelp, heal:cooldown(8) },
        },
    },

    bt.sequence {
        hasTarget,
        canSee,
        bt.parallel(1) {
            chase:timeout(6):retry(3),
            bt.sequence { attack:cooldown(0.8), bt.wait(0.2) } :loop(),
        },
    },

    bt.sequence { heardNoise, investigate:timeout(10) },

    bt.random({
        bt.sequence { patrol, bt.wait(3) } :loop(),
        bt.wait(5),
    }, { 3, 1 }),

} :serve(
    bt.poll(0.3, function(b: Board, agent)
        b.target = agent:findNearestEnemy()
        b.canSee = b.target ~= nil and agent:hasLineOfSight(b.target)
        b.allies = agent:countNearbyAllies()
    end),
    bt.poll(1.0, function(b: Board, agent)
        b.lastHeard = agent:getLastHeardPosition()
    end)
)

-- Run

local ctx = bt.run(root, board, npc, 10)

npc.Destroying:Once(function()
    ctx:destroy()
end)

API Reference

Leaves

Composites

Decorators

Chained methods on Node. Each returns a new Node.

Context

License

MIT