gale.ai.behavior_tree module

This file contains a behavior tree implementation to model the decision making of autonomous characters through a hierarchy of composable nodes.

Author: Alejandro Mujica (aledrums@gmail.com)

class gale.ai.behavior_tree.Status(*values)

Bases: Enum

Result of ticking a behavior tree node.

SUCCESS = 'success'

FAILURE = 'failure'

RUNNING = 'running'

class gale.ai.behavior_tree.Node

Bases: object

Base class for any node of a behavior tree.

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.Action(function)

Bases: Node

Leaf node that executes a function and reports its result as the node status.

Parameters:

function (Callable[[Any, float], Status])

function: Callable[[Any, float], Status]

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Condition(predicate)

Bases: Node

Leaf node that evaluates a predicate and succeeds or fails depending on its result.

Parameters:

predicate (Callable[[Any], bool])

predicate: Callable[[Any], bool]

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Composite(children)

Bases: Node

Base class for nodes that group several children nodes.

Parameters:

children (List[Node])

children: List[Node]

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.Sequence(children)

Bases: _IterativeComposite

Runs its children in order and succeeds only if all of them succeed. It stops (and fails) as soon as one of them fails, and reports RUNNING while the current child is still running, resuming from it on the next tick.

Parameters:

children (List[Node])

short_circuit_status: Status = 'failure'

exhausted_status: Status = 'success'

class gale.ai.behavior_tree.Selector(children)

Bases: _IterativeComposite

Runs its children in order and succeeds as soon as one of them succeeds. It only fails if all of them fail, and reports RUNNING while the current child is still running, resuming from it on the next tick.

Parameters:

children (List[Node])

short_circuit_status: Status = 'success'

exhausted_status: Status = 'failure'

class gale.ai.behavior_tree.Parallel(children, success_threshold=None, failure_threshold=None)

Bases: Composite

Runs all of its children on every tick and succeeds or fails according to how many of them succeeded or failed on this tick. Children that already reached SUCCESS or FAILURE are latched and no longer ticked on subsequent calls, so their side effects only run once, until this node itself finishes and resets.

Parameters:

• children (List[Node])

• success_threshold (int | None)

• failure_threshold (int | None)

success_threshold: int

failure_threshold: int

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.Decorator(child)

Bases: Node

Base class for nodes that wrap and alter the behavior of a single child node.

Parameters:

child (Node)

child: Node

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.Inverter(child)

Bases: Decorator

Inverts the result of its child: SUCCESS becomes FAILURE and vice versa. RUNNING is left untouched.

Parameters:

child (Node)

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Succeeder(child)

Bases: Decorator

Always reports SUCCESS once its child finishes, regardless of its actual result.

Parameters:

child (Node)

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Failer(child)

Bases: Decorator

Always reports FAILURE once its child finishes, regardless of its actual result.

Parameters:

child (Node)

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Repeater(child, times=None)

Bases: Decorator

Runs its child a fixed number of times (or forever), reporting RUNNING until it has finished all the repetitions.

Parameters:

• child (Node)

• times (int | None)

times: int | None

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.UntilSuccess(child)

Bases: Decorator

Keeps running its child until it succeeds.

Parameters:

child (Node)

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.UntilFailure(child)

Bases: Decorator

Keeps running its child until it fails.

Parameters:

child (Node)

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

class gale.ai.behavior_tree.Cooldown(child, duration)

Bases: Decorator

Prevents its child from being run again until a given amount of time has passed since the last time it finished, either by success or failure. While in cooldown, this node fails immediately.

Parameters:

• child (Node)

• duration (float)

duration: float

tick(agent, dt)

Execute this node.

Parameters:

• agent (Any) – The agent this behavior tree belongs to. It is passed down to every node so that leaves can inspect/modify it.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of this node after this tick.

Return type:

Status

reset()

Reset any internal state kept by this node. It is called whenever this node stops being run, either because it finished or because its parent moved on to another child, so that the next tick starts fresh.

Return type:

None

class gale.ai.behavior_tree.BehaviorTree(root)

Bases: object

Wraps a root node so that it can be conveniently ticked as a whole.

Usage example:

tree = BehaviorTree(

Selector([

Sequence([

Condition(lambda agent: agent.can_see_enemy()), Action(lambda agent, dt: agent.attack(dt)),

]), Action(lambda agent, dt: agent.patrol(dt)),

])

) tree.tick(agent, dt)

Parameters:

root (Node)

root: Node

tick(agent, dt)

Tick the tree from its root.

Parameters:

• agent (Any) – The agent this tree belongs to.

• dt (float) – Time elapsed (in seconds) since the last tick.

Returns:

The status of the root node after this tick.

Return type:

Status