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

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:

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:

{
  "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

mvn verify

The GitHub Actions workflow builds with Java 25 on pushes and pull requests.

4.4 KiB Raw Blame History