Jido.BehaviorTree.Tick (Jido Behavior Tree v1.0.0)

Represents a single execution cycle (tick) of a behavior tree.

A tick contains the context needed for a single traversal of the behavior tree, including the shared blackboard, timing information, and a sequence number for tracking execution order.

Ticks are immutable and are passed down through the tree during execution, allowing nodes to access shared state and timing information.

Summary

Types

t()

A single execution cycle of a behavior tree

Functions

append_directives(tick, new_directives)

Appends directives to the tick's directive list.

apply_agent_update(tick, agent, directives)

Updates both agent and appends directives in one call.

elapsed_time(tick)

Gets the elapsed time since the tick was created.

get(tick, key, default \\ nil)

Gets a value from the tick's blackboard.

increment_sequence(tick)

Increments the sequence number in the tick.

new(blackboard \\ Blackboard.new())

Creates a new tick with the given blackboard.

new(blackboard, timestamp, sequence)

Creates a new tick with explicit parameters.

new_with_context(blackboard, agent, directives \\ [], context \\ %{})

Creates a new tick with Jido agent context for strategy integration.

put(tick, key, value)

Sets a value in the tick's blackboard, returning an updated tick.

schema()

Returns the Zoi schema for this module

timed_out?(tick, timeout_ms)

Checks if the tick has exceeded a timeout.

update(tick, key, initial, fun)

Updates a value in the tick's blackboard using a function.

update_agent(tick, agent)

Updates the agent in the tick.

update_blackboard(tick, blackboard)

Updates the blackboard in the tick.

Types

t()

@type t() :: %Jido.BehaviorTree.Tick{
  agent: nil | any(),
  blackboard: any(),
  context: any(),
  directives: [any()],
  sequence: integer(),
  timestamp: any()
}

A single execution cycle of a behavior tree

Functions

append_directives(tick, new_directives)

@spec append_directives(t(), list()) :: t()

Appends directives to the tick's directive list.

Used by Action nodes to accumulate directives from Jido Effects.

apply_agent_update(tick, agent, directives)

@spec apply_agent_update(t(), term(), list()) :: t()

Updates both agent and appends directives in one call.

Convenience function for Action nodes applying Jido Effects.

elapsed_time(tick)

@spec elapsed_time(t()) :: integer()

Gets the elapsed time since the tick was created.

Examples

iex> tick = Jido.BehaviorTree.Tick.new()
iex> Process.sleep(10)
iex> elapsed = Jido.BehaviorTree.Tick.elapsed_time(tick)
iex> elapsed > 0
true

get(tick, key, default \\ nil)

@spec get(t(), term(), term()) :: term()

Gets a value from the tick's blackboard.

Examples

iex> bb = Jido.BehaviorTree.Blackboard.new(%{user_id: 123})
iex> tick = Jido.BehaviorTree.Tick.new(bb)
iex> Jido.BehaviorTree.Tick.get(tick, :user_id)
123

increment_sequence(tick)

@spec increment_sequence(t()) :: t()

Increments the sequence number in the tick.

Examples

iex> tick = Jido.BehaviorTree.Tick.new()
iex> updated_tick = Jido.BehaviorTree.Tick.increment_sequence(tick)
iex> updated_tick.sequence
1

new(blackboard \\ Blackboard.new())

@spec new(Jido.BehaviorTree.Blackboard.t()) :: t()

Creates a new tick with the given blackboard.

The timestamp is set to the current time and sequence starts at 0.

Examples

iex> bb = Jido.BehaviorTree.Blackboard.new(%{user_id: 123})
iex> tick = Jido.BehaviorTree.Tick.new(bb)
%Jido.BehaviorTree.Tick{blackboard: bb, sequence: 0}

new(blackboard, timestamp, sequence)

@spec new(Jido.BehaviorTree.Blackboard.t(), DateTime.t(), non_neg_integer()) :: t()

Creates a new tick with explicit parameters.

Examples

iex> bb = Jido.BehaviorTree.Blackboard.new()
iex> now = DateTime.utc_now()
iex> tick = Jido.BehaviorTree.Tick.new(bb, now, 5)
%Jido.BehaviorTree.Tick{blackboard: bb, timestamp: now, sequence: 5}

new_with_context(blackboard, agent, directives \\ [], context \\ %{})

@spec new_with_context(Jido.BehaviorTree.Blackboard.t(), term(), list(), map()) :: t()

Creates a new tick with Jido agent context for strategy integration.

This constructor is used by Jido.Agent.Strategy.BehaviorTree to pass agent state and execution context through the tree during traversal.

Parameters

blackboard - The shared blackboard
agent - The current Jido agent struct
directives - Initial list of directives (usually empty)
context - Strategy execution context

Examples

tick = Tick.new_with_context(blackboard, agent, [], %{strategy_opts: opts})

put(tick, key, value)

@spec put(t(), term(), term()) :: t()

Sets a value in the tick's blackboard, returning an updated tick.

Examples

iex> tick = Jido.BehaviorTree.Tick.new()
iex> updated_tick = Jido.BehaviorTree.Tick.put(tick, :result, "success")
iex> Jido.BehaviorTree.Tick.get(updated_tick, :result)
"success"

schema()

Returns the Zoi schema for this module

timed_out?(tick, timeout_ms)

@spec timed_out?(t(), non_neg_integer()) :: boolean()

Checks if the tick has exceeded a timeout.

Examples

iex> tick = Jido.BehaviorTree.Tick.new()
iex> Jido.BehaviorTree.Tick.timed_out?(tick, 1000)
false

update(tick, key, initial, fun)

@spec update(t(), term(), term(), (term() -> term())) :: t()

Updates a value in the tick's blackboard using a function.

Examples

iex> bb = Jido.BehaviorTree.Blackboard.new(%{counter: 5})
iex> tick = Jido.BehaviorTree.Tick.new(bb)
iex> updated_tick = Jido.BehaviorTree.Tick.update(tick, :counter, 0, &(&1 + 1))
iex> Jido.BehaviorTree.Tick.get(updated_tick, :counter)
6

update_agent(tick, agent)

@spec update_agent(t(), term()) :: t()

Updates the agent in the tick.

Used by Action nodes to update agent state after executing Jido actions.

update_blackboard(tick, blackboard)

@spec update_blackboard(t(), Jido.BehaviorTree.Blackboard.t()) :: t()

Updates the blackboard in the tick.

Examples

iex> tick = Jido.BehaviorTree.Tick.new()
iex> new_bb = Jido.BehaviorTree.Blackboard.put(tick.blackboard, :result, "success")
iex> updated_tick = Jido.BehaviorTree.Tick.update_blackboard(tick, new_bb)
iex> Jido.BehaviorTree.Blackboard.get(updated_tick.blackboard, :result)
"success"