Can you make it?
π
ServerMusic_Master_Prompt.txt
txt
1628 lines
βΆ
SERVERMUSIC β MASTER DEVELOPMENT PROMPT
1. PROJECT
Create a professional, production-ready Minecraft music plugin named:
ServerMusic
Target environment:
- Paper 26.2
- Java 25
- Java Edition
- Bedrock Edition through Geyser + Floodgate
- Server-wide music
- World-specific music
- Exact playback synchronization
- OP-only controls by default
This is NOT a demonstration plugin.
Build the complete system with clean architecture, proper error handling, security, performance and testing.
Do not use fake playback.
---
2. CORE IDEA
ServerMusic is a server-side music system similar in concept to a Discord music bot.
An authorized OP can control music using:
"/music play "
The input can be:
- Song name
- YouTube URL
- Spotify track URL
Examples:
/music play Faded Alan Walker
/music play https://www.youtube.com/watch?v=VIDEO_ID
/music play https://youtu.be/VIDEO_ID
/music play https://open.spotify.com/track/TRACK_ID
Music can target:
- the entire server
- one specific Minecraft world
---
3. MOST IMPORTANT RULE β ONE AUTHORITATIVE PLAYBACK CLOCK
The plugin must never create an independent playback timeline for every player.
The server is the source of truth.
For global music there is exactly ONE global playback state.
For world-specific music there is ONE playback state per active world.
Example:
Global music:
Faded β Alan Walker
03:15 / 03:32
Players in:
- Lobby
- SMP
- SPVP
- Nether
- End
- any other world
must hear approximately the same moment:
"03:15"
A player joining at that moment must NOT start at "00:00".
---
4. JOIN SYNCHRONIZATION
If the server is playing at:
"03:15"
and a player joins:
They must eventually hear approximately:
"03:15".
If loading the audio/resource takes 5 seconds:
Do NOT start them at "03:15".
Instead:
1. Detect the server's position at join.
2. Prepare the player.
3. Continue advancing the authoritative server clock.
4. Calculate the CURRENT position immediately before playback.
5. Start the player at that current position.
Therefore they may start around:
"03:20".
The server clock is always authoritative.
---
5. REJOIN SYNCHRONIZATION
A player leaves while the song is at:
"04:00".
The server continues playing.
The player rejoins when the song is:
"04:42".
They must start at approximately:
"04:42".
Do NOT remember their personal "04:00" position.
The current server/world playback state always wins.
---
6. WORLD CHANGE SYNCHRONIZATION
Players can move between worlds.
When a player changes worlds:
1. Detect the destination world.
2. Determine the effective music for that world.
3. Stop the previous music for that player.
4. Prepare the new music if necessary.
5. Calculate the CURRENT position of the destination playback state.
6. Start from that position.
Example:
Lobby:
"Faded β 03:15"
SPVP:
"Believer β 01:42"
Player teleports:
"Lobby β SPVP"
They stop hearing Faded and begin hearing Believer around:
"01:42".
---
7. TARGET MODES
Support two main targets:
ALL
/music play all
This means the entire server.
Every player in every world hears the same global track.
WORLD
/music play world
Only players currently in that world hear the world-specific track.
---
8. GLOBAL SERVER MUSIC
Example:
/music play all Faded Alan Walker
If the server contains:
world
world_nether
world_the_end
Lobby
SMP
SPVP
Events
every player in all of those worlds hears:
"Faded"
at the same playback position.
There must be ONE global playback clock.
Do NOT create:
- one timer for Lobby
- one timer for SMP
- one timer for SPVP
when "ALL" mode is active.
---
9. WORLD-SPECIFIC MUSIC
Example:
/music play world Lobby Faded Alan Walker
Only players in:
"Lobby"
hear that world-specific music.
Example:
/music play world SPVP Believer Imagine Dragons
Players in SPVP hear Believer.
Players in Lobby may hear Lobby music.
Players in other worlds may hear global music.
Each world-specific playback state is independent.
---
10. PRIORITY SYSTEM
Use this exact priority:
WORLD-SPECIFIC MUSIC
β
GLOBAL SERVER MUSIC
β
NORMAL MINECRAFT MUSIC
Therefore:
If global music is:
"Faded β 03:15"
and Lobby has:
"Believer β 01:42"
then:
Lobby players:
"Believer β 01:42"
SMP players:
"Faded β 03:15"
SPVP players:
"Faded β 03:15"
Nether players:
"Faded β 03:15"
If Lobby music stops:
Lobby players fall back to the global Faded track at its CURRENT position.
---
11. PLAY COMMANDS
Support:
/music play
For simple use, this should mean the default configured target.
Also explicitly support:
/music play all
/music play world
Examples:
/music play all Faded Alan Walker
/music play all https://youtube.com/watch?v=...
/music play world Lobby Faded
/music play world SPVP https://youtu.be/...
---
12. PLAY NOW
Support:
/music playnow all
/music playnow world
This immediately replaces the selected playback state.
Example:
/music playnow all Faded
All players switch to Faded from "00:00".
Example:
/music playnow world Lobby Believer
Only Lobby switches to Believer.
---
13. PAUSE
Global:
/music pause all
World:
/music pause world
Pause the selected playback state.
Record the exact authoritative position.
Example:
"05:27"
All affected players must pause around that position.
---
14. RESUME
Global:
/music resume all
World:
/music resume world
Resume from the stored authoritative position.
---
15. STOP
Global:
/music stop all
World:
/music stop world
Global stop:
- stop global music
- affected players fall back to world-specific music if one exists
- otherwise restore normal Minecraft music
World stop:
- remove that world's custom music
- players fall back to global music if active
- otherwise restore normal Minecraft music
---
16. SKIP
Global:
/music skip all
World:
/music skip world
Advance the corresponding queue.
All affected players switch to the next track.
The new track starts from:
"00:00"
for that playback scope.
---
17. QUEUE
Maintain separate queues.
Global queue:
Global Queue
1. Faded
2. Believer
3. Warriors
Lobby queue:
Lobby Queue
1. Night Changes
2. Perfect
SPVP queue:
SPVP Queue
1. Legends Never Die
2. Till I Collapse
Commands:
/music queue all
/music queue world
/music queue add all
/music queue add world
/music queue clear all
/music queue clear world
/music remove all
/music remove world
Queues must never mix between scopes.
---
18. AUTOMATIC TRACK ADVANCE
When a track finishes:
1. Check loop mode.
2. If TRACK loop is active, replay the same track.
3. If QUEUE loop is active, advance/cycle.
4. Otherwise select the next queue track.
5. If no track exists, stop that playback scope.
6. Synchronize affected players.
---
19. LOOP
Support:
/music loop all off
/music loop all track
/music loop all queue
and:
/music loop world off
/music loop world track
/music loop world queue
Loop state is independent for each playback scope.
---
20. SHUFFLE
Global:
/music shuffle all
World:
/music shuffle world
Shuffle only the selected queue.
Do not automatically replace the current track.
---
21. NOW PLAYING
Support:
/music nowplaying
/music nowplaying all
/music nowplaying world
For a player without an explicit target:
Determine the music currently affecting that player.
Example:
Now Playing
Faded β Alan Walker
03:15 / 03:32
Source: YouTube
Scope: Server
Requested by: Shadow
For a world:
Now Playing
Believer β Imagine Dragons
01:42 / 03:24
Source: YouTube
Scope: SPVP
Requested by: Shadow
---
22. VOLUME
Global:
/music volume all <0-100>
World:
/music volume world <0-100>
Validate values.
Reject:
- negative
- greater than 100
- invalid text
- malformed input
Do not crash.
---
23. SEARCH BY SONG NAME
Example:
/music play all Faded Alan Walker
The plugin must search the configured resolver.
Return:
- title
- artist/channel
- duration
- source
Select the best valid result.
If multiple-result selection is implemented, make it safe and OP-only.
---
24. YOUTUBE
Support:
https://www.youtube.com/watch?v=...
https://youtube.com/watch?v=...
https://youtu.be/...
Requirements:
- validate URLs
- resolve metadata
- use a technically supported playback backend
- handle deleted/private/unavailable content
- handle network errors
- handle timeouts
- never block the Paper main thread
Never execute a raw URL as a shell command.
Do not use unsafe:
"Runtime.exec()"
or uncontrolled:
"ProcessBuilder"
with player input.
---
25. SPOTIFY
Support:
https://open.spotify.com/track/TRACK_ID
Resolve:
- track
- artist
- album
- duration
- track ID
Do NOT bypass:
- DRM
- authentication
- encryption
- access controls
Treat Spotify primarily as metadata/search unless a legitimate supported playback backend is available.
If Spotify cannot directly provide playable audio, resolve the track metadata and use a supported playback source where possible.
Never pretend a song is playing when no client can hear it.
---
26. AUDIO DELIVERY β CRITICAL
A normal Paper plugin cannot simply stream arbitrary YouTube/Spotify audio into vanilla Minecraft using:
"player.playSound()"
Do NOT implement fake playback.
The plugin must use a technically valid audio delivery architecture.
The system must provide a supported way for:
- Java clients
- Bedrock clients through Geyser/Floodgate
to actually hear the selected music.
If a resource pack, client-side component or external audio backend is required:
- integrate it properly
- detect whether it is available
- document installation
- fail gracefully if unavailable
Never claim unsupported functionality is working.
---
27. JAVA AUDIO
Provide a valid Java Edition audio delivery method.
If using a custom resource pack:
- validate pack structure
- validate sound definitions
- validate audio files
- use safe internal sound IDs
- handle pack loading
- cache resources
---
28. BEDROCK AUDIO
Bedrock compatibility is mandatory.
Do NOT assume a Java resource pack automatically works on Bedrock.
Through Geyser/Floodgate, provide a technically valid Bedrock-compatible audio/resource delivery path.
If an additional Bedrock resource pack/addon/client component is required:
- provide the required files/setup
- detect readiness where possible
- explain installation
- synchronize playback using the same server clock
Java and Bedrock must use the same logical playback state.
---
29. RESOURCE PACK SECURITY
Protect against:
- path traversal
- malicious filenames
- corrupted files
- unsafe paths
- invalid sound identifiers
Reject paths such as:
"../../something"
Never allow player input to directly become a filesystem path.
---
30. VANILLA MUSIC
When ServerMusic is active:
Suppress/replace normal Minecraft background music where technically supported.
Do NOT disable other sounds.
Do not affect:
- combat sounds
- blocks
- mobs
- weather
- UI
- player sounds
When ServerMusic stops:
restore normal Minecraft music behavior.
---
31. SYNC CORRECTION
Configuration:
sync:
enabled: true
join-sync: true
tolerance-ms: 500
correction-enabled: true
correction-interval-seconds: 10
If a player drifts beyond tolerance:
correct their playback position.
Do not constantly restart playback.
Only correct meaningful drift.
---
32. SERVER PLAYBACK STATE
Use:
GlobalPlaybackState
and:
WorldPlaybackState
Each state should contain:
scope
currentTrack
playbackState
playbackStartedAt
pausedAt
currentPosition
duration
volume
loopMode
queue
Example:
GlobalPlaybackState
Track: Faded
Position: 03:15
WorldPlaybackState: Lobby
Track: Believer
Position: 01:42
WorldPlaybackState: SPVP
Track: Warriors
Position: 00:58
---
33. EFFECTIVE MUSIC RESOLUTION
For every player, calculate:
"getEffectiveMusicState(player)"
Logic:
IF player's world has active world-specific music:
use that world state
ELSE IF global music is active:
use global state
ELSE:
use normal Minecraft music
Recalculate when:
- player joins
- player changes world
- global playback changes
- world playback changes
- track changes
- pause
- resume
- stop
- volume changes
- loop changes
---
34. WORLD LIST
Worlds do not need to be manually hardcoded.
Any loaded Minecraft world should be targetable.
Examples:
Lobby
SMP
SPVP
world
world_nether
world_the_end
Events
---
35. TAB COMPLETION
For:
/music play world
suggest actual available worlds.
For:
/music stop
suggest:
"all"
"world"
For:
/music loop
suggest valid loop modes.
Never suggest nonexistent worlds.
---
36. OP/PERMISSIONS
By default:
Only OPs control ServerMusic.
Check:
"player.isOp()"
Also support:
servermusic.control
servermusic.admin
servermusic.volume
servermusic.queue
Configuration:
permissions:
op-only: true
Non-authorized players cannot control playback.
---
37. GUI
Optional:
/music gui
Authorized users can access:
- Play
- Pause
- Resume
- Stop
- Skip
- Queue
- Now Playing
- Volume
- Loop
- Shuffle
- Clear Queue
GUI must use the same MusicManager and playback system.
---
38. PLAYER JOIN
When a player joins:
1. Determine world.
2. Find world-specific state.
3. If present, use it.
4. Otherwise use global state.
5. If neither exists, use normal Minecraft music.
6. Synchronize to the current position.
---
39. PLAYER LEAVE
When a player leaves:
- remove their playback session
- do not change global/world playback
- do not reset queues
- do not reset the playback clock
---
40. MULTIPLE OPS
Multiple OPs may issue commands simultaneously.
Use one authoritative MusicManager.
Prevent:
- duplicate playback
- double skip
- race conditions
- queue corruption
- conflicting state updates
---
41. ASYNC OPERATIONS
Never block the Paper main thread with:
- YouTube requests
- Spotify requests
- searches
- metadata lookup
- audio preparation
- resource generation
- cache operations
- external backend requests
Use bounded asynchronous executors.
Return to the main thread only when required by Paper APIs.
---
42. RATE LIMITING
Configuration:
rate-limit:
searches-per-minute: 10
play-requests-per-minute: 10
Apply rate limiting even to OPs.
---
43. SECURITY
Protect against:
- command injection
- URL injection
- path traversal
- malicious filenames
- oversized commands
- malformed URLs
- invalid Unicode
- queue abuse
- resource exhaustion
- excessive network requests
Never expose:
- API keys
- tokens
- passwords
- private credentials
---
44. PERFORMANCE
Do not:
- create one playback engine per player
- create one timer per player
- perform network requests every tick
- restart audio constantly
- load huge libraries into RAM unnecessarily
Use:
- one authoritative clock per playback scope
- efficient caching
- bounded executors
- scheduled synchronization checks
---
45. CONFIG.YML
Create:
"config.yml"
Example:
music:
default-volume: 80
auto-play: false
resume-after-restart: true
loop: off
search-enabled: true
youtube-enabled: true
spotify-enabled: true
permissions:
op-only: true
queue:
max-size: 100
duplicate-tracks: true
auto-skip-failed: true
sync:
enabled: true
join-sync: true
tolerance-ms: 500
correction-enabled: true
correction-interval-seconds: 10
audio:
backend: auto
cache-enabled: true
cache-limit-mb: 512
resource-pack:
enabled: true
auto-send: true
required: false
announcements:
enabled: true
now-playing: true
queue-added: true
skipped: true
rate-limit:
searches-per-minute: 10
play-requests-per-minute: 10
debug: false
---
46. MESSAGES.YML
Create configurable messages for:
music-started
music-paused
music-resumed
music-stopped
music-skipped
track-added
queue-empty
no-permission
invalid-song
song-not-found
playback-error
invalid-volume
syncing
resource-error
backend-error
world-not-found
---
47. TRACK MODEL
Use a proper Track object containing:
id
title
artist
album
duration
source
sourceUrl
backendReference
requestedBy
requestedAt
Do not expose sensitive backend references.
---
48. CLEAN ARCHITECTURE
Use components similar to:
ServerMusicPlugin
|
+-- MusicCommand
|
+-- MusicManager
|
+-- PlaybackManager
|
+-- GlobalPlaybackState
|
+-- WorldPlaybackState
|
+-- QueueManager
|
+-- TrackResolver
| +-- YouTubeResolver
| +-- SpotifyResolver
| +-- SearchResolver
|
+-- AudioBackend
|
+-- ResourcePackManager
|
+-- PlayerSyncManager
|
+-- WorldMusicManager
|
+-- PermissionManager
|
+-- ConfigManager
|
+-- CacheManager
Do not put everything in one class.
---
49. PERSISTENCE
If:
resume-after-restart: true
store safely:
- global track
- global position
- global queue
- world tracks
- world positions
- world queues
- volume
- loop state
- playback state
After restart:
- validate tracks
- restore state
- prepare audio
- resume where possible
- skip unavailable tracks
- never crash
---
50. WORLD PERSISTENCE
World-specific music must remain associated with the correct world.
Do not rely only on temporary player data.
Use world identifiers/names safely.
If a configured world no longer exists:
- do not crash
- log a warning
- ignore that world until it exists again
---
51. PLUGIN DEPENDENCIES
Required:
- Paper 26.2 API
- Java 25
Optional:
- Geyser
- Floodgate
- audio backend
If optional dependencies are unavailable:
- detect them
- disable only affected functionality
- show clear error messages
- never crash the server
---
52. PAPER PLUGIN DESCRIPTOR
Create a valid Paper plugin descriptor for Paper 26.2.
Include:
- plugin name
- version
- main class
- authors
- commands
- permissions
- optional dependencies
Verify the target API is correct.
Do not accidentally compile for Paper 1.21.x.
Target is:
Paper 26.2.
---
53. JAVA 25
Compile and test against:
Java 25
Do not use an incompatible Java target.
---
54. ERROR HANDLING
Handle:
- invalid URLs
- missing songs
- unavailable videos
- private videos
- network failures
- timeouts
- backend failures
- resource-pack failures
- unsupported formats
- Geyser failures
- player disconnects
- world deletion
- corrupted configuration
- corrupted saved data
None may crash the server.
---
55. LOGGING
Support:
INFO
WARNING
ERROR
DEBUG
Configuration:
debug: false
Never spam the console.
Never log secrets.
---
56. NO FAKE IMPLEMENTATIONS
Do not leave core features as:
TODO
FIXME
placeholder
fake playback
return null
not implemented
Do not report:
"Now Playing"
unless the playback system actually has a valid way to deliver audio.
---
57. COMMAND SUMMARY
The final command system should support at minimum:
/music help
/music play
/music play all
/music play world
/music playnow all
/music playnow world
/music pause all
/music pause world
/music resume all
/music resume world
/music stop all
/music stop world
/music skip all
/music skip world
/music queue all
/music queue world
/music queue add all
/music queue add world
/music queue clear all
/music queue clear world
/music remove all
/music remove world
/music shuffle all
/music shuffle world
/music nowplaying
/music nowplaying all
/music nowplaying world
/music volume all <0-100>
/music volume world <0-100>
/music loop all
/music loop world
/music gui
The implementation may provide convenient aliases, but the above functionality must exist.
---
58. TESTING
Before declaring the plugin finished, test:
Basic
- "/music help"
- song-name search
- YouTube URL
- Spotify URL
- play
- playnow
- pause
- resume
- stop
- skip
- queue
- remove
- shuffle
- volume
- loop
Global
- global playback
- players in different worlds
- global synchronization
- new player joining
- player leaving/rejoining
- world changes
- global pause/resume
- global skip
World
- Lobby music
- SPVP music
- SMP music
- world-specific queue
- world-specific pause
- world-specific resume
- world-specific skip
- world-specific volume
- world-specific loop
- world-specific shuffle
- world-specific stop
Priority
Test:
Global music active
+
Lobby music active
Expected:
Lobby β Lobby music
Other worlds β Global music
Then stop Lobby music.
Expected:
Lobby β Global music
Then stop global music.
Expected:
Players without world music β normal Minecraft music
Synchronization
Test:
- player joins at 00:30
- player joins at 03:15
- player joins at 05:00
- player leaves and rejoins
- multiple players join simultaneously
- Java player joins
- Bedrock player joins
- Java player changes world
- Bedrock player changes world
- resource loading delay
- pause/resume
- skip
- track transition
Failure
Test:
- invalid URL
- deleted YouTube video
- unavailable track
- invalid Spotify URL
- network timeout
- backend unavailable
- resource failure
- invalid world
- corrupted config
- corrupted saved data
- oversized queue
- multiple OPs issuing commands
The server must remain stable.
---
59. FINAL DELIVERABLES
Provide:
1. Complete source code.
2. Compiled JAR.
3. "config.yml".
4. "messages.yml".
5. Required resource-pack/audio files or generation system.
6. Java setup instructions.
7. Bedrock/Geyser setup instructions.
8. Required dependencies.
9. Command documentation.
10. Permission documentation.
11. Troubleshooting documentation.
12. Audio backend documentation.
13. Java/Bedrock synchronization documentation.
14. Full testing checklist.
---
60. FINAL NON-NEGOTIABLE REQUIREMENTS
Plugin: ServerMusic
Target: Paper 26.2
Java: Java 25
Control: OP-only by default
Input: Song name + YouTube URL + Spotify URL
Listeners: Entire server or selected world
Java: Supported
Bedrock/Geyser: Supported
Global mode: "/music play all "
World mode: "/music play world "
Global synchronization: ONE playback clock
World synchronization: ONE playback clock per world-specific playback state
Join synchronization: Start at the current position
Rejoin synchronization: Start at the current position
World-change synchronization: Switch to the destination world's current position
Global priority: World-specific music overrides global music
Fallback: World-specific β Global β Normal Minecraft music
Queue: Separate queue per playback scope
Pause: Synchronized
Resume: Synchronized
Skip: Synchronized
Volume: Per playback scope
Loop: Per playback scope
Shuffle: Per playback scope
Vanilla music: Suppressed/replaced while ServerMusic is active where technically supported
Security: No unsafe command execution
Performance: No blocking network operations on the main thread
Stability: No external/backend/resource failure may crash the server
Most important rule:
The music is owned by the playback scope, NOT by individual players.
For "ALL" mode:
ONE SERVER β ONE SONG β ONE PLAYBACK POSITION β EVERY WORLD β EVERY PLAYER
For world mode:
ONE WORLD β ONE SONG β ONE PLAYBACK POSITION β EVERY PLAYER IN THAT WORLD
If a player joins at "03:15", they hear approximately "03:15".
If they join at "04:42", they hear approximately "04:42".
If they leave at "04:00" and return at "05:10", they hear approximately "05:10".
Never restart the song for a joining/rejoining player.
Never create independent playback timelines for players.
Build, compile, validate and test the complete implementation before declaring it finished.
Create the Paper 26.2 / Java 25 project and authoritative global/world playback-state core.
Add synchronized player/world handling and an explicit audio-backend boundaryβnever claim audio is playing without a real provider.
Add commands, validation, configuration, and persistence around that core.
Paper alone cannot stream arbitrary YouTube/Spotify audio to Java and Bedrock clients. The implementation will keep that limitation explicit and refuse unsupported playback rather than simulate it.
Created the ServerMusic control layer, but this is not yet the complete production plugin described in the prompt.
It includes the Java 25 / Paper 26.2 project setup, authoritative global and per-world clocks, world-over-global priority, queues and loop modes, join/world-change synchronization hooks, persistence, commands, permissions, rate limiting, and setup/troubleshooting documentation.
Actual audio delivery is not included. There is no bundled YouTube/Spotify resolver or Java/Bedrock audio backend, so /music play safely refuses to start without registered providers. Java and Bedrock playback, resource packs, and end-to-end synchronization therefore remain unimplemented and unverified. This avoids reporting music as playing when clients cannot hear it.
Fix it
π
ServerMusic-1.0.1-fix-prompt.txt
txt
856 lines
βΆ
SERVERMUSIC 1.0.0 β PRODUCTION FIX PROMPT
You are fixing the existing "ServerMusic-1.0.0" plugin.
TARGET
- Plugin: ServerMusic
- Paper: 26.2
- Java: 25
- Java Edition + Bedrock through Geyser/Floodgate
The existing JAR already contains the basic architecture, including components such as:
- MusicManager
- TrackResolver
- AudioBackend
- PlayerSyncManager
- PlaybackPersistence
- commands
- permissions
- rate limiting
- configuration
- messages
Do NOT rewrite working components unnecessarily.
The major problem is that the current implementation contains interfaces/abstractions for resolving and playing music, but does not provide a complete real implementation capable of obtaining supported audio and delivering it to Minecraft clients.
Fix this properly.
---
1. NO FAKE PLAYBACK
This is the most important requirement.
Do NOT make commands merely display:
"Now Playing: Faded"
while no player can actually hear anything.
Do NOT simulate playback with:
- console messages
- timers only
- fake sound IDs
- "player.playSound()" pretending to be arbitrary YouTube audio
- placeholder AudioBackend implementations
- empty TrackResolver methods
A track is only considered playing when there is an actual supported audio-delivery path.
---
2. IMPLEMENT REAL TRACK RESOLUTION
Implement the existing "TrackResolver" architecture.
Create real implementations such as:
TrackResolver
βββ YouTubeResolver
βββ SpotifyResolver
βββ SearchResolver
They must actually resolve supported input.
Supported input:
/music play
/music play
/music play
---
3. YOUTUBE
Support common YouTube URLs:
https://www.youtube.com/watch?v=...
https://youtu.be/...
The resolver must obtain:
- title
- artist/channel
- duration
- source URL
- backend reference required by the audio backend
Handle safely:
- invalid URL
- deleted video
- private video
- unavailable video
- timeout
- network failure
- unsupported content
Do all network work asynchronously.
Never block the Paper main thread.
---
4. SPOTIFY
Support:
https://open.spotify.com/track/
Resolve:
- title
- artist
- album
- duration
- track ID
Do NOT bypass Spotify DRM, authentication, encryption, or access controls.
A Spotify URL may be used to identify the requested track.
If the selected audio backend cannot legally/directly obtain playable audio from Spotify, resolve its metadata and use an authorized/supported playback source instead.
Never claim Spotify audio is playing if it is not actually available.
---
5. SONG-NAME SEARCH
Implement actual search.
Example:
/music play Faded Alan Walker
The plugin should:
1. Search the configured provider.
2. Find a valid result.
3. Resolve its metadata.
4. Pass the result to the AudioBackend.
5. Begin synchronized playback only after the backend confirms it is ready.
If no result exists:
Song not found.
Do not create fake tracks.
---
6. ACTUAL AUDIO BACKEND
The current "AudioBackend" abstraction must have a real production implementation.
Do not leave:
return null;
or:
throw new UnsupportedOperationException();
for the primary playback path.
Implement a concrete backend capable of delivering actual audio.
---
7. IMPORTANT MINECRAFT LIMITATION
A normal Paper server cannot directly stream arbitrary YouTube/Spotify audio to vanilla Minecraft clients simply by calling:
player.playSound(...)
Do not attempt to fake this.
Use a technically valid audio-delivery architecture.
The implementation must clearly define:
Internet
β
Track Resolver
β
Audio Source / Cache
β
Audio Backend
β
Minecraft-compatible audio delivery
β
Players
---
8. RESOURCE-PACK AUDIO
If the chosen architecture uses Minecraft resource-pack audio:
Implement the complete system.
It must include:
- valid resource-pack structure
- generated sound definitions
- valid audio files
- correct sound identifiers
- pack generation/update
- pack hashing
- safe caching
- client preparation
- playback control
- cleanup
Do not merely generate an empty resource pack.
---
9. AUDIO CONVERSION
If the source audio format is not directly compatible with the chosen Minecraft audio system:
Implement a proper conversion pipeline.
The conversion system must:
- run asynchronously
- validate input
- produce the required format
- handle conversion failure
- clean up temporary files
- enforce file-size limits
- prevent malicious paths
Do not run arbitrary commands from player input.
If an external media utility is required, its executable path must be configured/admin-controlled and arguments must be constructed safely.
Never pass the complete player-supplied URL as a shell command.
---
10. INTERNET CONNECTION
Clearly separate internet access into these components:
YouTubeResolver
SpotifyResolver
SearchResolver
AudioBackend
Only these components should perform external network operations.
The core playback state itself should NOT depend on making a web request every tick.
Do not continuously download/query the internet for playback position.
---
11. CACHE
Implement proper caching.
Example:
audio:
backend: auto
cache-enabled: true
cache-limit-mb: 512
When a track has already been prepared:
Request
β
Cache lookup
β
Cached audio found
β
Play without downloading again
When it is not cached:
Request
β
Resolver
β
Download/prepare
β
Cache
β
Play
The cache must use safe identifiers.
Never use raw URLs directly as filesystem paths.
---
12. OFFLINE MODE
If a track is already cached and playable:
The server should be able to play it without contacting the external source again, provided the selected audio-delivery backend supports offline cached playback.
If a track is not cached:
No internet
+
No cached audio
=
Playback unavailable
Show a clear error instead of pretending playback started.
---
13. PLAYBACK STATE
Do not modify the existing authoritative playback architecture unnecessarily.
Maintain:
GlobalPlaybackState
WorldPlaybackState
Each state must contain:
currentTrack
playbackState
playbackStartedAt
pausedAt
currentPosition
duration
volume
loopMode
queue
---
14. EXACT SYNCHRONIZATION
This MUST remain server-authoritative.
For global playback:
ONE GLOBAL CLOCK
For each world-specific playback:
ONE WORLD CLOCK
Never create an independent music clock per player.
---
15. JOIN SYNC
If global music is currently:
Faded
03:15
and a player joins:
Do NOT start at:
00:00
Prepare the audio first.
After preparation/loading, recalculate the current authoritative position.
If 5 seconds passed:
Start approximately at:
03:20
---
16. REJOIN SYNC
If a player leaves at:
04:00
and rejoins at:
04:42
they must start approximately at:
04:42
Do not restore an old personal position.
---
17. WORLD SYNC
Priority remains:
WORLD MUSIC
β
GLOBAL MUSIC
β
VANILLA MUSIC
Example:
Global:
Faded β 03:15
Lobby:
Believer β 01:42
Lobby players hear:
Believer β 01:42
Other worlds hear:
Faded β 03:15
---
18. WORLD CHANGE
When a player changes worlds:
1. Stop the old scope's audio.
2. Determine the destination world's effective music.
3. Prepare the destination audio if required.
4. Recalculate its current position.
5. Start at the current position.
Use the appropriate Paper world-change event.
Do not attempt to detect world changes by parsing commands.
---
19. PAUSE
When:
/music pause all
is executed:
1. Calculate exact current position.
2. Store it in GlobalPlaybackState.
3. Pause all affected players.
4. Do not advance the authoritative clock while paused.
Same principle for world-specific music.
---
20. RESUME
When resumed:
1. Keep the stored position.
2. Set a new playback start timestamp.
3. Start all affected players from the same position.
4. Recalculate position after loading.
---
21. SKIP
When skipped:
1. Stop current playback.
2. Select the next track.
3. Resolve/prepare it asynchronously.
4. Start it at "00:00".
5. Update authoritative state.
6. Synchronize all affected players.
---
22. QUEUES
Keep queues independent:
Global Queue
Lobby Queue
SPVP Queue
SMP Queue
...
Do not mix them.
---
23. EXISTING COMMANDS
Preserve and verify:
/music play
/music play all
/music play world
/music playnow all
/music playnow world
/music pause all
/music pause world
/music resume all
/music resume world
/music stop all
/music stop world
/music skip all
/music skip world
/music queue all
/music queue world
/music queue add all
/music queue add world
/music queue clear all
/music queue clear world
/music remove all
/music remove world
/music shuffle all
/music shuffle world
/music nowplaying
/music nowplaying all
/music nowplaying world
/music volume all <0-100>
/music volume world <0-100>
/music loop all
/music loop world
/music gui
/music help
---
24. OP/PERMISSIONS
Default:
permissions:
op-only: true
Support:
servermusic.control
servermusic.admin
servermusic.volume
servermusic.queue
Non-authorized players must not control playback.
---
25. JAVA + BEDROCK
The actual audio architecture must explicitly support both:
Java Edition
Bedrock Edition via Geyser/Floodgate
Do NOT assume Java resource-pack audio automatically works on Bedrock.
If Bedrock requires:
- a separate resource pack
- Geyser-compatible setup
- additional supported component
implement/document it.
If a feature genuinely cannot work through vanilla/Geyser clients, report that honestly rather than pretending it works.
---
26. PERFORMANCE
Never perform:
- YouTube requests
- Spotify requests
- searches
- downloads
- audio conversion
- resource generation
on the Paper main thread.
Use bounded async workers.
Do not create a thread per player.
Do not run network requests every tick.
---
27. SECURITY
Protect against:
- command injection
- URL injection
- path traversal
- malicious filenames
- huge downloads
- oversized queues
- malicious URLs
- resource exhaustion
Player input must never become an executable command.
Player input must never directly become an unrestricted filesystem path.
---
28. ERROR HANDLING
Every failed resolver/backend operation must produce a useful message.
Examples:
Unable to resolve this song.
The video is unavailable.
The audio backend is unavailable.
This track is not cached and cannot be downloaded.
The audio resource could not be prepared.
The requested world does not exist.
Never silently pretend success.
Never crash the server.
---
29. CONFIGURATION
Ensure the existing configuration contains:
music:
default-volume: 80
auto-play: false
resume-after-restart: true
loop: off
search-enabled: true
youtube-enabled: true
spotify-enabled: true
permissions:
op-only: true
queue:
max-size: 100
duplicate-tracks: true
auto-skip-failed: true
sync:
enabled: true
join-sync: true
tolerance-ms: 500
correction-enabled: true
correction-interval-seconds: 10
audio:
backend: auto
cache-enabled: true
cache-limit-mb: 512
resource-pack:
enabled: true
auto-send: true
required: false
rate-limit:
searches-per-minute: 10
play-requests-per-minute: 10
debug: false
Add any additional backend configuration required by the actual implementation.
---
30. NO BROKEN ABSTRACTIONS
Every core interface must have a working implementation.
Audit:
TrackResolver
AudioBackend
PlayerSyncManager
PlaybackPersistence
CacheManager
ResourcePackManager
Search the entire project for:
TODO
FIXME
UnsupportedOperationException
return null
empty implementation
placeholder
fake
mock
stub
Do not leave production-critical stubs.
---
31. BUILD VALIDATION
Build the plugin for:
Paper 26.2 + Java 25
Verify:
- JAR builds successfully
- plugin loads successfully
- no dependency errors
- no class-loading errors
- no runtime exceptions on startup
- commands register
- permissions register
- configuration loads
- messages load
---
32. FINAL TEST
Actually test:
YouTube
/music play all
Confirm players can actually hear the audio.
Spotify
/music play all
Confirm the selected supported playback path actually produces audio.
Search
/music play Faded Alan Walker
Confirm actual playback.
Global synchronization
Put players in different worlds.
Start:
/music play all Faded
Confirm they hear the same position.
World synchronization
Start:
/music play world Lobby Believer
Confirm only Lobby hears it.
Join
Join during:
03:15
Confirm the player starts near the current position after loading.
Rejoin
Leave at:
04:00
Return at:
04:42
Confirm playback begins near "04:42".
World change
Move:
Lobby β SPVP
Confirm the effective music changes correctly.
Fallback
Stop world-specific music.
Confirm players fall back to global music.
Stop global music.
Confirm players fall back to vanilla music.
---
33. FINAL REQUIREMENT
Do not declare the plugin fixed merely because the JAR compiles.
It is fixed only when:
1. Track resolvers actually resolve tracks.
2. AudioBackend actually delivers audio.
3. Java players can hear it.
4. Bedrock compatibility is correctly implemented or clearly handled.
5. Global playback is synchronized.
6. World playback is synchronized.
7. Join/rejoin synchronization works.
8. World-change synchronization works.
9. Cached playback works where supported.
10. Internet failures are handled gracefully.
11. No fake playback remains.
12. Paper 26.2 + Java 25 compatibility is verified.
Return a new production-ready:
"ServerMusic-1.0.1.jar"
and the updated source/configuration required for the complete implementation.
Audit the existing playback, resolver, backend, sync, cache, persistence, command, and configuration paths.
Implement the smallest complete fix supported by the projectβs current architecture; avoid claiming audio delivery the client platform cannot provide.
Update configuration and user-facing errors, then validate the resulting code paths.
Updated the command path so resolver calls run asynchronously, a missing resolver reports a specific error, /music play queues when its scope is already active, and /music playnow replaces the current track.
This does not make the plugin production-ready for audio delivery. The project still has no concrete track resolver or audio backend, and no cache or resource-pack manager. Paperβs normal sound API cannot stream arbitrary YouTube or Spotify audio, and Java resource-pack audio does not provide Bedrock support. I canβt honestly claim this produces audible playback or return it as a production-ready ServerMusic-1.0.1.jar; no build or client playback tests were performed.
package com.kodari.servermusic;
import org.bukkit.plugin.java.JavaPlugin;
import com.kodari.servermusic.audio.AudioBackend;
import com.kodari.servermusic.sync.PlayerSyncManager;
import com.kodari.servermusic.command.MusicCommand;
import com.kodari.servermusic.persistence.PlaybackPersistence;
import java.util.Objects;
import org.bukkit.scheduler.BukkitTask;
public final class ServerMusicPlugin extends JavaPlugin {
private MusicManager musicManager;
private PlayerSyncManager playerSyncManager;
private PlaybackPersistence persistence;
private BukkitTask persistenceTask;
@Override
public void onEnable() {
saveDefaultConfig();
saveResource("messages.yml", false);
int maxQueueSize = Math.max(1, getConfig().getInt("queue.max-size", 100));
int defaultVolume = Math.clamp(getConfig().getInt("music.default-volume", 80), 0, 100);
musicManager = new MusicManager(maxQueueSize, defaultVolume);
persistence = new PlaybackPersistence(getDataFolder(), musicManager,
getConfig().getBoolean("music.resume-after-restart", true));
persistence.load();
playerSyncManager = new PlayerSyncManager(this, musicManager);
getServer().getPluginManager().registerEvents(playerSyncManager, this);
playerSyncManager.start();
MusicCommand musicCommand = new MusicCommand(this, musicManager, playerSyncManager);
Objects.requireNonNull(getCommand("music")).setExecutor(musicCommand);
Objects.requireNonNull(getCommand("music")).setTabCompleter(musicCommand);
persistenceTask = getServer().getScheduler().runTaskTimerAsynchronously(this, persistence::save, 1200L, 1200L);
try {
AudioBackend backend = getServer().getServicesManager().load(AudioBackend.class);
if (backend == null || !backend.isAvailable()) {
getLogger().warning("No compatible ServerMusic audio backend is installed. Playback requests must fail closed; no audio is simulated.");
}
} catch (RuntimeException exception) {
getLogger().warning("The ServerMusic audio backend could not be checked. Playback requests must fail closed.");
}
}
@Override
public void onDisable() {
if (persistenceTask != null) persistenceTask.cancel();
if (persistence != null) persistence.save();
if (playerSyncManager != null) {
playerSyncManager.stop();
}
}
public MusicManager getMusicManager() {
return musicManager;
}
public PlayerSyncManager getPlayerSyncManager() {
return playerSyncManager;
}
}