JoinLeaveSound - Minecraft Join/Leave Sound Plugin

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.

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

1. Place JoinLeaveSound-1.1.0.jar into the server's plugins/ folder.
2. Restart the server or use a plugin manager to load it.
3. 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)

1. Newbie (when hasPlayedBefore() == false and newbie.enabled: true)
2. Custom groups (from top to bottom in the groups list, first match wins)
3. Default group (used when enable-default: true)
4. No sound (none of the above matched)

Configuration Example
Example Permission Assignment (LuckPerms)
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)

1. Player A joins → sound plays, cooldown starts.
2. Player B joins after 5s → no sound, cooldown resets (counts from second 5).
3. Player C joins after another 10s → sound plays.

Global Configuration (config.yml)


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

• Issues: GitHub Issues
• Source: https://github.com/Dalict/JoinLeaveSound