API Audio

Sound events and local playback

Lua API / Audio

Use sound assets for clips, sound events for reusable choices/defaults, and betamoon.audio:play for local one-shot effects.

Register a sound event

betamoon.soundEvents:add(definition) → sound event reference

Declare events in modInit() or modReload() after their sound assets.

local tap = betamoon.soundEvents:add {
    key = "mymod:block/machine/tap",
    clips = {
        { sound = "mymod:block/machine/click", weight = 2 },
        { sound = "mymod/sounds/alternate.wav", weight = 1 }
    },
    volume = 0.6,
    pitch = { min = 0.95, max = 1.05 },
    range = 24
}

Field definitions

Field	Type	Meaning
key	string	Required exact lowercase namespace:path key.
sound	sound reference/key/path	Single clip. Supply exactly one of sound or clips.
clips	list of tables	1–256 alternatives, each containing sound and optional weight.
volume	number	Gain in 0–1, default 1.
pitch	number or { min, max }	Fixed pitch or uniform random range, 0.01–4; defaults to 1. Missing range endpoints default to 1.
range	number	Positional fade distance in blocks, 0.01–1024; default 16.

A clip's sound accepts a sound asset, its exact key, or a relative OGG/WAV path. Weights default to 1 and must be in 0.000001–1,000,000. Each play selects one clip by its relative weight. A pitch range requires min <= max.

The first clip above must already be registered as a sound asset. For one clip, use sound = click instead of clips. Packs replace clip files; event selection and defaults stay in the script.

Sound-event lookup

• betamoon.soundEvents:get(key) returns a reference or nil when absent.
• betamoon.soundEvents:getRequired(key) returns a reference or raises an error when absent. find(query), first(query), and one(query) accept key, owner, and enabled; find returns the normal result list with overrideAll.

Sound-event reference

References are live views with key, owner, exists, enabled, clips, volume, pitch, and range. event:getKey() returns the exact namespaced key.

event:override(definition)

Overrides clips (or sound), volume, pitch, range, or enabled. The complete candidate is validated and its clips are acquired before it becomes visible. Removing the handle restores the next layer.

local muted = betamoon.soundEvents:getRequired("mymod:block/machine/tap"):override {
    priority = 20,
    changes = { enabled = false }
}

Keys are unique within the event registry and owned by the declaring script. Events are removed with reloadable script cleanup and must be re-registered during initialization.

Play a sound

betamoon.audio:play(sound, options?)

sound accepts a sound event reference, sound asset reference, exact registered key, or relative OGG/WAV path. For string keys shared by an event and clip, the event takes precedence; pass the sound asset reference to select the clip explicitly.

-- Inside a script callback:
betamoon.audio:play("mymod:block/machine/tap", {
    position = { x = 12.5, y = 65, z = -3.5 }
})

-- Nonpositional sound:
betamoon.audio:play("mymod/sounds/click.ogg", { volume = 0.4 })

Option	Meaning
position = { x, y, z }	World coordinates for positional playback. All three coordinates are required and finite, within ±32,000,000. Requires a mono clip. Omit for nonpositional playback.
volume	Replaces the event gain; 0–1. Default: event value or 1.
pitch	Replaces the event pitch; 0.01–4. Default: event choice or 1.
range	Replaces the event fade distance; 0.01–1024 blocks. Default: event value or 16.

Playback respects the player's sound-volume setting. Gain and range are independent: increasing range does not increase volume. Muted or unavailable sound output produces no sound. Clips are one-shot effects; playback is local to this client and does not broadcast to other players.

Inside an entity callback, ctx.entity:playSound(event, options?) plays a registered sound event at that entity's current position. It accepts the same volume, pitch, and range overrides. Entity declarations can also bind events to ambient, hurt, death, step, impact, and pickup behavior; see entity presentation and sounds.

The Clicker example registers a WAV and plays it from item use.

Already playing sounds finish with their current clip when a pack changes; subsequent plays use the replacement. Script unload and leaving/changing worlds stop that script's active sounds. At most 64 custom voices and 64 MiB of active decoded clip data are retained for playback; older voices are stopped when needed. The number audible at once also depends on the game's audio output.

Use asset refresh after editing files. See texture-pack overrides for sound override locations.