Minecraft Modding: Organizing Sound Assets

Introduction

In 1.7.2 the way sounds are organized is bit different than in previous versions and it can take a little bit of attention to get it right.  Also, sounds use a special format called OGG that some people may not be that familiar with.  All these need to be described in a JSON file which is a human-readable format for hierarchical tagged information.

This tutorial gives an introduction to these topics.  My examples are related to entity sounds, but the concepts should apply to other sound types in your mods.

Convert Entity Sound Assets Into OGG Format

For use in Minecraft, all your sound asset files should be OGG format. The OGG format (also called "Ogg Vorbis") has the benefit of being entirely open source and patent-free.

Your sound assets cannot be in MP3, WAV, or other such common formats but if you have such files you want to use it is easy to convert them.

Tip: Free converters are available to convert MP3 and WAV to OGG (I use one called “FreeMP3WMAOGGConverter”).

Tip: To listen to OGG files (perhaps to test that your file conversions worked) you can use the open source VLC media player.

Name Your Sound Asset Files Meaningfully

As you make mods, you'll find that for some you'll have a lot of sound assets.  Like everything in programming, I suggest you name your files meaningfully.

Warning: I'm not certain but it seems like it may be necessary (or at least common practice) to use all lowercase names for your sound asset files.

Put Entity Sound Assets Into Proper Folders

Warning: For those coming from earlier versions, in 1.7.2 the assets folder for Minecraft sounds changed to “sounds” (plural). So an example sounds path for one of my mods is:

ModdingWorkspace\WildAnimalsPlus\src\main\resources\assets\wildanimals\sounds\mob\elephant

Update sounds.json File As You Add Sound Assets

In 1.7.2 we use a JSON format to index our sounds assets (the assets themselves are arranged in various subfolders).  JSON has the advantages of being open source, human-readable, and supported well in Java.

Ensure The sounds.json File Is In Correct Folder

Key point: The sounds.json file should not be in the actual sounds asset folder, but rather at top level of assets for the mod.

Tip: Make sure the sounds.json is "seen" by Eclipse in the package explorer.  You may need to import the file (rather than just saving it).

For example, in one of my mods, the sounds.json is in: ModdingWorkspace\WildAnimalsPlus\src\main\resources\assets\wildanimals 

Edit The sounds.json File

Minecraft has defined a series of JSON tags to serve as an index to sound files.  In particular it maps names that you can reference in your mod code to actual file names.

In that mapping you can categorize the types of sound (this mostly is used for the volume slider controls), but also allows for some interesting functionality such as you can have an array of sounds associated with a tag which allows for some randomness, or you can chain together "events" (according to Dinnerbone).

Tip:  It is easy to mess up the JSON because it has a lot of nested brackets.  So you can use an online JSON validator to check that the JSON is properly constructed.  It is cool because they will allow you to collapse and expand the hierarchy.

Key point: The file names in your JSON should omit the .ogg file extension.

Example from one of my mod's sounds.json:

{
    "mob.bigCat.bark":
    {
        "category": "neutral",
        "sounds":
        [
            "mob/tiger/bark1",
            "mob/tiger/bark2",
            "mob/tiger/bark3"
        ]
    },
    "mob.bigCat.death":
    {
        "category": "neutral",
        "sounds":
        [
            "mob/tiger/death"
        ]
    },
    "mob.bigCat.growl":
    {
        "category": "neutral",
        "sounds":
        [
            "mob/tiger/growl1",
            "mob/tiger/growl2",
            "mob/tiger/growl3",
            "mob/tiger/growl4"
        ]
    }
}

It  should be fairly self-explanatory.  You can see that I'm simply giving names to sounds, along with a category, and associating them with actual sound files.  The interesting thing is that for some names I give multiple files -- this creates some variety (they will be randomly selected).  In this example, the growl will have variety between four actual growl sounds.

Referencing A Sound Asset From Your Code

Once the sounds.json is set up, you can reference the sound asset by using the name tag for the sound.

For example, to play a growl within an entity class:

playSound("mob.bigCat.growl", getSoundVolume(), getSoundPitch())

Conclusion

Hope this helps.  Please feel free to write suggestions for corrections or clarifications!