Content

Music

Give your server its own soundtrack. A piece of music is a playlist of your sounds. It plays to each player while they are somewhere it belongs, like a lobby world, a WorldGuard region or a box you mark out, or whenever a command or plugin starts it. Minecraft's own music is kept quiet while yours plays.

# music/lobby.yml
lobby:
  tracks: [theme, calm]      # sounds from sounds/. A bare name is this pack's
  shuffle: false
  loop: true                 # start again after the last track
  gap: 2                     # seconds of silence between tracks
  vanilla-music: false       # true lets Minecraft's own music play over it
  priority: 0                # the higher wins where two places overlap
  where:
    worlds: [lobby]
    regions: [spawn]         # WorldGuard regions
    areas:
      - { world: world, from: [0, 0, 0], to: [100, 255, 100] }

Field	Default	What it does
`tracks`	required	The sounds to play, in order. `theme` means this pack's `theme`; `otherpack:theme` names another's
`shuffle`	`false`	Play them in a random order, a new one each time round. A track never plays twice in a row
`loop`	`true`	After the last track, start again. `false` plays them once and falls silent
`gap`	1	Seconds of silence between tracks (0 to 600)
`vanilla-music`	`false`	Let Minecraft's own soundtrack play over yours
`priority`	0	Where two pieces' places overlap, the higher one plays. A tie goes to the id that sorts first
`where`	none	Where it plays by itself: any of `worlds`, `regions` and `areas`. Leave it out and it only plays when started

An area is a box of whole blocks with both corners inside it. Regions need WorldGuard; without it they never match.

The tracks#

Each track is an ordinary sound, so declare it in sounds/ first:

# sounds/music.yml
theme:
  category: music      # so the player's music slider controls it
  stream: true         # anything long should stream
  subtitle: "Lobby music plays"

Export music in stereo. A stereo file plays the same everywhere, which is what a soundtrack wants. Mono works too: a track follows the player, so it doesn't fade as they walk. See mono or stereo.

Minecraft can't queue sounds, so RP Engine starts each track when the one before it ends. It reads how long that is from the file. A track whose length it can't find (with a console warning on load) plays once, and the music stops after it.

What a player hears#

At most one piece at a time. In order:

What a command or plugin started for them.
Otherwise, the music of the place they are in.
Otherwise, nothing, and Minecraft's own music as usual.

Walking from one place into another switches the music within half a second.

Stopping music that was started brings back the music of the place you are in. Stopping a place's music keeps it quiet until you leave that place.

Commands#

/rp music                        every piece, and what is playing for you
/rp music play tunes:lobby       start one for yourself, from its first track
/rp music play tunes:boss Steve  start one for somebody else
/rp music skip                   on to the next track
/rp music stop                   stop it (twice to quiet the place's music too)

Each verb has its own permission, so you can let players stop or skip their own music without letting them start any:

Permission	Allows
`rpengine.music`	`/rp music`, and all three verbs below
`rpengine.music.play`	Starting music
`rpengine.music.stop`	Stopping music
`rpengine.music.skip`	Skipping a track
`rpengine.music.others`	Any of those for somebody else

All are op-only by default.

From a plugin#

Music music = engine.music();
music.play(player, ContentId.parse("tunes:boss").orElseThrow()); // until stopped
music.skip(player);
music.stop(player);
music.playing(player); // the piece, if any

A boss fight can start its own music and stop it when the boss dies, and the player's place music takes over again.