Sounds/1.17

Although not essential, sounds bring a greater immersion into the Minecraft world. Their usages within and outside the development environment gives a bit more polish to an already existing mod from background music to a single block break.

Creating a Sound

Sounds in Minecraft are comprised of two things: an audio file and a reference pointer to that audio file.

The reference pointer is known as sounds.json which should be created at assets/<modid>/sounds.json. This JSON defines resource names to point to the audio files added by a specific mod. The only thing necessary to define a sound is by creating an object, naming it, and then defining the location of the sound within a list.

By default, the only supported audio format is Ogg Vorbis represented by the extension .ogg. The file namespace:path when referenced in the JSON will be located within assets/<namespace>/sounds/<path>.ogg.

{
  "example_sound": {
    "sounds": [ "examplemod:example_sound_file" ]
  }
}

Using the example above, it creates a sound called example_sound and references the file assets/<modid>/sounds/example_sound_file.ogg.

Danger

Due to the way OpenAL (Minecraft's sound engine) works, for your sound to have attenuation - that is, for it to get quieter as the player walks away, it absolutely MUST be mono (have one audio channel).

Stereo sounds are always played at the player's location, making them ideal for ambient sounds and background music.

Instead of being constructed as a list of strings, each entry could also be an object which allows a greater control over what and how it is played.

Here are some variables that could be defined:

Parameter	Description
name	Sets the path to the sound file excluding the .ogg extension.
stream	Determines whether the sound should be streamed from the file. When true, it reduces the amount of lag from loading a large file; however, it only allows four instances of the sound to be played at once.
volume	A value between 0 and 1 to determine the volume of the sound played.

{
  "example_sound": {
    "sounds": [ "examplemod:example_sound_file" ]
  },
  "example_sound_complex": {
    "sounds":
    [
      {
        "name": "examplemod:complex/example_complex",
        "pitch": 0.6,
        "stream": true
      }
    ]
  }
}

Now there is a new sound within our JSON called example_sound_complex. This points to the audio file at assets/examplemod/sounds/complex/example_complex.json. The sound's pitch is lowered to 0.6 of its original value. The stream parameter is also set to true.

There are many more parameters that can give greater control on how sounds are played. However, this is left as an exercise to the reader to try and construct with the wiki.

Creating SoundEvents

A sounds.json left in its current state would only be defined in-game. There is currently no way to reference the sound within a mod. To do this, we utilize the SoundEvent class. Each SoundEvent class holds a ResourceLocation to reference a sound pointer defined in the sounds.json file. The sounds.json file used is determined by the namespace or the resource location passed into the class.

For example, to reference example_complex.ogg, you would store the reference name (e.g. example_sound_complex) within a new SoundEvent(new ResourceLocation("examplemod", "example_sound_complex")). This will locate assets/examplemod/sounds.json and try to find an example_sound_complex object nested within it.

Warning

SoundEvents must be registered on the ModEventBus to properly reference a sound on a server. However, SoundEvents or referencing a sound by name will still work on the client when the sound is not registered as long as the sound exists in sounds.json!

Playing Sounds

Vanilla has lots of methods for playing sounds that can be used in different scenarios.

Level

1. playSound(Player, BlockPos, SoundEvent, SoundCategory, volume, pitch)
   • Simply forwards to overload (2), adding 0.5 to each coordinate of the BlockPos given.
2. playSound(Player, double x, double y, double z, SoundEvent, SoundCategory, volume, pitch)
   • Client Behavior: If the passed in player is the client player, plays the sound event to the client player.
   • Server Behavior: Plays the sound event to everyone nearby except the passed in player. Player can be null.
   • Usage: The correspondence between the behaviors implies that these two methods are to be called from some player-initiated code that will be run on both logical sides at the same time - the logical client handles playing it to the user and the logical server handles everyone else hearing it without re-playing it to the original user. They can also be used to play any sound in general at any position server-side by calling it on the logical server and passing in a null player, thus letting everyone hear it.
3. playSound(double x, double y, double z, SoundEvent, SoundCategory, volume, pitch, distanceDelay)
   • Client Behavior: Just plays the sound event in the client level. If distanceDelay is true, then delays the sound based on how far it is from the player.
   • Server Behavior: Does nothing.
   • Usage: This method only works client-side, and thus is useful for sounds sent in custom packets, or other client-only effect-type sounds. Used for thunder.

ClientLevel

1. playSound(BlockPos, SoundEvent, SoundCategory, volume, pitch, distanceDelay)
   • Simply forwards to Level‘s overload (3), adding 0.5 to each coordinate of the BlockPos given.

Entity

1. playSound(SoundEvent, volume, pitch)
   • Forwards to LEvel‘s overload (2), passing in null as the player.
   • Client Behavior: Does nothing.
   • Server Behavior: Plays the sound event to everyone at this entity’s position.
   • Usage: Emitting any sound from any non-player entity server-side.

Player

1. playSound(SoundEvent, volume, pitch) (overriding the one in Entity)
   • Forwards to Level‘s overload (2), passing in this as the player.
   • Client Behavior: Does nothing, see override in LocalPlayer.
   • Server Behavior: Plays the sound to everyone nearby except this player.
   • Usage: See LocalPlayer.

LocalPlayer

1. playSound(SoundEvent, volume, pitch) (overriding the one in [[Sounds#player|Player])
   • Forwards to Level‘s overload (2), passing in this as the player.
   • Client Behavior: Just plays the Sound Event.
   • Server Behavior: Method is client-only.
   • Usage: Just like the ones in Level, these two overrides in the player classes seem to be for code that runs together on both sides. The client handles playing the sound to the user, while the server handles everyone else hearing it without re-playing to the original user.