Assets in OpenFL: embedding images, sounds and more

posted on Sep 14, 2014 in Haxe, OpenFL, Syntax
Assets in OpenFL Haxe

Assets include any type of raw resource that you may want to embed into your game or app. OpenFL has a built-in system for embedding and managing sounds, images, fonts and other types of files into your project.

The process starts with the application.xml file, where the paths to asset directories is located. This is also where you can specify custom parameters for filtering assets for different compiler targets, for example.

Each project directory has an assets subdirectory, which is used for storing all the assets to be embedded. Let's say we have an img folder there that we want to embed, so we add this line to application.xml:

<assets path="assets/img" rename="img" />

Say that we have another folder called audio, where we store audio files. We can add another line for embedding everything in that folder to our project the same way. We can also specify the type of the media that we're embedding - audio in this case:

<assets path="assets/audio" rename="audio" type="audio" />

The Haxe compiler will embed all these resources automatically. All we need to do is load them in our code using the static Assets class. The Assets class has many different methods for loading different kind of media, such as getBitmapData() for images, getSound() or getMusic() for audio, getFont() for fonts, etc.

We need to specify the path to the asset when we load it:

var bd:BitmapData = Assets.getBitmapData("img/logo.png");
var b:Bitmap = new Bitmap(bd);
addChild(b);

We can load audio in a similar way:

var sound:Sound = Assets.getSound("audio/song.wav");
sound.play();

A bit more advanced example, which loads the sound into a SoundChannel object, which has more control over the playback. We can, for example, create a custom SoundTransform object and change the volume of the played sound:

var sound:Sound = Assets.getSound("audio/song.wav");
var channel:SoundChannel = sound.play();
channel.soundTransform = new SoundTransform(0.1);

OpenFL currently supports 3 audio formats - wav, ogg and mp3. The wav file format is supported in all compiler targets, but might not be suitable for all needs, since the file size is big. The ogg file format can't be played in Flash. Mp3, however, can only be played in Flash projects. This is because the mp3 format is proprietary and Adobe has an agreement with the owners of the format so that the developers don't have to pay royalties when using it in Flash projects.

Because of this, if you're targeting multiple platforms, including Flash, you might want to embed mp3 version of a song when exporting to Flash, and ogg in all other cases.

This can be done in the application.xml file by creating conditions:

<asset path="assets/audio" rename="sound" include="*.ogg" unless="flash" />
<asset path="assets/audio" rename="sound" include="*.mp3" if="flash" />

This way the same sounds can be embedded in different formats for different platforms.

If you found this helpful, you might want to check out my other tutorials. Additionally, consider subscribing to my free newsletter for updates and bonus content!

23502