JoinLeaveSound - Minecraft 加入/离开服务器音效插件
简介
一款轻量级的 Bukkit/Spigot/Paper 插件,当有人加入或离开服务器时,向所有在线玩家播放可配置的音效。
代码仓库:
功能特性
- 自定义加入/离开音效(支持调节音量和音调)
- 基于权限组的音效系统(不同组别播放不同音效,按优先级匹配)
- 新手首次加入专属音效(拥有独立的冷却时间)
- 静音玩家管理 (
/jls mute/unmute <player>,支持离线玩家)
- 独立的冷却计时器(加入、离开、新手分别统计,防止因快速进出导致音效刷屏)
- 热重载 (
/jls reload)
- 多语言支持 (
lang/zh_CN.yml, lang/en_US.yml)
- OP 豁免开关(OP 可以不被触发音效)
- 调试模式(在控制台输出详细的匹配日志)
- 独立存储文件 (
muted-players.yml, groups.yml)
- 纯 Bukkit API,零依赖
安装方法
- 将
JoinLeaveSound.jar 放入服务器的 plugins/ 文件夹中。
- 重启服务器或使用插件管理器加载该插件。
- 通过编辑
plugins/JoinLeaveSound/ 目录下的文件来自定义设置。
配置文件结构
| 文件 |
用途 |
config.yml |
全局设置(冷却时间、语言、OP 豁免、调试模式) |
groups.yml |
权限组音效、默认音效、新手音效 |
lang/zh_CN.yml |
简体中文消息 |
lang/en_US.yml |
英文消息 |
muted-players.yml |
被静音的玩家列表(由插件自动维护) |
命令与权限
| 命令 |
别名 |
权限节点 |
描述 |
/joinleavesound reload |
/jls reload |
joinleavesound.reload |
重新加载所有配置和消息 |
/joinleavesound mute <player> |
/jls mute <player> |
joinleavesound.mute |
静音某玩家(支持离线状态) |
/joinleavesound unmute <player> |
/jls unmute <player> |
joinleavesound.mute |
取消对某玩家的静音 |
权限默认授予 OP。Tab 补全支持子命令和在线玩家名称。
权限组音效系统 (groups.yml)
匹配优先级(从高到低)
- 新手 (当
hasPlayedBefore() == false 且 newbie.enabled: true 时)
- 自定义组 (按照
groups 列表中从上到下的顺序,首个匹配成功即生效)
- 默认组 (当
enable-default: true 时使用)
- 无音效 (上述条件均未匹配时)
配置示例
# 启用默认组
enable-default: true
# 启用自定义组
enable-groups: true
# 新手首次加入音效
newbie:
enabled: true
join-sound:
sound: BLOCK_NOTE_BLOCK_PLING
volume: 1.0
pitch: 2.0
# 默认组音效
default:
join-sound:
sound: BLOCK_NOTE_BLOCK_PLING
volume: 1.0
pitch: 1.0
leave-sound:
sound: BLOCK_NOTE_BLOCK_BASS
volume: 1.0
pitch: 1.0
# 自定义组(按优先级排序)
groups:
admin:
permission: "joinleavesound.group.admin"
join-sound:
sound: UI_TOAST_CHALLENGE_COMPLETE
volume: 1.0
pitch: 1.0
leave-sound:
sound: ENTITY_LIGHTNING_BOLT_THUNDER
volume: 1.0
pitch: 1.0
vip:
permission: "joinleavesound.group.vip"
join-sound:
sound: ENTITY_PLAYER_LEVELUP
volume: 1.0
pitch: 1.2
leave-sound:
sound: ENTITY_ENDERMAN_TELEPORT
volume: 1.0
pitch: 1.0
权限分配示例 (LuckPerms)
/lp user Dalict permission set joinleavesound.group.admin true
/lp group vip permission set joinleavesound.group.vip true
常见场景对照表
| 配置情况 |
无权限玩家 |
VIP |
Admin |
| 开启默认组 + 有自定义组 |
默认音效 |
VIP 音效 |
Admin 音效 |
| 关闭默认组 + 有自定义组 |
无音效 |
VIP 音效 |
Admin 音效 |
| 开启默认组 + 空自定义组 |
默认音效 |
默认音效 |
默认音效 |
冷却系统
冷却类型
| 类型 |
配置路径 |
默认值 |
独立计时 |
| 普通加入 |
cooldown.join |
10 秒 |
✅ |
| 普通离开 |
cooldown.leave |
10 秒 |
✅ |
| 新手加入 |
cooldown.newbie |
0 秒(已禁用) |
✅ |
冷却行为说明
- 冷却期间:后续相同事件不会播放音效,但会重置冷却计时器。
- 冷却结束后:只有在距离上一次事件经过完整的冷却周期后,音效才能再次播放。
- 设置为 0 或负数:表示禁用该类型的冷却。
示例(加入冷却为 10 秒)
- 玩家 A 加入 → 播放音效,开始倒计时。
- 5 秒后玩家 B 加入 → 不播放音效,冷却重置(从第 5 秒开始重新计算)。
- 再过 10 秒玩家 C 加入 → 播放音效。
全局配置 (config.yml)
# 冷却时间(秒),设为 0 或负数以禁用
cooldown:
join: 10
leave: 10
newbie: 0
# 服务器语言 (zh_CN / en_US)
language: en_US
# OP 豁免:true = OP 永远不会触发音效
op-bypass: false
# 调试模式:在控制台记录详细的匹配信息
debug: false
多语言支持
插件自带 zh_CN(简体中文)和 en_US(英文)语言文件,位于 lang/ 目录下。
- 修改
config.yml 中的 language 值并执行重载即可切换语言。
- 如果缺少对应的语言文件,系统将自动回退使用
zh_CN。
- 如需添加新语言,只需在
lang/ 文件夹中放置一个命名正确的 .yml 文件即可。
常见问题
Q: 我可以禁用冷却吗?
A: 可以。将相应的冷却值设置为 0 即可。
Q: 被静音的玩家会完全听不到声音吗?
A: 是的,被静音的玩家不会触发任何加入/离开音效,并且他们的操作也会跳过冷却计时。
Q: 我可以使用哪些音效名称?
A: 请参阅 Bukkit Sound 枚举。
问:这个插件会与其他插件冲突吗?
答:不会。它仅监听标准的加入/离开事件,且不修改任何游戏机制。轻量级且无依赖。
问:我可以添加无限数量的自定义组吗?
答:理论上可以,数百个组不会影响性能。匹配过程仅仅是带有哈希查找的简单列表迭代。
问:如果禁用了新人音效,新玩家会听到什么?
答:他们将遵循正常的组/默认匹配流程,就像普通玩家一样。
问:在 LuckPerms 中支持自定义权限节点的 Tab 补全吗?
答:不支持,首次输入时必须手动键入。之后,LuckPerms 会记住这些节点。
问:当大量玩家同时加入或离开时,声音会变得嘈杂吗?
答:不会,冷却系统会抑制过多的声音,保持服务器氛围优雅。
许可证
MIT 许可证
支持与反馈
JoinLeaveSound - Minecraft Join/Leave Sound Plugin
Introduction
A lightweight Bukkit/Spigot/Paper plugin that plays configurable sounds to all online players when someone joins or leaves the server.
Repository:
Features
- Customizable join/leave sounds (volume & pitch adjustable)
- Permission-based group sound system (different sounds for different groups, prioritized)
- Newbie first-join exclusive sound (with independent cooldown)
- Mute player management (
/jls mute/unmute <player>, works offline)
- Independent cooldowns (join/leave/newbie tracked separately to prevent noise from rapid joins/leaves)
- Hot reload (
/jls reload)
- Multi-language support (
lang/zh_CN.yml, lang/en_US.yml)
- OP bypass toggle (OPs can be exempted from sounds)
- Debug mode (detailed matching logs in console)
- Isolated storage (
muted-players.yml, groups.yml)
- Pure Bukkit API, zero dependencies
Installation
- Place
JoinLeaveSound.jar into the server's plugins/ folder.
- Restart the server or use a plugin manager to load it.
- Customize settings by editing files under
plugins/JoinLeaveSound/.
Configuration File Structure
| File |
Purpose |
config.yml |
Global settings (cooldown, language, OP bypass, debug) |
groups.yml |
Permission group sounds, default sound, newbie sound |
lang/zh_CN.yml |
Simplified Chinese messages |
lang/en_US.yml |
English messages |
muted-players.yml |
Muted player list (maintained automatically) |
Commands & Permissions
| Command |
Alias |
Permission |
Description |
/joinleavesound reload |
/jls reload |
joinleavesound.reload |
Reload all configurations and messages |
/joinleavesound mute <player> |
/jls mute <player> |
joinleavesound.mute |
Mute a player (offline supported) |
/joinleavesound unmute <player> |
/jls unmute <player> |
joinleavesound.mute |
Unmute a player |
Permissions default to OP. Tab completion supports subcommands and online player names.
Permission Group Sound System (groups.yml)
Matching Priority (high to low)
- Newbie (when
hasPlayedBefore() == false and newbie.enabled: true)
- Custom groups (from top to bottom in the
groups list, first match wins)
- Default group (used when
enable-default: true)
- No sound (none of the above matched)
Configuration Example
# Enable default group
enable-default: true
# Enable custom groups
enable-groups: true
# Newbie first-join sound
newbie:
enabled: true
join-sound:
sound: BLOCK_NOTE_BLOCK_PLING
volume: 1.0
pitch: 2.0
# Default group sounds
default:
join-sound:
sound: BLOCK_NOTE_BLOCK_PLING
volume: 1.0
pitch: 1.0
leave-sound:
sound: BLOCK_NOTE_BLOCK_BASS
volume: 1.0
pitch: 1.0
# Custom groups (ordered by priority)
groups:
admin:
permission: "joinleavesound.group.admin"
join-sound:
sound: UI_TOAST_CHALLENGE_COMPLETE
volume: 1.0
pitch: 1.0
leave-sound:
sound: ENTITY_LIGHTNING_BOLT_THUNDER
volume: 1.0
pitch: 1.0
vip:
permission: "joinleavesound.group.vip"
join-sound:
sound: ENTITY_PLAYER_LEVELUP
volume: 1.0
pitch: 1.2
leave-sound:
sound: ENTITY_ENDERMAN_TELEPORT
volume: 1.0
pitch: 1.0
Example Permission Assignment (LuckPerms)
/lp user Dalict permission set joinleavesound.group.admin true
/lp group vip permission set joinleavesound.group.vip true
Common Scenarios
| Configuration |
Player without permission |
VIP |
Admin |
| Default on + custom groups |
Default sound |
VIP sound |
Admin sound |
| Default off + custom groups |
No sound |
VIP sound |
Admin sound |
| Default on + empty groups |
Default sound |
Default sound |
Default sound |
Cooldown System
Cooldown Types
| Type |
Config path |
Default |
Independent timer |
| Normal join |
cooldown.join |
10 seconds |
✅ |
| Normal leave |
cooldown.leave |
10 seconds |
✅ |
| Newbie join |
cooldown.newbie |
0 seconds (disabled) |
✅ |
Cooldown Behavior
- During cooldown: subsequent same events will NOT play the sound, but will reset the cooldown timer.
- After cooldown: the sound can play again only after a full cooldown period has elapsed since the last event.
- Set to 0 or negative: disables that cooldown type.
Example (join cooldown 10s)
- Player A joins → sound plays, cooldown starts.
- Player B joins after 5s → no sound, cooldown resets (counts from second 5).
- Player C joins after another 10s → sound plays.
Global Configuration (config.yml)
# Cooldown in seconds (0 or negative to disable)
cooldown:
join: 10
leave: 10
newbie: 0
# Server language (zh_CN / en_US)
language: en_US
# OP bypass: true = OPs never trigger sounds
op-bypass: false
# Debug mode: logs detailed matching info to console
debug: false
Multi-Language
The plugin ships with zh_CN (Simplified Chinese) and en_US (English) language files inside the lang/ directory.
- Change the
language value in config.yml and reload to switch.
- If a language file is missing, it automatically falls back to
zh_CN.
- To add a new language, just place a properly named
.yml file in the lang/ folder.
FAQ
Q: Can I disable cooldown?
A: Yes. Set the corresponding cooldown value to 0.
Q: Will muted players be completely silent?
A: Yes, muted players will not trigger any join/leave sounds, and cooldown is also skipped for them.
Q: What sound names can I use?
A: See the Bukkit Sound enum.
Q: Does this plugin conflict with other plugins?
A: No. It only listens to standard join/leave events and doesn't modify any game mechanics. Lightweight and dependency-free.
Q: Can I add unlimited custom groups?
A: Technically yes, hundreds of groups won't affect performance. Matching is just a simple list iteration with hash lookups.
Q: If newbie sound is disabled, what will new players hear?
A: They will follow the normal group/default matching flow, just like regular players.
Q: Can custom permission nodes be tab-completed in LuckPerms?
A: No, they must be typed manually the first time. After that, LP will remember them.
Q: Will it be noisy when many players join/leave at once?
A: No, the cooldown system suppresses excessive sounds, keeping the server atmosphere elegant.
License
MIT License
Support & Feedback
评论 0
登录后参与评分
还没有评论,来抢沙发吧