Effects¶

Quick Start: Spice it up with twists.

Effect writes go through one shared ledger: each modifier owns named entries per player and the engine merges them onto the live potion effects. The one-line forms live in the cheatsheet. Twins: <phaseffect> also ships <rhaseffect> and <ghaseffect>; see Role and global twins.

<pfx.set:Steve,glow,[[glowing,0,5]]> writes the glow entry for Steve, replacing its old doses. The doses nest as [[id, amplifier, seconds], ...] with whole amplifiers of 0 or more and positive seconds (-1 runs forever), each dose taking an optional trailing icon flag ([speed, 0, 5, false] hides the effect icon on the player's screen; default true). Fractional seconds apply exact ticks: the dose rounds to the nearest tick (0.20 is 4 ticks), floored at 1, no more no less. A trailing hide flag (default true) controls particles, like before. Effect ids match case-blind with an optional minecraft: prefix, and unknown ids skip with a logged warning.

<random-effect> draws one triple for those dose lists (<pfx.set:Steve,glow,[<random-effect>]>). The amplifier draws from arg one (0 default, clamped to 0..255), the seconds from arg two (30 default, bottomed at -1 for forever); both take singles or [min, max] whole pairs, and decimals refuse with a warning plus the default. EFFECTS settings keep whole seconds too; put fractional doses directly in the <pfx.set> list or compute them into a local value instead.

The id is optional: <pfx.set:Steve,[[glowing,0,5]]> (a list in second position) auto-assigns <modifier>-N with the smallest free N and yields the assigned id, so capture it in a flag (<lf:veil,<pfx.set:<p>,[[glowing,0,5]]>>). Named writes yield empty.

Each successful set or clear immediately refreshes the player's merged view, and a 5-tick engine beat re-picks winners so backups apply the moment a winner runs out. Per effect, the higher amplifier always wins, then the longer remaining (infinite beats finite). Two modifiers can hold the same effect under different ids and both survive: clearing one id never touches the other. Same amplifier and effect across ids never stack; each entry runs out at its own pace. Re-writing one id re-applies its doses with fresh ticks, so short doses stay up by re-pulsing the same id on a beat; untouched entries keep ticking down. A finite winner at 6 ticks or less hands over early to a longer-remaining runner-up, whatever its amplifier, so expiry never blips. Expired entries stay stored until cleared by hand (durations read 0). When a player quits or their match tears down, their whole ledger clears automatically, including lingering infinite effects.

<pfx.get:Steve,glow> reads one entry back as [[id, amplifier, seconds], ...] ([] when unset), doses with a hidden icon carrying a trailing false. <pfx.duration:Steve,glow,glowing> reads the live seconds left for one effect under one id (-1 runs forever, null when the id or the effect is absent). <phaseffect:Steve,speed,1> instead reads the player's live effect directly: true when held at amplifier 1 or more (min defaults to 0).

Blank players, blank ids, malformed doses, offline players, and bad hide flags warn plus null (sets and clears) or false (the live read). Online players without the effect read false silently.

The old <peffect>, <geffect>, and <reffect> writers (plus the peff, geff, and reff aliases) were removed: lines still using them warn with the ledger replacement and run untouched. Role and global twins (<rfx.set>, <gfx.set>, ...) fan one write out over a roster; see Shared Effects.

Next Steps¶

• Tag Cheatsheet
• Shared Effects
• Dirty Effect Hack
• Players