feat: add configurable ambient audio zones

2026-08-04 05:08:16 +02:00
parent a877b29748
commit 2e2a59b90a
15 changed files with 476 additions and 1 deletions
@@ -1,2 +1,90 @@
-# Ambient-Audio-Zone
+# Ambient Audio Zone

+A Paper 26.2 plugin for immersive, directional ambient audio driven by WorldEdit cuboid selections. Zones use any vanilla or resource-pack sound event (`minecraft:...` or `namespace:...`), are stored in YAML, and are indexed by chunk rather than scanned globally.
+
+## Requirements
+
+- **Paper 26.2** (`26.2.build.92-stable` API target) and **Java 25**
+- **WorldEdit 7.4.4+** installed on the server (for selection-backed create/region editing)
+- A resource pack installed on clients when using custom sound IDs
+
+Drop `AmbientAudioZone.jar` into `plugins/` and restart. It creates `plugins/AmbientAudioZone/config.yml` and `zones.yml`.
+
+## Commands
+
+| Command | Description | Permission |
+| --- | --- | --- |
+| `/ambientaudio create <name> <sound-id>` | Creates a zone from your complete WorldEdit selection. Origin starts at your current location. | `ambientaudio.create` |
+| `/ambientaudio edit <name> region` | Replaces the zone cuboid with your WorldEdit selection. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> origin [here\|x y z]` | Sets the directional sound source. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> sound <sound-id>` | Changes the sound event ID. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> fade <blocks>` | Sets the selection activation/fade envelope. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> volume\|pitch <value>` | Sets the sound gain or pitch. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> category <category>` | Sets a Bukkit `SoundCategory`, e.g. `MUSIC`, `RECORDS`, `AMBIENT`, `MASTER`. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> loop\|enabled <true\|false>` | Changes loop metadata or enable state. | `ambientaudio.edit` |
+| `/ambientaudio edit <name> priority <integer>` | Sets overlap priority. | `ambientaudio.edit` |
+| `/ambientaudio delete <name>` | Deletes a zone. | `ambientaudio.delete` |
+| `/ambientaudio list` | Lists zones. | `ambientaudio.list` |
+| `/ambientaudio reload` | Reloads both YAML files and rebuilds the index. | `ambientaudio.reload` |
+
+`ambientaudio.admin` grants all administrative commands (default: OP). The `/aaz` alias is available.
+
+## Zone configuration
+
+```yaml
+zones:
+  nightclub:
+    world: world
+    sound: lexian:music/nightclub
+    origin:
+      x: 120
+      y: 65
+      z: -45
+    region:
+      min: { x: 100, y: 60, z: -60 }
+      max: { x: 140, y: 80, z: -20 }
+      fade-distance: 32
+      volume: 1.0
+      pitch: 1.0
+      category: RECORDS
+      loop: true
+      priority: 100
+    enabled: true
+```
+
+`fade-distance` expands the cuboid's audible envelope. Outside that envelope the plugin does not select or start the zone. Within it, the sound packet is emitted at `origin`, so Minecraft's own positional audio supplies the continuous directional attenuation; set the origin at a speaker, stage, jukebox, or other real source rather than the cuboid centre.
+
+## Overlaps and performance
+
+By default, only the audible zone with the highest `priority` is selected. Set `playback.blend-overlapping-zones: true` in `config.yml` to play every audible zone. The zone index assigns a zone only to chunks touched by its fade-expanded X/Z bounds; each playback pass then evaluates only the list for a player's current chunk. The interval and grace period are configurable:
+
+```yaml
+playback:
+  check-interval-ticks: 10
+  leave-grace-ticks: 100
+  blend-overlapping-zones: false
+```
+
+When a selected zone remains selected, Ambient Audio Zone sends no new sound packet. Leaving starts a configurable grace timer; returning before it expires preserves the existing client playback instead of restarting it. Reloading or editing a zone intentionally replaces its active sound.
+
+## Resource-pack looping note
+
+Minecraft's public sound packet has no server-controlled *playback position*, pause, or true loop flag. For seamless loops, define custom events in the resource pack and let the **client** loop/stream them, for example:
+
+```json
+{
+  "music/nightclub": {
+    "sounds": [{ "name": "lexian:music/nightclub", "stream": true, "loop": true }]
+  }
+}
+```
+
+Use that event as `lexian:music/nightclub` in the zone. The plugin deliberately does not repeatedly replay a selected sound—doing so would cause audible starts and destroy seamless loops. Vanilla one-shot events play normally; their exact loop behaviour is determined by the vanilla sound definition.
+
+## Build
+
+```bash
+mvn verify
+```
+
+The GitHub Actions workflow builds with Java 25 on pushes and pull requests.