Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

melonjs-loading-assets

Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload, setParser, custom asset type, generated texture, procedural texture.

melonjs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add melonjs/melonJS --skill melonjs-loading-assets

About this skill


name: melonjs-loading-assets description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload, setParser, custom asset type, generated texture, procedural texture." license: MIT

Loading assets

The resource descriptor

Every asset is { name, type, src } plus type-specific extras:

import { loader } from "melonjs";

await loader.preload([
    { name: "tiles",   type: "image",    src: "data/img/tiles.png" },
    { name: "map1",    type: "tmx",      src: "data/map/map1.tmx" },
    { name: "tileset", type: "tsx",      src: "data/map/tileset.tsx" },
    { name: "sfx",     type: "audio",    src: "data/sfx/" },
    { name: "font",    type: "fontface", src: "data/font/PressStart2P.ttf" },
    { name: "atlas",   type: "json",     src: "data/img/atlas.json" },
]);

preload() has been awaitable since 19.8. The callback form still works and takes a third argument to suppress the built-in loading screen:

loader.preload(resources, onLoaded, /* switchToLoadState */ false);

The type list

The type strings are melonJS-specific — this is not a generic loader:

typefor
"image"textures, sprite sheets, normal maps
"json"data, texture-atlas descriptors, collision shapes from a shape editor
"tmx" / "tsx"Tiled maps and external tilesets
"audio"sound — src is a directory, see below
"video"video textures
"binary"raw data, bitmap font .fnt descriptors
"fontface"web fonts (.ttf, .woff)
"aseprite"Aseprite JSON + image
"shader"GLSL/WGSL shader sources — src or inline via data
"obj" / "mtl"Wavefront models and materials
"gltf" / "glb"glTF scenes
"js"scripts
any type you registeryour own formats, and things you generate rather than download — see Custom asset types

What belongs in the manifest — and what cannot

Preloading is not only for things with a URL. Three tiers, and the middle one is the one people miss.

After preloading, switch to a stage of your own. preload() puts you in state.LOADING, and that stage is transitional: build your scene in the callback and stay there, and nothing ever destroys it, so the built-in loading screen's logo and progress bar remain on top of your game. See melonjs-scenes-and-state.

1. Assets with a source. Everything in the type table above. Note "shader" takes inline source as well as a src, via the data field:

import { myRamp } from "./myRamp";   // a GLSL fragment body, in your own module

loader.preload([
    { name: "ramp", type: "shader", data: myRamp },
]);
const fx = loader.getShader("ramp");   // shared, already compiled

This matters more than it looks. A ShaderEffect compiles its program in its constructor, and compileProgram calls getProgramParameter(LINK_STATUS) immediately after linkProgram — a blocking call that forces the driver to finish. So building one during a scene costs that link on the frame it appears, and building three identical ones costs it three times. Preloaded as an asset it is compiled at load time, behind the loading screen, and the loader hands out a shared instance (effect.shared === true), which is what stops one renderable's teardown freeing it out from under the others. clone() does NOT help here — it constructs a new effect, and therefore links a new program.

2. Derived assets — build once, before the first stage. Canvases you bake, NoiseTexture2d, TextureAtlas: none of the built-in types describes these, and they must not be rebuilt per scene either. The renderer's texture cache is keyed by the image object, so a freshly baked canvas is a brand new GPU texture with a new mip chain — rebuild one per stage and a title → play → game-over cycle uploads four copies of the same pixels. Build each once and share it from a module the scenes read from, the way the platformer example builds its TextureAtlas.

Where you build it depends on what it costs. A gradient or a palette strip is well under a millisecond: build it after preload resolves. A bake that takes real time — procedural noise is the usual one: Earth Defender's sky, two fractal simplex fields over a 512² tile, takes about 200ms on a desktop — belongs inside the preload as an asset type of your own (Custom asset types). It then runs behind the loading screen and counts on the progress bar. Built on stage entry instead, it lands on the frame the scene is assembled, and with a transition running that frame is a black screen.

3. The engine's own shader programs — warmed for you, since 20.6. The mesh batcher compiles a program per feature combination (instance colours, instance data, fog — fog joins the key), lazily, on the first draw that needs it. prewarm builds them during preload() instead, behind the loading screen:

const app = new Application(1280, 720, {
    // on by default since 20.6 — named here only to show where it lives
    prewarm: true,
});

You do not call this yourself. preload() calls renderer.prewarm() once the assets are in and before LOADER_COMPLETE fires, so it happens while the progress bar is still up. Every preload() warms, not just the first, so a per-level preload warms whatever that level brought with it.

The one precondition for this part: a game that never calls loader.preload() does not get it. If you load assets another way, call `await app.renderer.

Read the complete source ↗