melonjs 20.7.0 → 20.9.0

package/skills/melonjs-renderables/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-renderables
-description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
+description: "Use this skill when subclassing Renderable, writing a custom draw() method, handling pointer or click events on game objects, applying post effects and shaders, or controlling draw order. Covers the pos-relative draw contract, isKinematic and input, addPostEffect vs the deprecated shader property, and z-ordering. Triggers on: Tween, easing, animate, Renderable, extends Renderable, draw(, update(, isKinematic, pointerEvent, registerPointerEvent, onClick, addPostEffect, removePostEffect, ShaderEffect, addChild, z-order, anchorPoint, floating."
 license: MIT
 ---
 
@@ -184,6 +184,11 @@ v.set(10, 20, v.z);   // keep it
 `pos` is an `ObservableVector3d`, whose `set(x = 0, y = 0, z = 0)` does the same
 — so `this.pos.set(x, y)` wipes the object's depth.
 
+`Renderable#setPosition(x, y, z?)` is the renderable-level form and does not:
+omit `z` and the depth is left exactly as it was. Reach for it whenever you
+are moving an object rather than editing a vector, and keep `v.set(x, y, v.z)`
+for the vector itself.
+
 ## 7. A settings key the class never reads is silently ignored
 
 A settings object is a plain literal: nothing rejects a key, so a name that
@@ -279,11 +284,12 @@ Hand-rolled equivalents miss the batching and the multi-backend support.
 | off-screen object never ticks | `update()` is gated on `inViewport` — set `alwaysUpdate = true` |
 | custom draw offset by half the size | centred `anchorPoint` default not zeroed |
 | spatial query never finds an object | `isKinematic` left `true` — not in the broadphase |
-| `z` unexpectedly 0 after a `set` | `Vector3d.set(x, y)` defaults `z` to 0 |
+| `z` unexpectedly 0 after a `set` | `Vector3d.set(x, y)` defaults `z` to 0 — `setPosition(x, y)` on the renderable leaves the depth alone |
 | a settings option appears to do nothing | the class never reads that key — see section 7 |
 | `isRenderable = false` did not hide the object | it gates bounds, not drawing — use `alpha` |
 
 ## Related skills
+- `melonjs-scenes-and-state` — `Tween` and the easing families, for animating any of this
 
 - `melonjs-getting-started` — Application lifecycle and the scene graph
 - `melonjs-20-migration` — the deprecated `shader` property and other pre-20 APIs

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

@@ -1,6 +1,6 @@
 ---
 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."
+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: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, 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
 ---
 
@@ -165,6 +165,18 @@ Returning nothing is falsy and the object can appear frozen while its state move
 `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()`.
 
+**Smooth a value toward a target with `math.damp`, not with `lerp` per
+frame.** `lerp(current, target, 0.1)` once per frame moves further on a slow
+frame than on a fast one, so the feel drifts with the frame rate:
+
+```js
+this.speed = math.damp(this.speed, targetSpeed, 5, dt / 1000);
+```
+
+`damp(current, target, lambda, dt)` takes SECONDS, so divide `dt`. Higher
+`lambda` converges faster. See `melonjs-camera-and-drawing` for the camera's
+own `follow()` damping, which is already frame-rate independent for you.
+
 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()`.
 
@@ -182,6 +194,17 @@ timer.clearInterval(id);        // in the Stage's onDestroyEvent
 `onActivateEvent` / `onDeactivateEvent` on a stage. Those two are `Renderable`
 hooks; put per-renderable teardown there instead.
 
+**The outgoing stage is destroyed before the incoming one is reset.** That
+ordering is what makes "each stage owns what it started" work: a scene can
+release a resource in `onDestroyEvent` and the next scene can claim the same
+one in `onResetEvent` without the teardown arriving late and undoing it.
+
+What a stage starts, it must end: `input.registerPointerEvent` regions,
+`event.on` subscriptions and running `Tween`s all outlive the stage that made
+them. Music is the exception rather than the rule, since `audio.playTrack()`
+stops the track it replaces, so `stopTrack()` in `onDestroyEvent` is only
+needed where the next screen has no music of its own.
+
 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
@@ -191,10 +214,63 @@ countdown that should not freeze needs. (That argument was ignored by
 
 ## Tweens
 
+### You are hand-rolling a tween if you write this
+
+The shape, in any of its spellings. If you are adding a field that counts
+milliseconds and dividing it by a constant to get a `0..1`, stop:
+
 ```js
-import { Tween, pool } from "melonjs";
+// ✗ a tween, written out longhand
+private flashMs = 0;
+// ... in update(dt)
+if (this.flashMs > 0) {
+    this.flashMs -= dt;
+    const k = this.flashMs / FLASH_MS;      // ← the 0..1
+    effect.setUniform("uIntensity", k * k); // ← and a curve, by hand
+}
+```
+
+```js
+// ✓ the same thing
+const driver = { k: 1 };
+new Tween(driver)
+    .to({ k: 0 }, { duration: FLASH_MS })
+    .easing(Tween.Easing.Quadratic.In)      // the curve, named
+    .onUpdate(() => effect.setUniform("uIntensity", driver.k))
+    .start();
+```
+
+The tells, any one of which is enough: a `*Ms` or `*Age` field that only
+`update()` touches; a division by a `*_MS` constant; `k * k`, `(1 - k) ** 2` or
+`** 1.4` written inline, which is an easing curve spelled by hand; an
+`if (x <= 0)` arm that exists only to clean up at the end, which is
+`onComplete`; a second timer counting the same duration to chain what happens
+next, which is `delay`.
+
+It matters beyond tidiness: a hand-rolled fade needs something to tick it, and
+an effect that is NOT a renderable (one living on the camera, say) has nothing
+that will. That forces an `update(dt)` method and a call site in the game loop
+whose only job is to drive the fade. A tween updates itself, so both disappear.
+
+### When NOT to reach for one
+
+Four shapes that look similar and are not tweens:
+
+| shape | what it is | use |
+| --- | --- | --- |
+| approaching a value that keeps MOVING | a follow, not an animation | `math.damp` |
+| a loop that never ends | oscillation | a sine of your own clock |
+| a gate: cooldown, spawn interval, invulnerability window | a timer, nothing is interpolated | a plain countdown |
+| the same effect on dozens of live objects | per-instance churn | a hand-rolled countdown really is cheaper |
 
-const t = pool.pull("Tween", sprite.pos)   // registered name is "Tween"
+The rule in one line: **fixed duration, known endpoint, one-shot, few
+instances.** All four, or it is not a tween.
+
+
+```js
+import { getPool, Tween } from "melonjs";
+
+const t = getPool("tween").get(sprite.pos) // typed pool, release when done
     .to({ x: 300 }, { duration: 500 })     // options object, not a number
     .easing(Tween.Easing.Quadratic.Out)
     .onComplete(() => { /* … */ })
@@ -216,6 +292,61 @@ Four traps:
 - **Stop a tween before destroying its target**, or `onUpdate` fires against a
   dead renderable.
 
+**To animate something that is not a property, tween a holder and push the
+value in `onUpdate`.** A shader uniform and a light's intensity are both set
+through a method, so there is nothing for `to()` to interpolate directly. The
+callback is invoked with the tweened object as `this` and the eased progress
+`0..1` as its argument:
+
+```js
+const fade = { level: 1 };
+getPool("tween").get(fade)
+    .to({ level: 0 }, { duration: 400 })
+    .easing(Tween.Easing.Quadratic.Out)
+    .onUpdate(function () {
+        effect.setUniform("uIntensity", this.level);
+        muzzleLight.intensity = this.level * 3;
+    })
+    .start();
+```
+
+Use a `function`, not an arrow, if you want `this` to be the tweened object;
+an arrow keeps the enclosing `this` and you read the holder by name instead.
+For a handful of pooled objects a hand-rolled countdown in `update()` is
+cheaper than a `Tween` each — this is the right tool for one-off effects, not
+for every particle.
+
+### Pick the easing, not just the duration
+
+Eleven families, each with `In`, `Out` and `InOut`. `Out` is what most UI
+wants: the value arrives decisively instead of creeping in. The two worth
+knowing by name beyond the power curves:
+
+| family | what it does |
+| --- | --- |
+| `Back` | **overshoots past the target and settles back**, which is impact: a stamp, a button press, anything that should LAND rather than arrive |
+| `Bounce` | lands and bounces, for something dropping onto a surface |
+
+```js
+// a stamp: scale falls to 1 and springs through it
+const driver = { scale: 5 };
+new Tween(driver)
+    .to({ scale: 1 }, { duration: 420 })
+    .easing(Tween.Easing.Back.Out)
+    .onUpdate(() => { label.currentTransform.identity(); label.scale(driver.scale); })
+    .onComplete(() => camera.shake(12, 400))     // the thump, when it truly lands
+    .start();
+```
+
+`Back` and `Elastic` **leave the range** between your start and end, so clamp
+anything that cannot take it, an opacity or a colour channel above all. The
+overshoot follows the direction of travel: a value tweened DOWN overshoots
+below its target.
+
+Reach for `onComplete` for anything that must happen on arrival, rather than a
+second timer counting the same duration. `delay` in the `to()` options chains
+the next one without a timer either.
+
 ## Guard teardown-adjacent callbacks
 
 Callbacks can fire while a stage is being torn down, when the current state is

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

@@ -103,7 +103,7 @@ Packing into one atlas keeps everything on a single binding.
 ## Visual properties
 
 ```js
-sprite.tint.setColor(255, 128, 0);   // multiply tint
+sprite.setTint("#ff8000");   // multiply tint
 sprite.alpha = 0.5;
 sprite.flipX(true);                   // mirror horizontally
 sprite.flipY(true);
@@ -141,9 +141,14 @@ The insets default to a quarter of the frame.
 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
+import { createPool } from "melonjs";
+
+const bulletPool = createPool((x, y) => {    // me.pool is deprecated
+    const instance = new Bullet(x, y);
+    return { instance, reset: (x, y) => instance.onResetEvent(x, y) };
+});
+const b = bulletPool.get(x, y);             // new Bullet(x, y), or reset(x, y) on a reused one
+world.removeChild(b);                       // returns it to bulletPool automatically
 ```
 
 Two consequences:

package/skills/melonjs-tilemaps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax."
+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 registerTiledObjectClass and 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, level.load async, await level.load, tileset, ImageLayer, isometric, hexagonal, staggered, pool.register, Collectable, Trigger, object layer, collision layer, parallax, registerTiledObjectClass, registerTiledObjectFactory."
 license: MIT
 ---
 
@@ -38,6 +38,10 @@ also skip `src` and pass the map inline via `data` (with `format: "json"` or
 `level <id> not found` for an unknown id — synchronously, in both forms, because
 that is a typo rather than a load failure.
 
+Those `game.` defaults are the engine's own, and `game` is whichever
+`Application` finished `init()` last. **Pass `container` explicitly** from a
+`Stage`, which has the right one: `level.load("map", { container: this.app.world })`.
+
 **`level.load` is deferred while the game loop is running.** It calls
 `state.stop()` and finishes the load on a timer, after the current frame, so by
 default it returns `true` before anything is in the world. Two ways to sequence
@@ -72,19 +76,30 @@ Tiled **class**, then its **name**, then the structural fallbacks `"text"`,
 `"tile"` and `"shape"`.
 
 ```js
-pool.register("mainPlayer", PlayerEntity);   // ← matches Tiled class OR name
+import { registerTiledObjectClass, registerTiledObjectFactory } from "melonjs";
+
+registerTiledObjectClass("Enemy", Enemy);   // ← matches Tiled class OR name
+registerTiledObjectFactory("Spine", (settings, map) => { /* → Renderable */ });
 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:
+These are the entry points to use. The registry is Tiled's own, held by the
+object factory, and has nothing to do with object pooling.
 
-```js
-import { registerTiledObjectClass, registerTiledObjectFactory } from "melonjs";
+`pool.register(className, classObj)` **also** works and registers a Tiled
+factory as a side effect, under the name and again under an `me.`-prefixed
+alias, unless you set `pool.autoRegisterTiled = false`. That is the older
+spelling, kept working for maps and games written against it, and it now
+prints a one-off deprecation notice: `me.pool` is deprecated since 18.0.0.
 
-registerTiledObjectClass("Enemy", Enemy);            // new Enemy(x, y, settings)
-registerTiledObjectFactory("Spine", (settings, map) => { /* → Renderable */ });
+Its third argument no longer buys anything here. It used to make Tiled
+objects recyclable; they are constructed directly now, and the container
+returns children to typed pools rather than to the name-keyed one. To pool a
+class you spawn constantly, give it a `createPool` and register it for Tiled
+separately:
+
+```js
+registerTiledObjectClass("mainPlayer", PlayerEntity);
 ```
 
 Register **before** loading. With no match the object falls through to the
@@ -94,11 +109,24 @@ 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"`.
+one to use for replacing something already registered.
+
+**Overriding a built-in name always works.** The engine's own classes are
+DEFAULTS: they fill a name nothing else has claimed, and yours takes it over
+whenever you register, before or after a map has loaded.
+
+```js
+registerTiledObjectClass("Trigger", MyTrigger);   // whenever you like
+```
+
+The throw is for a clash between two of *your* classes under one name. For
+that case `registerTiledObjectFactory` overwrites and only warns.
 
 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.
+`BitmapText`, `ImageLayer`, `ColorLayer`, `Light2d`, `Collectable`, `Trigger`
+and `Entity` as Tiled classes, so `Collectable` and `Trigger` work out of the
+box. Each is registered under its `me.`-prefixed alias as well, so a map
+authored against melonJS 1.x finds them where it looks.
 
 A `Trigger` forwards a **fixed list** of settings to `level.load()` — not
 whatever you pass it. Today that list is `container`, `onLoaded`, `flatten`,