Nodes over the world

Vixen.Ai.Nodes is the set of behaviour-tree nodes that touch the rest of the engine: walking a navmesh, turning, patrolling a route, asking whether a path exists, playing an animation state and making a sound.

It is a separate assembly with the widest reference list in Core/ — navigation, animation and audio at once — and that is safe for exactly one reason: nothing depends on it. A game links it if it wants the nodes, and a game that wants behaviour trees over its own movement code does not.

The half of a behaviour tree that is not decision-making. A Selector and a Blackboard decorator are the same in every game ever shipped; "walk over there" is the same in most of them, and this is where that lives so that a project does not write MoveToTask for the fourth time.

You do not want these for anything with a rule in it — a task that casts an ability, applies a status effect or checks a gameplay tag names a game's definitions and belongs to the game.

Each node reads and writes components the entity already carries, and fails rather than adding them. A tree step happens inside a chunk walk, and a structural change there invalidates every span the walk is holding — so a guard that can walk is authored with a NavigationAgent, and one that cannot is a bug worth seeing.

A movement node takes one key and does not care whether it holds a Vector3 or an Entity.

⚠ An entity target follows its entity; a position target does not. That is the difference between chasing somebody and going to where they were — and it is exactly the pair perception's default binding writes, so MoveTo(target) chases while MoveTo(seen) searches.

One .vxbt runs every guard in the game; the corridor each of them walks is a PatrolRoute placed in the level editor. Putting the points on the task would mean a behaviour tree per patrol route.

⚠ Only PatrolMode.Forward ever succeeds. A loop and a ping-pong have no end, so they stay Running for ever and are meant to be interrupted — by a decorator observing a perception key, which is the whole shape of a patrolling guard.

⚠ A patrol starts from the nearest point, not the first. A guard that respawns mid-route otherwise walks back to the start of it through whatever is in the way.

MoveTo and Patrol both stop the agent when they are aborted. An agent that kept walking to a destination its tree has forgotten about is the classic behaviour-tree bug — a guard that chases you while playing its idle — and it happens whenever a higher-priority branch takes over.

DoesPathExist has three settings, cheapest first:

⚠ There is no hierarchical test, and Budgeted is what stands in for one. Unreal's hierarchical query reads a coarse graph baked beside the mesh; Vixen bakes no such graph, and a second navigation structure kept in step with the first is a bad trade for one decorator. A budgeted search is wrong only in the direction that makes an agent give up rather than walk into a dead end.

⚠ It re-tests when its key changes, not when the world does. A door closing writes no blackboard key, so a branch already running keeps running until its MoveTo reports that the crowd failed. The decorator answers "is it worth starting"; the task answers "did it work".

AiFocus is one place everything downstream reads — a rotation task, an aim offset, a head-look constraint and a dialogue camera all want "what is this character looking at". DefaultFocus keeps it pointed at a key, and RotateToward with no key falls through to it.

⚠ The service clears the focus when the key is unset, and that is the half people leave out. A focus nobody cleared is a guard that keeps staring at where an enemy was after it has forgotten about it.

⚠ A focus is not saved, and cannot be. AiFocus.Target is an Entity, and an entity id is a dense, reused slot in one running process — written into a scene it names a different entity on the way back, or nothing. So AiFocus carries [Component] alone: no level places one, and a loaded world starts with no focus until the tree runs and chooses again. PatrolRoute is the placeable component here, because a route is a property of the level rather than of the moment.

Registering the nodes so a .vxbt can name them — the query and the sounds are the two things a schema cannot carry:

A guard that patrols until it sees something, chases while the sighting is fresh, and goes back to its route when it is not — which is P4's exit criterion as a file:

⚠ "Gives up" is one decorator over one float. No timer, no second branch holding a remembered position, and nothing in the tree that knows what a sense is: the age of the stimulus crosses half a second, the key's observers fire, and the branch is aborted.

• Perception — where target, seen and age come from.
• Behaviour trees — what an abort is, and why the decorator above interrupts.
• Authoring a behaviour tree — the editor these nodes appear in, and the factories that let an assembly contribute nodes.