RegionMusic
一个 Paper/Purpur 插件,当玩家进入 WorldGuard 区域(区域通常使用 WorldEdit + WorldGuard 创建/管理)时播放配置的音乐。
要求
- 服务器:Paper/Purpur(
plugin.yml 中的 api-version:1.21)
- Java:21
- WorldGuard:7.x(该插件声明了
depend: [WorldGuard])
- 客户端资源包(如果你使用自定义音效,如
namespace:key)
安装
- 将插件 jar 放入
plugins/ 目录。
- 确保已安装 WorldGuard,并且它在 RegionMusic 之前加载。
- 启动服务器一次,编辑
plugins/RegionMusic/config.yml,然后重启服务器。
区域选择(重要)
如果玩家所在位置有多个 WorldGuard 区域适用,插件会按以下方式选择最佳区域:
- 仅考虑在
config.yml 中具有配置部分 regions.<regionId> 的区域。
- 具有最高 WorldGuard
priority(优先级)的区域胜出。
- 如果优先级相等,则通过区域
id(字母顺序)稳定选择结果。
为该选定区域播放音乐。
配置
文件:plugins/RegionMusic/config.yml
最小设置(每个区域 1 首曲目):
regions:
spawn:
sound: "msr:spawn_theme"
category: "MUSIC"
volume: 1.0
pitch: 1.0
stopOnExit: true
多首曲目(随机播放,未耗尽前不重复)
你可以通过 sounds: 定义播放列表。曲目将以随机顺序播放,直到列表耗尽前不会重复,然后重新洗牌列表。
regions:
spawn:
sounds:
- "msr:spawn_theme"
- "msr:hscene2"
- "msr:hscene3"
category: "MUSIC"
volume: 1.0
pitch: 1.0
stopOnExit: true
连续播放 (continuous)
Paper/Spigot 没有提供“音效结束”事件,因此要自动播放下一首曲目,你必须配置持续时间。
regions:
spawn:
sounds:
- "msr:spawn_theme"
- "msr:hscene2"
category: "MUSIC"
continuous: true
durations:
"msr:spawn_theme": 2400 # ticks(20 ticks = 1 秒)
"msr:hscene2": 1360
gapTicks: 0
stopPreviousOnNext: true
支持的持续时间选项:
durationTicks:此区域内任何曲目的默认持续时间(ticks)。
durationSeconds:同上,但以秒为单位。
durations::映射 soundKey -> ticks(覆盖每首曲目的默认值)。
如果持续时间不准确:
- 持续时间长于实际曲目:你会听到静音,直到下一首曲目开始。
- 持续时间短于实际曲目:下一首曲目会提前开始;配合
stopPreviousOnNext: true,上一首曲目会被停止(可听见的切断)。
重复播放某曲目 N 次 (repeats)
你可以强制给定曲目连续重复 N 次,然后再进入下一首:
regions:
spawn:
sounds:
- "msr:spawn_theme"
- "msr:hscene2"
continuous: true
durations:
"msr:spawn_theme": 2400
"msr:hscene2": 1360
repeats:
"msr:hscene2": 3
值 < 1 被视为 1。
进入时停止原版音乐
为了防止区域音乐与原版背景音乐重叠,你可以在进入时停止 MUSIC 类别:
regions:
spawn:
stopVanillaMusicOnEnter: true
注意:
- 原版背景音乐是客户端侧的;插件尽力尝试停止
SoundCategory.MUSIC。
- 区域音轨会在停止
MUSIC 后的下一个 tick 启动,以避免罕见的客户端数据包顺序竞争条件。
完整的逐区域选项
sound: string - 单首曲目(旧版)。
sounds: [string] - 曲目列表(推荐)。
category: string - Bukkit 类别(MUSIC, RECORDS, ...),默认:MUSIC。
volume: number - 默认:1.0。
pitch: number - 默认:1.0。
stopOnExit: boolean - 离开所有配置的区域时停止当前正在播放的曲目,默认:true。
stopVanillaMusicOnEnter: boolean - 进入时停止 SoundCategory.MUSIC,默认:true。
continuous: boolean - 只要玩家停留在区域内就保持播放播放列表,默认:false。
durationTicks: int / durationSeconds: number - continuous 模式的默认持续时间。
durations: { "<soundKey>": <ticks> } - 逐曲目持续时间(ticks)。
gapTicks: int - 曲目之间的静音间隔,默认:0。
stopPreviousOnNext: boolean - 在开始下一首曲目之前立即停止上一首曲目,默认:true。
repeats: { "<soundKey>": <count> } - 让特定曲目连续重复 N 次。
资源包(自定义音效)
如果你使用类似 msr:spawn_theme 的自定义音效,客户端必须启用包含以下内容的资源包:
assets/msr/sounds.json(或者使用其他命名空间代替 msr)
assets/msr/sounds/<name>.ogg
重要提示:
.ogg 必须是 Ogg Vorbis 格式(不是重命名为 .ogg 的 MP3)。
soundKey 必须为小写(遵循 Minecraft ResourceLocation 规则)。
快速客户端测试:
/playsound msr:spawn_theme music @s ~ ~ ~ 1 1
如果你听到静音或出现“unknown soundEvent”错误,问题出在资源包/键上,而不是插件本身。
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
- Put the plugin jar into
plugins/.
- Make sure WorldGuard is installed and loads before RegionMusic.
- 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:
- Only regions that have a config section
regions.<regionId> in config.yml are considered.
- The region with the highest WorldGuard
priority wins.
- 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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧