Loading assets

Strategy

• Load assets before using them
• Load shared assets in a "preloader" scene and nonshared assets in the scene they will be used in
• Use a scene payload to load small assets before preload(), if needed
• For special cases, run the scene loader manually and use event callbacks

Assets

There are many types, and you can read about all of them.

Assets need to be loaded before you can use them, but once loaded, they are available everywhere. It doesn't matter which loader or scene loaded them. Once loaded they are in the Texture Manager (this.textures) or the asset caches (this.cache).

Use unique keys (names) for assets.

The loader

Each scene has a loader plugin, this.load, for loading assets.

Adding files to the loader

All the "load" methods queue a file by key (name) and URL.

this.load.image('treasure', 'treasure.png');
// OR
this.load.image({ key: 'treasure', url: 'treasure.png' });

As a shortcut, passing key only sets the url as well, using a default extension (by asset type):

// `url` will be 'treasure.png'
this.load.image('treasure');

If you don't care for the key/URL distinction, you can pass:

this.load.image({ key: 'treasure.png', extension: '' });

Then the asset key and URL are identical.

The loader will not add assets with duplicate keys (per asset type) at all:

// MISTAKE
this.load.image('sky', 'sky1.png');
this.load.image('sky', 'sky2.png');
// 'sky1.png' is loaded and stored as 'sky'.
// 'sky2.png' is not added or loaded.

Each "load" method can take an array, so there is no need to loop:

this.load.image([
  'conch',
  'treasure',
  'trident'
]);

this.load.spritesheet({
  { key: 'mermaid', url: 'mermaid.png', frameConfig: { frameWidth: 16, frameHeight: 16 } },
  { key: 'merman', url: 'merman', frameConfig: { frameWidth: 16, frameHeight: 16 } }
});

Thus you could write your own manifest pretty easily:

const files = {
  animation: [/* … */],
  audio: [/* … */],
  image: [/* … */],
  spritesheet: [/* … */],
};

this.load.animation(files.animation);
this.load.audio(files.audio);
this.load.image(files.images);
this.load.spritesheet(files.spritesheet};

A File Pack could do as well:

this.load.pack('pack1', {
  section1: {
    files: [
      { type: 'image', key: 'conch', url: 'conch.png' },
      { type: 'spritesheet', key: 'mermaid', url: 'mermaid.png', frameConfig: {/* … */} }
    ]
  }
});

You can add assets to the load queue while the loader is running. load.multiatlas(), load.pack(), and load.spine() work this way.

this.load.json('level1');
this.load.on('filecomplete-level1', (key, type, data) => {
  this.load.image(data.images);
  this.load.spritesheet(data.spritesheets);
});

preload()

Most of the time you will load assets in a scene preload() method.

When preload() returns, the loader starts automatically only if it has any files queued, then create() is called only after loading finishes.

If no files are queued when preload() returns, the loader doesn't start or complete and create() is called immediately.

Scene payload

A scene payload lets you load assets right when the scene starts.

const sceneConfig = {
  pack: {
    files: [
      { type: 'json', key: 'settings', url: 'settings.json' },
      { type: 'image', key: 'bar', url: 'bar.png' }
    ]
  },
  init: function () {
    this.game.registry.merge(this.cache.json.get('settings'));
  },
  preload: function () {
    const loadingBar = this.add.image(0, 0, 'bar');
    // …
  }
};

It's best for small assets you want to use right away, before create(). The scene does nothing at all until the payload completes.

Removing assets

You can remove assets to save memory. Remove any game objects or scene objects (e.g., Sounds) using these assets first!

Remove textures from the Texture Manager:

this.textures.remove('conch');

and other assets from their respective caches:

this.cache.audio.remove('chime');
this.cache.json.remove('settings');

Removing assets to reuse their keys for different assets is usually a bad idea.