melonjs 20.8.0 → 20.10.0

package/skills/melonjs-math/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: melonjs-math
+description: "Use this skill for vector and matrix maths in melonJS — Vector2d, Vector3d, their observable variants, Matrix2d, Matrix3d, and the math utility functions. Covers which methods mutate and which allocate, the vector pool and when clone() is the wrong tool, interpolation with lerp, slerp, damp and moveTowards, and the argument defaults that silently drop a component. Triggers on: Vector2d, Vector3d, ObservableVector2d, ObservableVector3d, Matrix2d, Matrix3d, vector, vector maths, dot, cross, normalize, length, distance, angle, lerp, slerp, damp, moveTowards, project, clamp, degToRad, radToDeg, clone, vector pool, vector3dPool, setMuted, setCallback, my vector is wrong, z is zero, scale ignores z., moveTowards ignores z, projectN, currentTransform, setTransform, matrix, transform matrix, column-major, val, Float32Array, basis matrix, orientation matrix."
+license: MIT
+---
+
+# Vectors, matrices and maths
+
+## The one rule that explains most surprises
+
+**Methods mutate `this` and return it. They do not return a new vector.**
+
+```js
+const a = new Vector3d(1, 0, 0);
+const b = new Vector3d(0, 1, 0);
+
+a.cross(b);        // a IS NOW the cross product; the original a is gone
+a.add(b).normalize().scale(3, 3, 3);   // chains, all in place
+```
+
+That is what makes the API allocation-free, and it is the opposite of what a
+functional style expects. If you need to keep the original, copy into
+something you own first:
+
+```js
+out.copy(a).cross(b);    // a untouched, nothing allocated
+```
+
+**The exceptions are named.** A handful of methods return a NEW vector, and
+each has a `*Self` sibling that does not:
+
+| allocates a new vector | mutates in place |
+|---|---|
+| `negate()` | `negateSelf()` |
+| `floor()` | `floorSelf()` |
+| `ceil()` | `ceilSelf()` |
+| `clamp(low, high)` | `clampSelf(low, high)` |
+| `clone()` | `copy(v)` |
+
+So `v.negate()` in a per-frame loop allocates every frame and `v.negateSelf()`
+does not. The names are the only clue; nothing in the call site shows it.
+
+## `clone()` comes from a pool, and only pays off if you give it back
+
+`clone()` is `vector3dPool.get(...)`. A pool is fast when instances come back:
+`get()` takes a free one and resets it. Nothing comes back on its own, so a
+clone that is simply dropped makes `get()` miss, construct, and write two
+registry entries.
+
+Measured, 3M operations:
+
+| | |
+|---|---|
+| `out.copy(a).cross(b)` | 39ms |
+| `new Vector3d(ax, ay, az).cross(b)` | 37ms |
+| `a.clone().cross(b)` | **2919ms** |
+
+So:
+
+- **Transient value inside a function?** Use a module-level scratch vector, or
+  `new Vector3d()`. Not `clone()`.
+- **Keeping it, then done with it?** `clone()` and `vector3dPool.release(v)`
+  when finished. Releasing is what makes the pool a pool.
+- **Writing a helper that returns a vector?** Take an optional `out`:
+
+```js
+const cross = (a, b, out = new Vector3d()) => out.copy(a).cross(b);
+```
+
+That is the engine's own convention, and it lets a hot caller supply scratch
+while a casual one ignores it.
+
+**A returned value can never be shared scratch.** The next call overwrites
+something the caller is still holding, and nothing fails loudly:
+
+```js
+const _t = new Vector3d();
+const bad = (v) => _t.copy(v).normalize();   // WRONG: two calls alias
+```
+
+## Argument defaults that drop a component
+
+Three signatures quietly discard what you did not pass. All three are
+reachable by writing the obvious thing.
+
+**`scale(x, y = x, z = 1)`** — `z` defaults to **1**, not to `x`. A uniform
+scale has to say so three times:
+
+```js
+v.scale(2);          // (1,2,3) -> (2,4,3)   z UNTOUCHED
+v.scale(2, 2, 2);    // (1,2,3) -> (2,4,6)   what you meant
+```
+
+**`set(x, y, z = 0)`** — setting two components **zeroes the third**:
+
+```js
+v.set(10, 20);       // z is now 0, whatever it was
+```
+
+**`Vector3d.pos` on a renderable is typed `Vector2d`.** `Renderable.pos` is an
+`ObservableVector3d` at run time but is declared through `Polygon` as a
+`Vector2d`, so `.z`, `.setMuted` and `.setCallback` need a cast from
+TypeScript. See issue #1510.
+
+## `cross` is two different functions
+
+```js
+v3.cross(other);   // Vector3d: MUTATES v3, returns this
+v2.cross(other);   // Vector2d: returns a NUMBER, mutates nothing
+```
+
+The 2D one is the z component of the 3D cross, which is the useful scalar for
+"which side is this on". Same name, different shape, different return.
+
+## Interpolation: four of them, and they are not interchangeable
+
+```js
+a.lerp(b, t);            // straight line, t in 0..1
+a.slerp(b, t);           // along the ARC, constant angular rate
+a.damp(b, lambda, dt);   // frame-rate independent ease toward b
+a.moveTowards(b, step);  // fixed distance per call, never overshoots
+```
+
+**`moveTowards` is X/Y ONLY, on `Vector3d` as well as `Vector2d`.** It is the
+one of the four that is not 3D: it measures the distance from `dx` and `dy`,
+steps along `atan2(dy, dx)`, and leaves `z` exactly where it was. The source
+says so in a comment and the JSDoc says "on the x and y axis", but the name
+gives no hint, and in a list like the one above it reads as the sibling of the
+other three. Anything moving in three dimensions wants `damp` or an explicit
+step; reach for `moveTowards` only when the motion really is planar.
+
+**`lerp` between two directions is uneven**: it slows at the ends, runs fast
+through the middle, and shortens the vector as it passes halfway. Anything
+whose direction matters more than its components wants `slerp` — a camera
+swinging to look somewhere, a turret tracking, a body moving over a sphere.
+`slerp` carries length linearly, so two unit vectors give a unit vector and
+nothing needs normalising afterwards.
+
+**`damp` is the one to use for "ease toward a target every frame"**, because
+`lerp(current, target, 0.1)` per frame is frame-rate dependent: it converges
+twice as fast at 120fps as at 60.
+
+## `project` scales THIS, and `projectN` is the one without the divide
+
+`a.project(b)` does not return the component of `a` along `b`. It scales **a**
+by `a.b / |b|^2` and returns `a`, so the result points along `a`, not along
+`b`. Worth knowing before you reach for it expecting the textbook projection.
+
+`projectN(v)` is the same thing for a `v` that is already unit, so it skips
+the `/ v.length2()`:
+
+```js
+a.project(b);   // a scaled by (a.b / |b|^2)
+a.projectN(b);  // a scaled by (a.b)      -- only correct when |b| = 1
+```
+
+Handing `projectN` a target that is NOT unit does not normalise anything, it
+just scales by the raw dot product. That is the price of it being cheaper, and
+it is the caller's job to meet the contract.
+
+Until 20.9 both 3D classes got this wrong: `Vector3d.projectN` and
+`ObservableVector3d.projectN` were copies of `project`, division and all,
+under `projectN`'s name and its "slightly more efficient" doc comment. Nothing
+in the engine called either one and nothing tested them, which is how it
+survived. Both are fixed and all four classes are now pinned by tests.
+
+## `length()` is `sqrt(x*x + y*y + z*z)`
+
+Fast and correct to 1 ULP for anything a game holds. It is NOT robust at
+extremes: components above ~1e154 overflow to `Infinity` and below ~1e-162
+underflow to `0`, because the squares are formed before the root. `Math.hypot`
+avoids that and costs 35 to 65% more. The engine takes the speed, which is the
+right trade for coordinates between 1e-3 and 1e6; nothing in a game is 148
+orders of magnitude from unit scale.
+
+`length2()` skips the square root. Use it for comparisons:
+
+```js
+if (a.distance(b) < r) { }            // a square root you did not need
+if (a.sub(b).length2() < r * r) { }   // same answer, cheaper
+```
+
+## Observable vectors
+
+`ObservableVector2d` / `ObservableVector3d` call a callback on every write,
+which is how a renderable knows its bounds went stale.
+
+```js
+v.setCallback(() => { ... });
+v.setMuted(true);     // write without firing it
+```
+
+**`setMuted` is what you want when writing several components**, so a
+half-updated vector does not fire a callback that reads the other half.
+`set()` already does this internally: it disables the callback, writes all
+three, fires once, and re-enables.
+
+Note the observable `set(x = 0, y = 0, z = 0)` defaults EVERY argument, so
+`set(10, 20)` zeroes z exactly as the plain vector does.
+
+## Matrices
+
+`Matrix2d` is 3x3 for 2D affine transforms; `Matrix3d` is 4x4. Both mutate and
+chain, same as vectors, and both come from pools.
+
+```js
+m.identity().translate(x, y).rotate(angle).scale(sx, sy);
+```
+
+**Order is the reverse of how it reads.** These post-multiply, so the call
+made LAST reaches the vertex FIRST. To rotate a thing about its own centre,
+translate to the centre last.
+
+### Every renderable already HAS one
+
+`Renderable.currentTransform` is a `Matrix3d`. If you are orienting something
+on screen, the matrix exists: write into it rather than building a parallel
+structure and copying.
+
+```js
+// the whole transform of a renderable, written in place
+mesh.currentTransform.identity().translate(x, y, z).rotate(angle, axis);
+```
+
+### The sixteen numbers are `val`, column-major
+
+Composing with `translate`/`rotate`/`scale` is one way to fill a matrix. The
+other is to write the numbers, which is what you want when the orientation
+comes from a basis you have already computed — three orthonormal vectors, a
+surface frame, a camera basis.
+
+`val` is a `Float32Array(16)` in **column-major** order, the OpenGL
+convention: each basis vector occupies a stride-4 run, and the translation is
+the last column.
+
+| | X column | Y column | Z column | translation |
+|---|---|---|---|---|
+| indices | `0,1,2` | `4,5,6` | `8,9,10` | `12,13,14` |
+
+```js
+// an orientation from three axes, straight into the renderable's own matrix
+const m = mesh.currentTransform.val;
+m[0] = right.x;   m[1] = right.y;   m[2] = right.z;   m[3] = 0;
+m[4] = up.x;      m[5] = up.y;      m[6] = up.z;      m[7] = 0;
+m[8] = fwd.x;     m[9] = fwd.y;     m[10] = fwd.z;    m[11] = 0;
+m[12] = 0;        m[13] = 0;        m[14] = 0;        m[15] = 1;
+```
+
+A helper that builds one should take the destination, the same way the engine
+takes an `out`, so it writes once into the matrix that will be used:
+
+```js
+const orient = (frame, out) => { /* writes out.val */ return out; };
+orient(frame, mesh.currentTransform);
+```
+
+### Getting numbers IN from somewhere else
+
+`setTransform(...)` takes the sixteen as arguments, and `copy(m)` takes
+another matrix:
+
+```js
+m.setTransform(a, b, c, d, e, f, g, h, i, j, k, l, p, q, r, s);
+m.copy(other);                 // Float32Array.set under the hood
+```
+
+Both are fine occasionally. In a per-frame loop, prefer writing `val` or
+`copy()` over spreading sixteen arguments, and note that **one matrix built
+once and applied to many renderables** is a `copy()` per renderable, not a
+rebuild per renderable.
+
+**`val` is `Float32Array`, so it holds float32.** Numbers you put in are
+rounded to single precision. That is where they were always heading, since
+this is what reaches the GPU, but it means a value read back out is not
+bit-identical to the double you wrote.
+
+## Utilities
+
+```js
+import { math } from "melonjs";
+
+math.clamp(v, lo, hi);
+math.lerp(a, b, t);              // scalars
+math.damp(a, b, lambda, dt);     // frame-rate independent
+math.degToRad(deg);  math.radToDeg(rad);
+math.random(lo, hi);             // integer
+math.randomFloat(lo, hi);
+math.weightedRandom(lo, hi);     // integer, biased toward LO
+math.round(n, decimals);
+math.pow(n);                     // n squared
+math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
+```
+
+## Symptoms
+
+| symptom | cause |
+|---|---|
+| z unchanged after scaling | `scale(s)` leaves z alone; pass `scale(s, s, s)` |
+| z became 0 for no reason | `set(x, y)` defaults z to 0 |
+| the original vector changed | the method mutates; `copy()` into something first |
+| memory climbs in a loop | `clone()` or `negate()`/`floor()`/`ceil()` per frame |
+| two helper results are the same object | a shared scratch vector was returned |
+| `.z` is a type error | `Renderable.pos` is declared `Vector2d` (#1510) |
+| rotation eases oddly between directions | `lerp` on directions; use `slerp` |
+| you built your own 16-number array | `Renderable.currentTransform` is already a `Matrix3d`; write its `val` |
+| a value read back from a matrix differs | `val` is `Float32Array`; it holds float32 |
+| easing differs at 120fps | per-frame `lerp`; use `damp` |
+
+## Related skills
+
+- `melonjs-3d` — `Camera3d`, meshes, and where these vectors are used in 3D
+- `melonjs-physics` — bodies, velocities and collision response
+- `melonjs-performance` — pooling in general, and what release() is for

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

@@ -1,6 +1,6 @@
 ---
 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, 3D particle motion through elevation and minSpread/maxSpread in 20.8, 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, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter."
+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, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter."
 license: MIT
 ---
 
@@ -28,6 +28,47 @@ emitter.burstParticles();      // one shot
 `duration` setting, which defaults to `Infinity` — a stream runs until
 `stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
 
+## Sprite-sheet particles
+
+Use `framewidth` and `frameheight` (the same names as on `Sprite`) to divide
+`image` into a regular grid. Each omitted dimension defaults to that of the
+image. Frames are numbered from zero left-to-right, then top-to-bottom; only
+whole cells count, so partial cells along the right/bottom edges are ignored.
+Margins and spacing are not supported.
+
+```js
+const explosion = new ParticleEmitter(x, y, {
+    image: loader.getImage("explosion-sheet"),
+    framewidth: 32, frameheight: 32,
+    frames: [0, 1, 2, 3],
+    minLife: 400, maxLife: 800,
+});
+world.addChild(explosion);
+explosion.burstParticles();
+```
+
+Omit `frames` to use every cell. Each particle traverses the sequence once
+over its own lifetime, with equal time for each entry; repeated indices hold
+a frame longer. Existing scale, opacity and rotation still apply. Bounds and
+the rotation pivot use one frame's dimensions, rather than the whole sheet.
+
+Set `randomFrame: true` for debris: a particle chooses one entry at birth and
+keeps it until it dies. Different frames share the same image and GPU batch.
+Without sheet settings, particles still draw the whole image as before, and
+that includes `randomFrame` on its own: it needs a grid to choose from, so
+pair it with `framewidth`/`frameheight` or it does nothing.
+
+Note the variety is in SHAPE, not colour. `tint` belongs to the emitter, so
+every particle from one emitter is tinted alike however many frames it picks
+between.
+
+Frame dimensions must be positive integers that fit inside the image, and an
+explicit `frames` sequence must be nonempty and contain valid integer indices.
+Invalid configurations throw `RangeError` before changing an emitter during
+`reset()`. The frame sequence is copied on construction/reset; resetting changes
+only future particles, so ones already alive finish with their original image,
+frame size and sequence.
+
 ## Where particles are born
 
 `width` and `height` are the spawn AREA, and both default to `1` — so by
@@ -184,19 +225,48 @@ Omit `target` and feed it yourself with `trail.addPoint(x, y)` — the mode for
 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:
+**`Trail` is 2D. Use `Trail3d` in a 3D scene** (20.9.0 and later). `Trail`
+stores points without a `z` and draws connected screen-space quads, which carry
+one depth for the whole renderable, so under a `Camera3d` the ribbon stays flat
+and does not narrow along its own length.
+
+```js
+const exhaust = new Trail3d(0, 0, {
+    target: ship,                 // samples pos.x / pos.y / pos.z
+    width: 6,                     // world units, and free to change per frame
+    lifetime: 260,
+    gradient: ["#eaffff", "#2ea8ff", "#2ea8ff00"],
+});
+exhaust.blendMode = "additive";
+app.world.addChild(exhaust);      // no z: it derives its own from its points
+```
 
-- **`ParticleEmitter` with `referenceSpace: "world"`** — particles stay where
-  they were dropped while the emitter moves on, and each one sits at the
-  emitter's depth slice so `Camera3d` projects it correctly. Add an `elevation`
-  and they recede as well. 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.
+`Trail3d` is a `Mesh`, which is most of the difference:
+
+- `billboard` is spelled and valued exactly as on `Sprite3d` —
+  `"spherical"` (the default here) faces the camera on all axes,
+  `true` / `"cylindrical"` faces it but stays upright, `false` uses the
+  `ribbonNormal` you give it. `billboard: false, ribbonNormal: [0, -1, 0]`
+  lays the ribbon in the ground plane for a tyre mark or a wake.
+- **`tint` works**, and is the per-frame colour lever. On `Trail` it does
+  nothing at all, because the primitive batcher reads the draw colour and never
+  the tint. `setColor()` / `setGradient()` rebuild the gradient for a change of
+  state; they allocate, so they are not per-frame.
+
+  **If the colour is going to change, author the gradient WHITE.** `tint`
+  multiplies, so tinting a cyan ribbon red gives muddy brown rather than red. A
+  neutral gradient hands the hue entirely to the tint, which is what lets one
+  lever take a trail from white through to red as something overheats.
+- A post effect reaches it properly, where `Trail` has to force a screen
+  capture.
+- It is **cheaper**: one indexed draw call, against one filled path per segment.
+- `length` is fixed at construction, because the geometry is sized once.
+  Assigning `maxPoints` throws rather than silently truncating the ribbon, and
+  a `length` that is not a finite number throws at construction.
+- It needs a `Camera3d`. Under a 2D camera it draws nothing and warns once.
+
+A world-space `ParticleEmitter` (`referenceSpace: "world"`) is still the right
+answer when you want discrete puffs rather than a continuous ribbon.
 
 ## Performance
 
@@ -219,7 +289,11 @@ tool for a trail behind an object moving *into* the scene. For that:
 
 | symptom | cause |
 |---|---|
-| trail looks flat under a `Camera3d` | `Trail` is 2D — use a world-space emitter or a ribbon mesh |
+| trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
+| `Trail3d` draws nothing, with a console warning | it needs a `Camera3d`; the app's `cameraClass` is still the 2D default |
+| `trail.tint` does nothing | `Trail` cannot be tinted at all; `Trail3d` can |
+| assigning `maxPoints` throws | `Trail3d` sizes its geometry once; pass `length` to the constructor |
+| `Trail3d: \`length\` must be a finite number` | a computed `length` came out `NaN`; it is refused rather than silently rendering nothing |
 | 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 |

package/skills/melonjs-performance/SKILL.md

@@ -59,16 +59,28 @@ 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
+import { createPool } from "melonjs";
+
+const bulletPool = createPool((x, y) => {
+    const instance = new Bullet(x, y);
+    return { instance, reset: (x, y) => instance.onResetEvent(x, y) };
+});
+
+const b = bulletPool.get(x, y);   // recycled: reset(x, y)
+                                  // fresh:    new Bullet(x, y)
+world.removeChild(b);             // returns to bulletPool 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.
+The container returns a child to whichever pool built it, so removal is enough;
+you only call `release()` yourself for something that was never added to the
+world.
+
+**`me.pool` is the older, string-keyed version and is deprecated since
+18.0.0.** `pool.register(name, Class, true)` / `pool.pull(name)` still work and
+print a one-off console notice, but a recycled object is no longer returned on
+removal, so pooling through it now costs an allocation per spawn. To register a
+class so a Tiled map can name it, use `registerTiledObjectClass` — that is a
+separate registry and is not deprecated.
 
 Two rules that cause subtle bugs when missed:
 
@@ -76,10 +88,11 @@ Two rules that cause subtle bugs when missed:
   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.
+  calls `onDeactivateEvent`, then tries to return the object to the pool that
+  built it; only when nothing owns it 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.
 
 - **`removeChild` is DEFERRED, which breaks a pool you re-lend in the same
   frame.** The removal is queued and runs after the update and draw stack has
@@ -98,14 +111,32 @@ Two rules that cause subtle bugs when missed:
   usual cause of a pooled effect that flickers out one frame after it is
   recycled.
 
-Engine classes are poolable too: `pool.pull("Tween", target)`. The canonical
-names are unprefixed — `Entity`, `Collectable`, `Trigger`, `Light2d`,
-`Particle`, `Sprite`, `NineSliceSprite`, `Renderable`, `Text`, `BitmapText`,
-`ImageLayer`, `Tween`, `ColorLayer`.
+**The engine's own classes are NOT in this pool.** They were registered in it
+once, which bought nothing: most had recycling off, so `pool.pull("Sprite")`
+was a plain construction behind a string key. The ones worth recycling have
+typed pools instead, reached by key and fully typed:
+
+```js
+const tween = getPool("tween").get(target);
+const label = getPool("text").get(x, y, { font: "Arial", size: 12 });
+getPool("text").release(label);          // yours to release, as with particles
+```
 
-`pool.register` additionally aliases every name under an `me.` prefix, pointing
-at the same entry, so `pool.pull("me.Tween")` resolves identically — and the
-same alias is registered with the Tiled object factory, which is why a map
+A recycled label comes back with its **base-class** state reset as well as its
+own: `floating`, `blendMode`, `alpha`, `tint`, the transform, the anchor, the
+behaviour flags, any mask and any post effect, and `depth` back to 0. The
+settings object names none of those, so set them again after `get()`. A pooled
+HUD number that is not re-marked `floating` is drawn through the camera, i.e.
+somewhere out in the world rather than on the screen, and `addChild(label, z)`
+is what gives it its depth back.
+
+`getPool` covers `vector2d`, `vector3d`, `point`, `matrix2d`, `matrix3d`,
+`bounds`, `color`, `polygon`, `line`, `rectangle`, `roundedRectangle`,
+`ellipse`, `tween`, `particle`, `text`, `colorLayer` and `bitmapTextData`.
+
+`pool.register` still aliases every name you give it under an `me.` prefix,
+pointing at the same entry, so `pool.pull("me.Bullet")` resolves identically —
+and the same alias reaches the Tiled object factory, which is why a map
 authored against melonJS 1.x still finds its classes. Prefer the unprefixed
 name in new code; do not "correct" an `me.`-prefixed one, it is not broken.
 
@@ -214,9 +245,12 @@ Since 20.6 the engine's own programs are built during `preload()` instead —
 `loader.preload()` calls `renderer.prewarm()` itself, on every call, when the
 application's `prewarm` setting is on, which is the default. So on a current
 version this is one cause you can rule out before looking further, **unless the
-game does not use the preloader at all**, which is the one way to miss it — see `melonjs-loading-assets`. It does not
-cover effects you construct inline, and it does not cover the rest of what a
-first frame pays for, below.
+game does not use the preloader at all**, which is the one way to miss it — see `melonjs-loading-assets`. Since 20.10 the
+pipelines that depend on the renderable (effects, blend modes, render targets)
+are warmed when an effect is attached or a renderable is added to the world, as
+long as that happens at least a frame before it is drawn: a pool built at stage
+start is covered, an object created and drawn in the same frame is not. None of
+this covers the rest of what a first frame pays for, below.
 
 How to tell them apart, all from the page:
 
@@ -333,6 +367,7 @@ In rough order for a typical 2D game:
 | memory grows with long music | missing `stream: true` |
 | slow only on some machines | Canvas fallback — no GPU tilemap path |
 | a freeze the first time a level shows, never again | shader variants linking on first draw — warm them behind the loading screen |
+| a freeze the first time an effect appears mid-play (a shield, a hit flash) | the effect attached in the same frame it is drawn — attach it when the pool is built, so the warm-up has a frame to finish |
 | the same scene stutters once per entry | a derived texture rebuilt per stage: the texture cache keys on the image object, so each rebuild is a new upload |
 
 ## Related skills

package/skills/melonjs-physics/SKILL.md

@@ -500,7 +500,8 @@ onCollisionStart(response, other) {
 What actually happens per adapter:
 
 - **built-in** — callbacks fire inline during `step()`. `Container.removeChild`
-  is deferred, so it is safe; `removeChildNow()` and `destroy()` are immediate,
+  is deferred, so it is safe; `removeChildNow()`, and the internal `destroy()`
+  it calls, are immediate,
   and the detector only survives them because it re-checks `body === undefined`
   after every user callback.
 - **planck** — `onCollisionStart` / `onCollisionEnd` are dispatched from

package/skills/melonjs-renderables/SKILL.md

@@ -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,7 +284,7 @@ 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` |
 

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

@@ -194,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
@@ -257,9 +268,9 @@ instances.** All four, or it is not a tween.
 
 
 ```js
-import { Tween, pool } from "melonjs";
+import { getPool, Tween } from "melonjs";
 
-const t = pool.pull("Tween", sprite.pos)   // registered name is "Tween"
+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(() => { /* … */ })
@@ -289,7 +300,7 @@ callback is invoked with the tweened object as `this` and the eased progress
 
 ```js
 const fade = { level: 1 };
-pool.pull("Tween", fade)
+getPool("tween").get(fade)
     .to({ level: 0 }, { duration: 400 })
     .easing(Tween.Easing.Quadratic.Out)
     .onUpdate(function () {

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: