GFBS: Auralis

An instance-based spatial audio runtime for Minecraft Forge 1.20.1.

GFBS: Auralis runs an independent OpenAL playback layer alongside Minecraft's vanilla sound engine. It gives mods, maps, command systems, and scripted experiences direct control over persistent sound instances, world-space positioning, streamed playback, attenuation, source priority, runtime parameter changes, and server-to-client orchestration.

---

Team maintaining this project: GFBS Mod Series Maintainers

维护此项目的团队: GFBS Mod Series Maintainers

---

Repository

• Source code
• Releases
• Issue tracker
• Pull requests

Status and compatibility

Component	Version
GFBS: Auralis	2.3.2
Minecraft	1.20.1
Minecraft Forge	47.4.13
Java	17
Mod ID	gfbs_auralis

The OpenAL engine and all audio-device operations run on the physical client. Install the mod on the server as well when using its commands, packets, synchronized state, entity binding, or block binding.

Features

See FEATURES.md for the feature overview and version-specific details.

Installation

1. Install Minecraft Forge for Minecraft 1.20.1.
2. Download a GFBS: Auralis JAR from GitHub Releases, or build the project from source.
3. Place the JAR in the mods directory of every required client.
4. Install the same JAR on the server when server commands or synchronized control are required.

GFBS: Auralis uses registered Minecraft SoundEvent resources. Audio files and sounds.json entries remain owned by the resource pack or mod that defines them.

Building from source

Clone the official repository and run:

git clone https://github.com/LytharaLab/GFBS-Auralis.git
cd GFBS-Auralis
./gradlew build

On Windows PowerShell:

git clone https://github.com/LytharaLab/GFBS-Auralis.git
Set-Location GFBS-Auralis
.\gradlew.bat build

The built JAR is written to build/libs/.

Start development environments with:

./gradlew runClient
./gradlew runServer

Java API quick start

Create and configure an instance from client-side code:

import net.minecraft.resources.ResourceLocation;
import net.minecraft.sounds.SoundEvent;
import net.minecraft.world.phys.Vec3;
import net.minecraftforge.registries.ForgeRegistries;
import org.lytharalab.gfbs.auralis.api.AuralisApi;
import org.lytharalab.gfbs.auralis.api.AuralisSoundInstance;

SoundEvent sound = ForgeRegistries.SOUND_EVENTS.getValue(
        new ResourceLocation("example", "reactor_hum")
);

if (sound == null) {
    throw new IllegalStateException("Missing sound event: example:reactor_hum");
}

AuralisSoundInstance instance = AuralisApi.create(sound)
        .setPosition(new Vec3(128.5, 64.0, -32.5))
        .setStatic(false)
        .setVolume(1.0f)
        .setPitch(1.0f)
        .setSpeed(1.0f)
        .setLooping(true)
        .setPriority(80)
        .setMinDistance(4.0f)
        .setMaxDistance(64.0f);

AuralisSoundInstance.bind(instance);
instance.play();

In 2.1.1, play() starts the logical voice. bind() makes the instance eligible for physical playback, but isBound() may remain false while the voice is virtual. The logical playback clock still advances, isPlaying() remains true, and the correct playback position is restored when the listener gets close enough or a physical source becomes available.

You can inspect this state with isVirtual(), getPlaybackPositionSeconds(), and getDurationSeconds().

Stop and release the source when the owning object is removed:

instance.stop();
AuralisSoundInstance.unbind(instance);

Playback completion and instance lifetime

Non-looping instances automatically dispose their audio resources after reaching the natural end by default. Disable that behavior when the same instance must be replayed:

AuralisSoundInstance instance = AuralisApi.create(MY_SOUND)
        .setAutoDisposeOnFinish(false);

AuralisSoundInstance.bind(instance);
instance.play();

// After natural completion the OpenAL source is returned to the pool, but the
// instance, static buffer or stream decoder remain available. This rebinds and
// starts from the beginning.
instance.play();

// Explicitly release the retained resources when finished.
AuralisSoundInstance.unbind(instance);

setAutoDisposeOnFinish(true) restores one-shot behavior. Source recycling is always enabled and is independent from instance disposal.

Use AuralisApi.createStreamed(...) for chunked streamed playback. Asynchronous variants are available through createAsync(...) and createStreamedAsync(...).

setStatic(true) creates a listener-relative sound without world-distance attenuation. Use setStatic(false) with setPosition(...) for a positional world sound.

Bus and native-effect quick start

Create the bus before assigning voices to it:

import org.lytharalab.gfbs.auralis.api.AuralisApi;
import org.lytharalab.gfbs.auralis.api.effect.AuralisEffects;
import org.lytharalab.gfbs.auralis.api.effect.EfxParameter;

var buses = AuralisApi.buses();
var ambience = buses.createBus("Ambience");
var reactor = buses.createBus("Reactor", "Ambience")
        .setVolumeDb(-3.0f);

var reverb = AuralisEffects.reverb("example:reactor_reverb")
        .setFloat(EfxParameter.REVERB_DECAY_TIME, 2.8f)
        .setFloat(EfxParameter.REVERB_GAIN, 0.4f)
        .setWet(0.35f);

reactor.addEffect(reverb);
instance.setBus("Reactor");

AudioBusSystem.view(name) returns the effective gain, audibility, route to Master, ordered effects, and compiled revision for diagnostics or management UIs.

Command control

All commands require permission level 2 and begin with /gfbs_auralis.

Play a positional looping sound for every player:

/gfbs_auralis play minecraft:block.beacon.ambient reactor_hum 1.0 1.0 1.0 false ~ ~ ~ true 80 4.0 64.0 @a

The play syntax is:

/gfbs_auralis play <sound> <id> <volume> <pitch> <speed> <static> <position> <looping> <priority> <min-distance> <max-distance> [targets]

Use streamed_play with the same arguments for streamed playback.

Runtime controls include:

/gfbs_auralis pause <id> [targets]
/gfbs_auralis stop <id> [targets]
/gfbs_auralis regulating volume <id> <value> [targets]
/gfbs_auralis regulating pitch <id> <value> [targets]
/gfbs_auralis regulating speed <id> <value> [targets]
/gfbs_auralis regulating position <id> <position> [targets]
/gfbs_auralis regulating static <id> <value> [targets]
/gfbs_auralis regulating looping <id> <value> [targets]
/gfbs_auralis regulating priority <id> <value> [targets]
/gfbs_auralis regulating min-distance <id> <value> [targets]
/gfbs_auralis regulating max-distance <id> <value> [targets]
/gfbs_auralis regulating bus <id> <bus> [targets]

Manage client bus layouts from the server:

/gfbs_auralis bus create <bus> <parent> [targets]
/gfbs_auralis bus remove <bus> [targets]
/gfbs_auralis bus parent <bus> <parent> [targets]
/gfbs_auralis bus volume <bus> <0..16> [targets]
/gfbs_auralis bus mute <bus> <true|false> [targets]
/gfbs_auralis bus solo <bus> <true|false> [targets]
/gfbs_auralis bus bypass-effects <bus> <true|false> [targets]

Tween controls support volume, pitch, speed, position, min-distance, and max-distance:

/gfbs_auralis tween <property> <id> <duration> <value> [easing-style] [easing-direction] [targets]

A sound may follow an entity or block position:

/gfbs_auralis bind <id> entity <entity> [targets]
/gfbs_auralis bind <id> block <block-position> [targets]
/gfbs_auralis unbind <id> [targets]

When the command source is a player, omitted targets default to that player. Command blocks and the server console must provide an explicit target selector.

Configuration

Client audio configuration includes:

• Maximum OpenAL source count, including automatic device-based selection.
• Sources reserved for Minecraft's vanilla audio engine.
• Streamed PCM chunk size and decoded-byte safety limit.
• Distance attenuation exponent.
• Volume smoothing factor.
• Optional HRTF initialization.

Server configuration includes concurrency limits, default volume, remote-sound control, and client-sync policy.

Changing source limits, streaming limits, or HRTF settings may require a client restart because they affect audio-engine initialization.

Architecture

src/main/java/org/lytharalab/gfbs/auralis/
├── api/         Public engine, bus, effect, OpenAL, plugin, event, and processor APIs
├── command/     Brigadier command registration and dispatch
├── core/        Bus compiler, EFX rack, controlled OpenAL access, events, and plugins
├── event/       Forge synchronization event handlers
├── network/     Client sound, bus, binding, and Tween packets
├── server/      Server-side sound state and synchronization
├── tween/       Tween service, easing, and playback state
├── utils/       OGG Vorbis decoding
└── *.java       OpenAL engine, source pool, buffer cache, and client controller

The server describes intended sound state and sends bounded control messages. The client owns decoding, OpenAL sources, listener updates, attenuation, streaming queues, and audio-device calls.

Scope and compatibility

GFBS: Auralis is intended for orchestrated audio systems that need independently addressable instances. It does not replace Minecraft's entire sound engine, rewrite ordinary vanilla sound playback, or provide audio assets by itself.

Mods that replace or deeply intercept OpenAL, Minecraft audio initialization, or sound-resource loading may require compatibility testing. Source limits are deliberately configurable so Auralis can reserve capacity for vanilla and other audio users.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening an issue or pull request. Participation in the project is governed by CODE_OF_CONDUCT.md.

License

GFBS: Auralis is available under the MIT License.

Copyright © 2026 LytharaLab.

Minecraft is a trademark of Microsoft Corporation. This project is not affiliated with or endorsed by Microsoft or Mojang Studios.