melonjs 20.2.0 → 20.3.0

package/skills/melonjs-loading-assets/SKILL.md

@@ -0,0 +1,157 @@
+---
+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, asset, preload, LOADER_COMPLETE, loading screen, unload."
+license: MIT
+---
+
+# Loading assets
+
+## The resource descriptor
+
+Every asset is `{ name, type, src }` plus type-specific extras:
+
+```js
+import { loader } from "melonjs";
+
+loader.setOptions({ crossOrigin: "anonymous" });   // needed for remote assets
+
+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:
+
+```js
+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 |
+| `"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 |
+| `"obj"` / `"mtl"` | Wavefront models and materials |
+| `"gltf"` / `"glb"` | glTF scenes |
+| `"js"` | scripts |
+
+## Two conventions that produce 404s
+
+**Audio `src` is a directory.** The loader appends the asset name plus each
+format from `audio.init()`, and picks the first that decodes:
+
+```js
+audio.init("mp3,ogg");                                  // before preloading audio
+{ name: "cling", type: "audio", src: "data/sfx/" }      // → data/sfx/cling.mp3
+```
+
+A full filename here gives you a 404. And `audio.init()` must run **before** any
+audio asset is preloaded.
+
+**A Tiled map needs its dependencies listed too** — the `.tmx`, any external
+`.tsx`, and the tileset images. Listing only the map produces a blank level.
+
+## Retrieving loaded assets
+
+```js
+loader.getImage("tiles");
+loader.getJSON("atlas");
+loader.getTMX("map1");
+loader.getGLTF("diorama");
+loader.getVideo("intro");
+loader.getFont("font");
+loader.getBinary("font-fnt");
+```
+
+Most engine classes take the asset **name** directly, so you often do not need
+these — `new Sprite(x, y, { image: "tiles" })` resolves it for you.
+
+## Base URLs
+
+Set a prefix per asset type rather than repeating it:
+
+```js
+loader.setBaseURL("image", "data/img/");
+loader.setBaseURL("audio", "data/sfx/");
+loader.setBaseURL("*", "https://cdn.example.com/");   // every 2D type at once
+```
+
+The `"*"` wildcard deliberately **skips `obj`, `mtl`, `gltf` and `glb`**: those
+resolve their own internal references (a `map_Kd` texture, a glTF `.bin`)
+relative to their file, so a global prefix would double-prefix them. Set those
+types individually.
+
+## Progress and completion
+
+Use the events. The old callback properties (`loader.onload`, `onProgress`,
+`onError`) were deprecated in 18.2 and **removed in 20.3** — being `let`
+bindings on an ES module namespace they could never be assigned from outside in
+the first place, so `loader.onProgress = fn` always threw a `TypeError`:
+
+```js
+import { event } from "melonjs";
+
+event.on(event.LOADER_PROGRESS, (progress) => { /* 0..1 */ });
+event.on(event.LOADER_COMPLETE, () => { /* … */ });
+event.on(event.LOADER_ERROR, (res) => { /* … */ });
+```
+
+## Unloading
+
+```js
+loader.unload({ name: "map1", type: "tmx" });
+loader.unloadAll();
+```
+
+`unloadAll()` also releases audio and GPU resources such as shader programs, so
+it is the right teardown for switching between large levels.
+
+## Loading between scenes
+
+The default loading screen appears automatically when `preload` switches state.
+For a custom one, register a `Stage` against `state.LOADING`:
+
+```js
+state.set(state.LOADING, new MyLoadingScreen());
+```
+
+If you preload without a loading stage and then change state immediately, pass
+`forceChange`:
+
+```js
+state.change(state.PLAY, true);
+```
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| audio 404s | `src` given as a file instead of a directory |
+| audio fails, `preload()` rejects with "Failed loading resource" | `audio.init()` not called before preloading — the real message is replaced by the loader's |
+| blank level, missing tiles | `.tsx` or tileset image not listed in the resources |
+| cross-origin textures fail | missing `loader.setOptions({ crossOrigin: "anonymous" })` |
+| text renders in a fallback font | web font not preloaded as `"fontface"` |
+| `BitmapText` renders nothing | the `.fnt` (as `"binary"`) or its image is missing |
+| `TypeError` assigning `loader.onProgress` / `onload` | removed in 20.3; they were never writable — use the `LOADER_*` events |
+
+## Related skills
+
+- `melonjs-getting-started` — where preloading sits in the bootstrap
+- `melonjs-tilemaps` — the full Tiled asset set
+- `melonjs-audio` — formats and the directory convention

package/skills/melonjs-particles-and-trails/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: melonjs-particles-and-trails
+description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, Trail, explosion, smoke, sparks, exhaust, emitter."
+license: MIT
+---
+
+# Particles and trails
+
+## An emitter does nothing until you tell it to emit
+
+Adding a `ParticleEmitter` to the world is not enough. Nothing appears, and
+nothing warns you.
+
+```js
+const emitter = new ParticleEmitter(x, y, {
+    image: loader.getImage("spark"),
+    totalParticles: 60,
+    speed: 4,
+    minLife: 200, maxLife: 800,
+});
+
+world.addChild(emitter);
+emitter.streamParticles();     // continuous — or:
+emitter.burstParticles();      // one shot
+```
+
+`streamParticles(ms)` takes an optional run time; without one it uses the
+`duration` setting, which defaults to `Infinity` — a stream runs until
+`stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
+
+For one-shot effects, `autoDestroyOnComplete: true` removes the emitter once its
+particles have finished. The `onComplete` callback fires at that same moment
+either way.
+
+For repeated effects (muzzle flashes, impacts) keep **one** long-lived emitter
+and re-aim it per shot, rather than allocating an emitter per event.
+
+## `referenceSpace` — which frame particles live in
+
+Added in 20.2. This decides what a particle's position is measured *from*, and
+it is the difference between an effect that trails behind a moving object and
+one that drags along with it.
+
+| value | particles are measured from | use for |
+|---|---|---|
+| `"local"` (default) | the emitter | flames, auras, anything welded to the object |
+| `"world"` | the container the emitter sits in | **trails, smoke, exhaust, dust** |
+| a `Container` | that container | a moving frame — snow inside a moving carriage |
+
+```js
+// exhaust that stays where it was emitted, so the ship flies away from it
+const exhaust = new ParticleEmitter(x, y, { referenceSpace: "world", /* … */ });
+```
+
+With the default `"local"`, a moving emitter carries its whole cloud along —
+which is right for a torch flame and wrong for a smoke trail. Changing it at
+runtime re-bases live particles, so nothing jumps.
+
+## Particle tuning changed in 20.2
+
+The 20.2 particle transform fix corrected a drift where drawn positions ran past
+simulated ones. Particles now travel roughly **half as far** over their life as
+they did before.
+
+Consequence: **speed values tuned on 19.x or earlier look wrong on 20.2+.** If
+you are copying emitter settings from older code or older tutorials, expect to
+raise `speed` or `maxLife`.
+
+## Trails
+
+`Trail` is a ribbon that follows a target — use it rather than hand-rolling a
+position history. **Its constructor takes one argument, the options object** —
+no `x, y` pair like every other renderable:
+
+```js
+const trail = new Trail({
+    target: sprite,             // a renderable or a plain Vector2d
+    length: 24,                 // max points kept (default 20)
+    width: 20,                  // max ribbon width in px (default 10)
+    lifetime: 500,              // per-point lifetime in ms (default 500)
+    widthCurve: [1, 0],         // 0 = head, 1 = tail
+    gradient: ["#fff", "#f80", "#f000"],
+});
+trail.blendMode = "additive";
+world.addChild(trail, 5);
+```
+
+Omit `target` and feed it yourself with `trail.addPoint(x, y)` — the mode for a
+sword slash, where the ribbon follows a weapon tip rather than an object. Points
+closer together than `minDistance` (default 4 px) are dropped.
+
+**`Trail` is 2D.** `addPoint` takes `(x, y)`, points are stored without a `z`,
+and the ribbon is drawn as connected screen-space quads. Under a `Camera3d` it
+draws a flat ribbon that does not recede with perspective — so it is the wrong
+tool for a trail behind an object moving *into* the scene. For that:
+
+- **`ParticleEmitter` with `referenceSpace: "world"`** — particles stay where
+  they were dropped while the emitter moves on, and the emitter propagates its
+  depth to each particle so `Camera3d` projects them correctly. This is the
+  built-in answer for exhaust, ski tracks and speed trails in 3D.
+- **A procedural `Mesh`** built from the object's recent path, with
+  `mesh.vertexColors` for a per-vertex gradient — more work, but a continuous
+  ribbon rather than discrete puffs.
+
+## Performance
+
+- Particles come from a shared pool, so a steady-state emitter allocates
+  nothing. Each emitter is still a `Container` that updates and draws every
+  frame, so one busy emitter beats many idle ones.
+- `totalParticles` (default 50) is a cap on how many are alive at once in stream
+  mode; `burstParticles()` launches that many in one go, or the count you pass.
+- `framesToSkip` (default 0) skips n updates between simulation steps — the
+  cheapest lever on an emitter with many particles.
+- Blending is per particle, set through the `blendMode` setting or by assigning
+  `emitter.blendMode` (which reaches the particles already alive as well as
+  later ones). Additive is cheap everywhere: fixed-function on both GPU
+  backends, native `lighter` on Canvas. The expensive modes are the advanced CSS
+  ones (`overlay`, `soft-light`, `color-dodge`, `darken`, …), which on WebGL 2
+  and WebGPU cost a destination capture plus a shader composite *per blended
+  draw*.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| trail looks flat under a `Camera3d` | `Trail` is 2D — use a world-space emitter or a ribbon mesh |
+| emitter added but nothing appears | `streamParticles()` / `burstParticles()` never called |
+| the cloud follows a moving emitter | default `referenceSpace: "local"` — use `"world"` for trails |
+| particles do not travel far enough | settings tuned pre-20.2, when drawn travel was doubled |
+| one-shot emitters accumulate | missing `autoDestroyOnComplete: true` |
+| frame rate drops with many effects | an emitter per event instead of one re-aimed emitter |
+
+## Related skills
+
+- `melonjs-renderables` — draw order and blend modes
+- `melonjs-effects-and-shaders` — blend mode cost on each backend

package/skills/melonjs-performance/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: melonjs-performance
+description: "Use this skill when a melonJS game drops frames, allocates heavily, or needs to scale to many objects. Covers object pooling, draw-call batching, atlases, baking with CanvasRenderTarget, instancing, culling and alwaysUpdate, the debug plugin, and where the real costs are. Triggers on: performance, slow, frame rate, fps, lag, pool, pool.register, pool.pull, batching, draw calls, InstancedMesh, culling, alwaysUpdate, inViewport, CanvasRenderTarget, optimise, profiling, debug plugin, memory."
+license: MIT
+---
+
+# Performance
+
+## Measure first
+
+Register the debug plugin and read the numbers before changing anything:
+
+```js
+import { plugin } from "melonjs";
+import { DebugPanelPlugin } from "@melonjs/debug-plugin";
+
+await app.init();
+plugin.register(DebugPanelPlugin, "debugPanel");
+```
+
+It reports frame time, draw calls, object counts, and can overlay collision
+shapes and bounds. **Draw calls** is usually the number that matters.
+
+## Batching: the biggest lever
+
+Both GPU backends batch **across textures**, not just within one: the quad
+batcher assigns each source image a texture unit and embeds the unit in the
+vertex data, so several different images still flush as a single draw. The pool
+is finite — the WebGL batcher gets `renderer.maxTextures` units (the
+`maxTextures` application setting, `"auto"` = the device limit capped at 32), the
+WebGPU batcher eight per segment. Overflow the pool and the batch flushes.
+
+So the goal is not "one image" but "few state changes". What actually ends a
+batch:
+
+- **Overflowing the texture-unit pool** — pack sprites into a `TextureAtlas` and
+  prefer one large tileset over several small ones, so a screenful of sprites
+  fits inside the pool with room to spare.
+- **Changing `blendMode`** — `setBlendMode` flushes before it touches GL state.
+  Group by blend mode where you can.
+- **Switching batcher** — interleaving primitives (`strokeRect`, `fillRect`,
+  debug shapes) or meshes between sprites flushes the quad batcher and rebinds.
+  Draw all the sprites, then all the primitives.
+- **Binding a custom shader** — a `ShaderEffect` on the quad batcher also turns
+  multi-texture batching *off* for the duration, dropping you back to one
+  texture per draw.
+
+The advanced blend modes are the expensive ones: `overlay`, `difference`,
+`hard-light`, `soft-light`, `color-dodge`, `color-burn`, `darken` and `lighten`
+cannot be expressed as fixed-function blending, so each such draw is bracketed
+on its own — capture the destination, redraw offscreen, composite through a
+shader. Right for accents, wrong for hundreds of objects. `normal`, `additive`,
+`multiply`, `screen` and `exclusion` are plain fixed-function state and cost
+nothing extra.
+
+## Pooling
+
+Anything spawned frequently — bullets, particles, pickups, damage numbers —
+should be pooled rather than allocated:
+
+```js
+pool.register("bullet", Bullet, true);      // third arg = enable recycling
+const b = pool.pull("bullet", x, y);        // recycled: onResetEvent(x, y)
+                                            // fresh:    new Bullet(x, y)
+world.removeChild(b);                        // returns to the pool automatically
+```
+
+`register` also publishes the class as a Tiled object factory under that name,
+so an object with a matching class or name in a `.tmx` map instantiates it. Set
+`pool.autoRegisterTiled = false` around the call for classes that should stay
+programmatic.
+
+Two rules that cause subtle bugs when missed:
+
+- **`onResetEvent` must restore everything the object's lifetime mutates** —
+  alpha, tint, scale, animation, velocity. Anything you forget carries into the
+  next use, which looks like a random visual glitch.
+- **Pooled objects do not fire `onDestroyEvent` on removal.** Removal always
+  calls `onDeactivateEvent`, then tries `pool.push`; only when that *fails* does
+  it fall through to `destroy()`, which is what calls `onDestroyEvent`. So a
+  successfully recycled object never sees it. Pair event subscriptions with
+  `onActivateEvent` / `onDeactivateEvent` instead, or you leak handlers.
+
+Engine classes are poolable too: `pool.pull("me.Tween", target)`.
+
+## `scale()` is multiplicative
+
+A pooled sprite arrives carrying its previous life's transform, and calling
+`scale()` each frame compounds. For absolute scaling:
+
+```js
+sprite.currentTransform.identity();
+sprite.currentTransform.scale(s, s, 1);
+```
+
+## Culling and update cost
+
+- `Container` recomputes `inViewport` for every child each frame against every
+  active camera, and skips both its `draw()` **and** its `update(dt)` when it is
+  off-screen. That gate is `inViewport || alwaysUpdate`, and it applies to every
+  container in every game, whichever physics you use.
+- On top of that, the **built-in physics adapter** gates body integration and
+  narrow-phase collision on the same `inViewport || alwaysUpdate` — so an
+  off-screen body stops simulating even if something else calls its `update`.
+  The planck and matter adapters have no such gate: they step the whole world
+  regardless of the camera.
+- Set `alwaysUpdate = true` on anything that must keep moving off-screen, and
+  accept the cost. On many objects it removes the saving entirely.
+- `floating = true` does **not** disable culling — it moves the test into screen
+  space: a floating renderable is checked against the camera's screen rectangle
+  (`0, 0, camera.width, camera.height`) instead of the world view. That is why a
+  HUD stays put as the camera moves. `Container.draw` then draws floating
+  children unconditionally, but `update()` is still gated, so a floating object
+  parked outside the screen rectangle stops updating.
+
+## Bake once, draw many
+
+When you would otherwise issue hundreds of identical draws every frame, render
+once into a `CanvasRenderTarget` and draw the result as a single sprite. This is
+the sanctioned idiom before reaching for a custom shader — hundreds of draws
+collapse to one.
+
+## Instancing in 3D
+
+`InstancedMesh` draws one mesh many times in a single call — the difference
+between a hundred trees and a hundred thousand. glTF scenes using
+`EXT_mesh_gpu_instancing` load as an `InstancedMesh` automatically.
+
+## Update loops
+
+- `update(dt)` should **return `true` only when something changed**. Returning
+  `true` unconditionally forces redraw work every frame.
+- Use `dt` for motion rather than assuming a fixed step — the engine already
+  paces it, and a fixed assumption breaks on high-refresh displays.
+- Use `timer.setTimeout` / `setInterval`, which are pause-aware. `window` timers
+  keep firing behind a pause menu.
+
+## Audio and assets
+
+- `stream: true` on long music tracks plays through a streaming element instead
+  of decoding the whole file into memory.
+- `pool` on an audio clip sizes the reuse pool for finished instances — it is
+  **not** a concurrency cap.
+- `loader.unloadAll()` between large levels drops every loaded asset and
+  `destroy()`s the shader programs the loader owns — that last part is a real
+  GPU release. Images, by contrast, only lose their loader-side reference; the
+  renderer's texture cache is not purged by unloading.
+
+## Where the costs actually are
+
+In rough order for a typical 2D game:
+
+1. Draw calls — fix with atlases and fewer tilesets
+2. Overdraw from large blended sprites
+3. Per-frame allocation — fix with pooling
+4. `alwaysUpdate` on objects that do not need it
+5. The engine itself, which is rarely the problem
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| high draw-call count | the texture-unit pool overflows, or primitives/meshes are interleaved with sprites |
+| draw calls jump when one effect is enabled | a custom shader on the quad batcher disables multi-texture batching |
+| frame time spikes and GC pauses | allocating per frame instead of pooling |
+| a recycled object looks wrong | `onResetEvent` does not restore every mutated property |
+| sprite grows every frame | `scale()` is multiplicative — reset the transform |
+| off-screen enemies stop moving | `update()` and built-in physics both gate on `inViewport`; set `alwaysUpdate` |
+| a HUD element vanishes | `floating` is culled against the screen rect, and it sits outside it |
+| everything updates even when idle | `update()` returning `true` unconditionally |
+| memory grows with long music | missing `stream: true` |
+| slow only on some machines | Canvas fallback — no GPU tilemap path |
+
+## Related skills
+
+- `melonjs-sprites-and-animation` — atlases and pooling in detail
+- `melonjs-renderer-backends` — why performance differs per machine
+- `melonjs-3d` — `InstancedMesh`