Trails
Trail3D - the ECS component that lays a fading world-space tube behind a moving entity, simulated in compute, extruded in the vertex stage and drawn inside the transparency pipeline.
A trail records where an entity has been and draws a fading strip of geometry along that path. The engine has one trail component: Trail3D, which extrudes a volumetric tube around the path in world space, so it has real thickness from every viewing angle. It is a plain ECS component - attach it to an entity that has a Transform64, register Trail3DSystem, and the engine handles spawning, aging and drawing. Trail2D ships as a component but nothing renders it; see Trail2D renders nothing at the end of this page.
Trail3D
Trail3D (from src/engine/graphics/ecs/trail3d/Trail3D.js) lays down a tube of knots behind the entity. Each knot carries a parallel-transported tangent frame, so the tube’s cross-section ring stays smoothly oriented along the centre-line even through tight curves. The component is the trail’s description; its knots live on the GPU, where the system simulates and draws them.
import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js";
import Trail3D from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3D.js";
import { Trail3DSystem } from "@woosh/meep-engine/src/engine/graphics3/Trail3DSystem.js";
// Register the system once (at bootstrap), with the scene its entities are in
const scene = EngineHarness.shadeScene(engine);
config.addSystem(new Trail3DSystem(engine.graphics, scene));
// Attaching to an entity that already exists? Register the component type first.
ecd.registerComponentType(Trail3D);
const trail = new Trail3D();
trail.maxAge = 0.5; // knots live half a second
trail.width = 0.4; // tube diameter, world units
trail.color.set(1.0, 0.55, 0.15, 1);
ecd.addComponentToEntity(entity, trail);
Two import details: the system is a named export under src/engine/graphics3/ and its constructor takes the graphics facade and the scene, as ShadedGeometrySystem does; the component is a default export. There is no Trail3DSystem3 - write the unsuffixed Trail3DSystem.
The head follows announced transforms. A trail reads where its entity is from the entity’s row in the GPU scene, which a transform write reaches when it is announced. A translation written by hand moves the trail only once it ends with t64_announce_change(ecd, entity), exactly as for a mesh or a particle emitter; systems that announce their own writes (PhysicsSystem, PathFollowingSystem and the rest) need nothing extra.
Trail3D properties (all also settable through fromJSON):
| Property | Type | Default | Notes |
|---|---|---|---|
maxAge | number | 5 | Seconds a knot lives before it disappears; fade runs over this span. The knot count is taken from it when the system registers the trail |
width | number | 1 | Tube diameter. Written into the head knot every frame, so animating it tapers the tube |
radialSegments | number | 8 | Subdivisions around the tube, at least 3. Fixed when the system registers the trail - re-add the component to change it |
spawnMode | TrailSpawnMode | Time | When a new knot is committed (see below) |
spawnDistance | number | 1 | Distance between knots when spawnMode is Distance |
color | Color | white | RGB tints the whole tube, in linear colour and unbounded; alpha is the trail’s base opacity. Both are read every tick |
fade | AnimationCurve | TRAIL3D_FADE_LINEAR | Opacity over a knot’s life: time is age over maxAge (0 at birth, 1 when it disappears), and the value multiplies color.a |
offset | Vector3 | (0,0,0) | Offset from the entity to the trail head, in the entity’s local frame - it rides the entity’s rotation and scales with it |
warmup | boolean | true | A new trail fades in over its first maxAge seconds (see Warm-up) |
Two more fields are not part of the JSON: knots, a TrailKnots layout for a trail that is laid down whole (see Authored knots), null for a trail the entity draws; and clearCount, which clear() moves.
There is no change signal to send. Once a tick the system compares each component’s fields with what it last staged and restages the trails that differ, so a game writes trail.color or trail.width from code that has never heard of the system.
Three properties that do nothing
textureURL, depthWrite and lightingEnabled exist on the component. They read, they write, they round-trip through toJSON / fromJSON, and they have no effect on what you see.
A trail is drawn by one unlit pipeline whose vertex stage reads a knot’s position, frame and thickness and the trail’s colour. There is no per-trail material to hang a texture on, no per-trail depth-write switch, and no lighting variant of the shader. All three are accessors over a TubeXMaterialSpec the component carries as trail.material, lightingEnabled through Trail3DFlags.Lit. Nothing in the render path reads any of it: the spec is inert bookkeeping that keeps scene JSON round-tripping.
A trail that needs to read as lit matter rather than as an emitter is not something this component can do. Either accept the flat colour, or build the geometry yourself on the dynamic-mesh path.
How a trail reaches the screen
Trail3DSystem simulates every trail on the GPU and draws it inside the transparency pipeline, as an AVBOIT transparency channel. A trail composites order-independently against transparent meshes, particles, water and other trails, so a trail behind glass or smoke sits behind it by depth. It tests the opaque scene’s depth and never writes depth, both faces of the tube are drawn, and it takes the volumetric fog at its depth. Keep renderer.transparency_mode on ShadeTransparencyMode.AVBOIT (the default, see Frame features): the MBOIT path draws no transparency channels, trails included.
The CPU builds no geometry. What is the CPU’s: registering a trail with the scene’s GPUTrailSystem (src/shade/renderer/trails/GPUTrailSystem.js) - a record, a run of knots in the shared knot pool, the entity’s transform row - the once-a-tick comparison of each component’s fields, and moving the trails’ clock. A frame costs the CPU a comparison per trail, and an upload only for the trails whose fields changed.
Everything per knot is the GPU’s. Each frame a compute pass moves every head to its entity’s world matrix, commits a knot when one is due, carries the ring frame along the tangent and finds how many knots can still be visible. A pass per view then drops the segments whose two knots have both faded out or whose bounds miss the frustum. The vertex stage extrudes what is left: each ring vertex sits at cos(angle) * normal + sin(angle) * binormal, half the knot’s thickness out from its centre. All trails with the same radialSegments share one indexed indirect draw in each pass, a segment an instance.
A knot stores when it was committed, not how old it is, so nothing rewrites a knot as it ages: a trail that has stopped fades out without further writes, and its faded segments are culled before they reach the rasterizer.
Time is the simulation’s. The trails’ clock advances by the delta Trail3DSystem.update is given, so a paused game holds its trails still. The head is read when a frame is drawn: a new trail’s knots start where its entity stands in the first frame drawn after the component is added.
Knot count
The system sizes the tube from maxAge when the trail is registered: 60 knots per second of life, clamped to between 2 and 1024 (trail_knot_count, from src/engine/graphics/ecs/trail3d/trail_knot_count.js). A 0.5 s trail gets 30 knots, a 3 s trail 180. Past roughly 17 s the cap bites, and a longer maxAge buys duration rather than detail - the same 1024 knots are simply spread over more time.
The count is fixed from then on. Changing maxAge on a live trail moves the fade and how often a knot is laid down, not the length of the ring; re-add the component for a trail that should be resized.
Spawn modes
TrailSpawnMode (from src/engine/graphics/trail/TrailSpawnMode.js) controls when the head commits a new knot:
| Mode | Knots are spaced evenly in | Behaviour |
|---|---|---|
Time (default) | time | A knot every maxAge / knotCount seconds. A fast emitter draws a long trail, a slow one a short trail; both last maxAge seconds |
Distance | space | A knot every spawnDistance world units, regardless of speed - uniform geometry with no stretching under acceleration |
Either way a knot is only committed when the head has actually moved, so a stationary emitter does not burn through its knots, and at most one knot is committed per drawn frame.
Clearing Trail3DFlags.Spawning (trail.clearFlag(Trail3DFlags.Spawning), from src/engine/graphics/ecs/trail3d/Trail3DFlags.js) stops the head following the entity: the trail stays where the last frame drew it and fades out.
Colour, opacity and fading
color belongs to the trail, not to its knots. RGB tints the whole tube and alpha is the base opacity that the age fade scales, so writing either on a live trail changes the entire tube from the next frame. The colour is linear and unbounded: values above 1 are how a trail is made brighter.
The per-knot fade is trail.fade, an AnimationCurve evaluated at each knot’s age over maxAge. Every trail starts on TRAIL3D_FADE_LINEAR (from src/engine/graphics/ecs/trail3d/TRAIL3D_FADE_LINEAR.js), a straight line from full opacity at birth to none at maxAge. That one instance is shared by every default trail and frozen, so editing it in place throws: assign a curve of your own, or start from its clone().
import { AnimationCurve } from "@woosh/meep-engine/src/engine/animation/curve/AnimationCurve.js";
import { Keyframe } from "@woosh/meep-engine/src/engine/animation/curve/Keyframe.js";
// hold full opacity for the first half of the knot's life, then fall away
trail.fade = AnimationCurve.from([
Keyframe.from(0, 1),
Keyframe.from(0.5, 1),
Keyframe.from(1, 0),
]);
The opacity is the tube’s as seen. The tube is a closed hull drawn from both sides, so a line of sight crosses two faces; the vertex stage gives each face half the optical depth, 1 - √(1 - α), and the two together cover exactly α. A curve that overshoots 0..1 is clamped first.
To gate a trail on a condition, animating width usually reads better than dropping opacity, because width is written per head knot: the tube already on screen keeps its thickness and the new end tapers away to nothing, instead of the whole streak dimming at once.
// e.g. show the trail only at speed
const target = speed > 17 ? 0.55 : 0;
trail.width += (target - trail.width) * Math.min(1, dt * 8);
Warm-up
With warmup on, the default, a new trail fades in: while the trail is t seconds old its head knot is born maxAge - t old, so the stretch laid down first is the faintest and the trail reaches its full look after its first maxAge seconds. Set trail.warmup = false for a trail that must be fully visible from its first frame, a tracer.
Teleporting the emitter
Moving an entity discontinuously (respawn, kickoff reset) would otherwise draw a streak from the old position to the new one. Call trail.clear() on teleport: at the next frame every knot expires and collapses onto the head where the entity stands, so no segment can bridge the two. The trail keeps its birth, so its warm-up does not run again.
Beams: a trail that is born whole
A normal trail draws itself by travelling. A beam does not travel - it leaves its source and arrives at its target inside one frame - so there is nothing to lay it down with. make_gradient_stroke builds a Trail3D that already has its whole shape: a stroke between two world points that only ages.
import { make_gradient_stroke } from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/make_gradient_stroke.js";
const beam = make_gradient_stroke({
from: muzzlePosition, // Vector3, world space
to: targetPosition, // Vector3, must not coincide with `from`
color: 0xffb02e, // packed RGB
thickness: 0.15, // world units
duration: 0.35, // seconds to fade out completely
age_from: 0.6, // the source end is born 60% through its life
age_to: 0,
texture: "" // asserted to be a string, but inert - see above
});
ecd.addComponentToEntity(entity, beam);
The gradient is nothing more than the two ends’ starting ages: the end seeded older thins out first, so a stroke whose source end is born most of the way through its life reads as retracting towards its target. age_from and age_to are fractions of duration and are asserted to be in [0,1].
make_gradient_stroke clears Trail3DFlags.Spawning for you, which is what stops the per-frame update dragging the head onto the entity and growing a tail towards it. The entity still needs a Transform64 - that is Trail3DSystem’s dependency - but the stroke does not follow it.
Authored knots
A stroke is the two-knot case of something more general. trail.knots takes a TrailKnots (from src/engine/graphics/trail/TrailKnots.js): knots laid down whole by the author - a stroke, a helix, an arc - instead of by an entity’s travel. The knots never move; they only age, and fade by the trail’s curve as they do.
import { TrailKnots } from "@woosh/meep-engine/src/engine/graphics/trail/TrailKnots.js";
import { Trail3DFlags } from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3DFlags.js";
const knots = new TrailKnots();
knots.setCount(count); // at least 2
for (let i = 0; i < count; i++) {
knots.setKnot(
i,
x, y, z, // world position
nx, ny, nz, // ring frame's first axis, unit
bx, by, bz, // second axis, unit, orthogonal to the first and to the tube's direction
thickness, // tube diameter at this knot
age // seconds the knot is born having lived
);
}
trail.knots = knots;
trail.clearFlag(Trail3DFlags.Spawning); // the shape is authored; the head must not follow the entity
The layout is uploaded when the system registers the trail and again whenever knots.version moves, which every setCount and setKnot does. An authored trail has as many knots as its layout, whatever its maxAge; a replaced layout brings its own count. seed_trail_stroke(trail, from, to, age_from, age_to) (from src/engine/graphics/ecs/trail3d/seed_trail_stroke.js) writes the straight two-knot layout make_gradient_stroke uses.
Live example
A sphere flying a figure-eight with a Trail3D behind it - drag to orbit, scroll to zoom:
Source
import { EngineHarness } from "@woosh/meep-engine/src/engine/EngineHarness.js";
import Entity from "@woosh/meep-engine/src/engine/ecs/Entity.js";
import { Transform64 } from "@woosh/meep-engine/src/engine/ecs/transform/Transform64.js";
import { t64_announce_change } from "@woosh/meep-engine/src/engine/ecs/transform/t64_announce_change.js";
import { ShadedGeometry } from "@woosh/meep-engine/src/engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
import { ShadedGeometrySystem } from "@woosh/meep-engine/src/engine/graphics3/ShadedGeometrySystem.js";
import Trail3D from "@woosh/meep-engine/src/engine/graphics/ecs/trail3d/Trail3D.js";
import { Trail3DSystem } from "@woosh/meep-engine/src/engine/graphics3/Trail3DSystem.js";
import { make_octahedron_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/primitives/make_octahedron_geometry.js";
import { meshlet_geometry_build_from_geometry } from "@woosh/meep-engine/src/shade/renderer/geometry/meshlet_geometry_build_from_geometry.js";
import { StandardShadeMaterial } from "@woosh/meep-engine/src/shade/renderer/material/StandardShadeMaterial.js";
import { Color } from "@woosh/meep-engine/src/core/color/Color.js";
import Vector3 from "@woosh/meep-engine/src/core/geom/Vector3.js";
const engine = await EngineHarness.bootstrap({
configuration: (config, engine) => {
const scene = EngineHarness.shadeScene(engine);
config.addSystem(new ShadedGeometrySystem(engine.graphics, scene));
config.addSystem(new Trail3DSystem(engine.graphics, scene));
},
});
await EngineHarness.buildBasics({
engine,
enableTerrain: false,
enableWater: false,
enableLights: true,
enableShadows: false,
focus: new Vector3(0, 0, 0),
distance: 7,
pitch: 0.5,
yaw: 0.3,
showFps: false,
});
const ecd = engine.entityManager.dataset;
// The emitter: a small bright sphere - a subdivided octahedron, every vertex
// of it landing on the radius.
const sphereGeometry = meshlet_geometry_build_from_geometry(make_octahedron_geometry(0.22, 3));
const sphereMaterial = new StandardShadeMaterial();
sphereMaterial.diffuse_color.copy(Color.from_sRGB_to_linear(Color.parse("#ffb02e")));
const mesh = ShadedGeometry.from(sphereGeometry, sphereMaterial);
// The trail: a 1.2 s orange tube, ~0.3 units thick. 1.2 s of life is 72 knots.
const trail = new Trail3D();
trail.maxAge = 1.2;
trail.width = 0.3;
trail.color.set(1.0, 0.55, 0.15, 1);
const t = new Transform64();
t.setTranslation(2.2, 0, 0);
// Entity.build registers the component types it carries, so Trail3D needs no
// explicit registerComponentType here.
const entity = new Entity()
.add(t)
.add(mesh)
.add(trail)
.build(ecd);
// Fly a figure-eight. The trail's head and the sphere both follow the transform
// as the scene holds it, which a translation written by hand reaches only once
// it is announced - so the write ends with an announcement. Without it neither
// the tube nor the ball moves.
const start = performance.now();
engine.graphics.on.preRender.add(() => {
const s = (performance.now() - start) / 1000;
t.setTranslation(
Math.sin(s * 1.7) * 2.2,
Math.sin(s * 3.4) * 0.8,
Math.cos(s * 1.7) * 2.2,
);
t64_announce_change(ecd, entity);
});Trail2D renders nothing
Trail2D (src/engine/graphics/ecs/trail2d/Trail2D.js) ships as a component and serializes, and a few utilities reference it. Nothing draws it. There is no Trail2DSystem and no screen-facing ribbon renderer. A Trail2D attached to an entity is inert data.
What to use, depending on what the ribbon is for:
- A beam or a streak:
make_gradient_stroke, above, which produces aTrail3D. - A trail behind a moving thing:
Trail3D, the only trail the engine draws. - A camera-facing ribbon: build it yourself on the dynamic-mesh path - a
Geometryyou rewrite each frame inside aDynamicMesh, drawn by a render extension of yours. The screen-facing expansion is yours to write, since no shader does it.
See also
- Effects - the dynamic-mesh path, plus decals, outlines and camera shake
- Particles & VFX - GPU simulations authored as node graphs with ParticleEffect
- Frame features - the transparency modes
- Rendering overview - what the renderer is and how ECS systems bind to it