Note: The API of this library will change early on
Other Note: Remember to follow the rules of FMOD's license when using this library
A library to integrate the FMOD audio engine with Haxe 4 games for Windows and HTML5 deployments
Primarily focuses on simplifying the FMOD Studio project workflow through the use of a well-documented helper library
The Windows integration was built on top of Aaron Shea's C++ integration with FMOD's official API
LICENCE: MIT
Download the package via Haxelib
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.
After configuring your project to work with this library, playing a song or sound effect is extremely simple:
// This example uses the create and update calls found in HaxeFlixel games
override public function create():Void {
// Plays a song in your game
FmodManager.PlaySong("event:/Music/MainLevel");
// Plays a sound in your game
FmodManager.PlaySoundOneShot("event:/SFX/Jump");
}
override public function update(elapsed:Float):Void {
// Update call required to process any asynchronous events
FmodManager.Update();
}Important note: HTML5 builds require a "startup scene" to load FMOD before the game starts. See the HTML5 Builds section for more information
Download FMOD Studio and setup your project:
This will be the tool you use to manage all audio for your game. Download FMOD Studio version 2.00.08 here. Once installed, follow the FMOD Studio Project Configuration section before moving on.
Add the library 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
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 FmodManager function calls with descriptions here.
Songs and sound effects are triggered by passing in the full FMOD bank event path to the FmodManager.PlaySong, FmodManager.PlaySoundOneShot, FmodManager.PlaySoundWithReference, FmodManager.PlaySoundAndAssignId functions. To use constants to reference the events instead of strings, follow the additional setup instructions found in the fmod-scripts folder of this repo (highly recommended).
important: This library needs a constant stream of update calls to function properly. Remember to call FmodManager.Update() at the beginning of every update loop of every state in your game.
Global library settings:
Global settings for haxefmod are in a Settings.hx file found in the installation location of this library. The relative location of this file from the root of the library is haxefmod/Settings.hx. Updating this library to newer versions will likely reset all global settings to their defaults.
Settings available:
DebugMessages //Bool: Enables console output for internal FMOD API calls (can be helpful if things aren't working)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 EZPlatformer example project (HaxeFlixel) in the example-project folder of this repo 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 structure:
This structure is only required if you plan to utilize the code generation script to sync your FMOD Studio project with your game code (highly recommended)
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:
fmod folder in your assets folder (so the path assets/fmod/ exists in your project) 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:
Checkout the fmod-scripts folder in this repo to learn how to setup 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:
When using Live Update in FMOD Studio, turn the auto-reconnect feature off or your game will not start. Hopefully this issue can be resolved fairly easily.
Note: The Live Update feature will only work for Windows builds. It is officially unsupported for HTML5 builds. The FMOD team said this has to do with limitations caused by running games inside a browser.
Inside the example-project folder, you will find a simple game from the HaxeFlixel flixel-demos repo with this FMOD library added to it. It showcases the following:
The FMOD Studio project for the example game is also included.
Play the game, explore the code, and open up the FMOD Studio project (try Live Update!). This will provide insight into the workflow, library calls, and features of this tool. Open the EZPlatofmrer folder directly with vscode to get autocomplete and function lookups as you look around the code.
To play the game, run lime test windows or lime test html5 in the EZPlatformer folder
haxefmod is not installed on your system by checking the output of haxelib list. If it is installed, you can uninstall it using haxelib remove haxefmodhaxelib at the local repo using haxelib dev haxefmod <directory_to_the_git_clone>This will setup the git repo as an "installed" version of haxefmod which can be imported by your projects the same way you import other libraries. You can see the special dev status when you find haxefmod in the output of haxelib list
If you have any feature requests or are having issues using the library, please open an Issue here on Github