91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# 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.
|