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

MIT License

Table of Contents

• Features
• Supported Platforms
• How to Use This Library
• HTML5 Builds
• FMOD Studio Project Configuration
• 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 play testing
• Easy referencing of FMOD Studio bank events in game code with the help of an auto-updated constants file (optional)

Supported Platforms

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 haxe-flixel 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). Download it from fmod.com/download.

Required version: - All platforms: FMOD Engine 2.03.12

For OS-native 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 native 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.

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 up 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 native builds (not HTML5). 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.

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 open an Issue here on GitHub.