Timelines
An effect is a list of tracks laid out on a timeline, plus events at moments in time.
{ "duration": 4, "loop": false, "params": { "color": "#ff3b1f", "radius": 2 }, "tracks": [ ... ], "events": [ ... ]}Tracks
Section titled “Tracks”Every track has these fields:
| Field | Meaning |
|---|---|
type |
What it draws: particles, trail, tendrils, beam, lightning, ring, mesh, decal, model, screen or effect |
start, end |
When it runs, in seconds. end defaults to the end of the effect |
at |
Where it sits: an attachment |
material |
How it is shaded: a material |
name |
Optional, shows up in error messages |
Inside a track, t runs from 0 to 1 between start and end, so a curve over t stretches with the track.
Particles get their own t over their life.
Attachments
Section titled “Attachments”"at": { "bone": ["right_arm:tip", "right_arm"], "offset": [0, 0.1, 0.2], "align": "head", "follow": true }Offsets are in blocks, in the anchor’s frame: x to the right, y up, z forward. align picks the frame: the entity’s
body, its head (where it looks), the world axes, the camera, or bone, which turns with the bone it is attached to as
the model animates. With bone, y runs along the bone toward its parent, so an arm’s y points up the arm to the
shoulder. follow: false leaves the track where it started.
On GeckoLib models, bone names are the geo file’s bones, and its locators work as bone names too, so a trail can
follow the tip of an animated blade:
{ "type": "trail", "at": { "bone": "blade_tip" }, "length": 0.35, "width": 0.3 }"at": "target" uses the second anchor set with .to(...).
Params
Section titled “Params”Params are the knobs an effect exposes. Declare them with defaults, then use them anywhere:
"params": { "color": "#ff3b1f", "radius": 2, "angry": false },"radius": "radius * (angry ? 1.5 : 1)","color": "$color"Code sets them with .param("radius", 4), commands with radius=4, and running effects can change them with
handle.set("radius", 6). .color(0xFF0000) sets the color param, or tints the whole effect if there is none.
Events
Section titled “Events”"events": [ { "time": 0, "sound": "minecraft:entity.generic.explode", "volume": 1.2, "pitch": 0.8 }, { "time": 0.4, "play": "mymod:debris", "at": { "offset": [0, 0.5, 0] } }, { "time": 0.4, "event": "impact" }]play starts another effect. event fires a named event that code can listen to:
handle.on("impact", e -> spawnDebris(e.position()));Sub-effects
Section titled “Sub-effects”An effect track plays another effect as part of this one, optionally on repeat:
{ "type": "effect", "effect": "mymod:spark_burst", "start": 0.5, "end": 3, "every": 0.25, "params": { "color": "#88ccff" } }"loop": true repeats the timeline until the effect is stopped. Tracks restart each time round; particles that are
already alive keep going. handle.stop() lets everything finish; handle.kill() removes it at once.
