# 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.