Lua Formation Follow

This documents the native formation-follow Lua helper for spawn scripts.

FormationFollow(...) lets one NPC follow another NPC's movement path in a configured formation. The function keeps the existing Lua script simple: pass the follower NPC, identify the leader, choose a formation pattern, then tune spacing and catch-up behavior.

Formation follow rebuilds are queued asynchronously at the zone level. The follower stores its configuration, resolves the leader when available, and applies the movement loop when the rebuild completes.

Completing the zone's initial spawn indexes preserves the active actors' scene identities, so formation requests made by their spawn scripts can finish after the zone loads. Removing or replacing an actor still invalidates work captured for its old scene.

Numeric spawn_id, location_id, and runtime_id references bind to the selected leader's allocation and zone publication after lookup, including while waiting for its movement path. A leader that has not loaded yet can resolve during the queued retry window. Once selected, a retired leader is not silently replaced by another spawn that reuses its ID; call FormationFollow again to select a new leader. The leader needs an authored or generated movement loop for the initial formation build.

After the initial build, behind uses the same live leader/trail tracking as the other formations. Its target is BackDistance * Slot along the leader's recent trail while moving. It slows or holds when ahead of its slot, suppresses catch-up when too close to an earlier behind follower, and stops when it reaches its slot behind a stopped leader. Spacing is a moving target with tolerance, not an exact fixed separation on every tick.

Automatic slots and column predecessor checks are separate for each leader/pattern. flank_left and flank_right followers can share the leader with behind followers without taking their column slots or becoming their column predecessors. Speed is the normal movement speed; live catch-up and spacing checks may temporarily raise, reduce, or stop movement.

FormationFollow

FormationFollow(NPC, Leader, Pattern, BackDistance, SideDistance[, Speed[, CatchupDistance[, MaxCatchupSpeed[, Slot[, LeaderRefType]]]]])

Return value: none. The call queues configuration/build work; it does not synchronously report that the follower is already moving.

Patterns

LeaderRefType

LeaderRefType is only needed when Leader is numeric.

When Leader is an actual spawn object, the function uses that spawn's runtime id and ignores LeaderRefType.

Examples

Follow A Leader Spawn Object

function spawn(NPC)
    local Leader = GetSpawn(NPC, 123456)
    if Leader ~= nil then
        FormationFollow(NPC, Leader, "behind", 4.0, 0.0, 2.0, 8.0, 5.0)
    end
end

Follow By Spawn Location Id

function spawn(NPC)
    FormationFollow(NPC, 430688, "inverse_v", 4.0, 2.0, 0, 8.0, 5.0, 0, "location_id")
end

This uses:

Explicit Slots

function spawn(NPC)
    FormationFollow(NPC, 430688, "behind", 3.0, 0.0, 2.0, 6.0, 5.0, 1, "location_id")
end

Use explicit slots when a script needs a predictable position. For behind, slot 1 is closest to the leader, slot 2 is behind slot 1, and so on. For inverse_v, odd slots go to one side and even slots go to the other side.

Mixed Behind And Flank Followers

Call each line for its own follower spawn. All three can auto-assign slot 1 because their patterns differ:

FormationFollow(BehindNPC, 133802494, "behind", 4.0, 0.0, 2.5, 8.0, 5.0, 0, "location_id")
FormationFollow(LeftNPC,   133802494, "flank_left", 4.0, 2.0, 2.5, 8.0, 5.0, 0, "location_id")
FormationFollow(RightNPC,  133802494, "flank_right", 4.0, 2.0, 2.5, 8.0, 5.0, 0, "location_id")

A second behind follower using automatic assignment takes the next column slot; the left and right followers do not change that assignment. The example uses normal speed 2.5 and catch-up speed 5.0; the live controller prevents an in-position follower from independently running ahead around the copied patrol loop.