Sound system¶
The sound system allows you to play sounds and music.
Note
The sound system currently does not feature a user interface and has to be configured by manually authoring JSON files.
Preparing sound effects¶
After preparing your audio files, you need to create the appropriate sound effects. A single sound effect comprises one or multiple audio samplers, which reference the actual audio files on disk.
To create a sound effect, create a my_sound_effect.effect.json
file in the media/sounds
directory in a data source of your choice, right next to your audio files. The effect file has the following format:
{
"my_sound_effect": {
// The member parameters of your effect as
// as depicted below
"audio_samplers": [
{
// Parameters for a single audio sampler as
// depicted below
}
]
}
}
A single effect supports the following parameters:
- audio_samplers
Array of audio samplers
The audio samplers for this effect. A single effect can play multiple samplers at the same time.
- volume
Float, optional
The volume for this sound effect. Use a value of
0.0
for a muted and a value of1.0
for the loudest sound effect.- looping
Boolean, optional
Set to
true
to automatically restart the effect instance when it has finished playing. Great for background music or ambient effects.- spatial
Boolean, optional
Set to
true
for spatial/3D sound effects. Spatial effects have a position in 3D space and change their volume depending on the listener’s position.- spatial_size
Float, optional
The spatial size of the effect. If the distance to the listener is less than this value, the effect fades into a non-spatial sound effect.
- dist_att_min
Float, optional
The minimum distance attenuation volume. Sound effects will never get quieter than this volume value when attenuated based on the distance to the listener.
- dist_att_power
Float, optional
Specifies how quickly a sound effect is attenuated based on the distance to the listener.
- dist_att_range
Float, optional
The range world units in which the distance attenuation operates. Effects out of this range will be attenuated to the volume specified by the
dist_att_min
parameter.
Audio samplers support the following parameters:
- file_names
Array of strings
List of file names, including the file extension, of the audio files to play for this sampler. If more than one file name is provided, a random file is picked every time the effect is restarted.
- volume
Float, optional
The volume for this sampler. Behaves the same as the global volume for the effect.
- timeline_offset
Float, optional
The position on the effect’s timeline in seconds when this sampler should start playing.
- pitch
Array of floats, optional
Randomly alters the pitch in the provided interval. Requires exactly two values in the array, which can be positive or negative. The first represents the minimum, and the second the maximum relative pitch change in cents.
Playing sound effects¶
Sound effects can either be played via the Lua scripting interface, the C API, or by placing a Sound Component in the scene.