Writing SequenceNodes

Overview

This tutorial demonstrates a couple of simple careBT SequenceNodes. For the demos the ActionNode (AddTwoNumbersAction) implemented in the previous tutorial is reused and two additional ActionNodes are implemented. The first one (CreateRandomNumberAction) generates a random numer and provides it as output parameter. The second one (PrintNumberAction) prints the, as input parameter, provided number on standard output.

Create the ActionNodes and the SimpleSequence1

This first example called SimpleSequence1 contains four child nodes.

The first two nodes generate two random numbers, the third one adds them and the last one prints the result.

Create a file named simple_sequence.py with following content. Or use the provided file: simple_sequence.py

import random

from carebt import ActionNode
from carebt import NodeStatus
from carebt import SequenceNode
from carebt.examples.action_with_params import AddTwoNumbersAction


########################################################################


class CreateRandomNumberAction(ActionNode):
    """The `CreateRandomNumberAction` example node.

    The `CreateRandomNumberAction` creates a random number between 1 and 10
    and binds it to the output parameter.

    Output Parameters
    -----------------
    ?number : int
        The randomly generated number

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '=> ?number')

    def on_tick(self) -> None:
        self._number = random.randint(1, 10)
        print(f'CreateRandomNumberAction: number = {self._number}')
        self.set_status(NodeStatus.SUCCESS)

########################################################################


class PrintNumberAction(ActionNode):
    """The `PrintNumberAction` example node.

    The `PrintNumberAction` prints the, as input parameter provided, number on
    standard output.

    Input Parameters
    ----------------
    ?number : int
        The number to print

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '?number')

    def on_tick(self) -> None:
        print(f'PrintNumberAction: number = {self._number}')
        self.set_status(NodeStatus.SUCCESS)

########################################################################


class SimpleSequence1(SequenceNode):
    """The `SimpleSequence1` example node.

    The `SimpleSequence` runs the nodes `CreateRandomNumberAction`,
    `CreateRandomNumberAction`, `AddTwoNumbersAction` and `PrintNumberAction`
    in a sequence. The first two nodes create random numbers, the third one
    adds them together and the last one prints the result. Furthermore, the
    result is returned by the ouput parameter *?c*.

    Output Parameters
    -----------------
    ?c : int
        The result

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '=> ?c')

    def on_init(self) -> None:
        self.append_child(CreateRandomNumberAction, '=> ?a')
        self.append_child(CreateRandomNumberAction, '=> ?b')
        self.append_child(AddTwoNumbersAction, '?a ?b => ?c')
        self.append_child(PrintNumberAction, '?c')

The code explained

The first statements are the includes for the Python random library, the careBT classes (ActionNode, NodeStatus, SequenceNode) and the AddTwoNumbersAction.

import random

from carebt import ActionNode
from carebt import NodeStatus
from carebt import SequenceNode
from carebt.examples.action_with_params import AddTwoNumbersAction

The CreateRandomNumberAction is a custom ActionNode which generates a random number which is bound to the output parameter ?number.

class CreateRandomNumberAction(ActionNode):
    """The `CreateRandomNumberAction` example node.

    The `CreateRandomNumberAction` creates a random number between 1 and 10
    and binds it to the output parameter.

    Output Parameters
    -----------------
    ?number : int
        The randomly generated number

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '=> ?number')

    def on_tick(self) -> None:
        self._number = random.randint(1, 10)
        print(f'CreateRandomNumberAction: number = {self._number}')
        self.set_status(NodeStatus.SUCCESS)

The PrintNumberAction is a custom ActionNode which prints the provided ?number on standard output.

class PrintNumberAction(ActionNode):
    """The `PrintNumberAction` example node.

    The `PrintNumberAction` prints the, as input parameter provided, number on
    standard output.

    Input Parameters
    ----------------
    ?number : int
        The number to print

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '?number')

    def on_tick(self) -> None:
        print(f'PrintNumberAction: number = {self._number}')
        self.set_status(NodeStatus.SUCCESS)

The SimpleSequence1 node is implemented as a Python class which inherits from SequenceNode.

class SimpleSequence1(SequenceNode):

The class definition is followed by the Docstring documentation of the node, which also documents the interface (output parameters).

    """The `SimpleSequence1` example node.

    The `SimpleSequence` runs the nodes `CreateRandomNumberAction`,
    `CreateRandomNumberAction`, `AddTwoNumbersAction` and `PrintNumberAction`
    in a sequence. The first two nodes create random numbers, the third one
    adds them together and the last one prints the result. Furthermore, the
    result is returned by the ouput parameter *?c*.

    Output Parameters
    -----------------
    ?c : int
        The result

    """

The constructor (__init__) of the SimpleSequence1 needs to call the constructor (super().__init__) of the SequenceNode and passes the bt_runner and the signature as arguments. The signature defines one output parameter called ?c.

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '=> ?c')

The on_init function is called rigth after the node was created. It is the place to put the code which should be executed once, after the node was created. For a SequenceNode the child nodes are typically added here.

    def on_init(self) -> None:
        self.append_child(CreateRandomNumberAction, '=> ?a')
        self.append_child(CreateRandomNumberAction, '=> ?b')
        self.append_child(AddTwoNumbersAction, '?a ?b => ?c')
        self.append_child(PrintNumberAction, '?c')

Run the example

Start the Python interpreter and run the SimpleSequence1 node:

>>> import carebt
>>> from carebt.examples.simple_sequence import SimpleSequence1
>>> bt_runner = carebt.BehaviorTreeRunner()
>>> bt_runner.run(SimpleSequence1, '=> ?x')
CreateRandomNumberAction: number = 6
CreateRandomNumberAction: number = 5
AddTwoNumbersAction: calculating: 6 + 5 = 11
PrintNumberAction: number = 11

>>> bt_runner.run(SimpleSequence1, '=> ?x')
CreateRandomNumberAction: number = 7
CreateRandomNumberAction: number = 9
AddTwoNumbersAction: calculating: 7 + 9 = 16
PrintNumberAction: number = 16

Create the SimpleSequence2

The SimpleSequence2 is a modified version of the SimpleSequence1. It shows how simple a different sequence of children can be created and how the parameters can be bound across the different children.

Add the following content to simple_sequence.py. Or use the provided file: simple_sequence.py

class SimpleSequence2(SequenceNode):
    """The `SimpleSequence2` example node.

    The `SimpleSequence2` demonstrates a modified version of the
    `SimpleSequence1`. The value provided as an input parameter is
    added to a randomly generated value. The result is then added
    to another randomly generated value. This final result is then
    provided as an output of the `SequenceNode`.

    Input Parameters
    ----------------
    ?a : int
        A number for the calculations

    Output Parameters
    -----------------
    ?e : int
        The result

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner, '?a => ?e')

    def on_init(self) -> None:
        self.append_child(CreateRandomNumberAction, '=> ?b')
        self.append_child(AddTwoNumbersAction, '?a ?b => ?c')
        self.append_child(PrintNumberAction, '?c')
        self.append_child(CreateRandomNumberAction, '=> ?d')
        self.append_child(AddTwoNumbersAction, '?c ?d => ?e')
        self.append_child(PrintNumberAction, '?e')

Run the example

Start the Python interpreter and run the SimpleSequence2 node:

>>> import carebt
>>> from carebt.examples.simple_sequence import SimpleSequence2
>>> bt_runner = carebt.BehaviorTreeRunner()
>>> bt_runner.run(SimpleSequence2, '5 => ?x')
CreateRandomNumberAction: number = 2
AddTwoNumbersAction: calculating: 5 + 2 = 7
PrintNumberAction: number = 7
CreateRandomNumberAction: number = 2
AddTwoNumbersAction: calculating: 7 + 2 = 9
PrintNumberAction: number = 9

>>> bt_runner.run(SimpleSequence2, '7 => ?x')
CreateRandomNumberAction: number = 1
AddTwoNumbersAction: calculating: 7 + 1 = 8
PrintNumberAction: number = 8
CreateRandomNumberAction: number = 2
AddTwoNumbersAction: calculating: 8 + 2 = 10
PrintNumberAction: number = 10

Create the SimpleSequence3

The SimpleSequence3 shows another example how custom ActionNodes and custom SequenceNodes can be reused and how the parameters can be bound.

Add the following content to simple_sequence.py. Or use the provided file: simple_sequence.py

class SimpleSequence3(SequenceNode):
    """The `SimpleSequence3` example node.

    The `SimpleSequence3` shows another example sequence where the two sequences
    implemented above are reused.

    """

    def __init__(self, bt_runner):
        super().__init__(bt_runner)

    def on_init(self) -> None:
        self.append_child(SimpleSequence1, '=> ?x')
        self.append_child(PrintNumberAction, '?x')
        self.append_child(SimpleSequence2, '?x => ?y')
        self.append_child(PrintNumberAction, '?y')

Run the example

Start the Python interpreter and run the SimpleSequence3 node:

>>> import carebt
>>> from carebt.examples.simple_sequence import SimpleSequence3
>>> bt_runner = carebt.BehaviorTreeRunner()
>>> bt_runner.run(SimpleSequence3)
CreateRandomNumberAction: number = 5
CreateRandomNumberAction: number = 8
AddTwoNumbersAction: calculating: 5 + 8 = 13
PrintNumberAction: number = 13
PrintNumberAction: number = 13
CreateRandomNumberAction: number = 2
AddTwoNumbersAction: calculating: 13 + 2 = 15
PrintNumberAction: number = 15
CreateRandomNumberAction: number = 1
AddTwoNumbersAction: calculating: 15 + 1 = 16
PrintNumberAction: number = 16
PrintNumberAction: number = 16

>>> bt_runner.run(SimpleSequence3)
CreateRandomNumberAction: number = 1
CreateRandomNumberAction: number = 2
AddTwoNumbersAction: calculating: 1 + 2 = 3
PrintNumberAction: number = 3
PrintNumberAction: number = 3
CreateRandomNumberAction: number = 6
AddTwoNumbersAction: calculating: 3 + 6 = 9
PrintNumberAction: number = 9
CreateRandomNumberAction: number = 3
AddTwoNumbersAction: calculating: 9 + 3 = 12
PrintNumberAction: number = 12
PrintNumberAction: number = 12

Note

The SimpleSequence3 example shows how easily a behavior can be composed out of already existing sub-behaviors, while the individual sub-behaviors can still be executed and tested separately.