🔊 Sounds

Overview

Custom sounds are configured in sounds.yml. Oraxen reads this file and generates one sounds.json per namespace, at assets/<namespace>/sounds.json. An event oraxen:welcome lands in assets/oraxen/sounds.json. Custom jukebox songs are registered directly into the server on Paper 1.21.6+, or packaged as a datapack on older versions.

Use this file to add brand new sound events, override existing vanilla sounds, or package longer audio tracks for music discs and other custom content.

Configuration

Sounds are configured in plugins/Oraxen/sounds.yml.

• 📁 plugins

  • 📁 Oraxen

    • 📄 sounds.yml

note

settings.automatically_generate must stay enabled if you want Oraxen to build sounds.json from this file. settings.generate_sounds is accepted as an alias. Disabling generation also disables jukebox song parsing and registration.

info

Sound files live in plugins/Oraxen/pack/sounds/. Oraxen then exports them to assets/minecraft/sounds/ in the generated resource pack. Namespaced sound files must go under pack/assets/<namespace>/sounds/ instead.

sound: welcome.ogg points to plugins/Oraxen/pack/sounds/welcome.ogg.
sound: music/welcome points to plugins/Oraxen/pack/sounds/music/welcome.ogg.

The .ogg extension is optional.

info

Legacy sound.yml files are migrated into sounds.yml automatically. The old map format under sounds: is now a list of sound entries, and every entry needs an id.

Sound Entry

Each entry in the sounds: list becomes one sound event.

🏷️ id

Sets the sound event id. This field is required for every entry, including vanilla replace: true entries.

sounds:
  - id: oraxen:welcome

If no namespace is specified, Minecraft's namespace is used. For example, id: welcome becomes minecraft:welcome.

🎵 category

Sets the sound category used when the sound plays.

sounds:
  - id: oraxen:welcome
    category: records

Default master

Categories
A full list of supported sound categories can be found here.

info

Common values include master, music, records, blocks, hostile, neutral, players, ambient, voice, and weather. record is accepted as an alias of records. Invalid categories fall back to master with a warning.

🎧 sound / sounds

Defines the audio file or files used by the sound event.

sounds:
  - id: oraxen:welcome
    sound: welcome.ogg

sounds:
  - id: oraxen:welcome
    sounds:
      - welcome_1
      - welcome_2
      - welcome_3

Sounds
Path to an existing sound file (relative to pack/sounds/, without .ogg).

info

sound is used when sounds is not set. An explicit empty sounds list produces an event with no files.

📝 subtitle

Sets the subtitle shown when the sound plays.

sounds:
  - id: oraxen:welcome
    subtitle: "Welcome Song"

🔁 replace

Marks the sound event as a replacement for an existing vanilla entry.

sounds:
  - id: block.wood.place
    replace: true

📡 stream

Tells Minecraft to stream the audio instead of loading it like a short sound effect.

sounds:
  - id: oraxen:welcome
    stream: true

🎚️ sound options

These fields are applied to the generated sound entries in sounds.json. They control stuff like volume, pitch or the attenuation distance.

sounds:
  - id: oraxen:welcome
    sound: welcome
    volume: 1.0
    pitch: 1.0
    weight: 1
    attenuation_distance: 16
    preload: false

💿 jukebox

Turns this sound into a custom jukebox song. jukebox_song is accepted as a section alias.

sounds:
  - id: oraxen:welcome
    jukebox:
      description: "<gold>Welcome <yellow>Song</yellow></gold>"
      duration: 180s
      comparator_output: 12
      range: 8

Fields
description - string, MiniMessage formatted, default subtitle or <white>Music Disc</white>
duration - duration, plain seconds or values with s/m style suffixes, for example 180 or 3m, default 120s, length_in_seconds is accepted as an alias
comparator_output - integer, clamped to 1 to 15, default 15
range - positive number, optional sound range
song_key - optional namespaced id for the jukebox song entry

info

When song_key is omitted, a non-namespaced sound id maps to oraxen:<key> while a namespaced id is used as-is. When attenuation_distance is unset and range is set, it defaults to the range rounded up.

info

On Paper 1.21.6+ songs are registered into the jukebox song registry at bootstrap and can be reloaded live with /oraxen reload discs. A datapack is generated only on versions below 1.21.6. On 1.21.6+ the old datapack is removed.

Example

settings:
  automatically_generate: true

sounds:
  - id: oraxen:welcome
    category: records
    sound: welcome.ogg
    stream: true
    subtitle: "Welcome Song"
    jukebox:
      description: "<gold>Welcome <yellow>Song</yellow></gold>"
      duration: 180s
      comparator_output: 12
      range: 8

  - id: block.wood.place
    replace: true

  - id: block.wood.break
    replace: true