Particles¶

Quick Start: Spice it up with twists.

Draw particle shapes with one tag per shape. Every group takes its geometry first and a settings list last, emits once, and leaves nothing behind. The one-line forms live in the cheatsheet.

Groups¶

parts. aliases the whole namespace, so <parts.line:...> works everywhere <particles.line:...> does. .l aliases .line only; the 2D line keeps its explicit .line2d head.

<particles.line:[0,64,0],[8,64,0],dust> draws a dust line and <parts.sphere:[0,64,0],3,[flame, 0.3]> draws a flame ball with wider spacing. Points are strict 3D [x, y, z] triples; located 6-lists [x, y, z, world, pitch, yaw] additionally pin the world (see below). Malformed geometry warns and draws nothing.

Settings¶

Settings are positional [style, spacing, mode, id, spawner]; pass leading items only and the rest take defaults. A bare value reads as the style, so dust equals [dust]. Blank items take defaults silently; malformed items warn once per match and take defaults.

Style names are case-blind (dust, DUST, minecraft:dust) and colors take hex with or without # (6b4c33, #6b4c33, short fff). Dust takes the color as dust data (red when omitted) and effect / instant_effect tint through the count-0 protocol (white when omitted); other dataless particles ignore the color silently. <random-color> draws a uniform six-digit hex for those color slots ([dust, <random-color>]). Unknown particle names warn and draw nothing. Particles whose data the settings cannot express (such as block or item particles) warn and draw nothing. Scalar-data particles (dragon_breath, sculk_charge, shriek) emit with neutral defaults (power 1.0, delay 0).

[[dust, 6b4c33], 0.1, [wave, 10, 0], ray, [-1, 0.25, true]] reads as brown dust every 0.1 blocks, a wave at 10 blocks per second from pos1, id ray, respawning every 0.25 seconds with random spread until cancelled. Wave velocity defaults to 20 blocks per second and start t (0 is pos1, 1 is pos2) defaults to 0. Spawner duration is seconds, -1 runs until <particles.cancel:id> cancels it; the interval floors at 0.05 seconds.

Spawners¶

Without a spawner the tag emits once and finishes. With [duration, interval, use-random] the system re-emits every interval: duration is seconds, -1 runs until <particles.cancel:id> cancels it, the interval floors at 0.05 seconds, and use-random re-spreads the shape per trigger (see below). Registering paints immediately; re-registering the same id re-arms the ticker from zero. Finite systems end themselves; infinite ones need an id, else they warn once and emit once.

Ids live in the calling modifier namespace (engine: ids belong to engine systems), so two modifiers can reuse ray without colliding. Cancel is idempotent: unknown or finished ids are a silent no-op. Match systems die with the match; global engine systems persist until cancelled.

Waves¶

Mode wave reveals the shape progressively instead of all at once: progress runs 0 to 1 along the traversal axis at velocity blocks per second, and start t picks the origin. t 0 starts at pos1 (line start, sphere top, circle ref), t 1 starts at the far end, and anything between waves both ways from t. Waves never bounce: at progress 1 the full shape shows.

Per-shape axes are deterministic:

Point and computed shapes have no axis, so wave mode on them warns once and emits the full shape. One-shot waves (no spawner) run a transient ticker and end themselves, cancellable by id while running. Spawner waves restart every interval: each trigger re-spreads (when random), resets to t, and reveals again; a wave that completes early holds its final frame until the next trigger.

Random spread¶

Spawner use-random applies one rigid transform per trigger, held across the wave reveal until the next trigger. Lines offset up to 1 block and carve points falling off the segment; spheres rotate; circles spin about their normal; rectangles, boxes, and cubes shift whole without carving; points jitter within a half-block cube. Flat (2D) shapes spread on the XZ plane. Spacing between surviving particles is preserved.

Worlds¶

Geometric tags draw in the world of the first located endpoint, else in the dispatch world (the executor world, or the first online participant world for runs without an executor). Requests with no world warn and draw nothing.

<particles.players:alice,bob,settings> draws a feet-to-feet line if and only if both players are online in the same world; offline players and cross-world pairs skip silently, since player presence is runtime state rather than author error.

Flat shapes¶

2D groups accept [x, z] pairs, triples, and located 6-lists. Triples keep their middle Y as the shape height; pure pairs rest at y 63 (vanilla sea level). <particles.rectangle:[0,0],[4,4],dust> frames a 4 by 4 outline at y 63, while <particles.line2d:[0,70,0],[4,4],dust> slopes from y 70 down to y 63. Rectangles use the first corner height.

Cube, block, and circle¶

<particles.cube:pos,scale,anchor,settings> anchors a wireframe cube: cubeMin = pos - anchor * scale, then plus scale. The scale is a uniform number or a per-axis triple (every axis positive); the anchor is a unit-cube triple defaulting to [0.5, 0.5, 0.5] (centered) and clamps to 0..1 with a warning. The anchor is optional, so arities 3 and 4 both work.

<particles.block:pos,settings> snaps the point to its block center (floor plus 0.5 per axis) and outlines that strict 1x1x1 cube; use cube for anything bigger or offset.

<particles.circle:p1,p2,settings> treats p1 and p2 as diameter endpoints: the center is the midpoint, the radius is half the distance, and the ring plane is perpendicular to p2 minus p1. Coincident points warn and draw nothing.

Fountain¶

<particles.fountain:origin,height,spread,settings> jets particles upward from the origin: height sets the jet height in blocks and spread its width, both positive (other values warn and draw nothing). The bare fountain settings mode loops any shape's traversal instead of finishing it, like a wave that restarts at the top forever; give the system an id and cancel it, or bound it with a spawner duration. Both the shape and the mode are premium: free falls back to interval with a warning.

Limits¶

Shapes cap at 4096 points per emission; larger shapes resample deterministically and warn once per match, so widen spacing when that warning appears. Each point tests individually against particles.max-visible-distance, so standing at the end of a long line still shows the near points while far shapes skip entirely, which keeps far viewers free.