melonjs 20.1.1 → 20.3.0

package/skills/melonjs-scenes-and-state/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: melonjs-scenes-and-state
+description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Stage, state, state.set, state.change, state.transition, state.pause, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze."
+license: MIT
+---
+
+# Scenes, game state and timing
+
+## Stages and the state manager
+
+A `Stage` is a screen. Register it against a state id, then change to it:
+
+```js
+import { Stage, state } from "melonjs";
+
+class PlayScreen extends Stage {
+    onResetEvent(app) { /* build the scene */ }
+    onDestroyEvent(app) { /* tear it down */ }
+}
+
+state.set(state.PLAY, new PlayScreen());   // register first
+state.change(state.PLAY);                   // then switch
+```
+
+Built-in ids: `state.LOADING`, `state.MENU`, `state.READY`, `state.PLAY`,
+`state.GAMEOVER` (no underscore), `state.GAME_END`, `state.SCORE`,
+`state.CREDITS`, `state.SETTINGS`, `state.DEFAULT`. `state.USER` (100) is the
+base for your own ids — `const CUTSCENE = state.USER + 1`.
+
+**Build scene content in `onResetEvent`, not the constructor.** `onResetEvent`
+runs on *every* entry to the state; the constructor runs once. Scene content
+created in the constructor exists once and is not rebuilt when you return.
+
+`onResetEvent(app)` receives the `Application` — use that rather than importing
+the global `game`.
+
+Extra arguments to `state.change` are forwarded:
+
+```js
+state.change(state.PLAY, false, { level: 2 });   // → onResetEvent(app, { level: 2 })
+```
+
+The second argument is `forceChange`: pass `true` to switch immediately instead
+of on a deferred tick, which is what you want when changing state right after a
+preload completes. It is ignored when a transition is configured — a transition
+always drives the switch from its own completion callback.
+
+`state.change` **throws** `Undefined Stage for state '<id>'` if nothing was
+registered for that id, and `state.set` throws if the second argument is not a
+`Stage` instance. Neither fails quietly.
+
+## Persistent objects across levels
+
+```js
+if (typeof this.HUD === "undefined") {
+    this.HUD = new Container();         // construct once (or UIBaseElement)
+}
+this.HUD.isPersistent = true;           // survives level changes
+this.HUD.floating = true;               // screen coordinates, not world
+app.world.addChild(this.HUD, 100);      // explicit z — see melonjs-renderables
+```
+
+## Transitions and pausing
+
+```js
+state.transition("fade", "#FFFFFF", 250);
+state.transition("mask", "#000", 500, new Ellipse(0, 0, 1, 1));  // shape required
+state.pause();                               // freeze update, keep drawing
+state.resume();
+app.freeze(150);                             // brief hit-stop (proxies state.freeze)
+```
+
+`state.transition` is global and sticky — once set it applies to every later
+`state.change`. The `"mask"` form needs its fourth argument, an `Ellipse` or
+`Polygon`; without one it warns and falls back to a direct switch.
+
+## The update loop
+
+There is no loop you own. Logic goes in `update(dt)` overrides, or a
+`GAME_UPDATE` subscription for scene-level animation:
+
+```js
+event.on(event.GAME_UPDATE, () => { /* per frame */ });
+```
+
+`update(dt)` must **return `true`** when the object changed and needs redrawing.
+Returning nothing is falsy and the object can appear frozen while its state moves.
+
+`dt` is milliseconds since the last frame and is the right basis for motion —
+the engine already paces it. Do not reach for `performance.now()`.
+
+A common idiom for a per-frame game controller with nothing to draw is a
+`Renderable(0, 0, 1, 1)` with `alwaysUpdate = true` and an empty `draw()`.
+
+## Timers: use the engine's, not the window's
+
+```js
+import { timer } from "melonjs";
+
+timer.setTimeout(fn, 1000);
+const id = timer.setInterval(fn, 500);
+timer.clearInterval(id);        // in the Stage's onDestroyEvent
+```
+
+`Stage` has only `onResetEvent` and `onDestroyEvent` — there is no
+`onActivateEvent` / `onDeactivateEvent` on a stage. Those two are `Renderable`
+hooks; put per-renderable teardown there instead.
+
+Engine timers are **pause-aware**. `window.setTimeout` keeps firing while the
+game is paused, which produces enemies spawning behind a pause menu. Pass
+`false` as the third argument — `timer.setInterval(fn, 500, false)` — for one
+that keeps running through a pause, which is what a pause-menu animation or a
+countdown that should not freeze needs. (That argument was ignored by
+`setInterval` before 20.3.)
+
+## Tweens
+
+```js
+import { Tween, pool } from "melonjs";
+
+const t = pool.pull("Tween", sprite.pos)   // registered name is "Tween"
+    .to({ x: 300 }, { duration: 500 })     // options object, not a number
+    .easing(Tween.Easing.Quadratic.Out)
+    .onComplete(() => { /* … */ })
+    .start();                    // ← without this, nothing happens
+```
+
+Four traps:
+
+- **A tween without `.start()`** (or `autoStart: true` in the `to()` options)
+  silently does nothing.
+- **`to()`'s second argument is an options object**
+  (`{ duration, easing, yoyo, repeat, delay, repeatDelay, interpolation,
+  autoStart }`). Passing a bare number is not a duration — it is read for a
+  `.duration` property, finds none, and the tween silently runs the default
+  1000 ms.
+- **Tweens freeze during `state.pause()` / `freeze()`** unless
+  `tween.updateWhenPaused = true` — which is how you get an effect that decays
+  *through* a hit-stop.
+- **Stop a tween before destroying its target**, or `onUpdate` fires against a
+  dead renderable.
+
+## Guard teardown-adjacent callbacks
+
+Callbacks can fire while a stage is being torn down, when the current state is
+already something else:
+
+```js
+if (!state.isCurrent(state.PLAY)) return;
+```
+
+Without the guard, a "children emptied" handler can reset the wrong stage.
+
+## Persistence
+
+```js
+import { save } from "melonjs";
+
+save.add({ hiscore: 0 });      // once; idempotent, loads any stored value
+save.hiscore = 1200;           // plain assignment writes to localStorage
+```
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| scene builds once and is empty on return | content created in the constructor, not `onResetEvent` |
+| `Undefined Stage for state 'N'` thrown | no `state.set` for that id first |
+| a tween finishes in 1000 ms whatever you pass | `to()` takes `{ duration }`, not a number |
+| object frozen while its state updates | `update()` not returning `true` |
+| timers fire behind a pause menu | `window.setTimeout` instead of `timer.setTimeout` |
+| a tween does nothing | `.start()` never called |
+| effect stops during a hit-stop | tween needs `updateWhenPaused = true` |
+| crash after a stage switch | callback ran during teardown — guard with `state.isCurrent` |
+| HUD scrolls away with the camera | missing `floating = true` |
+
+## Related skills
+
+- `melonjs-getting-started` — the Application and the first scene
+- `melonjs-renderables` — `floating`, draw order, update/draw contracts

package/skills/melonjs-sprites-and-animation/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: melonjs-sprites-and-animation
+description: "Use this skill when creating sprites, playing frame animations, or working with texture atlases in melonJS. Covers Sprite construction from a plain image or an atlas region, addAnimation/setCurrentAnimation, TextureAtlas for TexturePacker/ShoeBox/Aseprite, tint, flip, NineSliceSprite, and the centred anchorPoint that offsets naive positioning. Triggers on: Sprite, new Sprite, addAnimation, setCurrentAnimation, isCurrentAnimation, TextureAtlas, TexturePacker, Aseprite, ShoeBox, atlas, region, framewidth, frameheight, tint, flipX, flipY, NineSliceSprite, animation."
+license: MIT
+---
+
+# Sprites, animation and atlases
+
+> Creating sprites from images or atlases, driving frame animation, and the
+> positioning trap that catches almost everyone.
+
+## `pos` is the centre, not the top-left
+
+`Renderable.anchorPoint` defaults to **`(0.5, 0.5)`**, so a sprite's `pos` is its
+**centre**. `Container` forces `(0, 0)` instead, which is why containers and
+sprites appear to disagree.
+
+```js
+// a 64×64 sprite at (100, 100) covers 68..132, not 100..164
+const s = new Sprite(100, 100, { image: "hero", framewidth: 64, frameheight: 64 });
+
+s.anchorPoint.set(0, 0);   // switch to top-left positioning if you prefer
+```
+
+Writing top-left maths against the centred default puts everything half a sprite
+off, with no error. It is the most common source of "close but subtly wrong"
+placement.
+
+## Constructing a sprite
+
+From a plain image:
+
+```js
+const hero = new Sprite(x, y, {
+    image: "hero",          // preloaded asset name
+    framewidth: 32,
+    frameheight: 32,
+});
+```
+
+From a texture atlas region:
+
+```js
+const atlas = new TextureAtlas(loader.getJSON("sprites"), loader.getImage("sprites"));
+const coin = new Sprite(x, y, { image: atlas, region: "coin_01.png" });
+```
+
+`framewidth` / `frameheight` define the animation grid on a sheet. Omit them and
+the whole image is one frame.
+
+## Animation
+
+```js
+hero.addAnimation("idle", [0, 1, 2, 3], 100);   // frames, ms per frame
+hero.addAnimation("walk", [4, 5, 6, 7]);
+hero.addAnimation("die",  [8, 9], 150);
+
+hero.setCurrentAnimation("walk");
+hero.setCurrentAnimation("die", "idle");                          // chain to idle when it ends
+hero.setCurrentAnimation("die", { loop: false });                 // play once, hold the last frame
+hero.setCurrentAnimation("die", { loop: false, onComplete: fn }); // …and call fn when it does
+
+if (hero.isCurrentAnimation("walk")) { /* … */ }
+```
+
+Frame indices are into the `framewidth`/`frameheight` grid. With an atlas, use
+`atlas.getAnimationSettings([regionNames])` and spread it into the Sprite
+settings, or `atlas.createAnimationFromName([regionNames])`, which returns a
+ready-made Sprite. On a fixed-cell spritesheet only numeric indices are
+accepted — passing region names throws.
+
+The second argument to `setCurrentAnimation` is polymorphic. A **string** chains
+to that animation when this one ends. An **options object** takes
+`{ loop, next, speed, onComplete }`, and only an explicit `loop: false` stops the
+looping. A **bare function** is the legacy form: it fires at *every* cycle end,
+and only holds the last frame if it returns `false`. Omit the argument entirely
+and the animation loops forever.
+
+Re-selecting the animation that is already current is a no-op, so calling
+`setCurrentAnimation` every frame is safe. An unknown id throws.
+
+## Texture atlases
+
+`TextureAtlas` reads several formats:
+
+| source | how |
+|---|---|
+| TexturePacker / Free Texture Packer JSON | `new TextureAtlas(loader.getJSON(name), loader.getImage(name))` |
+| Aseprite **JSON export** | same as TexturePacker — the format is detected from `meta.app` |
+| Aseprite **`.aseprite` / `.ase` binary** | loader type `"aseprite"`, which stores the composited image *and* a JSON sidecar under the one asset name |
+| ShoeBox | JSON export using the melonJS exporter settings file; same call as TexturePacker |
+| fixed-cell spritesheet | `new TextureAtlas({ framewidth, frameheight, anchorPoint }, loader.getImage(name))` |
+| multi-page | pass an array of atlas JSON objects as the first argument |
+
+Helpers: `createSpriteFromName(name)`, `createAnimationFromName([names])`,
+`getAnimationSettings([names])`.
+
+Atlases matter for performance: the GPU batchers bind several textures at once
+(up to `renderer.maxTextures`), so a handful of separate images still batch —
+but once a frame crosses that many distinct textures the batch has to flush.
+Packing into one atlas keeps everything on a single binding.
+
+## Visual properties
+
+```js
+sprite.tint.setColor(255, 128, 0);   // multiply tint
+sprite.alpha = 0.5;
+sprite.flipX(true);                   // mirror horizontally
+sprite.flipY(true);
+sprite.blendMode = "additive";        // see the effects skill for the full list
+sprite.scale(2, 2);                   // ← multiplicative, see below
+```
+
+**`scale()` is multiplicative, not absolute.** Calling it every frame compounds.
+For absolute scaling reset first:
+
+```js
+sprite.currentTransform.identity();
+sprite.currentTransform.scale(s, s, 1);
+```
+
+This bites hardest with pooled sprites, which arrive carrying their previous
+life's transform.
+
+## `NineSliceSprite`
+
+For panels and dialogue boxes that stretch without distorting their corners:
+
+```js
+new NineSliceSprite(x, y, {
+    image: "panel", width: 300, height: 120,
+    insetx: 12, insety: 12,     // lowercase x/y — `insetX` is silently ignored
+});
+```
+
+`width` and `height` are mandatory and the constructor throws without them.
+The insets default to a quarter of the frame.
+
+## Pooling
+
+Frequently spawned sprites should be pooled:
+
+```js
+pool.register("bullet", Bullet, true);      // true = recyclable
+const b = pool.pull("bullet", x, y);        // new Bullet(x, y), or onResetEvent(x, y) on a reused one
+world.removeChild(b);                       // returns it to the pool automatically
+```
+
+Two consequences:
+
+- A recyclable class's `onResetEvent` must reset **everything** its lifetime
+  mutates — alpha, tint, scale, animation state. Anything you forget carries
+  over to the next use.
+- Pool-recycled objects do **not** fire `onDestroyEvent` on removal. Pair event
+  subscriptions with `onActivateEvent` / `onDeactivateEvent` instead.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| everything offset by half a sprite | top-left maths against the centred `anchorPoint` |
+| sprite grows every frame | `scale()` is multiplicative — reset the transform |
+| a recycled sprite keeps its old look | `onResetEvent` does not restore every mutated property |
+| event handlers leak on pooled objects | bound in the constructor rather than `onActivateEvent` |
+| animation never advances | no `framewidth`/`frameheight`, so the sheet is one frame |
+| animation plays once and stops | `{ loop: false }`, or a callback that returned `false` |
+| sprites do not batch | more distinct textures in one frame than `renderer.maxTextures` |
+| nine-slice corners stretch anyway | `insetX`/`insetY` instead of `insetx`/`insety` |
+
+## Related skills
+
+- `melonjs-renderables` — anchors, draw order, custom draw
+- `melonjs-getting-started` — preloading images and atlases

package/skills/melonjs-tilemaps/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: melonjs-tilemaps
+description: "Use this skill for Tiled maps in melonJS — loading TMX/TSX levels, spawning entities from Tiled objects, collision shapes authored in Tiled, isometric and hexagonal maps, and image layers. Covers the pool.register name contract, camera bounds, compressed maps needing the inflate plugin, and the level director API. Triggers on: Tiled, TMX, TSX, tilemap, level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
+license: MIT
+---
+
+# Tiled maps
+
+> melonJS's flagship content pipeline. Maps are authored in
+> [Tiled](https://www.mapeditor.org/) and loaded through the `level` director —
+> you rarely touch the `TMX*` classes directly.
+
+## Loading a level
+
+Preload the map **and** everything it references — the `.tmx`, any external
+`.tsx` tilesets, and the tileset images:
+
+```js
+await loader.preload([
+    { name: "map1",    type: "tmx", src: "data/map/map1.tmx" },
+    { name: "tileset", type: "tsx", src: "data/map/tileset.tsx" },
+    { name: "tiles",   type: "image", src: "data/img/tiles.png" },
+]);
+
+level.load("map1");           // inside Stage.onResetEvent
+```
+
+Asset `type` is `"tmx"` for maps and `"tsx"` for external tilesets — those are
+the only two type strings the loader knows. The *file* can be `.tmx` / `.tsx`
+(XML), or `.json` / `.tmj` / `.tsj`; the parser branches on the extension, not
+on the type. `type: "tmj"` throws `unknown or invalid resource type`. You can
+also skip `src` and pass the map inline via `data` (with `format: "json"` or
+`"xml"`).
+
+`level.load(levelId, options)` accepts `container` (default `game.world`),
+`onLoaded` (default `game.onLevelLoaded`), `flatten` (default `game.mergeGroup`)
+and `setViewportBounds` (default **`true`**). It throws `level <id> not found`
+for an unknown id.
+
+**`level.load` is deferred while the game loop is running.** It calls
+`state.stop()` and finishes the load in a `setTimeout`, so it returns `true`
+before anything is in the world. Do follow-up work from the `onLoaded` callback
+or an `event.LEVEL_LOADED` listener, not on the next line.
+
+`level.reload()`, `level.next()`, `level.previous()`, `level.getCurrentLevelId()`
+and `level.levelCount()` round out the namespace. `flatten: false` wraps each
+Tiled object group in its own `Container` named after the group.
+
+## Spawning entities from Tiled objects
+
+Objects are matched against a factory registry, in this order: the object's
+Tiled **class**, then its **name**, then the structural fallbacks `"text"`,
+`"tile"` and `"shape"`.
+
+```js
+pool.register("mainPlayer", PlayerEntity);   // ← matches Tiled class OR name
+level.load("map1");
+```
+
+`pool.register(className, classObj, recycling)` also registers the class as a
+Tiled object factory (and again under an `me.`-prefixed alias), unless you set
+`pool.autoRegisterTiled = false`. The dedicated entry points are:
+
+```js
+import { registerTiledObjectClass, registerTiledObjectFactory } from "melonjs";
+
+registerTiledObjectClass("Enemy", Enemy);            // new Enemy(x, y, settings)
+registerTiledObjectFactory("Spine", (settings, map) => { /* → Renderable */ });
+```
+
+Register **before** loading. With no match the object falls through to the
+structural factory and becomes a plain `Renderable` with a static body — it does
+not error, it just has none of your behaviour.
+
+`registerTiledObjectClass` **throws** if you register a *different* constructor
+under a name already taken (re-registering the same one is a no-op).
+`registerTiledObjectFactory` overwrites and only `console.warn`s, so it is the
+one to use for overriding a built-in such as `"shape"`.
+
+melonJS pre-registers `Renderable`, `Sprite`, `NineSliceSprite`, `Text`,
+`BitmapText`, `ImageLayer`, `ColorLayer`, `Light2d`, `Collectable` and `Trigger`
+as Tiled classes, so `Collectable` and `Trigger` work out of the box.
+
+## Camera bounds
+
+`level.load` sets the viewport bounds to the map size for you —
+`setViewportBounds` defaults to `true`, and the handler is re-run on every
+viewport resize, centring the map when it is smaller than the screen. You only
+need to do it by hand when you opted out:
+
+```js
+level.load("map1", { setViewportBounds: false });
+app.viewport.setBounds(0, 0, mapWidth, mapHeight);   // now it's on you
+```
+
+The same is true if you drive `TMXTileMap.addTo(container, flatten, setViewportBounds)`
+directly — note that method's `setViewportBounds` defaults to **`false`**, the
+opposite of `level.load`'s.
+
+## Collision shapes
+
+Draw collision geometry in Tiled on an object layer and melonJS turns it into
+world shapes automatically — rectangles, polygons, polylines, ellipses and
+points all work.
+
+The contract is the **layer name**: melonJS lowercases it and checks whether it
+*contains* `"collision"` (so `collision`, `Collision`, `world collision` all
+match). Inside such a layer, objects **with no name** get
+`collisionType = collision.types.WORLD_SHAPE` and `type = "static"`. A *named*
+object in a collision layer keeps whatever its factory gave it — that is how you
+mix triggers into the collision layer.
+
+An object that matches no factory and carries no text or tile data falls to the
+`"shape"` factory: a plain `Renderable` with a static `bodyDef` built from its
+geometry, which the world auto-registers with the active adapter on `addChild`.
+
+For per-object physics, set the object's custom properties in Tiled; they arrive
+on the settings object passed to your entity's constructor.
+
+## Map orientations
+
+Orthogonal, **isometric**, hexagonal, staggered and oblique are all supported;
+anything else throws `<orientation> type TMX Tile Map not supported!` at load.
+Isometric maps need y-sorting so objects overlap correctly:
+
+```js
+app.world.sortOn = "y";       // after level.load
+```
+
+`sortOn` only accepts `"x"`, `"y"`, `"z"` (the default) or `"depth"` and throws
+on anything else. `Vector2d`, `Vector3d`, their observable variants and `Polygon`
+all carry `.toIso()` / `.to2d()` for converting between screen and map space.
+
+## Image layers
+
+`ImageLayer` gives parallax backgrounds with a ratio per axis, set in Tiled or in
+code. Repeat behaviour matches Tiled's.
+
+## Compressed maps need a plugin
+
+A map saved with **gzip, zlib or zstd** compressed layer data throws
+`No inflate function set — GZIP/ZLIB decompression not supported!` at parse time
+without:
+
+```js
+import { plugin } from "melonjs";
+import { TiledInflatePlugin } from "@melonjs/tiled-inflate-plugin";
+
+plugin.register(TiledInflatePlugin);   // before preloading any compressed map
+```
+
+Uncompressed base64 and CSV layer data need no plugin. If a map loads in Tiled
+but not in melonJS, check the layer compression setting first.
+
+## Rendering
+
+Each tile layer resolves to one of three `renderMode`s — `"shader"`,
+`"prerender"` or `"perTile"` — auto-selected in that order of preference, or
+forced per layer. The `"shader"` path is a single quad per tileset with a
+per-pixel GID lookup in the fragment shader. It requires **all** of:
+
+- a renderer that reports GPU tile-layer support (WebGL 2 / WebGPU — not Canvas),
+- `world.gpuTilemap !== false` (the `gpuTilemap` application setting, default `true`),
+- an **orthogonal** layer — isometric, hexagonal, staggered and oblique always
+  fall back,
+- no collection-of-image tileset, no non-zero `tileoffset`, and tile overflow
+  within the shader's 4-cell limit.
+
+When a layer falls back, melonJS `console.warn`s once with the reason. Practical
+consequences: fewer tilesets means fewer batches (one packed tileset beats
+several small ones), and on the Canvas fallback large maps get noticeably
+slower. `world.preRender` (or a `preRender` layer property in Tiled) opts an
+unanimated layer into the offscreen-bake path instead.
+
+## Symptom → cause
+
+| symptom | cause |
+|---|---|
+| a Tiled object becomes a plain shape with no behaviour | its class/name does not match any registered factory, or it was registered after `level.load` |
+| the world is still empty right after `level.load` | the load is deferred via `setTimeout` while the loop runs — use `onLoaded` / `LEVEL_LOADED` |
+| `level <id> not found` | the map was never preloaded, or the asset `name` differs from the id passed to `load` |
+| `unknown or invalid resource type` | asset `type` set to `"tmj"` / `"tsj"` — use `"tmx"` / `"tsx"` with the `.tmj` / `.tsj` file |
+| camera will not scroll | `setViewportBounds: false`, or the map was added with `addTo()` (which defaults to `false`) |
+| `No inflate function set` at parse time | compressed layers without the tiled-inflate plugin |
+| collision shapes are not solid | the object layer's name does not contain `"collision"`, or the objects are named |
+| isometric objects overlap wrongly | `world.sortOn` not set to `"y"` |
+| missing tiles or a blank map | the `.tsx` or tileset image was not preloaded |
+| tilemap slow on some machines | layer fell back off the shader path — check the console warning for the reason |
+
+## Related skills
+
+- `melonjs-physics` — what the collision shapes become once loaded
+- `melonjs-getting-started` — preloading and the asset type list