# [3.7.0] - 2026-10-02 ### Added - **Point-source zones** (`/cjb zone source <zone> point`): music plays from the zone center, fades with distance and is not cut off when leaving. Optional; zones default to the previous behaviour. - **Zone jukebox** (`/cjb zone jukebox <zone>`): a placeable jukebox the zone plays from, with note particles; break it to move the zone. - Update notice for operators with clickable Modrinth and CurseForge links. ### Fixed - Fragment crafting no longer duplicates discs. - Unreadable `disc.json`, `zones.json`, `config.json`, `players.json` or language files are kept and no longer overwritten. - `/cjb skip` only skips playlists and zones; ending a single disc needs `customjukebox.stop`. Favourites need `customjukebox.playlist` for wider ranges. - Trail ruins now actually drop fragments when brushed. - Various fixes to shutdown, world unloading, Folia thread safety, GUI chat input and input validation.

## [3.6.0] - 2026-08-31 ### Added - **Volume in decibels** for the server, zone and personal commands: `-6db` is half, `-12db` a quarter, `-20db` a tenth — easier to judge by ear than the linear scale, where 0.5 does not sound half as loud. - **Presets and percentages** for zone and personal volume too, not just the server one: `silent`, `quiet`, `normal`, `loud`, `max` and values such as `30%`. - **Volume feedback names what it did** — `0.30 (30%, -10.5 dB)` — and warns above 1.0 that the sound is already at full loudness and only carries further, since Minecraft widens the radius (`volume * 16` blocks) rather than raising the gain. - **`/cjb zone volume <zone> <value> norestart`**, to let the current track finish at its old volume. - **`ambient-zones.pause-during-disc`**, to keep discs and zone music layered. ### Changed - All three volume commands share one parser, so their presets and ranges cannot drift apart. - The author prompt in the disc editor shows the formatting example itself, instead of pointing at the display name prompt that whoever opens the author field first never sees. - Editor titles drop the namespace prefix a server's disc ids share: `Edit: music_disc.newbeginnings_theme` becomes `Edit: newbeginnings_theme`. The prefix is read from the ids in use rather than assumed, so `custom.` or a multi-level one works the same; where ids do not all share one, nothing is stripped. ### Fixed - **Colour codes in a disc's author field were printed instead of applied** — `&eArtist` reached the tooltip as the literal text `<yellow>Artist`. Legacy codes are now recognised with either marker (`&` or `§`) and in either case, so hex and gradients survive as well. The same fix covers everywhere else the two markers were mixed: fragment lore, the jukebox subtitle, GUI text. - **A disc and an ambient zone played over each other.** The zone now falls silent for the listeners who can hear a disc and returns when it ends — not between the tracks of a playlist, where the next one starts immediately. - **A zone's own volume followed the server volume** for anyone with a personal volume set: at the shipped server volume of 4.0, a zone at 0.2 collapsed to a twentieth of the player's setting. An explicit zone volume is absolute now; only zones on `inherit` follow the server. - **`/cjb music volume` did nothing until the current track ended** — minutes, on a looping zone. It restarts what that one player hears, immediately. - **`/cjb volume ... restart` ignored ambient zones**, restarting jukebox playbacks only. The same applied to `/cjb mute` and `/cjb unmute`. - **`norestart` had no effect**, because saving a zone restarted it before the flag was read. - **Tab completion offered no quiet value.** `/cjb zone volume` suggested `inherit, 1, 2, 3, 4`, and since 1.0 is already full loudness, turning a zone down reliably ended at 1 and stayed loud. - **`/cjb volume` looked broken to an admin with a personal volume set**, which replaces the server volume rather than scaling it. The command now says which value wins and how to undo it. - **Chat confirmations printed the markup they had just applied**, while the item itself came out correctly coloured. - **Long names ran past the edge of the GUI** — admin panel entries and all five editor titles are shortened now, measured in visible characters so a gradient's tags are not cut in half. The disc item players receive keeps its full name. - **Language files never gained messages added after they were first written**; one long-running server was missing 170 of its 226. Missing messages are written in on every start, strictly additively — existing lines and comments are untouched.

## [3.5.0] - 2026-08-26 ### Added - **Per-player sound delivery hooks** — `CustomSoundPlayEvent` and `CustomSoundStopEvent`, both cancellable, fire once per player immediately before a custom disc sound is sent or stopped. Every delivery path passes through them: jukebox playback, a listener attaching to a running playback, `/cjb music on`, and ambient zones (including radio). Companion plugins that need to deliver a sound differently for some players — the Bedrock extension speaks a different sound namespace — cancel the event and play it themselves. Cancelling suppresses only that one sound packet; the player stays a tracked listener, so progress bar, `/cjb skip` and stop handling keep working for them. - **Disc items now carry their disc id as a `custom_model_data` string tag** in addition to the existing float. Java resource packs are unaffected (they select models by the float); the string gives Geyser an exact, unambiguous key to match a Bedrock item against, which a float threshold cannot provide. Disc items handed out before this version keep working but lack the tag — re-issue them with `/cjb give` if Bedrock textures matter.

## [3.4.0] - 2026-08-16 ### Added - **`/cjb skip`** — skips the track you are currently hearing. Resolves the source the same way the progress bar does: an ambient zone you are standing in takes precedence over a jukebox you are merely in range of. In a `synced` zone the whole zone advances; in an `individual` zone only your own cursor moves on. There is deliberately no "previous track": a resource-pack sound can only be started from its beginning, so going back would just be skipping forward through the rest of the playlist. - **Progress bar** — a boss bar showing the current track and how far into it you are, for jukeboxes, zones and radio alike. The elapsed time is the plugin's own bookkeeping (the server never learns the client's real playhead), which is exact for anyone present when the track started. Configurable via `playback.show-progress-bar` and `playback.progress-update-ticks`. This finally uses the timing methods `JukeboxPlayback` has carried unused since 1.x. - **Shuffle and repeat modes for playlists**: `/cjb playlist play <id> [shuffle] [loop|repeat-one|off]`, order-independent. Shuffling reshuffles on every lap (and avoids repeating a track across the wrap) so a looping playlist is not one fixed sequence forever. - **Shuffle for ambient zones**: `/cjb zone shuffle <id> <true|false>`, plus a toggle in the zone editor GUI. - **Server radio** — a new zone type that reaches every player in every world: `/cjb zone global <id>`. It reuses the whole zone machinery, so a radio station has the same playlist, loop, shuffle, playback mode and volume options, and a local zone with a higher `priority` still overrides it for players standing inside that zone. - **Personal music settings** (`/cjb music`, permission `customjukebox.music`, default true): `on`/`off`/`toggle` to opt out of plugin music entirely, `volume <0-4|reset>` for a personal volume, and `status` to see your settings plus what is currently playing. Both persist across sessions in a new `players.json`. A personal volume replaces the server volume rather than scaling it, so it stays predictable when an admin changes the global value; a server-wide `/cjb mute` still wins. Turning music off silences the current track immediately rather than at its end. - **Favourites** (`/cjb favorite`, permission `customjukebox.favorite`, default true): `add`/`remove`/`toggle`/`list`/`clear`, and `play [shuffle] [loop|repeat-one] [global|world|<radius>]` to play them as an ad-hoc playlist. Discs can also be favourited by shift-clicking them in the disc menu, which shows a ★ for entries already on the list. ### Fixed - **`/cjb music on` stayed silent until the next track.** A jukebox/playlist listener set is only filled when a track *starts*, and turning music off removed the player from it - nothing put them back mid-track. Re-enabling now re-attaches immediately: zones re-evaluate in the same tick instead of at the next scan, and any playback within earshot starts for that player. The track necessarily restarts from its beginning for them (the sound engine cannot seek), which the plugin now says out loud instead of leaving it to be discovered. - **`/cjb skip` reported "nothing playing" when something clearly was.** It resolved the playback strictly by listener membership, so a player who had just re-enabled their music - or who walked up after the track started - was told there was nothing to skip. Skip now resolves by earshot, preferring what the player actually hears and falling back to what is playing in range. - Both were found within minutes of the first real in-game test, and both traced back to the same root: listener sets are only populated at track boundaries. ### Changed - **`/cjb playlist play` and `/cjb favorite play` accept a playback range**: `[global|world|<radius>]`, the same vocabulary `/cjb play` already used. The queue stored a range all along and passed it to every following track - only the command never exposed it, so playlists were locked to `normal`. For permanently server-wide music a radio zone (`/cjb zone global`) remains the better tool; a global-range playlist is a one-off from your position. - **`all` is no longer a repeat-mode alias.** It means "server-wide range" in `/cjb play`, and now that the play commands accept both kinds of flag it would have meant two different things depending on the command. `loop`, `true` and `yes` still select repeat-all. ### Notes - Volume changes — personal or server-wide — apply from the next track. A sound already handed to the client cannot be adjusted, only restarted. - `players.json` only stores players who actually changed something; entries that are all-default are dropped on save.

## [3.3.0] - 2026-07-19 ### Added - **Ambient zones — auto-playing looping playlists for regions/areas**: a zone continuously loops a playlist and starts automatically for every player who enters its area, with no disc or command needed once configured. Ideal for lobby/hub background music or event ambience. Zones are stored in a new `zones.json` and managed via `/cjb zone` (permission `customjukebox.zone`, default op) or the `/cjb zone edit <id>` GUI. - **Three area types**: a **radius** around a point (no dependencies), a named **WorldGuard region** (`/cjb zone region <id> <region>`), or a **cuboid** box between two corner positions (`/cjb zone pos1 <id>` / `/cjb zone pos2 <id>`, covering the full block range between them like a WorldGuard selection). Overlapping zones resolve by `priority` (highest wins). - **Height range** (`/cjb zone height <id> <full|limited>`): by default (`full`) a zone ignores the Y axis — a radius zone is a vertical **cylinder** and a cuboid an infinite **column**, so players hear it at any height within the horizontal footprint. `limited` bounds the zone in Y too (a true 3D sphere/box). Defaults to `full` so lobbies aren't limited to a few blocks of vertical range. - **Whole-playlist loop**: each zone loops its playlist back to the first track at the end. - **Per-zone playback mode** (`/cjb zone playback <id> <synced|individual>`): - `synced` (default): one shared timeline — everyone in the zone hears the same track at the same time. Best for events. Late arrivals are handled by two **sync modes** (`/cjb zone sync <id> <immediate|next_track>`): `immediate` starts the current track from its beginning for a player who walks in mid-track (never silence, slightly offset); `next_track` waits for the next track boundary so they join perfectly in sync. This is because Minecraft's sound engine cannot seek — a running track cannot be joined at its exact current position; everyone re-syncs at each track boundary regardless. - `individual`: each player runs the playlist on their own from the moment they enter, always hearing **complete tracks start-to-finish** (no mid-song switching), looping the whole playlist — but not in sync with other players. Best for lobby/background music. `syncMode` does not apply here. - **Per-zone options**: `playlist`, `loop`, `playback`, `syncMode`, `fullHeight` (see Height range), `volume` (`inherit` or 0–4, controlling audible radius), `priority`, `enabled`. Set via subcommands or the editor GUI; `/cjb zone radius|center`, `pos1|pos2` and `region` shape the area from your position. - **Config**: master switch `ambient-zones.enabled` in `config.json`; scan cadence `settings.scan-interval-ticks` in `zones.json` (default 20 ticks). A single scanner assigns players to zones each interval. - **Folia-safe**: the scanner dispatches each player's evaluation and sound playback to that player's region thread; a new global scheduler path in `SchedulerUtil` drives the per-zone (and per-player, in `individual` mode) track timers. Discs without a configured duration are skipped in zones (a zone needs durations to advance/loop).

## [3.2.0] - 2026-07-12 ### Added - **Configurable "Now Playing" announcements**: the title shown in the center of the screen and the actionbar message when a custom disc starts can now be disabled individually via `playback.show-title` and `playback.show-actionbar` in `config.json` (both default to `true`, matching previous behavior). - **Automatic config merging**: on load, `config.json` and `disc.json` are compared against the plugin's bundled defaults and any keys introduced by a newer version are added automatically, without overwriting existing values. New options (like the `show-*` flags above) now appear in existing config files after an update/`reload` instead of having to be added by hand. In `disc.json` the `discs`/`categories`/`playlists` sections are treated as user content and are never re-seeded with the default examples, so deleted example discs do not reappear. - **Configurable backup count**: the number of timestamped `config`/`disc` backups kept is now set via `settings.max-backups` (default `5`, same as before). Set it to `0` to disable backups entirely — existing backup files are then pruned on the next save. Values are clamped to a maximum of 100. Previously the count was hard-coded to 5. ### Fixed - **GUI system rebuilt on InventoryHolder**: All plugin GUIs (Admin panel, disc/category/playlist editors, jukebox disc GUI) are now identified via a custom `InventoryHolder` instead of window titles and per-player context maps. This fixes a family of serious bugs: - Closing a GUI with ESC no longer leaves a stale session that hijacked clicks in chests/containers opened afterwards (previously this could **overwrite real chest contents** with GUI items and spawn free disc copies via the delete-confirmation dialog). - Opening the playlist editor or disc editor from the admin panel no longer breaks their click handling (the close event of the previous menu wiped the new context). - The same click is no longer processed by two GUIs at once (admin panel + disc editor). - The jukebox disc GUI no longer depends on a lossy title round-trip — hex/gradient `gui-title` values previously broke the comparison and made GUI items freely extractable. - `/cjb gui` uses the same holder-tagged inventory, and all GUI click handlers cancel the click *before* any session/permission checks, so a missing session can never make GUI items extractable. - **Item safety in GUIs**: `InventoryDragEvent` is now cancelled in all GUIs (items could previously be dragged into a GUI and lost), and collect-to-cursor double-clicks can no longer pull items out. - **Logout cleanup**: All GUI/wizard sessions are cleared on player quit. Previously a player who logged out mid-wizard had every chat message swallowed and processed as wizard input after rejoining. - **Folia: auto-stop/loop tasks are now cancellable**: `SchedulerUtil` returns a platform-independent `TaskHandle` (wrapping Folia's `ScheduledTask.cancel()`). Stale auto-stop tasks could previously stop a *newer* playback at the same jukebox (e.g. disc B stopped mid-song at disc A's old end time), and orphaned loop tasks multiplied. Tasks additionally verify they still belong to the same playback session when firing. - **Playlists survive volume/mute restarts**: `/cjb mute`, `/cjb unmute` and `/cjb volume <x> restart` no longer wipe the running playlist queue (playback previously went silent after the current track). - **Skeleton-kill fragment drops actually work**: the guaranteed drop when a skeleton kills a creeper never triggered (`getKiller()` only returns players). Now resolved via the last damage cause, including arrows, covering Skeleton/Stray/Bogged. - **Off-hand discs are recognized**: interaction handlers now use the hand that triggered the event. Off-hand discs previously got inserted by vanilla without the custom sound; the GUI also opened twice. With the GUI enabled, an off-hand disc now takes priority over opening the GUI. - **Ejecting by disc swap stops the sound**: right-clicking an occupied jukebox while holding another disc lets vanilla eject the record — the custom sound now stops with it (previously it kept playing over the empty jukebox). - **Hopper support**: a hopper extracting the disc stops the custom sound (it previously played to the end); a hopper inserting a custom disc starts the custom sound. Extraction is verified one tick later so transfers cancelled by protection plugins don't cut the music. - **Disc identity via PersistentDataContainer**: disc and fragment items now carry their ID in the PDC. Two discs sharing the same CustomModelData are no longer confused when editing/deleting/giving (legacy items still match by model data). Note: deleting a disc and recreating it under a new ID invalidates already-issued items of the old ID — they intentionally no longer match by texture alone. - **Thread-safety on Folia**: disc/category/playlist/language registries are now `ConcurrentHashMap` (a `/cjb reload` could previously throw `ConcurrentModificationException` in event handlers on other region threads); `UpdateChecker` results, mute state and playback flags are `volatile`; `onDisable` no longer calls the Bukkit scheduler on Folia (threw `UnsupportedOperationException`). - **config.json saves atomically** (temp file + atomic move, like disc.json) and `/cjb reload` reloads the persisted mute state. - **Validation restored**: disc/category/playlist IDs must be `[A-Za-z0-9_-]+` (IDs with spaces were previously creatable but unusable in commands); sound keys are validated as resource locations again — the wizard's error messages for these cases were dead code. - **Gradients fixed**: `<gradient:#RRGGBB:#RRGGBB>` was destroyed by the hex pre-pass in `AdventureUtil` and never rendered; hex colors are no longer downsampled to legacy codes on serialization. - **`/cjb volume`**: tab-completion no longer suggests locale-formatted values like `0,5` that the parser rejects; `NaN` no longer passes the range check. - **Permission `customjukebox.fragment`** is now actually checked by `/cjb fragment` (previously it required `customjukebox.give`, and the declared node was dead). Migration note: servers that granted `customjukebox.give` directly (not via `customjukebox.admin`) must additionally grant `customjukebox.fragment` to keep `/cjb fragment` access. - **Playback tracking leak**: discs without a configured duration no longer leave a tracking entry behind forever (fallback cleanup after 1 hour); `loop` without a duration now logs a warning instead of being silently ignored. - **Orphan cleanup**: deleting a disc removes it from all playlists; deleting a category detaches it from its discs. - **Deleting playlists/categories** in the admin panel now requires a confirming second right-click (they were previously deleted instantly and irreversibly); failed deletions report an error. - **Chat-input hardening**: input modes are consumed atomically (rapid double messages were processed twice), the disc editor's chat handler respects cancelled events, and all chat/wizard handlers re-check the admin permission before applying input. - **Log hygiene**: per-click and per-playlist-progression INFO logs are now behind the debug flag. ### Changed - `ParrotDanceListener` no longer schedules hundreds of empty per-parrot tasks (the vanilla dance animation cannot be forced via the Bukkit API); it now shows a short note-particle burst above nearby parrots instead. ### Performance - **Fewer disk writes on delete**: deleting a disc or category now rewrites `disc.json` a single time instead of once per affected playlist/disc (each of which previously also created a backup and scanned the backup directory). - **Folia scheduler**: reflection handles are resolved once against the public scheduler interfaces and cached, instead of being looked up on every schedule/cancel call on the playback hot path. - **Cheaper event hot paths**: hopper transfers are filtered by item/inventory type before any block-state lookup, and GUI event handlers use a non-snapshotting holder check — so hopper-heavy servers and players interacting with vanilla containers no longer pay for block-entity snapshots on every event.

## [3.1.0] - 2026-07-04 ### Changed - **Unified release**: The 2.x (Minecraft 1.21.x) and 3.0.0 (Minecraft 26.x) lines are merged into a single version. One jar now supports **Paper/Folia 1.21.4 through 26.x**. - Built against Paper API 1.21.4 with `api-version: '1.21'` and Java 21 bytecode — loads on 1.21.4+ servers (Java 21) and 26.x servers (Java 25) alike. - Contains all fixes from the 2.x line (2.1.5–2.2.1) plus the 3.0.0 modernizations (component-based CustomModelData, metadata API replacement). - **Example resource pack**: `max_format` raised to `[84, 0]` so the pack is accepted by Minecraft 26.x clients (format 84) while staying compatible with 1.21.9+. - **Debug logging**: Volume debug output now includes distance, sound/player coordinates, world check, and estimated max range to help diagnose audibility issues. ### Fixed - **Debug logging**: Cross-world distance calculation no longer throws an exception when a `GLOBAL` playback reaches players in other worlds (previously triggered a misleading "FAILED TO PLAY SOUND" error with debug mode enabled). Distance is now logged as `N/A (different world)` instead. - **Debug logging**: Numbers are formatted locale-independently (always `12.5` instead of `12,5` on e.g. German systems).

# [3.0.0] - 2026-05-02 ### Added - **Public API Events**: New event system for companion plugins - `DiscPlaybackStartEvent` — Cancellable event fired when a disc starts playing. Exposes disc, location, and mutable listener set. - `DiscPlaybackStopEvent` — Fired when playback stops, with `StopReason` enum (MANUAL, DURATION_END, BLOCK_BREAK, PLUGIN). - `DiscRegisteredEvent` — Fired when a new disc is created via GUI or config. - `DiscRemovedEvent` — Fired when a disc is removed, includes a snapshot of the deleted disc. - **API method**: `CustomJukeboxAPI.getPluginDataFolder()` — Allows companion plugins to locate disc sound files. ### Changed - **PlaybackManager**: Now fires `DiscPlaybackStartEvent` before playing sounds (allows cancellation and listener modification) and `DiscPlaybackStopEvent` on stop. - **DiscManager**: Now fires `DiscRegisteredEvent` on disc creation and `DiscRemovedEvent` on disc deletion. ### Technical - New package: `de.boondocksulfur.customjukebox.api.events` with 4 event classes - All events follow standard Bukkit event patterns (HandlerList, static getHandlerList) - Zero behavior change for existing users — events are no-ops without listeners - Foundation for the new [BS-CustomJukebox Bedrock Extension](https://modrinth.com/plugin/bs-customjukebox-bedrock-extension)

## [2.2.1] - 2026-05-03 ### Fixed - **UpdateChecker**: Now filters by game version via Modrinth API so users only see updates compatible with their Minecraft version. Prevents cross-version update notifications (e.g., 26.1 updates shown to 1.21.x servers).

## [2.2.0] - 2026-05-02 ### Added - **Public API Events**: New event system for companion plugins - `DiscPlaybackStartEvent` — Cancellable event fired when a disc starts playing. Exposes disc, location, and mutable listener set. - `DiscPlaybackStopEvent` — Fired when playback stops, with `StopReason` enum (MANUAL, DURATION_END, BLOCK_BREAK, PLUGIN). - `DiscRegisteredEvent` — Fired when a new disc is created via GUI or config. - `DiscRemovedEvent` — Fired when a disc is removed, includes a snapshot of the deleted disc. - **API method**: `CustomJukeboxAPI.getPluginDataFolder()` — Allows companion plugins to locate disc sound files. ### Changed - **PlaybackManager**: Now fires `DiscPlaybackStartEvent` before playing sounds (allows cancellation and listener modification) and `DiscPlaybackStopEvent` on stop. - **DiscManager**: Now fires `DiscRegisteredEvent` on disc creation and `DiscRemovedEvent` on disc deletion. ### Technical - New package: `de.boondocksulfur.customjukebox.api.events` with 4 event classes - All events follow standard Bukkit event patterns (HandlerList, static getHandlerList) - Zero behavior change for existing users — events are no-ops without listeners - Foundation for the new [BS-CustomJukebox Bedrock Extension](https://modrinth.com/plugin/bs-customjukebox-bedrock-extension)