Sound

1. Playing sound from Pascal code

Load a sound file to sound buffer like this:

// add this to your uses clause:
uses ..., CastleSoundEngine;
 
// use this at initialization:
var
  Buffer: TSoundBuffer;
 
procedure LoadSoundBuffers;
begin
  Buffer := SoundEngine.LoadBuffer('castle-data:/sample.wav');
end;

At any point in your application, play this sound like this:

SoundEngine.PlaySound(Buffer);

See SoundEngine.PlaySound docs for the description of parameters.

2. Using sounds repository (XML file)

It is often comfortable to define a repository 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. Do it by creating an XML file, for example named sounds.xml, looking like this:

<?xml version="1.0"?>
<sounds>
  <sound name="sample" url="sample.wav" />
  <!-- Actually, you can omit the url, by default it's the same
       as sound name with .wav extension. -->
</sounds>

See creating game sounds guide for detailed specification about sound XML files. See TRepoSoundEngine docs and examples/fps_game/ for example. You have to initialize the sound repository by assigning to SoundEngine.RepositoryURL, like this:

SoundEngine.RepositoryURL := 'castle-data:/sounds/index.xml';

After this, you can refer to your sounds by name. You can play named sounds from Pascal code:

var
  SoundType: TSoundType;
begin
  SoundType := SoundEngine.SoundFromName('sample');
  // play as 3D sound
  SoundEngine.Sound3D(SoundType, Vector3(1, 2, 3), false { looping });
  // play as non-3D sound
  SoundEngine.Sound(SoundType, false { looping });
end;

The SoundEngine.Sound3D and SoundEngine.Sound are a little easier to use than SoundEngine.PlaySound, they have fewer parameters. That is because the default sound properties (it's individual gain (volume), importance (priority), URL and other stuff) is already recorded in the sounds XML file.

You can also refer to sound names from files like resource.xml (for creatures/items sounds) or material_properties.xml (for footsteps) or level.xml (for level music). See creating game data guide for reference of these files.

3. Playing sound from X3D

Get a sample sound file and place it within your game data. You can find some sample files inside examples/fps_game/data/sounds/, or in our demo models (subdirectory sound/), or on websites like OpenGameArt.org.

To add a looping sound to an X3D file in classic encoding (xxx.x3dv files) add this:

Sound {
  source AudioClip { url "sample.wav" loop TRUE }
}

Remember that URL "sample.wav" is specified relative to the location of your xxx.x3dv file. In the simplest case, just place both xxx.x3dv and sample.wav in the same directory, and you're fine.

4. Controlling the sound afterward (TSound)

For more advanced uses, you can use the return value of SoundEngine.PlaySound, SoundEngine.Sound3D or SoundEngine.Sound. It's either nil (if no resources were available to play this sound, and it's priority doesn't allow overriding other sounds) or it's a TSound instance. If you have TSound instance, you can save it to a variable and use for various purposes. For example you can update sound parameters during the game, e.g. changing TSound.Position, TSound.Gain and such. You can use it's TSound.OnRelease event to be notified when source stops playing. You can stop playing the sound by TSound.Release.