Working with assets

Flambe has very smart concept of working with assets, that allows you to quickly load, add and replace assets. It picks the best asset for the right platform.

Assetpacks

Within a default setup, you should put all your assets inside your projectfolder/assets. Inside the assets folder you can create directories. These are your assetpacks. You have to load them separately. In the default Flashdevelop project, you have one assetpack called "global", If you want to load assets later on, create a different folder (assetpack). When you have loaded an AssetPack, all files in it are instantly available (which is pretty nice). If you want to exclude file under some conditions, you also have to use other assetpacks; organize your folder wisely.

Inside the assetpack folder, you can put images, sounds and other files. Anything that is placed in the folder, is included and available when you have loaded it.

When you compile, assets are copied to the deploy folder

All assets are moved into build/web after compilation and also while the assetserver runs. A list of assets is created internally. You should never mess in the assets of the build/web folder, they are overwritten on a compile AND you can get runtime errors if files missing in that folder, because then you broke the 'list of assets'. To ensure having a clean build/web folder, you can safely remove it before a compile, but in normal conditions, Flambe manages this for you.

Important note If you removed/changed/moved/renamed a file, you should always recompile+test if it still works.

How to load an AssetPack

A Manifest object lists assets and where they can be found. Typically Manifest.fromAssets() is used to create a Manifest from files in the project's assets directory, but they can also be dynamically constructed, to load assets from other sources over the web.

var loader = System.loadAssetPack(Manifest.fromAssets("foldername"));
loader.progressChanged.connect(function () {
  trace("Download progress: " + (loader.progress/loader.total));
});
loader.get(function (pack) {
  // Download complete, use the pack to start the game
});

🐼 Get textures from assetpack

var texture = pack.getTexture("myImage"); // returns the texture of myImage.jpg or myImage.png from the assetpack

To show the actual image, read Working with images.

📢 Get a sound from assetpack

You have to encode all sounds in supported formats: m4a, mp3, ogg. Flambe will auto-magically select the right sound for the current platform; there is no need to provide an extension.

var sound = pack.getSound("mySound");

To play the sound and control volume and playback, read Working with sound.

📄 Grab other files from assetpack

Need a JSON/XML or any other extension? Make sure you encode it to JSON or XML, File.toString() returns the file content as String.

var myJson:Dynamic = Json.parse(pack.getFile("data.json").toString());

var myXML:XML = Xml.parse(pack.getFile("data.xml").toString());

To read about loading/parsing config files, read Configuration files.

Load/show external assets

To load external assets, you need to create a Manifest, add assets using an identifier and URL to it, then let System load it. You can use the identifier later to get it back out of the Manifest after loading.

  var manifest = new Manifest();
  manifest.add("textfile", "http://www.mydomain.com/myFile.txt");
  
  // give manifest hint 'Image'; needed since lack of extension
  manifest.add("facebookPhoto", "https://graph.facebook.com/markknol/picture", Image); 
  
  System.loadAssetPack(manifest).get(function (pack) 
  {
	trace(pack.getFile("textfile").toString());
	trace(pack.getTexture("facebookPhoto"));
  });

Note; you can have crossdomain issues if the domain doesn't allow others to load content from their server.

Adding HTML ImageElement to Flambe

If you want to add an existing image from the html-page into your Flambe workflow:
Make sure you have access to the ImageElement on the Haxe side. Then you can call System.renderer.createTexture() to turn it into a Flambe texture.

💥 Disposing Assetpacks

It possible to dispose all the assets in an AssetPack. After calling this, any calls to getTexture, getSound, or getFile will assert.

pack.dispose();

🌎 Multi-language assetpacks

To setup multilanguage assetpacks, you need a default assetpack. For example, call the assetpack (folder) "content". Then, you could use this folder structure:

assets/content/ // default
assets/content_nl-NL/ // Dutch
assets/content_en-US/ // English
assets/content_pt-BR/ // Brazilian Portuguese

Then use Manifest.fromAssetsLocalized instead of Manifest.fromAssets and provide a language code.

// Gets the RFC 4646 language tag of the environment. 
// For example, "en-US", "pt", or null if the locale is unknown
var languageCode = System.locale; 

var loader = System.loadAssetPack(Manifest.fromAssetsLocalized("content", languageCode));
loader.get(function (pack) {
  // Download complete. Veel plezier!
});

Flambe tries to find a pack suffixed with the closest available variant of the locale. For example, fromAssetsLocalized("foo", "pt-BR") will first try to load "content_pt-BR", then "content_pt", then just "content". Note, it does not mix folder content, so the localized assetpacks should all have the same amount of assets.