Revision as of 04:56, 10 February 2017

In Staxel, *.sound files are collections of sounds that the game will use depending on it's condition. These files include everything from UI sounds, to the sounds while stepping on blocks to the ambience and music.

There can be three type of music files used with Staxel.

• *.wav - Used for all sound effects. This includes tools, UI etc.
• *.wav.csr - Used to compress *.wav files on disc. The game will decompress them on load.
• *.ogg - Used purely for ambience and music.

As a note, these files will not play by themselves, some other component, such as a tile, needs to play these sounds.

Adding New Sounds To Staxel

Staxel also allows you to add new sounds to staxel. The process for doing so is actually quite simple and as long as you know how to get the sounds, the rest shall follow easily.

Before beginning make sure to follow #Setting up for Mod Creation. There are however two things that you will probably need before getting started however.

First, you need to have an object already made so that you can test the sound. Follow #Creating a In-game object to create one. Anything will do.

Second, you need to have some sound files already made. As a note, the game only allows *.wav files to be played as sounds. If your sounds are not in this format then you can use Audacity and export them to *.wav files.

Once this is done, move the object and the sound files to a new mod folder. Then create a file with an ending of .sound, and place the following into it.

{
  "code" : "mods.modname.modsoundname",
  "sounds" : [
    {
      "file" : "mods/modname/modsoundname1",
      "volume" : 0.4
    },
    {
      "file" : "mods/modname/modsoundname2",
      "volume" : 0.4
    }
  ]
}

You can replace the temporary names with whatever will work for your mod. Do not add .wav to the end of the file. The game automatically adds this. Now in this example it shows 2 sound files added. You can add any number of sounds from 1 to some large number, and the game will just randomly select a sound from the list. If you only have one sound, then remove the content between the { } and remove the preceding comma.

Congrats you have created your sound. Now to get an object to play it, add the following line to the object's *.tile file.

"stepSoundGroup" : "mods.modname.modsoundname"

Once this line is added in, head to gamedata/bin/ and start up Staxel.ContentBuilder.exe. When this has started up, click Validate Resources and wait until the progress bar has done. Now you can load up and hear your sound whenever you walk over your object.

Compressing Sounds

Staxel also has the option to compress these files to save space but not lose quality. These files will be played back the same as any normal *.wav file, but will take up much less space than even a zipped file.

Before doing this, you will want to make sure you have a backup of the sound file, as it will be overwritten.

You can compress your file by simply heading to gamedata/bin/ and start up Staxel.ContentBuilder.exe. When this has started up, click Compress .wav assests, wait a moment and then click Validate Resources and wait until the progress bar has done. Now all the sound assests you added are compressed and will still run in staxel.

Config Options

"__inherit"

Valid options (String): Any path pointing to any text file (*.config recommended). Starting at, but not including, the "content" folder

This option specifies a file, in which the game will import alongside the file you are creating. The game will then use the information in the inherited file and place the information in the current file over it. As in, any values that are in the file that is inheriting file will override any values in the inherited file. The main point of this option is to bring files with duplicated info into one file, thus reducing space used by files and also the ability to change one file and affect all items inheriting that file.

For example: If you have a *.config file that includes;

{
  "code" : "mods.testsound",
  "sounds" : [
    {
      "file" : "mods/modname/modsoundname1",
      "volume" : 0.4
    }
  ]
}

And then have the line "_inherit" : "FilePathHere/file.config" in your file, it will automatically pull any data from the inherited file, but then replace values in that file with the values above.

"code"

Valid options (String): Any valid string. Common to make the string the path to the model but with periods [.] replacing slashes [/]

This option is required to uniquely identify any object or resource. This path must be unique to all other codes, but does not have any other requirements.

For example: Having the code "mods.testsound.soundgroup1" creates an object that has the handle "mods.testsound.soundgroup1"

"sounds"

Sounds is a list of smaller JSON files which contain information on files. It is written as:

{
  "sounds" : [
    {
      //Stuff here
    },
    {
      //Stuff here
    }
  ]
}

Each set contains the values below.

"file"

Valid options (String): Any path pointing to a audio file. Do not include ".wav", ".ogg" or ".wav.csr". Starting at, but not including, the "content" folder

This option points to the audio file. It is however missing the extension on purpose as the game will add the extension while playing the sound.

For example: Having the file name "mods/testsound/sound1" look for an object that is either "mods/testsound/sound1.wav", "mods/testsound/sound1.ogg" or "mods/testsound/sound1.wav.csr" depending on context.

"volume"

Valid options (float): A value between 0.0 and 1.0.

Mutally exlusive from "randomVolume" option. Cannot have volume and randomVolume at the same time for a single file.

This option tells the game exactly how loud to play the sound.

"randomVolume"

Valid options (vector): A vector set with two values between 0.0 and 1.0.

Mutally exlusive from "randomVolume" option. Cannot have volume and randomVolume at the same time for a single file.

This option tells the game exactly to play the sound at a random volume between two points, x (min) and y (max). The vector can be created as so;

"randomVolume" : {
    "x" : 0.1,
    "y" : 0.8
}

"randomPitch"

Valid options (float): A value to multiply base value that is between 0.0 and 1.0.

The amount that the played sound's pitch will change between consecutive plays of a sound.

"ambience"

Ambience is used when a weather file specifies what set of sounds to be used during day or night. Specifing this is the file, will allow you to control what these values are rather than using the default values.

This can be safely ignored if not creating a sound that will be played as ambience. To create these settings however, put the following in your file:

"ambience" : {
    "frequency" : 800,
    "volume" : 1.0,
    "volumeVariance" : 0.0,
    "freqVariance" : 400,
    "pitchVariance" : 0.5,
    "distance" : 10.0,
    "distanceVariance" : 20.0
}

"frequency"

Valid options (Int): A valid interger number for the number of milliseconds between plays.

This is the amount of time between two plays of the sounds in the group.

"freqVariance"

Valid options (Int): A valid interger number for the variance of the number of milliseconds between plays.

This is the range, -"freqVariance" to "freqVariance", around the base frequency that the sound will be played at.

"volume"

Valid options (float): A value between 0.0 and 1.0.

Mutally exlusive from "randomVolume" option. Do not include both in the same set

This option tells the game exactly how loud to play the sound. Applied to the original sound volume in the sound group.

"volumeVariance"

Valid options (float): A value to multiply base value that is between 0.0 and 1.0.

This is the range, -"volumeVariance" to "volumeVariance", around the base volume's value. Only affects the "volume" value in ambience.

"pitchVariance"

Valid options (float): A value to multiply base value that is between 0.0 and 1.0.

The amount that the played sounds pitch will change between plays of the sound.

"distance"

Valid options (float): A value of distance from the player to the sound.

The amount of space between the player and the sound. This will end up changing volume and other things.

"distanceVariance"

Valid options (float): A value for the variance of the distance.

The range of distance, -"distanceVariance" to "distanceVariance", around the distance that the sound is emitted