> For the complete documentation index, see [llms.txt](https://wiki.auraplugins.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.auraplugins.eu/readme.md).

# Introduction

**AuraSounds** brings your Minecraft server to life with **ambient sounds** and **zone music** — crickets at night in the swamp, a crackling tavern fireplace, an epic score that starts the moment players step into your dungeon.

No mods. No client-side installs beyond a resource pack. Just drop a YAML file and your world has a soundtrack.

## What can it do?

* 🌿 **Ambient sounds** — positional audio sources placed anywhere in the world, with a radius and natural volume falloff. Walk closer, it gets louder.
* 🎵 **Zone music** — one music track per area (a WorldGuard region or a built-in area), with priorities and smooth transitions. Only one music plays at a time per player.
* 🎲 **Random one-shots** — sounds that play at random intervals, at a random spot *around* the player: distant roars, far-off thunder, things that go bump in the night. No coordinates needed.
* 🌙 **A powerful condition system** — play sounds only at night, only in rain, only in certain biomes, below a certain altitude, underground, in water, while sneaking, during a full moon… and combine all of it with AND / OR / NOT logic.
* 🎨 **Custom audio support** — use vanilla sounds out of the box, or your own audio through **ItemsAdder**, **Nexo**, or any manually-hosted resource pack.
* 🎬 **Scenes** — group sounds together, export them with relative coordinates, and re-import them anywhere (or on another server).
* ⚡ **Performance-first design** — per-world sound indexing, cached WorldGuard lookups, no NMS.

## How it works in 15 seconds

1. Install the plugin (and optionally a resource pack with your own audio).
2. Create a sound file in `plugins/AuraSounds/sounds/` — or use the in-game commands.
3. Players hear it automatically when they are in the right place, at the right time, under the right conditions.

```yaml
# plugins/AuraSounds/sounds/swamp_night.yml
type: ambient
playback:
  sound: 'minecraft:entity.frog.ambient'
  loop: {enabled: true, duration: '4s', interval: '2s'}
source:
  radius: 24
  falloff: true
  points:
    - {world: world, x: 100, y: 64, z: -200}
conditions:
  time: ['night']
  biomes: ['minecraft:swamp']
```

That's a complete, working ambient sound. Frogs, at night, in the swamp, around one spot. 🐸

## Where to next?

* New here? Start with [Installation](/getting-started/installation.md) then the [Quick Start](/getting-started/quick-start.md) — you'll have your first sound running in five minutes.
* Want your own audio files in the game? Read [Custom Sounds & Resource Packs](/getting-started/custom-sounds.md).
* Looking for every option? See the [Sound File Reference](/guides/sound-files.md) and the [Conditions Reference](/guides/conditions.md).

## Requirements

|                |                                                                     |
| -------------- | ------------------------------------------------------------------- |
| Server         | Paper or Spigot **1.21+** (Paper recommended) — **Folia supported** |
| Java           | **21** or newer                                                     |
| Optional hooks | WorldGuard, PlaceholderAPI, ItemsAdder, Nexo                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.auraplugins.eu/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.