Skip to main content
Sound definitions manage audio files and sound events in Minecraft add-ons, mapping sound identifiers to audio files and configuring playback properties.

​
SoundDefinitionCatalogDefinition

SoundDefinitionCatalogDefinition manages the sound definitions catalog file (RP/sounds/sound_definitions.json), which maps sound event names to audio files.

​
Class Signature

class SoundDefinitionCatalogDefinition {
  // Properties
  id?: string;
  readonly isLoaded: boolean;
  readonly file?: IFile;
  _data?: ISoundDefinitionCatalog;
  
  // Sound definition methods
  getSoundDefinitionSetNameList(): string[] | undefined;
  getSoundDefinitionSoundInstanceList(): (string | ISoundReference)[] | undefined;
  getCanonincalizedSoundPathList(): string[] | undefined;
  readonly soundDefinitionPathList?: string[];
  
  // Sound queries
  getSoundDefinitionMatchesByPath(file: IFile): { [name: string]: ISoundDefinition } | undefined;
  getSoundReferenceMatchesByPath(file: IFile): { [name: string]: ISoundReference[] } | undefined;
  hasSoundByPath(soundDefSet: ISoundDefinition, path: string): ISoundReference | string | undefined;
  
  // Sound management
  ensureDefintionForFile(project: Project, file: IFile): void;
  
  // Loading and persistence
  static async ensureOnFile(file: IFile, handler?): Promise<SoundDefinitionCatalogDefinition>;
  async load(): Promise<void>;
  persist(): boolean;
  
  // Utilities
  getPackRootFolder(): IFolder | undefined;
  getRelativePath(file: IFile, packRootFolder: IFolder): string | undefined;
  async addChildItems(project: Project, item: ProjectItem): Promise<void>;
  async deleteLinkToChild(childItem: ProjectItem): Promise<void>;
}

​
Loading Sound Definitions

import { SoundDefinitionCatalogDefinition } from 'minecraft-creator-tools';

// Load sound definitions catalog
const soundDefs = await SoundDefinitionCatalogDefinition.ensureOnFile(file);

console.log('Sound definitions loaded');

// Get all sound definition names
const soundNames = soundDefs.getSoundDefinitionSetNameList();
if (soundNames) {
  for (const name of soundNames) {
    console.log('Sound:', name);
  }
}

// Get all sound file paths
const soundPaths = soundDefs.getCanonincalizedSoundPathList();
if (soundPaths) {
  for (const path of soundPaths) {
    console.log('Audio file:', path);
  }
}

​
Working with Sound Definitions

// Access sound definitions
if (soundDefs._data?.sound_definitions) {
  const soundDefSet = soundDefs._data.sound_definitions;
  
  for (const soundName in soundDefSet) {
    const soundDef = soundDefSet[soundName];
    console.log('Sound:', soundName);
    console.log('Category:', soundDef.category);
    console.log('Sounds:', soundDef.sounds);
  }
}

// Add new sound definition
if (soundDefs._data) {
  if (!soundDefs._data.sound_definitions) {
    soundDefs._data.sound_definitions = {};
  }
  
  soundDefs._data.sound_definitions['custom.magic.cast'] = {
    category: 'player',
    sounds: [
      {
        name: 'sounds/magic/cast',
        volume: 1.0,
        pitch: 1.0,
        is3D: true,
        weight: 10
      }
    ]
  };
  
  soundDefs.persist();
}

​
Sound Definitions JSON Structure

{
  "format_version": "1.14.0",
  "sound_definitions": {
    "custom.monster.roar": {
      "category": "hostile",
      "sounds": [
        {
          "name": "sounds/mob/monster/roar1",
          "volume": 1.0,
          "pitch": 1.0,
          "is3D": true,
          "weight": 10
        },
        {
          "name": "sounds/mob/monster/roar2",
          "volume": 0.9,
          "pitch": 0.95,
          "is3D": true,
          "weight": 8
        },
        {
          "name": "sounds/mob/monster/roar3",
          "volume": 1.1,
          "pitch": 1.05,
          "is3D": true,
          "weight": 7
        }
      ]
    },
    "custom.ambient.magic": {
      "category": "ambient",
      "sounds": [
        "sounds/ambient/magic_hum"
      ]
    },
    "custom.item.use": {
      "category": "player",
      "max_distance": 16.0,
      "sounds": [
        {
          "name": "sounds/item/use",
          "volume": 0.7,
          "is3D": false
        }
      ]
    }
  }
}

​
Sound Definition Properties

​
Sound Definition Object

interface ISoundDefinition {
  category?: string;              // Sound category
  max_distance?: number;          // Maximum hearing distance
  min_distance?: number;          // Minimum hearing distance
  sounds: (string | ISoundReference)[];  // Sound files
}

interface ISoundReference {
  name: string;                   // Path to audio file
  volume?: number;                // Volume (0.0 - 1.0)
  pitch?: number;                 // Pitch multiplier
  is3D?: boolean;                 // 3D positional audio
  weight?: number;                // Selection weight
  stream?: boolean;               // Stream from disk
  load_on_low_memory?: boolean;   // Load in low memory mode
}

​
Sound Categories

  • ambient - Ambient environment sounds
  • weather - Weather sounds (rain, thunder)
  • player - Player action sounds
  • neutral - Neutral mob sounds
  • hostile - Hostile mob sounds
  • block - Block interaction sounds
  • bucket - Bucket sounds
  • bottle - Bottle sounds
  • ui - User interface sounds
  • music - Background music

​
Working with Audio Files

​
Finding Sounds by Path

import { IFile } from 'minecraft-creator-tools';

// Find sound definitions that reference a file
const matches = soundDefs.getSoundDefinitionMatchesByPath(audioFile);
if (matches) {
  for (const soundName in matches) {
    const soundDef = matches[soundName];
    console.log('Found in:', soundName);
    console.log('Category:', soundDef.category);
  }
}

// Find specific sound references
const soundRefs = soundDefs.getSoundReferenceMatchesByPath(audioFile);
if (soundRefs) {
  for (const soundName in soundRefs) {
    const refs = soundRefs[soundName];
    for (const ref of refs) {
      if (typeof ref === 'object') {
        console.log('Volume:', ref.volume);
        console.log('Pitch:', ref.pitch);
      }
    }
  }
}

​
Auto-creating Definitions

import { Project } from 'minecraft-creator-tools';

// Automatically create sound definition for audio file
soundDefs.ensureDefintionForFile(project, audioFile);
// Creates definition based on file name

// Example: sounds/mob/dragon/roar.ogg
// Creates: dragon.roar sound definition

​
Checking if Sound Exists

if (soundDefs._data?.sound_definitions) {
  const dragonRoar = soundDefs._data.sound_definitions['dragon.roar'];
  
  if (dragonRoar) {
    const hasSound = soundDefs.hasSoundByPath(
      dragonRoar,
      'sounds/mob/dragon/roar'
    );
    
    if (hasSound) {
      console.log('Sound already registered');
    }
  }
}

​
Complete Sound Definition Examples

​
Multiple Variants with Weights

{
  "custom.footstep.stone": {
    "category": "player",
    "sounds": [
      {
        "name": "sounds/step/stone1",
        "volume": 0.5,
        "is3D": true,
        "weight": 10
      },
      {
        "name": "sounds/step/stone2",
        "volume": 0.45,
        "is3D": true,
        "weight": 10
      },
      {
        "name": "sounds/step/stone3",
        "volume": 0.55,
        "is3D": true,
        "weight": 8
      },
      {
        "name": "sounds/step/stone4",
        "volume": 0.5,
        "is3D": true,
        "weight": 7
      }
    ]
  }
}

​
Music with Streaming

{
  "music.game.custom_theme": {
    "category": "music",
    "sounds": [
      {
        "name": "sounds/music/custom_theme",
        "volume": 0.6,
        "stream": true,
        "load_on_low_memory": true
      }
    ]
  }
}

​
Positional Sound with Distance

{
  "custom.machine.running": {
    "category": "block",
    "max_distance": 32.0,
    "min_distance": 1.0,
    "sounds": [
      {
        "name": "sounds/machine/running",
        "volume": 0.8,
        "is3D": true
      }
    ]
  }
}

​
Creating Sound System

import { SoundDefinitionCatalogDefinition } from 'minecraft-creator-tools';

const soundDefs = await SoundDefinitionCatalogDefinition.ensureOnFile(file);

// Initialize if needed
if (!soundDefs._data) {
  soundDefs._data = {
    format_version: '1.14.0',
    sound_definitions: {}
  };
}

if (!soundDefs._data.sound_definitions) {
  soundDefs._data.sound_definitions = {};
}

const defs = soundDefs._data.sound_definitions;

// Add weapon sounds
defs['custom.weapon.sword.swing'] = {
  category: 'player',
  sounds: [
    { name: 'sounds/weapon/sword/swing1', volume: 0.7, is3D: true, weight: 10 },
    { name: 'sounds/weapon/sword/swing2', volume: 0.7, is3D: true, weight: 10 },
    { name: 'sounds/weapon/sword/swing3', volume: 0.7, is3D: true, weight: 8 }
  ]
};

defs['custom.weapon.sword.hit'] = {
  category: 'player',
  sounds: [
    { name: 'sounds/weapon/sword/hit1', volume: 0.9, is3D: true, weight: 10 },
    { name: 'sounds/weapon/sword/hit2', volume: 0.85, is3D: true, weight: 8 }
  ]
};

// Add magic sounds
defs['custom.magic.spell.cast'] = {
  category: 'player',
  sounds: [
    { name: 'sounds/magic/cast', volume: 1.0, pitch: 1.0, is3D: false }
  ]
};

defs['custom.magic.spell.impact'] = {
  category: 'neutral',
  max_distance: 48.0,
  sounds: [
    { name: 'sounds/magic/impact', volume: 1.2, is3D: true }
  ]
};

// Add ambient sounds
defs['custom.ambient.dungeon'] = {
  category: 'ambient',
  max_distance: 64.0,
  sounds: [
    { name: 'sounds/ambient/dungeon/echo1', volume: 0.3, is3D: true, weight: 10 },
    { name: 'sounds/ambient/dungeon/echo2', volume: 0.25, is3D: true, weight: 8 },
    { name: 'sounds/ambient/dungeon/drip', volume: 0.4, is3D: true, weight: 5 }
  ]
};

// Add monster sounds
defs['custom.monster.boss.roar'] = {
  category: 'hostile',
  max_distance: 128.0,
  sounds: [
    { name: 'sounds/mob/boss/roar', volume: 1.5, pitch: 0.8, is3D: true }
  ]
};

defs['custom.monster.boss.death'] = {
  category: 'hostile',
  max_distance: 96.0,
  sounds: [
    { name: 'sounds/mob/boss/death', volume: 1.8, stream: true, is3D: true }
  ]
};

// Save
soundDefs.persist();
console.log('Sound system created with', Object.keys(defs).length, 'definitions');

​
Using Sounds in Definitions

​
In Entity Definitions

{
  "minecraft:entity": {
    "component_groups": {},
    "components": {
      "minecraft:ambient_sound_interval": {
        "event_name": "custom.monster.idle",
        "range": 16.0,
        "value": 8.0
      },
      "minecraft:hurt_on_condition": {
        "damage_conditions": [
          {
            "cause": "contact",
            "damage_per_tick": 2,
            "on_damage": {
              "event": "custom:take_damage_sound"
            }
          }
        ]
      }
    },
    "events": {
      "custom:take_damage_sound": {
        "queue_command": {
          "command": "/playsound custom.monster.hurt @a ~ ~ ~ 1.0"
        }
      }
    }
  }
}

​
In Animation Definitions

{
  "animations": {
    "animation.custom.attack": {
      "animation_length": 1.0,
      "timeline": {
        "0.0": [
          "/playsound custom.weapon.sword.swing @a ~ ~ ~ 1.0"
        ],
        "0.5": [
          "/playsound custom.weapon.sword.hit @a ~ ~ ~ 1.0"
        ]
      }
    }
  }
}

​
Audio File Formats

Supported audio formats:
  • .ogg - Recommended (Ogg Vorbis)
  • .fsb - Supported (FMOD Sound Bank)
  • .wav - Supported but larger file size
Recommended settings:
  • Sample rate: 44100 Hz
  • Bit depth: 16-bit
  • Channels: Mono for 3D sounds, Stereo for music

Build docs developers (and LLMs) love

Get started for freeTalk to us