Skip to content

Sound Data Generation

Jump to bottom
Maksym Uimanov edited this page Jan 30, 2026 · 1 revision

GenerateSound

The @GenerateSound annotation enables automated sound definition generation during the gradle runData phase. This annotation eliminates the need for manual sound JSON file creation by allowing developers to configure sound properties directly on Holder<SoundEvent> fields.

Responsibilities / Purpose

The @GenerateSound annotation serves to:

  • Automate sound definition generation - Create sound JSON files from annotated fields
  • Configure sound properties - Set volume, pitch, weight, attenuation, and streaming options
  • Support multiple sound variants - Allow multiple sound files for the same sound event
  • Integrate with localization - Work seamlessly with the framework's translation system
  • Simplify sound setup - Replace manual data provider implementations

How it works

The annotation system operates during data generation by scanning fields annotated with @GenerateSound. Each annotated field must be a Holder<SoundEvent> and the annotation properties define the sound's behavior. The framework generates corresponding sound definition JSON files and automatically creates subtitle localization keys.

Core Architecture

  • Field-level annotation - Applied to Holder<SoundEvent> fields
  • Multi-sound support - Each annotation can contain multiple sound definitions
  • Property-based configuration - Sound behavior defined through nested annotation properties
  • Automatic registration - Fields are automatically discovered and processed during data generation

How to use / Configure

Basic Sound

public final class ModSounds {
    private static SoundEventFactory SOUND_EVENT_FACTORY = InjectionPool.getFromInstance(SoundEventFactory.class);

    @GenerateSound(@GenerateSound.Sound(fileName = "example_sound"))
    public static final Holder<SoundEvent> EXAMPLE_SOUND = SOUND_EVENT_FACTORY.create("example_sound");
}

Sound with Custom Properties

public final class ModSounds {
    private static SoundEventFactory SOUND_EVENT_FACTORY = InjectionPool.getFromInstance(SoundEventFactory.class);

    @GenerateSound(@GenerateSound.Sound(
        fileName = "custom_sound",
        volume = 0.8,
        pitch = 1.2,
        weight = 2,
        attenuationDistance = 24
    ))
    public static final Holder<SoundEvent> CUSTOM_SOUND = SOUND_EVENT_FACTORY.create("custom_sound");
}

Multiple Sound Variants

public final class ModSounds {
    private static SoundEventFactory SOUND_EVENT_FACTORY = InjectionPool.getFromInstance(SoundEventFactory.class);

    @GenerateSound({
        @GenerateSound.Sound(fileName = "step_1", weight = 1),
        @GenerateSound.Sound(fileName = "step_2", weight = 1),
        @GenerateSound.Sound(fileName = "step_3", weight = 1)
    })
    public static final Holder<SoundEvent> STEP_SOUND = SOUND_EVENT_FACTORY.create("step_sound");
}

Extension and Customization

Sound Types

Configure different sound types for various purposes:

@GenerateSound(@GenerateSound.Sound(
    fileName = "ambient_sound",
    type = SoundDefinition.SoundType.SOUND
))
// Standard sound effect

@GenerateSound(@GenerateSound.Sound(
    fileName = "background_music",
    type = SoundDefinition.SoundType.MUSIC
))
// Background music

@GenerateSound(@GenerateSound.Sound(
    fileName = "record_sound",
    type = SoundDefinition.SoundType.RECORD
))
// Music disc sound

Volume Configuration

Set appropriate volume levels:

@GenerateSound(@GenerateSound.Sound(
    fileName = "quiet_sound",
    volume = 0.1
))
// Very quiet (10% volume)

@GenerateSound(@GenerateSound.Sound(
    fileName = "normal_sound",
    volume = 1.0
))
// Normal volume (100%)

@GenerateSound(@GenerateSound.Sound(
    fileName = "loud_sound",
    volume = 2.0
))
// Loud (200% volume)

Pitch Configuration

Adjust sound pitch:

@GenerateSound(@GenerateSound.Sound(
    fileName = "low_pitch",
    pitch = 0.5
))
// Half pitch (lower)

@GenerateSound(@GenerateSound.Sound(
    fileName = "normal_pitch",
    pitch = 1.0
))
// Normal pitch

@GenerateSound(@GenerateSound.Sound(
    fileName = "high_pitch",
    pitch = 1.5
))
// Higher pitch

Attenuation Distance

Set sound travel distance:

@GenerateSound(@GenerateSound.Sound(
    fileName = "close_sound",
    attenuationDistance = 8
))
// Short distance (8 blocks)

@GenerateSound(@GenerateSound.Sound(
    fileName = "normal_sound",
    attenuationDistance = 16
))
// Normal distance (16 blocks)

@GenerateSound(@GenerateSound.Sound(
    fileName = "far_sound",
    attenuationDistance = 32
))
// Long distance (32 blocks)

When to use

  • Custom sound effects - Use for mod-specific sounds (ambient, actions, events)
  • Music and audio - Use for background music, jukebox songs, and long audio files
  • Sound variations - Use when multiple sound files should play randomly for one event
  • Weighted sounds - Use when some variants should play more frequently than others
  • Localization integration - Use when working with the framework's translation system

The @GenerateSound annotation is designed for most sound generation scenarios, providing type safety and integration with the framework's ecosystem. For highly specialized sound requirements or complex audio systems, manual sound definition providers offer more direct control.

🚀 Getting Started
🧩 Core Concepts
⚙️ Data Generation
🚨 Events
🛠 Engine Layers
🧪 Resources

Clone this wiki locally