melonjs 20.8.0 → 20.9.0

package/skills/melonjs-3d/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: melonjs-3d
-description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit, setBasis, getBasis, lookAt, up vector, gimbal."
+description: "Use this skill for anything 3D or 2.5D in melonJS — Camera3d, Mesh, InstancedMesh, Sprite3d billboards, Light3d, ground shadows, glTF/GLB scenes, and depth sorting. Covers the Y-down/+Z-forward convention that is the inverse of OpenGL, the cameraClass opt-in, clip planes, and what does not work on the Canvas fallback. Triggers on: Camera3d, Mesh, InstancedMesh, Sprite3d, Trail3d, ribbon, exhaust trail, Light3d, billboard, glTF, glb, 3D, 2.5D, depth, cameraClass, fov, setClipPlanes, setFog, fog, distance fog, height fog, heightFalloff, transparent, transparency, alpha, blendMode, fade, castGroundShadow, lit, setBasis, getBasis, lookAt, up vector, gimbal, slerp, great circle, turn a direction."
 license: MIT
 ---
 
@@ -71,6 +71,86 @@ That flips the world's sort to `"depth"`, switches the broadphase to a 3D index,
 and renders sprites and meshes with perspective projection. `Camera3d` extends
 `Camera2d`, so follow, fade, shake and post effects all still work.
 
+### Keep the camera, do not fish it back out
+
+`app.viewport` is the **active stage's** default camera, so it is typed
+`Camera2d`: a stage overrides the application's `cameraClass`, and the
+built-in loading screen does exactly that. Reading your `Camera3d` back out of
+it therefore needs a cast, and a cast that is wrong while the loader is up:
+
+```js
+const camera = app.viewport as Camera3d;   // works, until it does not
+```
+
+Own it instead. Pass the camera in and keep the typed reference, and nothing
+downstream ever narrows:
+
+```js
+class GameStage extends Stage {
+    readonly camera: Camera3d;
+
+    constructor(app) {
+        const camera = new Camera3d(0, 0, app.renderer.width, app.renderer.height);
+        super({ cameras: [camera] });
+        this.camera = camera;
+    }
+}
+```
+
+A freshly built camera is named `"default"`, and a stage registers its
+`cameras` by name, so this IS the stage's default camera: `app.viewport`
+returns the same instance.
+
+### The two patterns differ in LIFETIME, and that decides which you want
+
+This is the part that bites. `cameraClass` builds a **fresh camera for each
+stage**, which the engine does deliberately so "Camera3d state shouldn't
+bleed across stages". An owned camera passed through `super({ cameras })` is
+built once and lives as long as the stage object, which for a stage you
+register with `state.set()` means as long as the application.
+
+So anything you attach to the camera now outlives the visit:
+
+```js
+// in onResetEvent — runs EVERY time the stage is entered
+app.viewport.addPostEffect(bloom);
+```
+
+With `cameraClass` that lands on a fresh camera each time and is harmless.
+With an owned camera it stacks: a second bloom on the second visit, a third
+on the third. The symptom is text and edges appearing to double or smear,
+because the scene is being post-processed once per accumulated effect.
+
+Note that `removePostEffect` DESTROYS the effect rather than detaching it, so
+"just remove it on the way out" is not a free undo.
+
+**Choose on lifetime, not on typing:**
+
+| your effects / camera state are | use |
+|---|---|
+| set up per stage visit, in `onResetEvent` | `cameraClass` — fresh camera per stage |
+| set up once, in the stage constructor | an owned camera in `super({ cameras })` |
+
+If you want the typed reference but your setup is per-visit, keep
+`cameraClass` and narrow once on reset:
+
+```js
+override onResetEvent(app) {
+    const viewport = app.viewport;
+    if (!(viewport instanceof Camera3d)) {
+        throw new Error("this stage needs a Camera3d");
+    }
+    this.camera = viewport;   // typed, checked, and still fresh per visit
+}
+```
+
+That is what the Earth Defender example does, and why: it attaches post
+effects on every reset and never removes them.
+
+Narrowing beats asserting wherever you read the shared slot: the language
+verifies `instanceof`, and fails loudly if the application was never given a
+`cameraClass`, where a cast fails silently at the first 3D call.
+
 Per-stage opt-in also works, which is useful when the loading screen is 2D:
 
 ```js
@@ -91,8 +171,9 @@ class GameStage extends Stage {
   Objects beyond the far plane clip or project with bad w-divides; a `near` that
   is too small wastes depth precision and distant props z-fight. Use
   `camera.setClipPlanes(near, far)`.
-- **`camera.pos.set(x, y)` is 2-argument and zeroes z.** Use `camera.depth` —
-  the documented z accessor — or assign `pos.x`/`pos.y` individually.
+- **`camera.pos.set(x, y)` is 2-argument and zeroes z.** Use
+  `camera.setPosition(x, y, z)`, which leaves the depth untouched when `z` is
+  omitted; `camera.depth` is the z accessor if you only want that.
 - **`lookAt(target)` solves pitch and yaw only**, so on its own it cannot
   express "up is this direction" and it leaves `roll` alone. Pass an up to
   bank the horizon too: `camera.lookAt(target, up)`, where `up` is what should
@@ -159,6 +240,52 @@ the same picture.** If a game already transforms its world into view space by
 hand, there is nothing to gain by switching; the value of `setBasis` is not
 having to write that transform in the first place.
 
+## Turning a direction: `slerp`, not `lerp`
+
+`lerp` walks the straight line between the two tips, which passes INSIDE the
+sphere. The result points the right way at both ends, lingers near them, rushes
+the middle, and comes out shorter than either input as it crosses the midpoint.
+On a camera swing that reads as a lurch; on a body walking over a globe it dips
+into the surface.
+
+`Vector3d#slerp` turns along the great circle instead, at a constant angular
+rate, and carries the length across linearly, so two unit vectors give back a
+unit vector and nothing needs renormalizing.
+
+```js
+// a turret, a camera, a ship: a facing chasing another facing
+facing.slerp(toTarget, 0.25);
+
+// frame-rate independent, the same shape as math.damp
+facing.slerp(toTarget, 1 - Math.exp((-6 * dt) / 1000));
+```
+
+`ObservableVector3d` has it too and fires its callback ONCE, so
+`renderable.pos.slerp(...)` is one notification rather than three.
+
+**`Vector2d` has the same method**, and it is not a cut-down copy: in 2D the
+whole turn is one signed angle, so there is no sine to divide by and no
+degenerate near-parallel case at all. What it buys a 2D game is the wrap: a
+heading damped as a NUMBER from 170 degrees to -170 degrees sweeps the long 340
+instead of the short 20, and an arc between directions cannot do that.
+
+Two degenerate pairs are handled inside rather than left to the caller, and
+both turn up in ordinary game code:
+
+- **the same direction**, where every path between them is the same path.
+- **opposite directions**, where infinitely many great circles pass through
+  both and none is the shorter way round. The textbook formula divides by a
+  vanishing sine here and hands back `NaN`, which propagates into a position or
+  a matrix and the object disappears. `slerp` picks a stable perpendicular and
+  turns through half a circle instead.
+
+That second case is why a hand-rolled version is a liability rather than a
+shortcut: anything orbiting a planet reaches the antipode of where it started,
+every run.
+
+**`math.damp` for a scalar, `slerp` for a direction.** Same job, different
+space; what `damp` cannot do is keep a vector on the sphere.
+
 ## Depth sorting
 
 Under `Camera3d` the world sorts on `"depth"` **every frame** (recursively), so
@@ -273,6 +400,12 @@ const glow = new Mesh(0, 0, {
 Ground shadows ride the same pass — a blob is a decal, and decals are its first
 client rather than a feature of their own.
 
+**`Trail3d`** is the transparent pass's other obvious client: a camera-facing
+ribbon for an exhaust streak, a speed trail or a tyre mark. It is a `Mesh`, so
+it sorts and fogs with everything else here, and like the rest of this tier it
+needs a `Camera3d`. `Trail` is the 2D one and stays flat under a perspective
+camera. See `melonjs-particles-and-trails`.
+
 ## Distance fog
 
 Off until you ask for it, and one call on the camera:
@@ -456,7 +589,7 @@ There are four levels, and picking the wrong one is the usual reason a colour
 
 | level | how | use for |
 |---|---|---|
-| whole object | `mesh.tint.setColor(r, g, b)` | flash on hit, team colour, fading one object |
+| whole object | `mesh.setTint("#ff8800")`, or `mesh.tint.setColor(r, g, b)` | flash on hit, team colour, fading one object |
 | per vertex | `settings.vertexColors`, or `mesh.setVertexColor(i, color)` | a gradient *within* one mesh — distance haze, a darker crease |
 | per material | `textureGroups`, from a multi-material OBJ + MTL | a model whose parts differ, in one draw call |
 | per instance | `new InstancedMesh(…, { instanceColors: true })` then `setInstanceColor(i, color)` | a thousand copies that differ |
@@ -671,6 +804,7 @@ is read **every draw**, so all of them can be animated.
 |---|---|---|
 | `castGroundShadow` | yes | yes |
 | `shadowGroundY` | yes, the caster's own floor | yes, **one plane** through the SET's origin |
+| `shadowGroundPoint` | yes on a `Mesh` or `Sprite3d`; on a `GLTFModel` part only by setting it after the load, since it is neither a model nor a `level.load` option | **no**, warns and ignores |
 | `shadowGroundNormal` | yes | yes, one plane for the set |
 | `shadowOpacity` | yes | yes |
 | `shadowScale` | yes | yes |
@@ -681,13 +815,22 @@ is read **every draw**, so all of them can be animated.
 | height fade as the caster rises | yes | **no** |
 | a different value per instance | n/a | **no**, and there is no plan for one |
 
-The two "no"s are the same limitation seen twice: a set gets ONE shadow plane
-and ONE shared quad, so the instance's own height is dropped and nothing can
-vary between instances. Everything else is one value for the whole set, which
-is what a set means. A scatter over curved ground is therefore one set per flat
-facet, and a flying scatter wanting a height fade has to be per-object meshes.
-
-Nothing here is per-object-only. If a claim that a setting "does not work on an
+The last two "no"s are the same limitation seen twice: a set gets ONE shadow
+plane and ONE shared quad, so the instance's own height is dropped and nothing
+can vary between instances. Everything else is one value for the whole set,
+which is what a set means. A scatter over curved ground is therefore one set
+per flat facet, and a flying scatter wanting a height fade has to be
+per-object meshes.
+
+`shadowGroundPoint` (20.9) is the one genuinely per-object setting, and the
+reason is structural rather than missing work: the instanced tier builds its
+plane THROUGH the set's own origin so the translation's x and z drop out of
+the intercept, which is then `groundY + lift / nY`. An arbitrary point does
+not drop out, and that same `nY` divisor is why the 75 degree tilt ceiling
+cannot be lifted there either. `InstancedMesh` warns and ignores rather than
+storing it, so a game cannot think it took.
+
+Apart from that one, if a claim that a setting "does not work on an
 `InstancedMesh`" is in your head, it is out of date: `shadowOffset` and
 `shadowStretch` both reached the instanced tier in 20.8.
 
@@ -698,8 +841,27 @@ skip geometry with no vertical extent — a ground plane. Per object,
 given, safeguard included; `shadowGroundY` names the floor the blob lands on,
 `shadowOpacity` how dark it is and `shadowScale` how big it is.
 
+On ground that is not flat, name the floor with `shadowGroundPoint` instead:
+a point and `shadowGroundNormal` are a plane, and the blob leaves the caster's
+vertical column to land on it. `shadowGroundY` cannot express that, because
+the blob is always directly below the caster in world Y, which is only "below"
+on level ground. It is also what lifts the tilt ceiling, since that ceiling
+measures tilt from world up and so assumes a camera looking down the Y axis.
+
+The height fade follows whichever floor you named. With a point **and** a
+normal it is measured along that normal; with a point alone it is the
+straight-line distance to the point. So on a sphere the blob fades with
+ALTITUDE rather than with the vertical drop, which is the whole reason the
+point exists. Two consequences worth knowing, because they fail in opposite
+directions: a `shadowGroundNormal` facing inward makes the height negative, so
+the fade clamps to full strength and the blob never fades at all; and a point
+on the wrong side of the caster reads as a large height, so the blob
+disappears outright rather than thinning to a ring the way a backwards
+`shadowGroundY` does. It is also the one shadow setting that THROWS rather
+than clamping or hiding: a non-finite component is rejected on the spot.
+
 The blob is an ellipse sized to the caster's own footprint and placed at the
-caster's x/z. So a tall or narrow object (a character, a tree, a pickup) shows
+caster's x/z, or at `shadowGroundPoint` when one is set. So a tall or narrow object (a character, a tree, a pickup) shows
 its shadow clearly, while a wide, flat-bottomed one resting on the floor covers
 its own completely from a camera looking down at it. That is the shadow
 behaving correctly, not a bug.
@@ -731,7 +893,8 @@ mesh.shadowStretch = 2;        // and lengthen it along the same line
 `shadowOffset` is measured in multiples of the blob's **own radius**, not in
 world units, so one value serves a boulder and a pebble and every part of a
 glTF model. About `stretch - 1` is what keeps the shadow attached to its
-caster. It is honoured **only when `shadowGroundY` is set**, because the
+caster. It is honoured **only when the floor has been named**, by
+`shadowGroundY` or by `shadowGroundPoint`, because the
 blob is a flat quad on one named plane: sliding it across a plane the game has
 not named puts it where there may be no floor. `shadowStretch` is clamped to 3
 and the blob fades as it pulls, so an extreme value degrades to nothing rather
@@ -761,12 +924,18 @@ prop.shadowGroundNormal = [Math.sin(0.35), -Math.cos(0.35), 0];  // a 20 deg slo
 
 World up is `(0, -1, 0)`, because render space is Y-down, and that is the
 default. The blob is **rotated** onto the plane rather than projected, so it
-keeps its size; it still sits directly under the caster, since the normal
-turns it rather than moving it. The tilt is clamped at 75 degrees, past which
-an edge-on blob has nothing left to show. It needs `shadowGroundY`, for the
-same reason the offset does: tilting the bounds fallback has no anchor to turn
+keeps its size; it sits directly under the caster, since the normal turns it
+rather than moving it, unless `shadowGroundPoint` says where instead. It needs
+the floor named, by `shadowGroundY` or `shadowGroundPoint`, for the same
+reason the offset does: tilting the bounds fallback has no anchor to turn
 about.
 
+The tilt is clamped at 75 degrees alongside `shadowGroundY`, past which an
+edge-on blob has nothing left to show. That ceiling measures tilt from WORLD
+up, which stands in for "tilted away from the viewer" only while the camera
+looks down the Y axis, so it is lifted alongside `shadowGroundPoint`, where a
+point and a normal state the plane outright.
+
 On an `InstancedMesh` one plane serves the **whole set**: it passes through
 the set's origin at `shadowGroundY`, faces the normal, and every blob is
 projected onto it whatever height its own instance sits at, exactly as the
@@ -845,7 +1014,8 @@ Loaded through the same level director as everything else:
 await loader.preload([{ name: "diorama", type: "glb", src: "data/diorama.glb" }]);
 level.load("diorama", { scale, castGroundShadow, shadowGroundY, onLoaded });
 
-// every ground-shadow setting travels, not just those two: a loaded scene can
+// every ground-shadow setting travels except shadowGroundPoint, which is
+// per object and dropped by a scene load: a loaded scene can
 // be told where its sun is, and `shadowLight` is re-read every draw
 level.load("diorama", {
     scale, castGroundShadow: true, shadowGroundY: 0,
@@ -931,6 +1101,10 @@ To branch rather than fail, read `app.renderer.supportsDepthBuffer` after
 | one marker must stay readable in fog | `fog: false` on that mesh |
 | an object casts no visible shadow | wide and flat-bottomed — its own blob is underneath it; raise `shadowScale` (or slide it out with `shadowOffset`), not `shadowGroundY`, which haloes it instead of revealing it |
 | a dark ring around the top of an object | `shadowGroundY` lifted too far, floating the blob up into the caster |
+| a tilted blob never fades as its caster rises | `shadowGroundNormal` faces inward, so the height came out negative and clamped to full strength |
+| a blob vanishes completely after setting `shadowGroundPoint` | the point is on the wrong side of the caster; the fade reads that as height and hides it |
+| `shadowGroundPoint` throws | it is the one shadow setting that rejects a bad value instead of clamping: all three components must be finite |
+| a scatter ignores `shadowGroundPoint` | `InstancedMesh` shares one plane across the set and warns; use one set per facet, or per-object meshes |
 | a mesh sits at the wrong depth after being added | `autoDepth` overwrote `pos.z` with the child index — pass `addChild(mesh, z)` |
 | a mesh sits half its size off | `anchorPoint` — only on the 2D-camera path; a `Camera3d` mesh pivots on its model origin |
 | a billboard tips over when the camera looks down | `"spherical"`, or a mistyped mode string falling through to it — use `true` / `"cylindrical"` |

package/skills/melonjs-3d-assets/SKILL.md

@@ -33,21 +33,35 @@ or it renders flat. See `melonjs-3d` for the camera.
 |---|---|---|
 | `scale` | `1` | pixels per glTF unit, applied to the whole scene. Blender's metre-scale export usually needs 20–100. |
 | `container` | `game.world` | where the nodes are added |
-| `onLoaded` | `app.onLevelLoaded` | called with the **level id**, not the scene |
+| `onLoaded` | `game.onLevelLoaded` | called with the **level id**, not the scene |
 | `async` | `false` | return a promise that settles once the scene is in the world, instead of a boolean |
 | `rightHanded` | `true` | see below |
 | `lights` | `true` | instantiate authored `KHR_lights_punctual` lights as `Light3d` world children |
 | `lightIntensityScale` | — | keep authored intensity ratios instead of normalising every light to 1 |
+
+Those `game.` defaults are the engine's, not a recommendation. `game` is
+whichever `Application` finished `init()` last, so **pass `container`
+explicitly** from a `Stage`, where the right one is in your hand:
+
+```js
+level.load("sceneId", { container: this.app.world, scale: 40 });
+```
 | `castGroundShadow` | inherits the app setting (**on**) | blob shadows for this scene's meshes |
 | `shadowGroundY` | each object's own base | world Y of the floor the blobs land on |
 | `shadowOpacity` | `0.45` | how dark the blobs are |
 | `shadowScale` | `1` | blob footprint multiplier; `0` or less hides them |
-| `shadowOffset` | `0` | slide them along the light, in blob radii; needs `shadowGroundY` |
+| `shadowOffset` | `0` | slide them along the light, in blob radii; needs `shadowGroundY`, which is the only way a scene load can name its floor |
 | `shadowStretch` | `1` | lengthen them along it, clamped to 3 |
 | `shadowDirectionX` / `shadowDirectionZ` | `0` | the ground direction they are cast along |
 | `shadowGroundNormal` | world up | up normal of the floor, for a scene that is not level |
 | `shadowLight` | — | a `Light3d` to take the direction from, re-read every draw |
 
+`shadowGroundPoint` is **not** on that list, and a scene load drops it without
+a warning. One floor POINT shared by every part of a scene would stack the
+whole thing's blobs on a single spot, which is nonsense where one floor
+HEIGHT is perfectly sensible. Ground that is not flat is a per-object answer:
+set it on the parts you want once the load has finished.
+
 `onLoaded` receives the level id — it is a "done" signal, not a handle on the
 scene. You need it, or `async`: with the game loop running, `level.load` stops
 the loop and defers the actual load to a timer, so by default it returns
@@ -138,6 +152,26 @@ asset fails to load. Export uncompressed.
 it through. Pixel-art models want `"nearest"`.
 
 ### `baseColorFactor` is LINEAR; a `tint` is sRGB
+**Pass the factor as a setting and the encoding is done for you.** `Mesh`
+takes `baseColorFactor` — `[r, g, b]` in 0..1, linear, which is the form the
+loader hands back — so a mesh built from a node passes the node's own field
+straight through:
+
+```js
+const node = loader.getGLTF("palm").nodes[0];
+const mesh = new Mesh(x, y, {
+    vertices: node.vertices, normals: node.normals,
+    uvs: node.uvs, indices: node.indices, normalize: false,
+    baseColorFactor: node.baseColorFactor,   // encoded, not scaled
+});
+```
+
+The setting's type admits `undefined`, because the loader declares the field
+optional and that line has to compile under `exactOptionalPropertyTypes`.
+`Sprite3d` forwards it too, and `mesh.setBaseColorFactor(f)` applies one after
+construction. For an ordinary sRGB colour use `setTint` instead — the rest of
+this section is why the two are different.
+
 
 The loader handles this for you. It only bites when you build meshes yourself
 from `loader.getGLTF(name).nodes` — which is what you do for per-node control,