FMOD for Haxe on HTML5, HashLink, Windows, Linux, and macOS

Having problems or want to chat? Join the Haxe Discord!

Table of Contents

• Features
• Supported Platforms
• Prerequisites
• How to Use This Library
• HTML5 Builds
• Selecting an FMOD Engine Version
• FMOD Studio Project Configuration
• License
• Special Thanks
• Feature Requests and Contact

Features

• Sounds loaded using an FMOD bank file
• Event parameters for dynamically altering sounds based on in-game actions
• Callbacks which enable the game to respond to the audio
• Live Update for mixing sounds while playtesting
• Easy referencing of FMOD Studio bank events in game code with the help of an auto-updated constants file (optional)

Supported Platforms

Platform	Architecture	Targets
HTML5	All	WebAssembly
Windows	x86_64	C++, HashLink
Linux	x86_64	C++, HashLink
macOS	ARM64 (Apple Silicon)	C++, HashLink

Prerequisites

FMOD Engine SDK - Download version 2.03.12 from fmod.com/download. See How to Use This Library for setup instructions.

C++ compiler (C++ builds only) - lime build mac, lime build windows, and lime build linux require a C++ compiler. HashLink and HTML5 builds do not.

• macOS: Xcode Command Line Tools - install with xcode-select --install
• Windows: Build Tools for Visual Studio 2022 with the "Desktop development with C++" workload selected during installation. Direct download, or find the Fall 2022 LTSC build tools link here.
• Linux: gcc and g++ (install via your package manager, e.g. sudo apt install build-essential)

How to Use This Library

This library has been tested on games built with the lime and openfl CLI tools, and should work on any Haxe framework that utilizes the Project.xml file for builds.

See haxe-fmod-test for a working example of a HaxeFlixel game with this FMOD integration.

1. Add the library to your Haxe project:

Download the package via Haxelib

If required, import the library in your project. On HaxeFlixel projects, add <haxelib name="haxefmod" /> to the "Libraries" section of your Project.xml file.

2. Download FMOD Studio and set up your project:

This will be the tool you use to manage all audio for your game. Download FMOD Studio here. Once installed, follow the FMOD Studio Project Configuration section before moving on.

3. Set up the FMOD Engine SDK:

This library requires you to supply your own FMOD Engine SDK (separate from FMOD Studio). The only officially supported version is 2.03.12. Download it from fmod.com/download.

If you would like to use any other version of the FMOD Engine, see Selecting an FMOD Engine Version.

For C++ and HashLink builds, set the FMOD_SDK environment variable to point to the FMOD Engine directory:

# For Linux/macOS
# in ~/.bashrc or ~/.zshrc
export FMOD_SDK="$HOME/fmod/fmodstudioapi20312" # (use $HOME, not ~)

# For Windows
# in the Environment Variables UI
# FMOD_SDK=C:\path\to\installer\output

For HTML5 builds, set a separate FMOD_SDK_WEB variable:

# For Linux/macOS
# in ~/.bashrc or ~/.zshrc
export FMOD_SDK_WEB="$HOME/fmod/fmodstudioapi20312html5" # (use $HOME, not ~)

# For Windows
# in the Environment Variables UI
# FMOD_SDK_WEB=C:\path\to\fmodstudioapi20312html5

This allows you to have both your C++/HashLink SDK and HTML5 SDK configured simultaneously.

4. Check your setup:

haxelib run haxefmod check will check various aspects of your local dev environment to verify your setup and is highly recommended.

5. Use the library in code:

The FmodManager class is the primary way to interact with FMOD in your game. It abstracts away nearly all of the low-level details of the FMOD API. You can look through all of the available function calls with descriptions here.

Songs and sound effects are triggered by passing the full FMOD bank event path to functions like:

• FmodManager.PlaySong
• FmodManager.PlaySoundOneShot
• FmodManager.PlaySoundWithReference
• FmodManager.PlaySoundAndAssignId

To use constants instead of strings to reference events, follow the instructions in the fmod-scripts.

public function StartLevel():Void {
    // Plays a song in your game
    FmodManager.PlaySong("event:/Music/MainLevel");
    // or if using the FMOD Studio enum generation script
    FmodManager.PlaySong(FmodSongs.MainLevel);
}

public function JumpPressed():Void {
    // Plays a sound in your game
    FmodManager.PlaySoundOneShot("event:/SFX/Jump");
    // or if using the FMOD Studio enum generation script
    FmodManager.PlaySoundOneShot(FmodSFX.Jump);
}

6. Build and run:

All targets work with standard lime commands:

lime test html5
lime test hl
lime test windows
lime test linux
lime test mac

HTML5 Builds

For HTML5 builds to work, a dedicated scene must be run before the game starts to give the FMOD Engine a chance to fully load. See the example project for a demonstration of how to handle this. The Main.hx file loads the startup scene, the startup scene initializes FMOD and waits for it to report back as initialized, then the game is started.

Selecting an FMOD Engine Version

The officially supported FMOD Engine version is 2.03.12. Other versions may work fine, but I have not tested them.

Importantly, this library comes pre-bundled with HashLink binaries (hdlls) for FMOD Engine version 2.03.12.

If you use a different FMOD Engine version and want HashLink builds, you must compile the hdll for your platform from source against your installed version of the FMOD Engine:

# 1. Set FMOD_SDK to your version
export FMOD_SDK=/path/to/your/fmodstudioapi

# 2. Compile the hdll (from your project directory)
haxelib run haxefmod build-hdll

# 3. Build as normal
lime test hl

This requires a C compiler (gcc on Linux, cc on macOS, cl on Windows) and HashLink headers installed on your system.

The build-hdll command will auto-detect your platform, find HashLink headers in common locations, compile the hdll, and place it in a .haxefmod/ directory in your project. If HashLink headers aren't found automatically, set HASHLINK_DIR to your HashLink installation directory.

How the hdll is resolved

At build time, lime test hl uses a tiered fallback to find the right hdll:

1. Project-local .haxefmod/hlaxe_fmod.hdll - used if present (custom-compiled via build-hdll)
2. Pre-built <haxefmod_library_install_location>/templates/bin/hl/<Platform>/hlaxe_fmod.hdll - ships with the library (FMOD Engine 2.03.12)

The build log will tell you which one was used.

C++ and HTML5 targets do not rely on the hdll and will work with any FMOD version (although they will warn if you use anything other than 2.03.12).

FMOD Studio Project Configuration

FMOD Studio project structure:

If you would like to utilize the code generation script to sync your FMOD Studio project with your game code (highly recommended), use the following structure:

• Songs should be placed inside a folder titled "Music" in your FMOD Studio project
• Sound effects should be placed inside a folder titled "SFX" in your FMOD Studio project

FMOD Studio bank builds:

This library only supports loading a single master bank for all sounds.

Set your FMOD Studio project to build banks to the correct location:

• Create an fmod folder in your assets folder (so the path assets/fmod/ exists in your project)
• Open your FMOD Studio project and at the top of the window, click Edit->Preferences, then click the "Build" tab on the window that pops up.
• Under "Built banks output directory (optional)", click "Browse" and navigate to the new fmod folder and select it.

From now on, your Master.bank and Master.strings.bank files should be built in a folder found at assets/fmod/Desktop (the Desktop folder is created by FMOD Studio).

FMOD Studio Scripts:

Check out the fmod-scripts folder in this repo to learn how to set up FMOD Studio to generate a Haxe constants file (.hx) that can be used to reference your Music and SFX in code without using strings.

FMOD Studio Live Update:

One of the most powerful features of the FMOD ecosystem. Mix your sounds in real-time by binding FMOD Studio to a running instance of your game.

Live Update only works on C++ and HashLink builds. HTML5 builds will not work. The FMOD team said this is a limitation caused by running games inside web browsers and they have no plans to support this.

Note: On macOS and Windows, you may see a firewall dialog asking to allow incoming network connections when running your game. This is caused by the Live Update feature, which opens a local network socket (port 9264) so FMOD Studio can connect to your game for real-time audio mixing.

License

MIT

Special Thanks

This entire project was started as an expansion of Aaron Shea's faxe.

Feature Requests and Contact

If you have any feature requests or are having issues using the library, please do one (or both) of the following:

• Join the haxe-fmod channel on the official Haxe Discord and ask any questions you have there. Responses will be quick!

• Open an Issue here on GitHub.