BehaviorTreeInstance

Remarks

A step is not a traversal. A classic behaviour tree walks from the root every frame. This one keeps the active node and does nothing at all when nothing has changed: the active task ticks, active services tick if their interval has elapsed, and pending aborts are serviced. An agent walking across a courtyard costs one MoveTo.Tick and a service every 0.4 s — which is the measurable claim doc 37 § D7 makes, and BehaviorTreeCostTests checks it both ways in one test.

⚠ An abort never happens inside a tick. A blackboard write during a task's own tick is the ordinary case — tasks write their results — and acting on it there would tear down the state of the thing currently executing. A notification therefore only sets a bit; the tree works out what that means at the top of the next step, before any node updates. The cost is stated rather than hidden: a condition that goes false during a task's tick takes effect at the start of the next tick.

⚠ Observers are registered once, on the union of every key any observing decorator reads, and not per branch. Registering per branch is what Unreal does and it buys nothing here, because the scope test — is the decorator's parent composite on the active path, and is the active node inside or after its subtree — is a pair of integer comparisons made when the change is resolved. Paying registration churn on every branch change to save setting a bit would be the wrong way round.

This is the one managed object per agent. Everything else — every node's state, every decorator's, every service's timer — is a window into the block, so a thousand agents on one tree is a thousand blocks sized at load with nothing allocated in a step.

Fields and properties (11)

• public const int MaximumTransitionsPerStep

  How many node transitions one step may make before it is called a runaway.

• public BehaviorTreeTemplate Template

  The tree being run.

• public AgentMemoryHandle Handle

  Its state block.

• public int ActiveNode

  The running task's node index, or -1.

• public int LastTransitions

  How many nodes the last step entered or left.

• public bool Overran

  Whether the last step ran out of transitions before anything settled.

• public ActionStatus LastResult

  What the tree returned the last time it finished.

• public int Completions

  How many times it has run to completion.

• public AiBreakpoints? Breakpoints

  Where a step stops, when a debugger has set any. AiSystem hands this over.

• public bool Trace

  Whether every node's last result is remembered, so an editor can tint the tree by it.

• public bool Halted

  Whether a breakpoint has stopped this agent. A stopped tree does nothing at all.

Methods (15)

• public BehaviorTreeInstance(BehaviorTreeTemplate template, AgentMemoryPool memory)

  Creates an instance of a template.

• public ActionStatus? LastResultOf(int node)

  What a node returned the last time it finished, while Trace was on.

• public void Resume()

  Lets a stopped agent carry on from where it is.

• public bool DecoratorPassed(int slot)

  What a decorator answered the last time anything asked it.

• public void Reset()

  Puts the tree back to never having run, without telling anything it was interrupted.

• public float TagCooldownRemaining(Symbol tag, float now)

  How long is left on a named cooldown, in seconds.

• public void StartTagCooldown(Symbol tag, float until)

  Starts a named cooldown.

• public ActionStatus Step(in AgentContext agent, float delta)

  Runs the tree for one of this agent's turns.

• public void Abort(in AgentContext agent)

  Stops whatever is running and tells each part it was interrupted.

• public void Release(in AgentContext agent)

  Gives the memory block and every nested instance back.

• public void OnBlackboardChanged(Blackboard blackboard, BlackboardKey key)
• public BehaviorTreeInstance? Nested(int node, BehaviorTreeTemplate? child, in AgentContext agent)

  The nested instance a dynamic-subtree task owns, creating it if it must.

• public Span<byte> StateOf(int node)

  One node's state, for a task, the debugger and a test.

• public int ActivePath(Span<int> path)

  The path from the root to the active node, root first.

• public void Record(in AgentContext agent, AgentDebugRecorder recorder)

  Records what the tree is doing, in the one shape all three planners fill.

Used by (25)

• AgentContextVixen.Ai
• AiBreakpointTestsVixen.Ai.Tests
• AiBreakpointsVixen.Ai
• AiSnapshotsVixen.Ai
• AiSystemVixen.Ai
• AiSystemTreeTestsVixen.Ai.Tests
• BehaviorContextVixen.Ai
• BehaviorTreeAbortOrderingTestsVixen.Ai.Tests
• BehaviorTreeAbortTestsVixen.Ai.Tests
• BehaviorTreeCompositeTestsVixen.Ai.Tests
• BehaviorTreeCostTestsVixen.Ai.Tests
• BehaviorTreeDecoratorTestsVixen.Ai.Tests
• BehaviorTreeDeterminismTestsVixen.Ai.Tests
• BehaviorTreeServiceTestsVixen.Ai.Tests
• BehaviorTreeTaskTestsVixen.Ai.Tests
• CompileStateVixen.Ai
• FleetVixen.Ai.Tests
• RunQueryNodeTestsVixen.Ai.Nodes.Tests
• RunSubtreeDynamicTaskVixen.Ai
• SetTagCooldownDecoratorVixen.Ai
• TagCooldownDecoratorVixen.Ai
• TreeHarnessVixen.Ai.Tests
• AgentDebugModelVixen.Editor.Ai
• BehaviorTreeProjectionVixen.Editor.Ai
• LiveTreeCanvasTestsVixen.Editor.AssetEditors.Tests