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 (in the game caches or Texture Manager) before you can use them, but once loaded, they are available everywhere.

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' });

If you don't care for the key/URL distinction, pass the URL itself as key and omit url:

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

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.png',
  'treasure.png',
  'trident.png'
]);

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);
// …

But by then you're nearly writing a File Pack:

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

preload()

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

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

If no files are queued, the loader doesn't start or complete and create() is called immediately. This is what happens during a typical scene restart. No loading at all happens during the second scene cycle.

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.