Difference between revisions of "Sound"

From wiki
Jump to: navigation, search
("ambience")
(Add new properties and update formatting.)
 
(7 intermediate revisions by the same user not shown)
Line 49: Line 49:
  
 
= Compressing Sounds =
 
= Compressing Sounds =
Staxel also has the option to compress these files to save space but not lose quality. 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 <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.  When this has started up, click '''<tt>Compress .wav assests</tt>''', wait a moment and then click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Now all the sound assests you added are compressed and will still run in staxel.
+
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 '''<tt>*.wav</tt>''' 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.'''
  
= Config Options =
+
You can compress your file by simply heading to <code>gamedata/bin/</code> and start up '''<code>Staxel.ContentBuilder.exe</code>'''.  When this has started up, click '''<tt>Compress .wav assests</tt>''', wait a moment and then click '''<tt>Validate Resources</tt>''' and wait until the progress bar has done. Now all the sound assests you added are compressed and will still run in staxel.
== "__inherit" ==
+
'''Valid options (String): <code>Any path pointing to any text file (*.config recommended). Starting at, but not including, the "content" folder</code>'''
+
  
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;
 
<pre>{
 
  "code" : "mods.testsound",
 
  "sounds" : [
 
    {
 
      "file" : "mods/modname/modsoundname1",
 
      "volume" : 0.4
 
    }
 
  ]
 
}</pre>
 
  
And then have the line <code> "_inherit" : "FilePathHere/file.config"</code> in your file, it will automatically pull any data from the inherited file, but then replace values in that file with the values above.
+
= Useful components =
 +
Sounds do not have many useful components. Sounds don't have many components as they are not specifically used by the game but they do have a single component which is used specifically for sounds.  
  
 +
== [[Ambience Component]] ==
 +
This component is used to specify sounds for playing as ambience. In game this is specifically used to play the bird sounds you hear throughout the day.
  
 +
For more information on how to use the ambience component, head to [[Ambience Component#When and How to use]].
 +
 +
 +
 +
= Config Options =
 
== "code" ==
 
== "code" ==
'''Valid options (String): <code>Any valid string. Common to make the string the path to the model but with periods [.] replacing slashes [/] </code>'''
+
'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A unique string which sound what this object is.</code>'''
 +
 
 +
'''Default Value:''' No default value is specified. Always need to provide your own.
 +
 
  
 
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.
 
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.
Line 81: Line 80:
  
 
== "sounds" ==
 
== "sounds" ==
Sounds is a list of smaller JSON files which contain information on files. It is written as:
+
Sounds is a list of smaller JSON/Blob files which contain information on files. It is written as:
 
<pre>{
 
<pre>{
 
   "sounds" : [
 
   "sounds" : [
Line 94: Line 93:
  
 
Each set contains the values below.
 
Each set contains the values below.
 +
 +
 +
== "emitterCode" ==
 +
'''Valid options ([[Modding_Key_Terms#String|String]]): <code>The kind of sound emitter to use.</code>'''
 +
 +
'''Default Value:''' If not specified, will default to "staxel.audioEmitter.Default".
 +
 +
This is the type of emitter you want to use for this Sound. Different [[Audio Emitters]] have different properties. The current emitters in the game are;
 +
 +
* "staxel.audioEmitter.Default": The normal sound emitter.
 +
* "staxel.audioEmitter.Fireworks": The emitter used for fireworks. Has longer range than the default emitter.
 +
* "staxel.audioEmitter.ClockTowerChime": Same as the fireworks emitter, but for the Clock.
 +
  
 
=== "file" ===
 
=== "file" ===
'''Valid options (String): <code>Any path pointing to a audio file. Do not include ".wav", ".ogg" or ".wav.csr". Starting at, but not including, the "content" folder </code>'''
+
'''Valid options ([[Modding_Key_Terms#String|String]]): <code>A string which contains the path to an audio file. Do not include ".wav", ".ogg" or ".wav.csr".</code>'''
 +
 
 +
'''Default Value:''' No default value is specified. Always need to provide your own.
 +
 
  
 
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.
 
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.
Line 102: Line 117:
 
For example: Having the file name <code> "mods/testsound/sound1"</code> look for an object that is either "mods/testsound/sound1.wav", "mods/testsound/sound1.ogg" or "mods/testsound/sound1.wav.csr" depending on context.
 
For example: Having the file name <code> "mods/testsound/sound1"</code> 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): <code>A value between 0.0 and 1.0.</code>'''
 
  
'''Mutally exlusive from "randomVolume" option. Do not include both in the same set'''
+
=== "randomPitch" ===
 +
'''Valid options ([[Modding_Key_Terms#Vector 2|Vector 2]] - [[Modding_Key_Terms#Float|Float]]): <code>{"x":-1.0, "y":1.0}</code>'''
  
This option tells the game exactly how loud to play the sound.  
+
'''Default Value:''' If not specified, then pitch will not vary.
  
=== "randomVolume" ===
+
This option tells the game exactly to play the sound at a random pitch between two points, x (min) and y (max).
'''Valid options (vector): <code>A vector set with two values between 0.0 and 1.0.</code>'''
+
  
'''Mutally exlusive from "randomVolume" option. Do not include both in the same set'''
 
  
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" ===
<pre>
+
'''Valid options ([[Modding_Key_Terms#Vector 2|Vector 2]] - [[Modding_Key_Terms#Float|Float]]): <code>{"x":0.0, "y":1.0}</code>'''
"randomVolume" : {
+
    "x" : 0.1,
+
    "y" : 0.8
+
}
+
</pre>
+
  
== "ambience" ==
+
'''Default Value:''' If this is specified, "volume" cannot be used. Only one of the two can, and must, be specified.
Will need to get information on how exactly it is used.
+
  
Ambience is a single set of values which are then passed on to player to create a new sound based certain settings. It can be made as:
+
This option tells the game exactly to play the sound at a random volume between two points, x (min) and y (max).
<pre>
+
"ambience" : {
+
    "frequency" : 800,
+
    "volume" : 1.0,
+
    "volumeVariance" : 0.0,
+
    "freqVariance" : 400,
+
    "pitchVariance" : 0.5,
+
    "distance" : 10.0,
+
    "distanceVariance" : 20.0
+
}
+
</pre>
+
  
=== "frequency" ===
 
'''Valid options (Int): <code>A valid interger number for the number of milliseconds between plays./code>'''
 
  
This is the amount of time between two plays of the soundgroup.
+
=== "volume" ===
 +
'''Valid options ([[Modding_Key_Terms#Float|Float]]): <code>A value between 0.0 and 1.0.</code>'''
  
=== "freqVariance" ===
+
'''Default Value:''' If "randomVolume" is specified, this cannot be used. Only one of the two can, and must, be specified.
'''Valid options (Int): <code>A valid interger number for the variance of the number of milliseconds between plays./code>'''
+
  
This is the range, -"freqVariance" to "freqVariance", around the base frequency that the sound will be played at.
 
  
=== "volume" ===
+
This option tells the game exactly how loud to play the sound.

Latest revision as of 02:01, 17 November 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.


Useful components

Sounds do not have many useful components. Sounds don't have many components as they are not specifically used by the game but they do have a single component which is used specifically for sounds.

Ambience Component

This component is used to specify sounds for playing as ambience. In game this is specifically used to play the bird sounds you hear throughout the day.

For more information on how to use the ambience component, head to Ambience Component#When and How to use.


Config Options

"code"

Valid options (String): A unique string which sound what this object is.

Default Value: No default value is specified. Always need to provide your own.


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/Blob files which contain information on files. It is written as:

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

Each set contains the values below.


"emitterCode"

Valid options (String): The kind of sound emitter to use.

Default Value: If not specified, will default to "staxel.audioEmitter.Default".

This is the type of emitter you want to use for this Sound. Different Audio Emitters have different properties. The current emitters in the game are;

  • "staxel.audioEmitter.Default": The normal sound emitter.
  • "staxel.audioEmitter.Fireworks": The emitter used for fireworks. Has longer range than the default emitter.
  • "staxel.audioEmitter.ClockTowerChime": Same as the fireworks emitter, but for the Clock.


"file"

Valid options (String): A string which contains the path to an audio file. Do not include ".wav", ".ogg" or ".wav.csr".

Default Value: No default value is specified. Always need to provide your own.


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.


"randomPitch"

Valid options (Vector 2 - Float): {"x":-1.0, "y":1.0}

Default Value: If not specified, then pitch will not vary.

This option tells the game exactly to play the sound at a random pitch between two points, x (min) and y (max).


"randomVolume"

Valid options (Vector 2 - Float): {"x":0.0, "y":1.0}

Default Value: If this is specified, "volume" cannot be used. Only one of the two can, and must, be specified.

This option tells the game exactly to play the sound at a random volume between two points, x (min) and y (max).


"volume"

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

Default Value: If "randomVolume" is specified, this cannot be used. Only one of the two can, and must, be specified.


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