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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add melonjs/melonJS --skill melonjs-loading-assets技能说明
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:
| type | for |
|---|---|
"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 register | your 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.