trails.module

The point ring a trail is threaded along, and the ribbon built over it.

newPath{ lifetime, minDistance, maxPoints } opens a path. push(path, x, y, z, now) records the head position when it has travelled minDistance since the last point, and answers whether it recorded one. expire(path, now) drops what has outlived lifetime.

ribbon(path, opts) builds the surface: two vertices per point, offset either side of the direction of travel, joined into a strip. It returns flat positions / normals / uvs / colors / indices — the shape renderer.mesh.create takes — and nil under two points, which is no surface.

local geo = Trails.ribbon(path, {
    now = getTime(),
    widthHead = 0.3, widthTail = 0,
    colorHead = { 1, 0.9, 0.4 }, colorTail = { 1, 0.2, 0 },
    alphaHead = 1, alphaTail = 0,
    orientation = "camera",       -- or "fixed", about `up`
    cameraPosition = eye,
})

ribbon is pure — the same points, camera and settings give the same arrays — so a trail's geometry can be checked without a scene.

register / unregister / pathOf track paths by entity id, and stats() reports how many trails are live and how many points they hold between them.