Effects

Intro

RTP can play fireworks, notes, particles, potions, and sounds around a teleport.

The recommended way to configure effects is the effects/ config directory (presets applied on teleport lifecycle phases), exposed across platforms via effects-api. See the API page and the effects-api module for the SPI.

RTP also supports a legacy permission-driven grammar (documented further below) for fireworks, notes, particles, potions, and sounds. Each effect is read from permissions matching the format rtp.effect.[event].[effect].[data], parsed asynchronously on command, pre-teleport, and teleport. Effect data can be cut off at any point and the remaining values use defaults. For heavy use, prefer the effects/ presets (or a dedicated plugin) over a long permission list.

Configuring the effects/ directory

The effects/ config directory holds one file per effect group. The filename (minus .yml) is the group name, e.g. effects/default.yml is the default group. RTP ships three files:

File	Stage (when)	Purpose
default.yml	postteleport	Unconditional fallback played after a successful teleport.
default-pre.yml	preteleport	Fallback for the pre-teleport stage.
default-cancel.yml	cancel	Fallback played when a teleport is cancelled.

The default group is hardcoded: even if default.yml is deleted, the loader synthesises an empty default group (when: postteleport, no effects) so resolution never fails. Edit the file to customise the fallback. Create additional files to add more groups.

Group keys

Each file has a fixed set of inner keys:

Key	Required	Purpose
when	yes	The teleport-pipeline stage that fires this group. Vocabulary: firstjoin, join, presetup, postsetup, preload, postload, preteleport, postteleport, cancel, queuepush, queuepop.
effects	yes	Ordered list of <effect-name>.<arg1>.<arg2>... tokens (same grammar as the legacy permission suffix, documented below).
permission	no	Bukkit-style permission node that gates membership in this group.
players	no	Explicit UUID/name allowlist. A permission-less escape hatch and the primary path on Fabric servers without fabric-permissions-api.
inherit	no	Other group names whose effects are prepended. Defaults to the stage's default group when omitted; pass inherit: [] to opt out.
version	yes	Internal schema version. Do not edit.

Effect token grammar

Tokens are dot-separated and consumed left to right. Trailing arguments are optional and fall back to the effect's defaults.

SOUND   .TYPE.VOLUME.PITCH.DX.DY.DZ
PARTICLE.TYPE.NUMBER                            (server >= 1.9)
POTION  .TYPE.DURATION.AMPLIFIER.AMBIENT.PARTICLES.ICON
NOTE    .TYPE.TONE
FIREWORK.TYPE.NUMBER.POWER.COLOR.FADE.FLICKER.TRAIL.SAFE.DX.DY.DZ
GLIDE   .TYPE                                   (built into effects-api)

Numeric arguments are integers only. The . is both the field separator and the decimal point, so writing 1.0 tokenizes to two tokens (1 then 0). SOUND VOLUME/PITCH are integer percent (0..100, where 100 == full); 1.0 would give volume 1% (silent) and pitch 0%. Use whole numbers, e.g. SOUND.ENTITY_ENDERMAN_TELEPORT.100.100.0.0.0.

POTION DURATION is in ticks (20 = 1 s) and AMPLIFIER is 0-based; AMBIENT/PARTICLES/ICON take true/false. Type tokens are matched case-insensitively against the platform registry (Bukkit Sound/Particle/...; Fabric namespaced ResourceLocation). The shipped default.yml contains a large commented-out catalog of every bundled effect type you can copy from.

Example

when: postteleport
permission: rtp.effect.vip
effects:
  - SOUND.ENTITY_PLAYER_LEVELUP.100.100.0.0.0
  - PARTICLE.TOTEM_OF_UNDYING.40
  - POTION.SLOW_FALLING.120.0

version: "1.0"

Legacy permission grammar

The effect data formats below are shared by the effects/ token grammar above and the legacy rtp.effect.[event].[effect].[data] permission nodes.

Firework

firework data has the following format:

type.number.power.color.fade.flicker.trail

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/FireworkEffect.Type.html

• type: what shape of firework, default=BALL
• number: how many fireworks, default=1
• power: how far to go before exploding, default=0
• color: hex ignition color, default=ffffff
• fade: hex fade color, default=ffffff
• flicker: whether to flicker, default=false
• trail: whether to have a trail, default=false

Note

note data has the following format:

instrument.tone

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Instrument.html

• instrument: what instrument to use, default=PIANO
• tone: what tone to use, default=0

Particle

particle data has the following format:

particle.number

https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html

• particle: what particle to show, required
• number: how many particles, default=0

Potion

potion data has the following format:

potionEffectType.duration.amplifier.ambient.particles.icon

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html

• potionEffectType: what potion effect to use, required
• duration: how long, in ticks, the potion should last, default=255
• amplifier: how strong the effect should be, default=1
• ambient: I don't know what this does, default=false
• particles: whether to show potion particles, default=false
• icon: whether to show potion icon, default=false

Sound

sound data has the following format:

sound.volume.pitch

There are 600+ sounds and tabcompletion has limits, so it isn't useful to register all of them as permissions at startup.

https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html

• sound: what sound use, required
• volume: how loud as a percentage, default=100
• pitch: pitch as a percentage, default=100