AI roaming reference

The components that make monsters wander, patrol, attack on sight and run home when pulled too far. For how to use it, see AI roaming.

VtRoaming

Component. Add it with Add Component → Vantage → AI → VtRoaming.

Wander, patrol and leash behaviour for monsters. Attached by VtUnit when the definition’s VtUnitDefinition.roamRadius is above 0, or by a VtMobSpawner that carries a VtPatrolRoute.

Inspector fields

Field	Type	Default	Range	Description
Roam Radius (`roamRadius`)	`float`	8	≥ 0	Radius around home the unit wanders within. 0 = no wandering (patrol routes still work).
Leash Radius (`leashRadius`)	`float`	25	≥ 0	Distance from home past which the unit drops aggro and runs back invulnerably. 0 = no leash.
Idle Min Seconds (`idleMinSeconds`)	`float`	2	≥ 0	Shortest pause between walks, in seconds.
Idle Max Seconds (`idleMaxSeconds`)	`float`	5	≥ 0	Longest pause between walks, in seconds.
Roam Speed Multiplier (`roamSpeedMultiplier`)	`float`	0.5	≥ 0.1	Move speed multiplier while wandering or patrolling.
Return Speed Multiplier (`returnSpeedMultiplier`)	`float`	2.5	≥ 0.1	Move speed multiplier while running home after a leash break.
Arrive Threshold (`arriveThreshold`)	`float`	0.5	≥ 0.1	Distance under which a destination counts as reached.
Patrol Route (`patrolRoute`)	VtPatrolRoute	None		Optional waypoint route. When set the unit walks it in order instead of wandering, and home follows along so the leash stays relative to the route. Usually assigned by a VtMobSpawner.

Scripting API

Member	Description
`VtRoaming.RoamState State { get; }`	Current state.
`Vector3 Home { get; }`	The position the leash and wandering are measured from. Captured at `Initialize`; moves along a patrol route; change it with `SetHome`.
`Vector3 CurrentDestination { get; }`	Where the unit is currently walking or returning to.
`VtPatrolRoute PatrolRoute { get; set; }`	Waypoint route to follow instead of wandering. Null wanders. Setting it restarts at the first waypoint.
`bool UsesMover { get; }`	True when a `VtTopDownClickToMove` sibling carries out the movement.
`event Action<VtRoaming.RoamState, VtRoaming.RoamState> OnStateChanged`	Fires on every state transition with (previous, next).
`void Initialize()`	Cache siblings, capture home, seed the first idle pause. Idempotent; public for the late-attach path.
`void SetHome(Vector3 newHome)`	Move the home position, for example after a teleport or respawn.
`void Tick(float deltaTime)`	Advance the state machine by `deltaTime` seconds. Authority-only.
`protected virtual void StepTowards(Vector3 destination, float speed, float deltaTime)`	Move the transform one step toward `destination` at `speed` units per second. Only used when no `VtTopDownClickToMove` sibling exists. The base version is a straight line on the ground plane; override it to route through your own movement.

VtHostileAi

Component. Add it with Add Component → Vantage → AI → VtHostileAi.

Makes a unit behave like a monster: it attacks hostile units that come inside its definition’s VtUnitDefinition.aggroRange, and it fights back whenever something else hands it a target (a threat table, a taunt, your own code calling VtCombatEngagement.SetTarget).

Inspector fields

Field	Type	Default	Range	Description
Scan Interval (`scanInterval`)	`float`	0.25	≥ 0.05	Seconds between scans for hostile units inside the definition’s Aggro Range while idle.
Line Of Sight Mask (`lineOfSightMask`)	`LayerMask`	Nothing		Layers that block line of sight. Leave empty to notice hostiles through walls.
Eye Height (`eyeHeight`)	`float`	1	≥ 0	Height above the unit’s position the sight check is cast from and to.

Scripting API

Member	Description
`event Action<IVtAttackable> OnTargetAcquired`	Fires when the scan picks a new target on sight. Not fired for targets handed in from outside (threat, taunt).
`void Initialize()`	Cache sibling components. Idempotent; public for the late-attach path.
`void Tick(float deltaTime)`	Advance by `deltaTime` seconds: keep the basic attack armed against the current target, or scan for one. Authority-only.
`IVtAttackable FindNearestHostile()`	The closest attackable unit of a hostile faction inside the definition’s aggro range, with line of sight when `lineOfSightMask` is set. Null when there is none or the aggro range is 0.

VtPatrolRoute

Component. Add it with Add Component → Vantage → AI → VtPatrolRoute.

An ordered list of waypoints a VtRoaming unit walks instead of wandering. Place it in the scene, drag waypoint transforms into waypoints, or leave the list empty and parent empty objects under it: children are used in hierarchy order. Assign the route on a VtMobSpawner or set VtRoaming.PatrolRoute from code.

Inspector fields

Field	Type	Default	Description
Waypoints (`waypoints`)	`Transform`[]	Empty	Waypoints in walking order. Leave empty to use this object’s children in hierarchy order.
Loop (`loop`)	`bool`	On	After the last waypoint continue at the first. Off walks the route back and forth.
Gizmo Color (`gizmoColor`)	`Color`	`#33CCFFE6`	Gizmo colour for the route in the Scene view.

Scripting API

Member	Description
`int Count { get; }`	Number of waypoints, explicit or from children.
`Vector3 GetPoint(int index)`	World position of waypoint `index`, clamped into range. Returns this object’s position when the route is empty.
`void Advance(ref int index, ref int direction)`	Step `index` to the next waypoint. `direction` is +1 or -1 and flips at the ends when `loop` is off.
`void SetWaypoints(Transform[] points)`	Replace the explicit waypoint list from code.

Enums

VtRoaming.RoamState

State machine values, readable for animation and debug overlays.

Value	Description
`Idle`	Waiting for the next walk.
`Walking`	Walking to a wander point or patrol waypoint.
`InCombat`	Chasing the engagement target.
`Returning`	Leash broken: invulnerable and running home.