Sound Events

Sound events define how audio files are played in-game, including volume, pitch randomization, attenuation, and layering. They are the core building blocks of Hytale’s audio system.

Asset Location

Sound events are stored in Assets/Server/Audio/SoundEvents/:

• DirectoryAssets/Server/Audio/SoundEvents/

  • SFX_Attn_Loud.json
  • SFX_Attn_Moderate.json
  • SFX_Attn_Quiet.json
  • SFX_Attn_VeryLoud.json
  • SFX_Attn_VeryQuiet.json
  • DirectoryBlockSounds/

    • DirectoryBush/

      • …
    • DirectoryTall_Grass/

      • …
    • DirectoryLeavesGround/

      • …
  • DirectoryEnvironments/

    • DirectoryAmbiences/

      • …
    • DirectoryWeather/

      • …
  • DirectorySFX/

    • DirectoryChests/

      • …
    • DirectoryPlayer/

      • DirectoryHealth/

        • …
      • DirectoryMovement/

        • …
      • DirectoryAction/

        • …
    • DirectoryWeapons/

      • DirectorySword/

        • …
      • DirectoryMace/

        • …
      • DirectoryBow/

        • …

Audio files (.ogg) are in Assets/Common/Sounds/.

Sound Event Schema

Basic Structure

SFX_Example.json

{
  "Layers": [
    {
      "Files": ["Sounds/Path/Sound.ogg"],
      "Volume": 0,
      "RandomSettings": {
        "MinPitch": -2,
        "MaxPitch": 2
      }
    }
  ],
  "Volume": 0,
  "Parent": "SFX_Attn_Moderate"
}

Required Fields

Field	Type	Description
Layers	array	One or more audio layers to play

Top-Level Properties

Field	Type	Default	Description
Volume	float	0	Overall volume adjustment (dB). Range: -100 to 10
Pitch	float	0	Pitch adjustment in semitones. Range: -12 to 12
MusicDuckingVolume	float	0	Amount to duck music volume when playing (dB). Range: -100 to 0
AmbientDuckingVolume	float	0	Amount to duck ambient sounds when playing (dB). Range: -100 to 0
Parent	string	-	Parent sound event for inheritance
AudioCategory	string	-	Volume category (e.g., AudioCat_Weapons)
MaxInstance	int	50	Max concurrent instances. Range: 1 to 100
MaxDistance	float	16	Distance at which sound fades out completely (blocks)
StartAttenuationDistance	float	2	Distance at which attenuation begins (blocks)
PreventSoundInterruption	bool	false	Prevent interruption of this sound event

Layer Properties

Field	Type	Default	Description
Files	string[]	-	Audio file paths (one chosen at random)
Volume	float	0	Layer volume adjustment (dB). Range: -100 to 10
StartDelay	float	0	Delay in seconds before this layer starts playing
Looping	bool	false	Whether this layer loops
Probability	int	100	Chance of this layer playing when triggered (percentage)
ProbabilityRerollDelay	float	1	Delay in seconds before re-rolling whether this layer plays
RoundRobinHistorySize	int	0	Same file won’t repeat within this many plays. 0 disables. Range: 0 to 32
RandomSettings	object	-	Randomization parameters

RandomSettings Object

Field	Type	Description
MinVolume	float	Minimum random volume offset (dB). Range: -100 to 0
MaxVolume	float	Maximum random volume offset (dB). Range: 0 to 10
MinPitch	float	Minimum random pitch offset (semitones). Range: -12 to 0
MaxPitch	float	Maximum random pitch offset (semitones). Range: 0 to 12
MaxStartOffset	float	Max seconds to offset playback start. Useful for looping sounds to prevent phasing

Attenuation Templates

Base templates define spatial audio behavior:

Template	Max Distance	Start Attenuation	Use Case
SFX_Attn_VeryQuiet	~15 blocks	~1 block	Subtle sounds
SFX_Attn_Quiet	~25 blocks	~1 block	Normal sounds
SFX_Attn_Moderate	~35 blocks	~2 blocks	Combat sounds
SFX_Attn_Loud	~45 blocks	~2 blocks	Loud effects
SFX_Attn_VeryLoud	~60 blocks	~3 blocks	Explosions, roars

SFX_Attn_Loud.json

{
  "Layers": [
    {
      "Files": ["Sounds/TEST/SFX_Test_Blip_A.ogg"],
      "RandomSettings": {
        "MinPitch": 0,
        "MaxPitch": 0,
        "MinVolume": 0
      },
      "Volume": 6.0
    }
  ],
  "Volume": 0,
  "MaxDistance": 45,
  "StartAttenuationDistance": 2
}

Examples

Simple Sound Event

SFX_Player_Hurt.json

{
  "Layers": [
    {
      "Files": [
        "Sounds/PlayerActions/Hurt/Player_Hurt_01.ogg"
      ],
      "RandomSettings": {
        "MinPitch": 0,
        "MaxPitch": 0
      },
      "StartDelay": 0,
      "Volume": -2.0
    }
  ],
  "MaxInstance": 3,
  "Volume": -5,
  "PreventSoundInterruption": true,
  "Parent": "SFX_Attn_Moderate"
}

Sound with Random Variants

Multiple files in Files array are randomly selected:

SFX_Mace_T1_Impact.json

{
  "Layers": [
    {
      "Files": [
        "Sounds/Weapons/Mace/Impacts/Mace_T1_Impact_01.ogg",
        "Sounds/Weapons/Mace/Impacts/Mace_T1_Impact_02.ogg",
        "Sounds/Weapons/Mace/Impacts/Mace_T1_Impact_03.ogg",
        "Sounds/Weapons/Mace/Impacts/Mace_T1_Impact_04.ogg",
        "Sounds/Weapons/Mace/Impacts/Mace_T1_Impact_05.ogg"
      ],
      "Volume": 6.0,
      "RandomSettings": {
        "MinVolume": -1,
        "MinPitch": -2,
        "MaxPitch": 2
      },
      "StartDelay": 0
    }
  ],
  "Volume": 0,
  "PreventSoundInterruption": true,
  "AudioCategory": "AudioCat_Mace",
  "Parent": "SFX_Attn_Moderate"
}

Multi-Layer Sound

Combine multiple sounds for complex effects:

Example multi-layer sound

{
  "Layers": [
    {
      "Files": ["Sounds/Weapons/Sword/Swing_Base.ogg"],
      "Volume": 0
    },
    {
      "Files": ["Sounds/Weapons/Sword/Swing_Whoosh.ogg"],
      "Volume": -3,
      "StartDelay": 0.05
    }
  ],
  "Parent": "SFX_Attn_Moderate"
}

Looping Sound

Looping is set per-layer, not at the top level:

SFX_Candle_Loop.json

{
  "Layers": [
    {
      "Files": ["Sounds/Ambient/Fire_Loop.ogg"],
      "Looping": true
    }
  ],
  "Volume": -4,
  "Parent": "SFX_Attn_Moderate"
}

Sound Event Categories

Player Sounds

Located in SFX/Player/:

Category	Examples
Health/	Hurt, Death, Fall damage
Movement/	Jump, Swim, Footsteps
Action/	Pickup, Drop, Grab

Weapon Sounds

Located in SFX/Weapons/:

Weapon	Sound Types
Sword/	Swing, Impact, Block
Mace/	Swing, Impact, Charged
Bow/	Draw, Release, Impact
Battleaxe/	Swing, Impact
Staff/	Cast, Impact

Block Sounds

Located in BlockSounds/:

Category	Examples
Bush/	Hit, Break, MoveIn
Tall_Grass/	MoveIn
LeavesGround/	Walk, Land, Break

Environment Sounds

Located in Environments/:

Category	Examples
Ambiences/	Zone ambient loops
Weather/	Rain, Thunder, Wind

Audio Categories

Sound events can specify an AudioCategory for volume control:

Category	Description
AudioCat_Music	Background music
AudioCat_Ambience	Environmental sounds
AudioCat_Weapons	Weapon sounds
AudioCat_Mace	Mace-specific sounds
AudioCat_NPC	NPC vocalizations
AudioCat_UI	Interface sounds

Using Sound Events

In Block Definitions

{
  "BlockType": {
    "BlockSoundSetId": "Stone",
    "AmbientSoundEventId": "SFX_Candle_Default_Loop",
    "InteractionSoundEventId": "SFX_Door_Open"
  }
}

In Animation Sets

{
  "AnimationSets": {
    "Walk": {
      "Animations": [{
        "Animation": "...",
        "SoundEventId": "SFX_Fox_Run"
      }]
    }
  }
}

In Interactions

{
  "InteractionVars": {
    "Swing_Damage": {
      "DamageEffects": {
        "WorldSoundEventId": "SFX_Sword_Impact"
      }
    }
  }
}

Creating Custom Sound Events

MyPlugin_CustomSound.json

{
  "Layers": [
    {
      "Files": [
        "MyPlugin/Sounds/Effect_01.ogg",
        "MyPlugin/Sounds/Effect_02.ogg",
        "MyPlugin/Sounds/Effect_03.ogg"
      ],
      "Volume": 0,
      "RandomSettings": {
        "MinPitch": -1,
        "MaxPitch": 1,
        "MinVolume": -2
      }
    }
  ],
  "Volume": 0,
  "MaxInstance": 5,
  "PreventSoundInterruption": false,
  "AudioCategory": "AudioCat_Weapons",
  "Parent": "SFX_Attn_Moderate"
}

Tip

Use the attenuation templates (SFX_Attn_*) as parents to inherit spatial audio settings rather than configuring them manually.

Best Practices

1. Use Parent templates - Inherit from attenuation templates for consistent spatial audio
2. Provide variants - Multiple files in Files array prevent repetitive sounds
3. Add pitch randomization - Small pitch variations (+/- 2 semitones) add naturalness
4. Set appropriate MaxInstance - Prevent audio clutter from overlapping sounds
5. Use AudioCategories - Allow players to adjust volume by category

Related

• Audio Overview - Audio system overview
• Audio Effects - Reverb and EQ presets
• Item Sound Sets - Sound set collections