Orders and control groups reference

The components that give orders to selected units and keep control groups, and the group and formation API. For how to use it, see Orders and control groups.

VtUnitOrders

Component. Add it with Add Component → Vantage → Orders → VtUnitOrders. Adds VtUnit automatically.

Lets players command a unit: move, attack-move, attack, hold position and stop. While it has no order the unit attacks hostile units that come inside its definition Aggro Range. Attached by VtUnit when the definition has VtUnitDefinition.takesOrders on; VtOrderInput gives the orders to the selected units.

Inspector fields

Field	Type	Default	Range	Description
Scan Interval (`scanInterval`)	`float`	0.25	≥ 0.05	Seconds between scans for hostile units while idle, attack-moving or holding.
Arrival Distance (`arrivalDistance`)	`float`	0.75	≥ 0.05	Planar distance to the destination that counts as arrived when the unit is not moving.

Scripting API

Member	Description
`VtOrderScheduler Scheduler { get; }`	The order logic. Read its state here; give orders through `Issue`.
`VtOrderKind Kind { get; }`	The order being carried out.
`Vector3 OrderPoint { get; }`	The destination or held position of the current order.
`IVtAttackable OrderTarget { get; }`	The target of the current attack order, or null.
`event Action<VtOrderKind> OnOrderChanged`	Fires when an order is given or ends, with the order now held. Fires on the authority.
`void Initialize()`	Find the sibling components and set up the order logic. Runs on its own when needed; safe to call more than once.
`bool Issue(VtOrderKind kind, Vector3 point, IVtAttackable target = null)`	Give order `kind`: `point` is the destination of a move or attack-move, `target` the target of an attack. On the authority the order starts at once; on a predicting client it is sent to the authority. Returns false when it was refused or this copy of the unit cannot give orders.
`void Tick(float deltaTime)`	Advance the order by `deltaTime` seconds. Authority only.

VtOrderInput

Component. Add it with Add Component → Vantage → Orders → VtOrderInput. Adds VtUnitSelection automatically.

RTS orders for the units a VtUnitSelection holds. Command (right-click by default) on the ground moves the selected units there in formation, Command on a hostile unit or a resource node attacks it, the attack-move key followed by Confirm Target (left-click by default) attack-moves, and the stop and hold keys do what they say. Only selected units of the selecting side that have VtUnitOrders take orders; other selected units are only shown. Which units a command attacks is VtFactionRules.CanAttackOnCommand.

Inspector fields

Raycasts

Field	Type	Default	Range	Description
Ground Mask (`groundMask`)	`LayerMask`	Everything		Layers a move order can land on.
Unit Mask (`unitMask`)	`LayerMask`	Everything		Layers the unit colliders are on, for attack orders.
Ray Distance (`rayDistance`)	`float`	500	≥ 1	Max raycast distance, in world units.

Input

Field	Type	Default	Description
Command Action (`commandAction`)	`InputActionReference`	None	Moves or attacks at the pointer, and cancels a started attack-move. Empty uses Command from the Vantage input actions, the right mouse button by default.
Confirm Target Action (`confirmTargetAction`)	`InputActionReference`	None	Picks the attack-move point or target. Empty uses Confirm Target, the left mouse button by default. When it shares a button with Command, confirming wins.
Attack Move Action (`attackMoveAction`)	`InputActionReference`	None	Starts an attack-move; the next Confirm Target press picks the point or the target. Empty uses Attack Move from the Vantage input actions, A by default.
Stop Action (`stopAction`)	`InputActionReference`	None	Stops the selected units. Empty uses Stop, S by default.
Hold Action (`holdAction`)	`InputActionReference`	None	Makes the selected units hold their position. Empty uses Hold Position, H by default.
Cancel Action (`cancelAction`)	`InputActionReference`	None	Cancels a started attack-move. Command cancels too. Empty uses Cancel, Esc by default.

Formation

Field	Type	Default	Range	Description
Formation Spacing (`formationSpacing`)	`float`	1.6	≥ 0.1	World units between formation slots.

Feedback

Field	Type	Default	Range	Description
Spawn Move Marker (`spawnMoveMarker`)	`bool`	On		Spawn a VtMoveMarker where a move or attack-move lands.

Scripting API

Member	Description
`bool IsTargetingAttackMove { get; }`	True while an attack-move waits for its Confirm Target press.
`bool BlocksPointerThisFrame { get; }`	True while an attack-move waits for its click and on the frame it ended, so that click does not also select.
`float FormationSpacing { get; set; }`	World units between formation slots.
`Func<Vector2, Ray> ScreenPointToRay { get; set; }`	Turns a screen position into the ray orders are raycast along. Null uses the main camera.
`event Action<VtOrderKind, int> OnOrderIssued`	Fires after an order went to the selected units, with the order and how many units took it.
`int GetCommandableUnits(List<VtUnit> results)`	Fill `results` with the selected units that take orders from this side: same faction as the selection viewer, alive, with an enabled `VtUnitOrders`. Returns the count.
`int OrderMove(Vector3 point)`	Move the selected units to `point` in formation. Returns how many took the order.
`int OrderAttackMove(Vector3 point)`	Attack-move the selected units to `point` in formation. Returns how many took the order.
`int OrderAttack(IVtAttackable target)`	Send the selected units at `target`. Returns how many took the order.
`int OrderStop()`	Stop the selected units. Returns how many took the order.
`int OrderHold()`	Make the selected units hold their position. Returns how many took the order.
`void BeginAttackMoveTargeting()`	Wait for a Confirm Target press that picks the attack-move point or target. Does nothing without commandable units.
`void CancelTargeting()`	Stop waiting for the attack-move click.
`int ConfirmAttackMove(Vector3 point, IVtAttackable hostile = null)`	Finish a started attack-move: attack `hostile` when given, otherwise attack-move to `point`. Returns how many units took the order, 0 when no attack-move was started.

VtControlGroups

Component. Add it with Add Component → Vantage → Selection → VtControlGroups. Adds VtUnitSelection automatically.

Control groups on the number keys for the sibling VtUnitSelection. Ctrl and a group key saves the selection as that group, Shift and a group key adds the selection to it, and the key alone selects the living units of the group. Pressing it twice quickly also moves the camera to them.

Inspector fields

Field	Type	Default	Range	Description
Group Actions (`groupActions`)	`InputActionReference`[]	10 entries		One action per group. With the Assign Modifier held it saves the selection, with the Additive Modifier it adds it, alone it selects the group. Empty entries use Control Group 1 to 10 from the Vantage input actions, keys 1 to 0 by default.
Assign Modifier Action (`assignModifierAction`)	`InputActionReference`	None		Held with a group action to save the selection as the group. Empty uses Assign Modifier, Ctrl by default.
Additive Modifier Action (`additiveModifierAction`)	`InputActionReference`	None		Held with a group action to add the selection to the group. Empty uses Additive Modifier, Shift by default.
Double Tap Seconds (`doubleTapSeconds`)	`float`	0.35	≥ 0.05	Seconds between two presses of a group key that also move the camera to the group.
Focus Camera On Double Tap (`focusCameraOnDoubleTap`)	`bool`	On		Move the camera to a group when its key is pressed twice quickly.

Scripting API

Member	Description
`VtControlGroupSet Groups { get; }`	The groups.
`int GroupCount { get; }`	How many groups there are.
`Action<Vector3> FocusCamera { get; set; }`	Moves the camera to a point. Null uses `VtTopDownCamera.FocusOn` on the main camera.
`event Action<int, bool> OnGroupRecalled`	Fires after a group was selected, with its index and whether the camera moved to it.
`InputAction GetGroupAction(int group)`	The action that selects `group`, for key labels. Null past the last group.
`void AssignSelection(int group)`	Save the current selection as `group`.
`void AddSelection(int group)`	Add the current selection to `group`.
`bool Recall(int group, double time)`	Select the living units of `group`. A second call for the same group within the double-tap time also moves the camera to them. `time` is in seconds. Returns false for an empty group, which leaves the selection as it was.
`static Vector3 Centre(IReadOnlyList<VtUnit> units)`	The average position of `units`, ignoring destroyed ones.

VtControlGroupSet

Class.

Numbered groups of units a player saves and calls back, such as groups 1 to 0 on the number keys. A unit can be in several groups. Destroyed units drop out when a group is read. Pure C#.

Scripting API

Member	Description
`int GroupCount { get; }`	Number of groups.
`event Action<int> OnGroupChanged`	Fires after a group changed, with its index.
`IReadOnlyList<VtUnit> Units(int group)`	The units in `group`, in the order they were added. Empty for an invalid index.
`bool Contains(int group, VtUnit unit)`	True when `unit` is in `group`.
`void Assign(int group, IEnumerable<VtUnit> units)`	Replace `group` with `units`, without nulls or duplicates.
`void Add(int group, IEnumerable<VtUnit> units)`	Add `units` to `group`, skipping units already in it.
`void Remove(VtUnit unit)`	Take `unit` out of every group.
`void Clear(int group)`	Empty `group`.

VtFormation

Static class.

Formation slots for group orders: a grid centred on the destination and turned to face the direction of travel, and a pass that sends each unit to a near free slot so paths cross less.

Scripting API

Member	Description
`static void GridSlots(int count, Vector3 center, Vector3 facing, float spacing, List<Vector3> results)`	Fill `results` with `count` points in a grid centred on `center`, `spacing` apart. Rows run across `facing`, front row first. One unit gets the centre itself.
`static void AssignNearest(IReadOnlyList<Vector3> positions, IReadOnlyList<Vector3> slots, int[] assignment)`	Give every unit a slot. Slots are filled in order, each by the nearest unit without one. `assignment` receives the slot index per unit, or -1 when there were fewer slots.

Enums

VtOrderKind

An order a unit with VtUnitOrders carries out.

Value	Description
`Idle`	No order. The unit attacks hostile units that come inside its aggro range.
`Move`	Walk to a point and ignore enemies on the way.
`AttackMove`	Walk to a point and fight every hostile unit met on the way.
`Attack`	Attack one target until it dies.
`HoldPosition`	Stay in place and attack only what is within attack range.
`Stop`	Stop moving and fighting, then go idle. Given as an order, never held.