Sound

1. The most important classes and their usage

• TCastleSound: The most important class, you should use this always when you want to play any sound.

  This is a non-visual component that represents a sound file with some playback parameters. The most important properties are:

  • URL — undoubtedly the most important property, set this to actually load the sound file.

  • Stream — optionally use "streaming", which is an alternative loading method best suited for longer playing sounds (like music tracks).

  • Volume — how loud the sound is. This is multiplied by volume at TCastlePlayingSound.Volume and TCastleSoundSource.Volume and by spatial calculations.

  • Pitch — sound playing speed. As with volume, the volume of TCastleSound.Pitch is multiplied by similar parameters controlled at TCastlePlayingSound.Pitch and TCastleSoundSource.Pitch.

  TCastleSound by itself doesn't manage playing the sound. You have to use SoundEngine.Play to play the sound (the simplest way to play, for non-spatial sounds) or TCastleSoundSource (for sounds that can be spatial; assign to TCastleSoundSource.Sound for looping, use TCastleSoundSource.Play for non-looping).

• TCastleSoundSource: A way to play spatial (3D) sounds.

  This is a behavior (see documentation about behaviors) that enhances any TCastleTransform so that it emits (possibly spatial) sounds.

  TCastleSoundSource refers to TCastleSound for an actual sound information. You can set TCastleSoundSource.Sound (for looping). Or call TCastleSoundSource.Play (for non-looping).

• TCastlePlayingSound: Optional, use if you need more control before and during the sound playback.

Both TCastleSoundSource and TCastleSound can be created, configured and linked in the CGE editor, e.g. when designing your state. You can hear the 3D sounds in the editor. You can also create and control them from code, as all CGE components.

2. Examples

• See all the examples in examples/audio subdirectory.

• In particular open the examples/audio/game_3d_sound demo. It's a simple example of how TCastleSoundSource and TCastleSound can be set up in the CGE editor.

• See also examples/fixed_camera_game as a demo how to design a collection of sounds. In particular:

  • examples/fixed_camera_game/data/sounds/all_sounds.castle-component describes all sounds
  • examples/fixed_camera_game/code/gamesound.pas loads them

3. Editor sound features

• Sound volume, and "auto-mute on play" are available in the editor settings.

• Drag-and-drop sound files on the viewport to automatically create a spatial sound: TCastleTransform, TCastleSoundSource, TCastleSound.

4. Playing sound from Pascal code

Load a sound file as TCastleSound like this:

1. Add CastleSoundEngine to your uses clause.

2. Declare variable to hold it like MySound: TSound;

3. Initialize the variable and load sound file, e.g. in Application.OnInitialize:

   MySound := TCastleSound.Create(Application);
   MySound.URL := 'castle-data:/my-sound.wav';

4. Play the sound like this:

   SoundEngine.Play(MySound);

See source code of examples/audio/simplest_play_sound/ for a working simplest possible example of this.

5. Using sounds collection (.castle-components file)

It is often comfortable to define a collection of sounds, which means that each sound file is assigned a simple name and configuration (e.g. priority, default volume), and all the sound files can be loaded easily from any place in code (regardless of the current TUIState).

Do it by using a TCastleComponent as a design root and adding TCastleSound children. Save the resulting design to a file like all_sounds.castle-component.

See examples/fixed_camera_game for an example of this approach. In particular:

• examples/fixed_camera_game/data/sounds/all_sounds.castle-component describes all sounds
• examples/fixed_camera_game/code/gamesound.pas loads them

6. Sound backends

By default we use OpenAL to play sounds. It's a great full-featured open-source audio library, perfect match for our open-source game engine.

You can alternatively switch to use the FMOD sound backend. This is just an option. FMOD is proprietary (not open-source) and commercial (though free in some cases, for indie devs).

• Main advantage of FMOD in CGE for now is Nintendo Switch compatibility.

• Big future advantage may be integration with the FMOD Studio. The goal of FMOD Studio is to make the work of sound designer easier. The sfx person can create sound effects in FMOD Studio, in a way that is agnostic to the game engine, and the code (like your game) simply sends "events" that may cause some sound effect (playing something, stopping something, fading in/out something...).