resources

Resources & Asset Loading

melonJS provides a resource loader to preload images, audio, maps, fonts, and other assets before your game starts.

Defining Resources

Resources are defined as an array of objects with name, type, and src properties:

const resources = [
    // images
    { name: "player",   type: "image", src: "data/img/player.png" },
    { name: "tileset",  type: "image", src: "data/img/tileset.png" },

    // texture atlas (JSON + image)
    { name: "sprites",  type: "json",  src: "data/img/sprites.json" },
    { name: "sprites",  type: "image", src: "data/img/sprites.png" },

    // Tiled maps
    { name: "level1",   type: "tmx",   src: "data/map/level1.tmx" },
    { name: "level1",   type: "tmx",   src: "data/map/level1.json" },

    // audio (provide path without extension — melonJS picks the best format)
    { name: "bgm",      type: "audio", src: "data/bgm/" },
    { name: "jump",     type: "audio", src: "data/sfx/" },

    // bitmap font
    { name: "PressStart2P", type: "binary", src: "data/font/PressStart2P.fnt" },
    { name: "PressStart2P", type: "image",  src: "data/font/PressStart2P.png" },

    // web font
    { name: "MyFont",   type: "fontface", src: "data/font/myfont.woff2" },
];

Preloading

Load all resources at once using loader.preload(). It returns a Promise, so you can either pass a callback or await it (both work):

import { loader, state } from "melonjs";

// callback form
loader.preload(resources, () => {
    // all assets loaded — start the game
    state.change(state.PLAY);
});

// ...or await it (the callback still fires too, if you pass one)
await loader.preload(resources);
state.change(state.PLAY);

Resource Types

Type	Description
image	PNG, JPG, or other image files for sprites and tilesets
json	JSON data files (texture atlas, custom data)
tmx / tsx	Tiled map and tileset files (XML or JSON format)
audio	Sound effects and music (MP3, OGG — provide directory path)
binary	Raw binary/text data (bitmap font .fnt files, custom formats)
fontface	Web font files (WOFF2, TTF) loaded as CSS font-face
xml	XML data files
video	Video files for video sprites

Accessing Loaded Resources

After preloading, access resources through the loader:

import { loader } from "melonjs";

const image = loader.getImage("player");
const json = loader.getJSON("sprites");
const tmx = loader.getTMX("level1");

Lazy Loading

To load a single resource after the initial preload — callback form, or await the no-callback form:

// callback form (returns the resource count)
loader.load(
    { name: "bonus", type: "image", src: "data/img/bonus.png" },
    () => { console.log("bonus loaded"); },
    () => { console.error("failed to load bonus"); }
);

// ...or await it (no callbacks → returns a Promise, rejects on failure)
await loader.load({ name: "bonus", type: "image", src: "data/img/bonus.png" });

Loader Options

Configure cross-origin and caching settings:

loader.setOptions({
    crossOrigin: "anonymous",
});

Audio Setup

Initialize the audio engine before preloading:

import { audio } from "melonjs";

audio.init("mp3,ogg");

This tells melonJS which audio formats to try, in order of preference.