Harmonia v1.0

Your jukeboxes sit silent. Your players collect music discs they never use because there is no reason to. A jukebox plays a song for a few minutes and then nothing. It is a vanity block at best, forgotten inventory clutter at worst.

Harmonia turns every jukebox into a buff station. Insert a music disc and the jukebox projects an aura. Every player inside the radius receives potion effects tied to that disc. Pigstep gives Strength. Cat gives Speed. Ward gives Resistance. Your jukeboxes go from decoration to infrastructure.

No commands. No economy. No gimmicks. Just vanilla potion effects delivered through a system that runs at tick-level performance with zero world scans.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Core Features

Every disc is configurable. Every aura is instant. Every mechanic is vanilla.


◆ All 22 Music Discs Supported

• Every vanilla disc from 13 to bounce, including pigstep, otherside, relic, creator, precipice, and tears
• Version-aware loading: discs unavailable on your server version are silently skipped with a console note
• Same config.yml works on Paper 1.21.0 through 1.21.4+ without edits

• Individual radius per disc in blocks
• Custom potion effect list with configurable amplifier levels
• Enable or disable any disc without deleting its configuration
• Optional per-disc permission locks for progression gating

• Single repeating task at configurable tick rate, no per-tick block scanning
• Cached active jukebox list with O(1) lookups
• Chunk-aware cleanup on unload
• Zero world scans, zero memory leaks, zero tick spam

• Each disc tracks its own play duration
• Restarts automatically two seconds before natural end
• Short discs like 11 (71s) loop sooner, long discs like blocks (345s) loop later
• Toggleable via config: loop forever or let discs finish naturally

• /harmonia gui opens a multi-page inventory of every configured disc
• Each disc shows status, radius, effects, and how to obtain it in vanilla
• Click any disc to open a detail view with full effect breakdown
• Dynamic navigation adapts to any inventory size
• Permission-locked indicators show players what they can and cannot access

• harmonia.use: receive any aura effect (default: true)
• harmonia.disc.pigstep: per-disc permission for progression
• harmonia.bypass.radius: receive effects regardless of distance
• harmonia.admin: inherits reload, gui, and bypass
• harmonia.gui: open the disc browser

• English, Polish, German, Spanish, French, Russian, Chinese, Italian, Portuguese, Japanese, Korean, Dutch, Turkish
• All GUI labels, messages, disc obtainment info, and notifications are translated
• New languages auto-extract from the JAR on update without overwriting your edits
• Switch language in config.yml and /harmonia reload

• Jukebox broken while playing: effects removed instantly, no lingering buffs
• Disc ejected mid-play: aura deactivates, all effects cleaned
• Player logs out: tracked effects cleared from memory
• Chunk unloaded: jukeboxes in that chunk deactivated
• Server restart: full cleanup on disable
• Fast disc swap: old effects removed, new disc effects applied immediately

• Async GitHub release check on startup
• Admins notified on join when a new version is available
• Your config.yml and language files are never overwritten during updates

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Default Disc Effects[/CENTER]


Every value above is the default. Change any disc's radius, effects, and amplifier levels in config.yml.

• Survival and SMP servers Give players a reason to hunt music discs. Pigstep becomes a combat buff. Cat becomes a movement tool. Every disc has value beyond decoration.
• RPG and progression servers Lock discs behind permissions. Players unlock stronger auras as they progress. Ward requires a boss kill. Creator requires exploration. Build a reward system around jukeboxes.
• Community builders Place jukeboxes in community areas. Your spawn has Haste from blocks. Your farm has Speed from cat. Your PvP arena has Resistance from ward. Jukeboxes become infrastructure.
• Plugin enthusiasts Clean architecture, SOLID principles, zero deprecated API, full Adventure Component support. The codebase is built like a premium SaaS product because it is one.