PathFollower

Moves its entity along a path at a constant speed in metres per second, and turns it to face the way it moves: a train or tram on its track, a patrol on its route, a boat down a river, a camera dolly, a ghost car on a racing line, a creep walking a tower-defence lane.

The path is any of:

• a list of points (points): straight lines between them, or a smooth Catmull-Rom curve through them with smooth = true;
• a spline from @builtin::modules.spline (follow(spline.new(...)) takes its points, its mode and whether it is closed);
• a route or a lane loop from @builtin::modules.pathNetwork (follow(net:route(a, b)), follow(net:lanePath(ids, { closed = true }), { mode = "loop" })).

Speed is constant along the curve whatever the spacing of the points, because the path is measured by arc length (spline.measure / spline.atDistance).

Fields

Field	Default	Meaning
points	{}	The points the path runs through, in order.
smooth	false	A smooth curve through the points rather than straight lines.
closed	false	The path joins its last point back to its first.
speed	5	Metres per second along the path; negative runs it backward.
distance	0	How far along the path the entity is, in metres. Set it to place the entity.
mode	"loop"	At the end: "loop" starts again, "pingPong" turns back, "once" stops (and sets playing false).
orient	true	Turn the entity to face its direction of travel (its -Z forward), pitching with the slope.
height	0	Metres above the path the entity rides.
playing	true	Whether it moves.

The follower sets the entity's transform each frame, so it drives an entity with no dynamic body: a kinematic train, a prop, a camera rig. A car driven by physics follows a path by steering toward net:lookAhead(...) instead (see the pathNetwork module).

Methods

Method
:follow(path, opts?)	Follow a path from its start; opts sets speed, mode, smooth, closed, distance, height, orient with it. Answers the path's length.
:length()	The length of the path being followed, in metres.

local spline = require("@builtin::modules.spline")
local tram = entity.spawn("tram")
tram.component.add("Model", { model = "@builtin::meshes.cube" })
tram.component.add("PathFollower", { speed = 8 })
tram.component.get("PathFollower"):follow(spline.new({
    { 0, 0, 0 }, { 60, 0, 20 }, { 120, 0, 0 }, { 60, 0, -40 },
}, { mode = "catmullRom", closed = true }))