The behavior tree system

Composable behavior tree nodes for NPC AI using MAST labels as leaf nodes.

Overview

The behavior tree functions provide a higher-level alternative to the brain system for structuring NPC logic. Each function schedules a set of MAST labels as parallel tasks and returns a promise that resolves based on the tree's semantics:

Node type	Resolves when
`bt_seq` (Sequence)	All children succeed in order — fails as soon as any child fails
`bt_sel` (Select)	First child to succeed — tries next on failure
`bt_invert`	Inverts the child's result
`bt_until_success`	Repeats the child label until it returns `BT_SUCCESS`
`bt_until_fail`	Repeats the child label until it returns `BT_FAIL`
`bt_repeat`	Repeats the child label indefinitely

These are designed to be composed with await in MAST. Within a behavior tree label, use BT_SUCCESS or BT_FAIL to signal the outcome.

bt_get_variable / bt_set_variable read and write from the behavior tree's shared blackboard data so child labels can communicate without task-scope coupling.

Quick example

MAST pyMAST

== npc_ai ==
await bt_sel(attack_if_close, patrol)

== attack_if_close ==
enemies = broad_test_around(get_pos(BRAIN_AGENT_ID), 1000) & role("enemy")
if len(enemies) == 0: BT_FAIL
target(BRAIN_AGENT_ID, closest(BRAIN_AGENT_ID, enemies))
BT_SUCCESS
== patrol ==
target_pos(BRAIN_AGENT_ID, waypoint_x, 0, waypoint_z)
BT_SUCCESS

from sbs_utils.procedural.behavior import bt_seq, bt_sel, bt_invert, bt_until_success

# Sequence: do A then B (fails if A fails)
await bt_seq(move_to_target, fire_weapons)

# Select: try A, fall back to B
await bt_sel(attack_label, patrol_label)

# Repeat until the patrol label returns BT_SUCCESS
await bt_until_success(patrol_label)

Return values in BT labels

Within a behavior tree leaf label, end with one of:

BT_SUCCESS   # this node succeeded
BT_FAIL      # this node failed
OK_IDLE      # still running (yield and retry next tick)

API

`bt_export_variable(name, value)`

Export a variable from the behavior tree to the main (root) task's scope.

Parameters:

Name	Type	Description	Default
`name`	`str`	Variable name.	required
`value`	`any`	Value to assign.	required

`bt_get_variable(name, defa_value=None)`

Get a variable from the current behavior tree's blackboard data.

Parameters:

Name	Type	Description	Default
`name`	`str`	Variable name.	required
`defa_value`	`any`	Value returned when the variable is absent. Defaults to None.	`None`

Returns:

Name	Type	Description
`any`		The variable value, or `defa_value`.

`bt_invert(a_bt_promise)`

Behavior tree inverter — flips the success/failure result of a promise.

Parameters:

Name	Type	Description	Default
`a_bt_promise`	`PromiseBehave \| label`	Promise or label whose result should be inverted.	required

Returns:

Name	Type	Description
`PromiseBehaveInvert`		A promise that inverts the child result.

`bt_repeat(a_bt_promise, count)`

Repeat a behavior tree promise a fixed number of times.

Parameters:

Name	Type	Description	Default
`a_bt_promise`	`PromiseBehave \| label`	Promise or label to repeat.	required
`count`	`int`	Maximum number of repetitions.	required

Returns:

Name	Type	Description
`PromiseBehaveRepeat`		A promise that resolves after `count` successful iterations or fails if the child fails.

`bt_sel(*args, **kwargs)`

Behavior tree selector — succeeds as soon as any child succeeds.

Parameters:

Name	Type	Description	Default
`*args`	`label`	Labels to run as selector children.	`()`
`data`	`dict`	Keyword argument passed as variables to each child task. Defaults to None.	required

Returns:

Name	Type	Description
`PromiseBehaveSel`		A promise that resolves on the first child success, or fails if all children fail.

`bt_seq(*args, **kwargs)`

Behavior tree sequence — succeeds only if every child succeeds in order.

Parameters:

Name	Type	Description	Default
`*args`	`label`	Labels to run as sequential children.	`()`
`data`	`dict`	Keyword argument passed as variables to each child task. Defaults to None.	required

Returns:

Name	Type	Description
`PromiseBehaveSeq`		A promise that resolves when all children succeed, or fails as soon as any child fails.

`bt_set_variable(name, value)`

Set a variable on the current behavior tree's blackboard data.

Parameters:

Name	Type	Description	Default
`name`	`str`	Variable name.	required
`value`	`any`	Value to assign.	required

`bt_until_fail(a_bt_promise)`

Repeat a behavior tree promise until it fails.

Parameters:

Name	Type	Description	Default
`a_bt_promise`	`PromiseBehave \| label`	Promise or label to repeat.	required

Returns:

Name	Type	Description
`PromiseBehaveUntil`		A promise that keeps rewinding the child until it returns `BT_FAIL`.

`bt_until_success(a_bt_promise)`

Repeat a behavior tree promise until it succeeds.

Parameters:

Name	Type	Description	Default
`a_bt_promise`	`PromiseBehave \| label`	Promise or label to repeat.	required

Returns:

Name	Type	Description
`PromiseBehaveUntil`		A promise that keeps rewinding the child until it returns `BT_SUCCESS`.