Defines the behavior for all behavior tree nodes.

Every node in a behavior tree must implement this behavior to define how it responds to ticks and how it can be halted when necessary.

Node Types

There are three main categories of nodes:

1. Composite Nodes - Control the execution of multiple child nodes

   • Sequence: Execute children in order until one fails
   • Selector: Execute children in order until one succeeds

2. Decorator Nodes - Modify the behavior of a single child node

   • Inverter: Invert the child's success/failure status
   • Succeeder: Convert completion to success
   • Failer: Convert completion to failure
   • Repeat: Repeat the child a specified number of times

3. Leaf Nodes - Perform actual work or conditions

   • Action: Execute a Jido action
   • Wait: Pause execution for a duration
   • SetBlackboard: Write values into the tick blackboard

Implementation

When implementing a node, you define a struct to hold the node's state and implement the two required callbacks:

defmodule MyNode do
  @schema Zoi.struct(
    __MODULE__,
    %{
      my_data: Zoi.any(description: "Custom node data") |> Zoi.optional()
    },
    coerce: true
  )

  @type t :: unquote(Zoi.type_spec(@schema))
  @enforce_keys Zoi.Struct.enforce_keys(@schema)
  defstruct Zoi.Struct.struct_fields(@schema)

  def schema, do: @schema

  @behaviour Jido.BehaviorTree.Node

  @impl true
  def tick(node_state, tick) do
    # Your tick logic here
    {:success, updated_node_state}
  end

  @impl true
  def halt(node_state) do
    # Your halt logic here
    updated_node_state
  end
end

Telemetry

Behavior tree nodes emit telemetry events via Jido.Observe for observability. Events use the [:jido, :bt, :node, ...] namespace to align with core Jido telemetry.

Node Tick Events

• [:jido, :bt, :node, :tick, :start] - Node tick started
• [:jido, :bt, :node, :tick, :stop] - Node tick completed
• [:jido, :bt, :node, :tick, :exception] - Node tick raised an exception

Node Halt Events

• [:jido, :bt, :node, :halt, :start] - Node halt started
• [:jido, :bt, :node, :halt, :stop] - Node halt completed
• [:jido, :bt, :node, :halt, :exception] - Node halt raised an exception

Metadata

All events include the following metadata:

• :node - The node module being executed
• :sequence - The tick sequence number (for tick events)

When running as a Jido strategy, additional metadata is included from Tick.context:

• :agent_id - The agent's unique identifier
• :agent_module - The agent module name
• :strategy - The strategy module name

Measurements

• :duration - Execution time in nanoseconds (on :stop and :exception)
• :system_time - Start timestamp in nanoseconds (on :start)