Adding Sounds

Basics

Sounds are defined as SoundEvent assets — JSON files that reference .ogg audio files and control how they play (volume, pitch, distance, layering).

Pack location: Common/Sounds/ (audio files) + corresponding SoundEvent JSON
Base game reference: Assets.zip/Common/Sounds/

Audio File Requirements

Format: Ogg Vorbis (.ogg)
Block sounds: mono (single channel)
Item sounds: stereo (two channels)
Other sounds: mono or stereo

SoundEvent

A SoundEvent defines a single playable sound with one or more layers.

{
  "Volume": 0,
  "Pitch": 0,
  "StartAttenuationDistance": 2.0,
  "MaxDistance": 16.0,
  "MaxInstance": 50,
  "PreventSoundInterruption": false,
  "AudioCategory": "SFX_Category",
  "Layers": [
    {
      "Files": [
        "Sounds/SFX/My_Sound_01.ogg",
        "Sounds/SFX/My_Sound_02.ogg"
      ]
    }
  ]
}

Properties

Field	Type	Default	Description
`Volume`	float	`0`	Base volume in decibels (-100 to +10)
`Pitch`	float	`0`	Base pitch in semitones (-12 to +12)
`StartAttenuationDistance`	float	`2.0`	Distance (blocks) before volume fades
`MaxDistance`	float	`16.0`	Maximum audible distance (blocks)
`MaxInstance`	int	`50`	Max concurrent instances (1-100)
`PreventSoundInterruption`	boolean	`false`	Prevents this sound from being interrupted
`AudioCategory`	string	—	References an AudioCategory asset for volume bus grouping
`MusicDuckingVolume`	float	`0`	How much to duck music when playing (-100 to 0 dB)
`AmbientDuckingVolume`	float	`0`	How much to duck ambient when playing (-100 to 0 dB)

Layers

Each SoundEvent can have multiple layers that play independently. Each layer selects a random file from its Files array.

{
  "Layers": [
    {
      "Volume": 0,
      "StartDelay": 0.0,
      "Looping": false,
      "Probability": 100,
      "ProbabilityRerollDelay": 1.0,
      "RoundRobinHistorySize": 3,
      "RandomSettings": {
        "MinVolume": -3,
        "MaxVolume": 3,
        "MinPitch": -2,
        "MaxPitch": 2
      },
      "Files": [
        "Sounds/SFX/Hit_01.ogg",
        "Sounds/SFX/Hit_02.ogg",
        "Sounds/SFX/Hit_03.ogg"
      ]
    }
  ]
}

Field	Type	Default	Description
`Volume`	float	`0`	Layer volume in dB (-100 to +10)
`StartDelay`	float	`0.0`	Delay before playing (seconds)
`Looping`	boolean	`false`	Whether the layer loops
`Probability`	int	`100`	Chance to play each time (0-100%)
`ProbabilityRerollDelay`	float	`1.0`	Seconds before re-rolling probability
`RoundRobinHistorySize`	int	`0`	Prevents repeating recent files (0 = disabled, max 32)
`RandomSettings`	object	—	Per-play volume/pitch randomization

RandomSettings adds variation each time the sound plays:

Field	Type	Range	Description
`MinVolume`	float	-100 to 0 dB	Minimum volume offset
`MaxVolume`	float	0 to +10 dB	Maximum volume offset
`MinPitch`	float	-12 to 0 semitones	Minimum pitch offset
`MaxPitch`	float	0 to +12 semitones	Maximum pitch offset
`MaxStartOffset`	float	seconds	Random start position for looping sounds

Block Sound Sets

Map block interaction events to SoundEvent IDs. Each block type can reference a BlockSoundSet.

Pack location: Alongside block definitions

{
  "SoundEvents": {
    "Walk": "SFX_Block_Walk_Stone",
    "Land": "SFX_Block_Land_Stone",
    "MoveIn": "SFX_Block_MoveIn_Stone",
    "MoveOut": "SFX_Block_MoveOut_Stone",
    "Hit": "SFX_Block_Hit_Stone",
    "Break": "SFX_Block_Break_Stone",
    "Build": "SFX_Block_Build_Stone",
    "Clone": "SFX_Block_Clone_Stone",
    "Harvest": "SFX_Block_Harvest_Stone"
  },
  "MoveInRepeatRange": { "min": 0.5, "max": 1.5 }
}

Block sound events:

Event	When it plays
`Walk`	Player walks on the block
`Land`	Player lands on the block
`MoveIn`	Entity enters the block’s space
`MoveOut`	Entity leaves the block’s space
`Hit`	Block is hit (mining)
`Break`	Block is broken
`Build`	Block is placed
`Clone`	Block is cloned (creative)
`Harvest`	Block is gathered

Block sounds must be mono and non-looping.

Item Sound Sets

Map item UI events to SoundEvent IDs.

{
  "SoundEvents": {
    "Drag": "SFX_Item_Drag_Default",
    "Drop": "SFX_Item_Drop_Default"
  }
}

Event	When it plays
`Drag`	Item dragged in inventory UI
`Drop`	Item dropped in inventory UI

Item sounds must be stereo and non-looping.

Sound Categories

Each SoundEvent plays through a sound category bus:

Category	Use for
`Music`	Background music
`Ambient`	Environmental ambience
`SFX`	Sound effects (default)
`UI`	UI interaction sounds

Audio Categories

AudioCategory assets define volume bus hierarchies. Child categories inherit parent volume (multiplicative).

{
  "Volume": 0
}

Using Sounds in Other Assets

In Projectiles

{
  "DeathSoundEventId": "SFX_Arrow_Impact"
}

In Interactions

{
  "Effects": {
    "WorldSoundEventId": "SFX_Sword_Swing",
    "PlayerSoundEventId": "SFX_Weapon_Whoosh"
  }
}

WorldSoundEventId plays as a 3D sound at the interaction position. PlayerSoundEventId plays as a 2D sound to the acting player only.

In NPC Behaviors

{
  "Type": "PlaySound",
  "SoundEventId": "SFX_Wolf_Growl"
}

In GameplayConfig

See Gathering config for block interaction sounds.

File Locations

What	Your Pack	Base Game Reference
Audio files (.ogg)	`Common/Sounds/`	`Assets.zip/Common/Sounds/`
SoundEvent definitions	with audio files	with audio files
Block sound sets	with block definitions	`Assets.zip/Server/Item/Block/Sounds/`
Item sound sets	with item definitions	`Assets.zip/Server/Item/ItemSounds/`