View source for Sounds

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 <code>sounds.json</code> which should be created at <code><nowiki>assets/<modid>/sounds.json</nowiki></code>. 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 [https://xiph.org/vorbis/ Ogg Vorbis] represented by the extension <code>.ogg</code>. The file <code>namespace:path</code> when referenced in the JSON will be located within <code><nowiki>assets/<namespace>/sounds/<path>.ogg</nowiki></code>.

<syntaxhighlight lang="json">
{
  "example_sound": {
    "sounds": [ "examplemod:example_sound_file" ]
  }
}
</syntaxhighlight>

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

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:
{| class="wikitable sortable" border=1
!Parameter !!Description 
|-
|   name   ||  Sets the path to the sound file excluding the <code>.ogg</code> 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. 
|-
|}

<syntaxhighlight lang="json">
{
  "example_sound": {
    "sounds": [ "examplemod:example_sound_file" ]
  },
  "example_sound_complex": {
    "sounds":
    [
      {
        "name": "examplemod:complex/example_complex",
        "pitch": 0.6,
        "stream": true
      }
    ]
  }
}
</syntaxhighlight>

Now there is a new sound within our JSON called <code>example_sound_complex</code>. This points to the audio file at <code>assets/examplemod/sounds/complex/example_complex.json</code>. The sound's pitch is lowered to 0.6 of its original value. The <code>stream</code> 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 [https://minecraft.gamepedia.com/Sounds.json wiki].

== Creating <code>SoundEvent</code>s ==

A <code>sounds.json</code> 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 <code>SoundEvent</code> class. Each <code>SoundEvent</code> class holds a <code>ResourceLocation</code> to reference a sound pointer defined in the <code>sounds.json</code> file. The <code>sounds.json</code> file used is determined by the namespace or the resource location passed into the class.

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

<code>SoundEvent</code>s must be [[Registration|registered]] to be referenced in code. 

== Playing Sounds ==

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

=== <code>World</code> ===

# <code><nowiki>playSound(PlayerEntity, BlockPos, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#*Simply forwards to overload (2), adding 0.5 to each coordinate of the BlockPos given.
# <code><nowiki>playSound(PlayerEntity, double x, double y, double z, SoundEvent, SoundCategory, volume, pitch)</nowiki></code>
#* <code>Client Behavior</code>: If the passed in player is the client player, plays the sound event to the client player.
#* <code>Server Behavior</code>: Plays the sound event to everyone nearby except the passed in player. Player can be <code>null</code>.
#* <code>Usage</code>: 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 <code>null</code> player, thus letting everyone hear it.
# <code><nowiki>playSound(double x, double y, double z, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* <code>Client Behavior</code>: Just plays the sound event in the client world. If distanceDelay is true, then delays the sound based on how far it is from the player.
#* <code>Server Behavior</code>: Does nothing.
#* <code>Usage</code>: 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.

=== <code> ClientWorld </code> ===

# <code><nowiki>playSound(BlockPos, SoundEvent, SoundCategory, volume, pitch, distanceDelay)</nowiki></code>
#* Simply forwards to <code>World</code>‘s overload (3), adding 0.5 to each coordinate of the <code>BlockPos</code> given.

=== <code> Entity </code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code>
#* Forwards to <code>World</code>‘s overload (2), passing in <code>null</code> as the player.
#* <code>Client Behavior</code>: Does nothing.
#* <code>Server Behavior</code>: Plays the sound event to everyone at this entity’s position.
#* <code>Usage</code>: Emitting any sound from any non-player entity server-side.

=== <code> PlayerEntity</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#Entity|Entity]]</code>)
#* Forwards to <code>World</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Does nothing, see override in <code>[[Sounds#clientplayerentity|ClientPlayerEntity]]</code>.
#* <code>Server Behavior</code>: Plays the sound to everyone nearby <code>except</code> this player.
#* <code>Usage</code>: See <code>[[Sounds#clientplayerentity|ClientPlayerEntity]]</code>.

=== <code> ClientPlayerEntity</code> ===

# <code><nowiki>playSound(SoundEvent, volume, pitch)</nowiki></code> (overriding the one in <code>[[Sounds#playerentity|PlayerEntity]]</code>)
#* Forwards to <code>World</code>‘s overload (2), passing in <code>this</code> as the player.
#* <code>Client Behavior</code>: Just plays the Sound Event.
#* <code>Server Behavior</code>: Method is client-only.
#* <code>Usage</code>: Just like the ones in <code>World</code>, 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.