RegionMusic

A Paper/Purpur plugin that plays configured music when a player enters WorldGuard regions (regions are typically created/managed using WorldEdit + WorldGuard).

Requirements

• Server: Paper/Purpur (api-version in plugin.yml: 1.21)
• Java: 21
• WorldGuard: 7.x (the plugin declares depend: [WorldGuard])
• A client resource pack (if you use custom sounds like namespace:key)

Installation

1. Put the plugin jar into plugins/.
2. Make sure WorldGuard is installed and loads before RegionMusic.
3. Start the server once, edit plugins/RegionMusic/config.yml, then restart the server.

Region Selection (Important)

If multiple WorldGuard regions apply at the player's location, the plugin selects the best region like this:

1. Only regions that have a config section regions.<regionId> in config.yml are considered.
2. The region with the highest WorldGuard priority wins.
3. If priorities are equal, the choice is stabilized by region id (alphabetical order).

Music is played for that selected region.

Configuration

File: plugins/RegionMusic/config.yml

Minimal setup (1 track per region):

regions:
  spawn:
    sound: "msr:spawn_theme"
    category: "MUSIC"
    volume: 1.0
    pitch: 1.0
    stopOnExit: true

Multiple Tracks (Shuffled, No Repeats Until Exhausted)

You can define a playlist via sounds:. Tracks are played in a shuffled order without repeats until the list is exhausted, then the list is reshuffled.

regions:
  spawn:
    sounds:
      - "msr:spawn_theme"
      - "msr:hscene2"
      - "msr:hscene3"
    category: "MUSIC"
    volume: 1.0
    pitch: 1.0
    stopOnExit: true

Continuous Playback (continuous)

Paper/Spigot does not provide a “sound finished” event, so to automatically play the next track you must configure durations.

regions:
  spawn:
    sounds:
      - "msr:spawn_theme"
      - "msr:hscene2"
    category: "MUSIC"

    continuous: true
    durations:
      "msr:spawn_theme": 2400 # ticks (20 ticks = 1 second)
      "msr:hscene2": 1360
    gapTicks: 0
    stopPreviousOnNext: true

Supported duration options:

• durationTicks: default duration for any track in this region (ticks).
• durationSeconds: same, but in seconds.
• durations:: a map soundKey -> ticks (overrides the default per track).

If durations are inaccurate:

• Duration longer than the real track: you will get silence until the next track starts.
• Duration shorter than the real track: the next track starts early; with stopPreviousOnNext: true the previous track will be stopped (audible cut).

Repeat A Track N Times (repeats)

You can force a given track to repeat N times consecutively before advancing to the next one:

regions:
  spawn:
    sounds:
      - "msr:spawn_theme"
      - "msr:hscene2"
    continuous: true
    durations:
      "msr:spawn_theme": 2400
      "msr:hscene2": 1360
    repeats:
      "msr:hscene2": 3

Values < 1 are treated as 1.

Stop Vanilla Music On Enter

To prevent region music from overlapping vanilla background music, you can stop the MUSIC category on enter:

regions:
  spawn:
    stopVanillaMusicOnEnter: true

Notes:

• Vanilla background music is client-side; the plugin does a best-effort stop of SoundCategory.MUSIC.
• The region track is started on the next tick after stopping MUSIC to avoid rare client packet-order races.

Full Per-Region Options

• sound: string - a single track (legacy).
• sounds: [string] - a list of tracks (recommended).
• category: string - Bukkit category (MUSIC, RECORDS, ...), default: MUSIC.
• volume: number - default: 1.0.
• pitch: number - default: 1.0.
• stopOnExit: boolean - stop the currently playing track when leaving all configured regions, default: true.
• stopVanillaMusicOnEnter: boolean - stop SoundCategory.MUSIC when entering, default: true.
• continuous: boolean - keep playing the playlist while the player stays in the region, default: false.
• durationTicks: int / durationSeconds: number - default duration for continuous.
• durations: { "<soundKey>": <ticks> } - per-track durations (ticks).
• gapTicks: int - silence gap between tracks, default: 0.
• stopPreviousOnNext: boolean - stop the previous track right before starting the next one, default: true.
• repeats: { "<soundKey>": <count> } - repeat a specific track N times consecutively.

Resource Pack (Custom Sounds)

If you use custom sounds like msr:spawn_theme, clients must have a resource pack enabled that contains:

• assets/msr/sounds.json (or another namespace instead of msr)
• assets/msr/sounds/<name>.ogg

Important:

• .ogg must be Ogg Vorbis (not an MP3 renamed to .ogg).
• soundKey must be lowercase (Minecraft ResourceLocation rule).

Quick client-side test:

/playsound msr:spawn_theme music @s ~ ~ ~ 1 1

If you get silence or an “unknown soundEvent” error, the issue is in the resource pack / key, not the plugin.