spline.placement

Placement helpers layered on top of spline.core sampling. Use this to distribute instances along a path, generate fence-post transforms, or constrain an entity to a normalised progress value on a spline. Each returned placement carries position, forward, right, rotation, and the source t.

Exports

• Placement.distribute(path, count, opts?) -> { Placement } — count evenly spaced placements (in t).
• Placement.distributeBySpacing(path, spacing, opts?) -> { Placement } — placements at constant world-space spacing.
• Placement.fence(path, spacing, opts?) -> { Placement } — alias for distributeBySpacing with fence-shaped semantics.
• Placement.constrain(entityId, path, progress, opts?) -> Placement? — set an entity's local position/rotation to a spline progress value.
• Placement.midpoint(a, b) -> Vec3 — convenience midpoint helper for two vec3-shaped points.

Types:

• PlacementOpts = { up?: Vec3, verticalOffset?: number, lateralOffset?: number, easing?: ..., steps?: number, orientToPath?: boolean }
• Placement = { t: number, position: Vec3, forward: Vec3, right: Vec3, rotation: Quat }
• Quat = { x: number, y: number, z: number, w: number }

Usage

local Placement = require("@builtin::modules.spline.placement")

local posts = Placement.distributeBySpacing(path, 1.5, { lateralOffset = 0.6 })
for _, p in ipairs(posts) do
    local e = entity.spawn("post")
    e.localPosition = { p.position.x, p.position.y, p.position.z }
    e.localRotation = { p.rotation.x, p.rotation.y, p.rotation.z, p.rotation.w }
end

Placement.constrain(playerId, path, currentProgress)

Notes

• Default up vector is {x=0, y=1, z=0}. Override via opts.up for non-Y-up worlds.
• lateralOffset displaces the placement along the spline's right vector (perpendicular to forward, in the up plane).
• verticalOffset displaces along the up vector.
• constrain returns nil when the entity id is invalid; pass orientToPath = false to update position without touching rotation.