Skip to content
Michalis Kamburelis edited this page May 19, 2019 · 9 revisions

Table of Contents

Introduction

Castle Game Engine can use various backends for our sound (CastleSoundEngine unit). By default we use OpenAL which works nicely, is open-source and cross-platform (works on desktop and mobile). However, you may choose to use another backend.

One of the alternative backends is FMOD, using a commercial (closed-source) FMOD library. FMOD works nicely, and is even more cross-platform (in particular it supports also Nintendo Switch). It also supports more sound file formats out-of-the-box.

Note that using FMOD is not free. See https://www.fmod.com/ for library downloads and pricing.

Activating FMOD in CGE

Use CastleFMODSoundBackend unit, and call UseFMODSoundBackend procedure at any point. You usually want to call it early, before any sound was loaded or played, this way the default sound backend (OpenAL on desktop and mobile) will not even be initialized.

Compiling and using CastleFMODSoundBackend unit means that the application will link to FMOD at startup. You have to distribute FMOD libraries if you use CastleFMODSoundBackend (whether you call UseFMODSoundBackend or not). See the next section for details.

Getting FMOD library and copying it to your project

To get FMOD libraries create an account on https://www.fmod.com/ , and download "FMOD Studio API". This should include "FMOD Studio API and FMOD Core API" (we actually use only "FMOD Core API" now).

Below we give detailed instructions for some popular platforms. See FMOD platform-specific documentation for more information.

TODO: We want to simplify the instructions below in the future. The plan is to support <libraries path="..." /> element in CastleEngineManifest.xml, which would allow to specify OS/CPU specific libraries in your project (aaa.dll on Windows, libaaa.so on Linux etc., in subdirectories named like ${CPU}-${OS}) and let the CGE build tool automatically do everything that is necessary. For now, follow the steps below for Windows and Linux.

On Windows

"FMOD Studio API" on Windows is an install package, and when you run it you get C:\Program Files (x86)\FMOD SoundSystem\FMOD Studio API Windows (if installed to the default directory). For Windows 64-bit just copy the DLL from C:\Program Files (x86)\FMOD SoundSystem\FMOD Studio API Windows\api\core\lib\x64\fmod.dll alongside the game exe.

You also have to distribute FMOD library with your application. Currently, it is easiest to add this to your CastleEngineManifest.xml file:

  <package>
    <include path="fmod.dll" />
  </package>

On Linux

"FMOD Studio API" on Linux is a tar.gz archive. Unpack it anywhere, and from api\core\lib\x86_64 subdirectory (assuming you use Linux on x86_64 CPU) copy the 3 libfmod.so* files (one is actual library, 2 are just symlinks). We advise copying these 3 files to the libraries/x86_64-linux/ subdirectory of your project.

The dynamic library must be known even during compilation (as Unix linker checks the symbols when linking). To make it work, compile on Linux with command-line option -k-Llibraries/x86_64-linux/ for FPC (this passes the -Llibraries/x86_64-linux/ option to the linker, which means "look for libraries in libraries/x86_64-linux/). You can do this by adding to CastleEngineManifest.xml this:

 <compiler_options>
    <custom_options>
      <option>@fpc-options.cfg</option>
    </custom_options>
  </compiler_options>

Then create fpc-options.cfg file with these contents:

#ifdef LINUX
#ifdef CPUX86_64
-k-Llibraries/x86_64-linux/
#endif
#endif

To make it work on user's system, create a shell (bash) script that sets $LD_LIBRARY_PATH to include your local fmod copy, and then executes the application. Like this:

#!/bin/bash
set -e
# Include current directory in LD_LIBRARY_PATH, to find fmod dynamic library
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:libraries/x86_64-linux/"
./play_sounds # <- replace this with name of your application

Save this file e.g. under run.sh name, do chmod +x run.sh, and now you can execute it like ./run.sh.

You also have to distribute FMOD library, and run.sh with your application. Add this to your CastleEngineManifest.xml file:

  <package>
    <include path="run.sh" />
    <include path="libraries/x86_64-linux/" recursive="True" />
  </package>

(If your CastleEngineManifest.xml already contained <package>, then merge their contents instead of adding new <package> element.)

On Nintendo Switch

The details are in the Nintendo Switch README inside CGE version for Nintendo Switch.

Limitations

For now, we only support 2D sounds using FMOD. Sound spatialization with FMOD is not implemented yet (although it could be, FMOD is powerful -- requests and pull requests are most welcome).

For now, we use "FMOD Core API", which means that we use FMOD as a general sound loading and playback library, which you can use with regular sound files (wav, OggVorbis and many other formats supported by FMOD). You cannot yet use FMOD Studio to design "sound events" that could be played by CGE.

Clone this wiki locally
You can’t perform that action at this time.