melonjs 20.6.0 → 20.8.0

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

@@ -39,7 +39,7 @@ 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 |
+| `"json"` | data, texture-atlas descriptors, collision shapes from a shape editor |
 | `"tmx"` / `"tsx"` | Tiled maps and external tilesets |
 | `"audio"` | sound — **`src` is a directory**, see below |
 | `"video"` | video textures |

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, 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."
+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."
 license: MIT
 ---
 
@@ -28,6 +28,101 @@ emitter.burstParticles();      // one shot
 `duration` setting, which defaults to `Infinity` — a stream runs until
 `stopStream()`. `burstParticles(n)` launches `n`, or `totalParticles`.
 
+## Where particles are born
+
+`width` and `height` are the spawn AREA, and both default to `1` — so by
+default every particle launches from the same pixel. That is fine for a
+fountain and wrong for an explosion: additive sprites piled on one point clip
+all three channels there however well they are tinted, so a burst reads as one
+bright flash rather than as debris.
+
+Give it the size of whatever broke. The area is measured from the emitter's own
+position, NOT centred on it, so offset by half or the whole burst sits down and
+to the right of its source:
+
+```js
+const area = radius * 2;
+const emitter = new ParticleEmitter(x - area / 2, y - area / 2, {
+    width: area, height: area,
+});
+```
+
+## Particles in 3D
+
+By default a particle keeps the depth it was born at for its whole life: it
+moves across the emitter's plane and never toward or away from the camera.
+Under a `Camera3d` that reads as a flat sticker anywhere but dead ahead.
+
+`elevation` lifts the launch out of that plane and `elevationVariation` spreads
+it. `angle` is the azimuth within the plane, as it always was:
+
+```js
+const emitter = new ParticleEmitter(x, y, {
+    angle: 0, angleVariation: Math.PI * 2,
+    elevation: 0, elevationVariation: Math.PI / 2,   // a sphere of debris
+    speed: 9,
+});
+world.addChild(emitter, z);     // the depth slice the burst belongs to
+emitter.burstParticles();
+```
+
+`speed` is the length of the whole 3D vector, so an "all directions" burst
+covers the sphere evenly instead of bunching toward the poles.
+
+Both default to `0`, and that is a gate rather than the 3D path with zeros in
+it: an emitter that asks for no elevation runs the same two trig calls it
+always did, writes no depth and starts no sort.
+
+**The launch is in WORLD axes.** `vel.x` and `vel.y` add to the particle's
+`pos.x`/`pos.y` and `velZ` adds to its depth, so `angle` and `elevation`
+describe a direction in the world, not on the screen. Building them from a
+camera basis works only while the camera's axes ARE the world axes, which stops
+being true the moment you pose a `Camera3d`. For a direction `d` already in
+world terms the pair is `angle: Math.atan2(-d.y, d.x)`,
+`elevation: Math.asin(d.z)`.
+
+### Cones, rings and spheres: aiming around an axis
+
+`angleVariation` and `elevationVariation` are sampled INDEPENDENTLY, spreading
+particles over a rectangle of azimuth by elevation. That cannot describe a
+shape defined against a direction. A ring of debris leaving a point on a sphere
+is the set of directions at ninety degrees to that point's normal, and on a
+rectangle the elevation that satisfies it is a function of the azimuth, so no
+pair of variations gets there.
+
+Set `maxSpread` and `angle`/`elevation` become an AXIS instead. Each particle
+leaves at a polar angle between `minSpread` and `maxSpread` off that axis,
+around a uniformly random azimuth:
+
+| `minSpread` … `maxSpread` | shape |
+|---|---|
+| `0` … `0.5` | a tight cone along the axis |
+| `0` … `Math.PI` | the whole sphere |
+| either value at `Math.PI / 2` | a flat disc perpendicular to the axis |
+
+An explosion on a planet's surface is a ring tangent to it: set the axis to the
+surface normal and use `minSpread: Math.PI / 2 - 0.3, maxSpread: Math.PI / 2`.
+Keeping the band at or inside ninety degrees is what stops debris tilting back
+into the body it came off. `angleVariation` and `elevationVariation` are unused
+while `maxSpread` is set.
+
+### Sorting, and why it is keyed off the blend mode
+
+A 3D burst only needs depth sorting when its blend is order dependent, and the
+emitter decides that for you. Additive blending is commutative, so an additive
+burst looks the same however it is ordered and pays nothing; `"normal"` is not,
+so a 3D burst drawn with it is sorted back to front.
+
+The two differ in more than cost. Additive sprites overlapping near the centre
+of a burst sum to white however they are tinted, so debris that has to keep its
+colour wants `textureAdditive: false` and accepts the sort. A common shape is
+two emitters: a solid, sorted body of debris with a sparser additive spray of
+sparks over it.
+
+The default particle sprite is a filled SQUARE, which additive blending hides
+and normal blending does not. Pass your own soft `image` for non-additive
+debris.
+
 For one-shot effects, `autoDestroyOnComplete: true` removes the emitter once its
 particles have finished. The `onComplete` callback fires at that same moment
 either way.
@@ -95,9 +190,10 @@ 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.
+  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.
@@ -129,6 +225,12 @@ tool for a trail behind an object moving *into* the scene. For that:
 | 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 |
+| a 3D burst is invisible under a `Camera3d` | before 20.8 a particle was culled at twice its depth; update |
+| the whole burst launches from one pixel | `width`/`height` are the spawn area and default to `1` |
+| the burst sits down-right of its source | the spawn area starts at the emitter's position; offset by half |
+| the middle of a burst goes white | additive sprites overlapping — `textureAdditive: false`, or spread them |
+| debris chunks look like squares | the default sprite is a filled square; pass your own `image` |
+| a ring tilts with the camera instead of staying on a surface | the launch axis is in WORLD axes, not the camera basis |
 
 ## Related skills
 

package/skills/melonjs-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, render targets, hdr."
 license: MIT
 ---
 
@@ -81,6 +81,23 @@ Two rules that cause subtle bugs when missed:
   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
+  unwound, so an object you remove and immediately hand out again is torn out
+  from under its new owner when the queue drains: it vanishes, and the frame
+  after that the removal throws `Child is not mine.` Take it out immediately
+  instead, keeping the instance alive for reuse:
+
+  ```js
+  world.removeChildNow(bullet, true);   // keepalive: do NOT destroy it
+  this.freeList.push(bullet);
+  ```
+
+  `removeChildNow(child, keepalive)` with `keepalive` true skips the destroy,
+  which is what you want for anything you own the lifetime of. This is the
+  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`,
@@ -95,13 +112,34 @@ name in new code; do not "correct" an `me.`-prefixed one, it is not broken.
 ## `scale()` is multiplicative
 
 A pooled sprite arrives carrying its previous life's transform, and calling
-`scale()` each frame compounds. For absolute scaling:
+`scale()` each frame compounds. `rotate()` is the same. For absolute values,
+reset first:
 
 ```js
 sprite.currentTransform.identity();
 sprite.currentTransform.scale(s, s, 1);
 ```
 
+**Order matters, and it is the opposite of what reads naturally.**
+`Matrix2d.scale` multiplies the matrix ROWS, so it applies AFTER whatever the
+matrix already holds. Scale first and then rotate; rotate first and the scale
+lands in the rotated frame and SHEARS anything non-uniform:
+
+```js
+// correct: a long thin quad, rotated
+t.identity();
+t.scale(length / texW, width / texH);
+t.rotate(angle);
+
+// wrong: the same quad arrives as a parallelogram
+t.identity();
+t.rotate(angle);
+t.scale(length / texW, width / texH);
+```
+
+The symptom is a sprite that looks right at 0 and 90 degrees and skews in
+between, which reads as a bad texture rather than as a transform bug.
+
 ## Culling and update cost
 
 - `Container` recomputes `inViewport` for every child each frame against every
@@ -231,6 +269,45 @@ SwiftShader, where the absolute numbers are wildly pessimistic and the JS
 profile shows the time as `(program)`, outside JS entirely. Ratios transfer;
 milliseconds do not.
 
+## Render targets, and what `hdr` costs
+
+A render target is a canvas-sized GPU surface. The engine allocates them
+lazily and only where a multi-pass chain actually needs one, which is worth
+knowing before assuming an effect is expensive:
+
+- a renderable with **no** post effects: none
+- a renderable with **exactly one** post effect: still none. It takes the
+  `customShader` fast path and draws straight into whatever target is already
+  bound
+- a **camera** with effects: a pair (one capture, one ping-pong intermediate)
+- a sprite with **two or more** effects: its own pair
+
+So the first lever is the count, not the cost of any one effect: going from
+one effect to two on a sprite is what allocates, not going from a cheap shader
+to an expensive one.
+
+`hdr: true` changes the format of that camera pair from 8 bits per channel to
+half-float, which is **8 bytes per pixel instead of 4**. At 1920×1080 that is
+about 8 MB per target instead of 4 MB, so roughly +8 MB for the pair. With
+`antiAlias` on, the capture half is also multisampled and its multisampled
+surface takes the same format, so that part doubles too.
+
+Nothing else moves. Sprite chains and the advanced-blend target stay 8-bit
+whatever `hdr` says, for a correctness reason rather than a thrifty one: their
+final blit composites with `ONE_MINUS_SRC_ALPHA`, and additive blending
+accumulates alpha past 1 in a float target, which would turn that factor
+negative and subtract the backdrop.
+
+**With `hdr` off, nothing changes at all** — every target keeps the 8-bit
+attachment it has always had, and a game that never adds a camera post-effect
+allocates no render targets in the first place. The setting costs nothing
+until something is actually using it.
+
+```js
+// what you actually got, which is not always what you asked for
+if (app.renderer.supportsHDR === false) { /* grade for a chain that clamps */ }
+```
+
 ## Where the costs actually are
 
 In rough order for a typical 2D game: