Loading Assets

Matt Karl edited this page Dec 16, 2015 · 3 revisions

There is a convenient loading system built into SpringRoll's Core Module which is a wrapper for PreloadJS. This system is responsible for loading different types of media (audio, images, data) as well as providing functionality for caching assets, loading multiple assets at once, manage complex load types, handling load progress, and URL browser cache-busting.

Application had three methods load, unload and getCache which are the main API methods for loading assets.

API Usage

Load Single File by String

app.load("assets/images/background.png", function(image)
{
    // image is an <img> DOM element
});

Load Single File by Object

app.load({
    src: "assets/images/background.png",
    complete: function(image){}, // when loading completes
    progress: function(loaded){} // loading progress from 0 - 1
});

Load Collection of Strings

app.load(
    ["assets/images/background.png",  "assets/images/character.png"],
    function(images)
    {
        // images is an array of <img> elements 
    }
);

Load Collection Of Objects

Allow callbacks on a per item basis instead of waiting until everything is done.

app.load([
        {
            src: "assets/images/background.png",
            complete: function(result, tasks){}
        },
        {
            src: "assets/config/files.json",
            complete: function(result, tasks){}
        }
    ],
    function(results)
    {
        // results is an array which contains an <img>
        // and a JSON object 
        // matching the same order as input
    }
);

Loading with Non-File Async Task

app.load([
        {
            src: "assets/images/background.png",
            complete: function(result, tasks){}
        },
        {
            src: "assets/images/character.png",
            complete: function(result, tasks){}
        },
        function(done)
        {
            // some async task event here call done() when finished
            done();
        }
    ],
    function(results)
    {
        // results is an array of results 
        // matching the same order as input
        // async function's result is ignored unless
        // something is passed to done();
    }
);

Load Map of Strings

app.load(
    {
        background: "assets/images/background.png",
        files: "assets/config/files.json",
        character: "assets/images/character.png"
    }, 
    function(results)
    {
        // results is a map (eg results.background, results.files, results.character )
        // where each item contains the contents of the load <img> or JSON Object
    }
);

Load Collection of Objects

Load a list of assets. Complete function returns the list of tasks being loaded, so more tasks can be added on callback, for instance loading a JSON file and then loading additional files.

app.load([
        {
            id: "character",
            src: "assets/images/character.png",
            complete: function(image, asset, assets){}
        },
        {
            id: "background",
            src: "assets/images/background.png",
            complete: function(image, asset, assets){}
        }
    ],
    function(results)
    {
        // if ids in the objects are set, results is a map
        // which maps to the result of each load
    }
);

Load Map of Objects

app.load({
       character: {
            src: "assets/images/character.png",
            complete: function(image, asset, assets){}
        },
        background: {
            src: "assets/images/background.png",
            complete: function(image, asset, assets){}
        }
    },
    function(results)
    {
        // results is a map matching input, like loading a collection with ids
    }
);

Caching Assets

Cache A Load

An asset can be loaded and the result will be saved into the Application's asset cache. No complete callback is required here to load the image since the result will be saved.

app.load({
    id: "Background",
    src: "assets/images/background.png",
    cache: true
});

var image = app.getCache('Background'); // returns <img>

Cache A Load Without ID

If no id field is provided, the cache ID will be the base name of the file.

app.load({
    src: "assets/images/background1.png",
    cache: true
});

var image = app.getCache('background1'); // returns <img>

Unload Asset

app.unload('Background'); // Unload and destroy by cache ID
app.unload('Background', 'Character'); // Unload multiple
app.unload(['Background', 'Character']); // Unload list
app.unloadAll(); // Remove all assets

Asset Load Types

All asset objects support cache (Boolean), id (String) and complete (Function) fields.

Load Task

Generically load any file.

{
	src: "assets/images/Background.jpg"
}

Function Task

An asynchronous task, can do anything. When it's complete, done() needs to be called. If any arguments are pass to done, then that first one is used as the result (optional).

function (done)
{ 
        done();
}

or

{
	id: "taskId",
	async: function(done)
	{
		done();
	}
}

Color/Alpha Task

Special load for an image that's split into a color and alpha images. Will automatically combine images and return the new <canvas> object.

{
	color: "assets/images/Widget.jpg",
	alpha: "assets/images/Widget.png"
}

EaselJS Loading

Texture Atlas Task

Requires EaselJS Display, will return springroll.TextureAtlas object.

{
	atlas: "assets/images/Spritesheet_atlas.json",
	image: "assets/images/Spritesheet.png",
	type: "easeljs"
}

Or the color-split version:

{
	atlas: "assets/images/Spritesheet_atlas.json",
	color: "assets/images/Spritesheet_color.jpg",
	alpha: "assets/images/Spritesheet_alpha.png",
	type: "easeljs"
}

Flash Art Task

Requires EaselJS Display. When used with the AssetManager, it's possible to completely unload library symbols defined in the Flash-exported file. Will return springroll.easeljs.FlashArt object.

{
	src: "assets/js/Transition.js",
	type: "easeljs",
	format: "springroll.easeljs.FlashArt",
	//images array is optional
	images: [
		"url/to/image1.png",
		{
			id: "image2",
			alpha: "url/to/image2-alpha.png",
			color: "url/to/image2.color.jpg"
		},
		{
			atlas: "url/to/atlas.json",
			image: "url/to/atlas.png"
		}
	]
}

Spritesheet Task

Requires EaselJS Display. Support for Flash CC 2015 export of SpriteSheets. Will return createjs.SpriteSheet object. See CreateJS docs for more information.

{
	images: ["assets/images/sprites_atlas.png"],
	frames: [[64, 0, 96, 64], [0, 0, 64, 64]]
}

Or the color-split version:

{
	images: [{
		color: "assets/images/sprites_atlas_color.jpg",
		alpha: "assets/images/sprites_atlas_alpha.png" 
	}],
	frames: [[64, 0, 96, 64], [0, 0, 64, 64]]
}

Alternatively, if you just want to load the spritesheet from the JSON that Flash exports, you can use this asset definition. The format must be specified.

{
	src: "assets/images/Transition_atlas_.json",
	type: "easeljs",
	format: "createjs.SpriteSheet"
}

Bitmap Task

Load an image but the object that is returned is a createjs.Bitmap instead of the image DOM element.

{
	src: "assets/images/Image.png",
	format: "createjs.Bitmap"
}

Bitmap MovieClip Task

Requires EaselJS Animation, will return springroll.easeljs.BitmapMovieClip object. BitmapMovieClips are exported using the FlashToolkit for SpringRoll.

{
	anim: "assets/images/Character_anim.json",
	atlas: "assets/images/Character_atlas.json",
	image: "assets/images/Character.png",
	type: "easeljs"
}

Or the color-split version:

{
	anim: "assets/images/Character_anim.json",
	atlas: "assets/images/Character_atlas.json",
	color: "assets/images/Character_color.jpg",
	alpha: "assets/images/Character_alpha.png",
	type: "easeljs"
}

Pixi Loading

Individual Texture:

// Format for a regular image
var asset = {
	type: "pixi",
	image: "assets/images/texture.png"
};
//format for a color/alpha split image
asset = {
	type: "pixi",
	color: "assets/images/texture-color.jpg",
	alpha: "assets/images/texture-alpha.png"
};
app.load(asset, function(result)
{
    // result is a PIXI.Texture object
    // if 'cache' is true on the asset, then texture is added to the global Pixi cache
    // for PIXI.Texture.fromImage() usage
});

Texture Atlas - Texture and atlas data:

// Format for a regular texture atlas
var asset = {
	type: "pixi",
	atlas: "assets/images/atlasData.json",
	image: "assets/images/atlasTexture.png"
};
//format for a color/alpha split texture
asset = {
	type: "pixi",
	atlas: "assets/images/atlasData.json",
	color: "assets/images/atlasTexture-color.jpg",
	alpha: "assets/images/atlasTexture-alpha.png"
};
app.load(asset, function(result)
{
    // result is a springroll.pixi.TextureAtlas object
    // if 'cache' is true on the asset, then textures are added to the global Pixi cache
    // for PIXI.Texture.fromImage() usage
});

Bitmap Font - Texture and font data:

// Format for a regular bitmap font
var asset = {
	type: "pixi",
	font: "assets/images/fontData.fnt",
	image: "assets/images/fontTexture.png"
};
//format for a color/alpha split bitmap font
asset = {
	type: "pixi",
	font: "assets/images/fontData.fnt",
	color: "assets/images/fontTexture-color.jpg",
	alpha: "assets/images/fontTexture-alpha.png"
};
app.load(asset, function(result)
{
    // result is a font object (no class)
    // if 'cache' is true on the asset, then font is added to the global Pixi cache
    // bitmap fonts - PIXI.extras.BitmapFont.fonts.
});

AdvancedMovieClip - TextureAtlas and an anim JSON:

// Format for a regular texture atlas
var asset = {
	type: "pixi",
	anim: "assets/images/animData.json",
	atlas: "assets/images/atlasData.json",
	image: "assets/images/atlasTexture.png"
};
//format for a color/alpha split texture
asset = {
	type: "pixi",
	anim: "assets/images/animData.json",
	atlas: "assets/images/atlasData.json",
	color: "assets/images/atlasTexture-color.jpg",
	alpha: "assets/images/atlasTexture-alpha.png"
};
app.load(asset, function(result)
{
    // result is a springroll.pixi.AdvancedMovieClip
});

Spine animation:

// Format for anim with a springroll TextureAtlas
var asset = {
	type: "pixi",
	spineAnim: "assets/animations/skeleton.json",
	atlas: {
		//standard TextureAtlas asset
		type: "pixi",
		atlas: "assets/images/atlasData.json",
		image: "assets/images/atlasTexture.png"
	},
	//extra images to add to the atlas
	images: {
		//standard Texture assets
		extraImage1: {
			type: "pixi",
			image: "assets/images/extraImage1.png"
		}
	}
};
//format for anim with a an atlas exported by Spine
asset = {
	type: "pixi",
	spineAnim: "assets/animations/skeleton.json",
	atlas: {
		//asset for springroll.pixi.SpineAtlasTask
		type: "pixi",
		spineAtlas: "assets/images/atlasData.atlas",
		//dictionary of images used by the atlas, as Texture assets
		images: {
			type: "pixi"
			nameInAtlas: "assets/images/nameInAtlas.png"
		}
	},
};
app.load(asset, function(result)
{
    // result is a springroll.pixi.TextureAtlas object
    // if 'cache' is true on the asset, then textures are added to the global Pixi cache
    // for PIXI.Texture.fromImage() usage
});

Extending the LoadQueue API

For advanced loading situation, we have exposed access to the createjs.LoadQueue object. For more information see the PreloadJS docs for LoadQueue.

// The app.loader.load function returns a new LoadQueue item.
var load = app.loader.load("assets/images/background.jpg", function(result)
{
    // load has completed
    // result is a springroll.LoaderResult object
});

// Listen to a LoadQueue event
load.on("filestart", function()
{
     // load has begun
});
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.