melonjs 20.10.0 → 20.11.0

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

@@ -1,6 +1,6 @@
 ---
 name: melonjs-loading-assets
-description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload."
+description: "Use this skill for loading and managing game assets in melonJS — the resource descriptor format, the full asset type list, preload versus load, retrieving loaded assets, base URLs and cross-origin settings, and the loading screen. Triggers on: loader, loader.preload, loader.load, resources, getImage, getJSON, getTMX, getGLTF, getVideo, getFont, setBaseURL, setOptions, crossOrigin, withCredentials, credentials, cookies, authenticated assets, CORS, asset, preload, LOADER_COMPLETE, loading screen, unload, setParser, custom asset type, generated texture, procedural texture."
 license: MIT
 ---
 
@@ -50,6 +50,7 @@ The type strings are melonJS-specific — this is not a generic loader:
 | `"obj"` / `"mtl"` | Wavefront models and materials |
 | `"gltf"` / `"glb"` | glTF scenes |
 | `"js"` | scripts |
+| any type you register | your own formats, and things you generate rather than download — see [Custom asset types](#custom-asset-types) |
 
 ## What belongs in the manifest — and what cannot
 
@@ -84,14 +85,24 @@ is compiled at load time, behind the loading screen, and the loader hands out a
 renderable's teardown freeing it out from under the others. `clone()` does NOT
 help here — it constructs a new effect, and therefore links a new program.
 
-**2. Derived assets — build once, after the preload.** Canvases you bake,
-`NoiseTexture2d`, `TextureAtlas`: the loader cannot carry these, but they must
-not be rebuilt per scene either. The renderer's texture cache is keyed by the
-**image object**, so a freshly baked canvas is a brand new GPU texture with a
-new mip chain — rebuild one per stage and a title → play → game-over cycle
-uploads four copies of the same pixels. Build them once after `preload`
-resolves and share them, the way the platformer example builds its
-`TextureAtlas` into a module the scenes read from.
+**2. Derived assets — build once, before the first stage.** Canvases you bake,
+`NoiseTexture2d`, `TextureAtlas`: none of the built-in types describes these,
+and they must not be rebuilt per scene either. The renderer's texture cache is
+keyed by the **image object**, so a freshly baked canvas is a brand new GPU
+texture with a new mip chain — rebuild one per stage and a title → play →
+game-over cycle uploads four copies of the same pixels. Build each once and
+share it from a module the scenes read from, the way the platformer example
+builds its `TextureAtlas`.
+
+*Where* you build it depends on what it costs. A gradient or a palette strip is
+well under a millisecond: build it after `preload` resolves. A bake that takes
+real time — procedural noise is the usual one: Earth Defender's sky, two fractal
+simplex fields over a 512² tile, takes about 200ms on a desktop — belongs
+**inside** the preload as an asset type of your
+own ([Custom asset types](#custom-asset-types)). It then runs behind the loading
+screen and counts on the progress bar. Built on stage entry instead, it lands on
+the frame the scene is assembled, and with a transition running that frame is a
+black screen.
 
 **3. The engine's own shader programs — warmed for you, since 20.6.** The mesh
 batcher compiles a program per *feature combination* (instance colours, instance
@@ -230,6 +241,83 @@ loader.getBinary("font-fnt");
 Most engine classes take the asset **name** directly, so you often do not need
 these — `new Sprite(x, y, { image: "tiles" })` resolves it for you.
 
+## Custom asset types
+
+`loader.setParser(type, parserFn)` teaches the loader a type of its own. An entry
+of that type then sits in the preload list like any other: it is one step of the
+progress bar, and `preload()` waits for it before `LOADER_COMPLETE`. Use it for a
+file format melonJS does not know, and for anything you **generate** that takes
+long enough to matter.
+
+```js
+import { loader, Sprite } from "melonjs";
+
+const skies = new Map();
+
+// once, before preloading: registering a type twice logs a warning
+loader.setParser("sky", (asset, onload, onerror) => {
+    bakeSky(asset.name)                 // your generator, returning a Promise
+        .then((canvas) => {
+            skies.set(asset.name, canvas);
+            onload();                   // takes no value, see below
+        }, onerror);
+    return 1;                           // one asset, settling later
+});
+
+await loader.preload([
+    { name: "nebula", type: "sky" },    // no src: nothing to download
+    // ...the rest of the manifest
+]);
+
+// in the stage, later: already baked
+const backdrop = new Sprite(0, 0, { image: skies.get("nebula") });
+```
+
+The contract:
+
+- **Call `onload()` or `onerror(error)`, exactly once,** now or later. Return `1`
+  when you will, `0` when there is nothing to load (the loader then moves on
+  without waiting).
+- **The loader keeps nothing for a type it does not know.** `onload` takes no
+  value, and `loader.getImage` and friends will not find your result. Keep it
+  yourself, keyed by `asset.name`, and read it from there.
+- **`name` and `type` are a complete entry.** `src` is only for a type that
+  fetches something. `data` is typed for the built-in uses (a string, or a
+  `{glsl, wgsl}` pair), so for a generator's settings, keep a table in your own
+  module keyed by name and let the entry carry only the name. That also keeps
+  the preload and the stages from disagreeing on a seed.
+- **Base URLs:** a `src` is prefixed only by `setBaseURL(yourType, …)`. The `"*"`
+  wildcard does not cover custom types.
+- **Do not hold the main thread for the whole bake.** A parser runs alongside
+  the downloads, and a 200ms synchronous loop freezes the loading screen and
+  stalls every other asset's progress for that long. Bake in slices of a few
+  milliseconds and yield between them, with `setTimeout`, not
+  `requestAnimationFrame`, which stops in a background tab and would hold the
+  whole preload with it. Skip the yield while the tab is hidden: a background
+  tab runs timers about once a second, which turns a bake of 25 slices into 25
+  seconds, and there is no loading screen on show to keep smooth:
+
+```js
+const bakeSky = async (name) => {
+    const { size, seed } = SKIES[name];         // your recipe table
+    const tile = startTile(size, seed);         // set up the canvas and the noise
+    for (let y = 0; y < size; ) {
+        const start = performance.now();
+        while (y < size && performance.now() - start < 8) {
+            tile.fillRow(y++);
+        }
+        if (!document.hidden) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+    return tile.finish();
+};
+```
+
+The Earth Defender example does exactly this for its two nebula skies
+(`fx/nebula.ts`): a `"nebula"` type, two name-only entries in its manifest, and
+stages that ask for a sky by name and find it baked.
+
 ## Base URLs
 
 Set a prefix per asset type rather than repeating it:
@@ -326,6 +414,9 @@ throws, the same trap as the removed `loader.onload` / `onProgress`.
 | text renders in a fallback font | web font not preloaded as `"fontface"` |
 | `BitmapText` renders nothing | the `.fnt` (as `"binary"`) or its image is missing |
 | `TypeError` assigning `loader.onProgress` / `onload` | removed in 20.3; they were never writable — use the `LOADER_*` events |
+| `load : unknown or invalid resource type` | a custom type in the manifest before its `loader.setParser` call |
+| black or frozen screen when a stage is first entered, the profile shows your own code (noise, a canvas bake) | a costly derived asset built on stage entry — bake it inside the preload as a [custom asset type](#custom-asset-types) |
+| a custom asset preloads but the result is nowhere to be found | `onload` takes no value and the loader stores nothing for custom types — keep the result in your own module |
 
 ## Related skills
 

package/skills/melonjs-math/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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, Noise, getNoise1d, flicker, wobble."
 license: MIT
 ---
 
@@ -291,6 +291,25 @@ math.pow(n);                     // n squared
 math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 ```
 
+### Values that wobble over time
+
+`Noise`, the generator behind `NoiseTexture2d`, also samples directly. For a
+value that should drift without repeating (a torch's flicker, a sway, a camera
+wander), sample it with time:
+
+```js
+import { Noise } from "melonjs";
+
+const noise = new Noise({ seed: 7, frequency: 1.5, octaves: 3 });
+// around 1; give each object its own offset so they do not move together
+const flicker = 1 + 0.2 * noise.getNoise1d(seconds + offset);
+```
+
+`getNoise1d` returns `[-1, 1]` (with fractal octaves most values fall within
+about ±0.6), `frequency` is in changes per unit of the input, and the same seed
+gives the same field every run. A sum of sines repeats where people notice it,
+and `Math.random()` every frame jitters instead of drifting.
+
 ## Symptoms
 
 | symptom | cause |
@@ -305,6 +324,7 @@ math.DEG_TO_RAD  math.RAD_TO_DEG  math.TAU  math.ETA  math.EPSILON
 | 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` |
+| a flicker or sway looks mechanical, or visibly repeats | a sum of sines or a per-frame `Math.random()`: sample `Noise#getNoise1d(time)` |
 
 ## Related skills
 

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: 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."
+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, tintOverLife, colour over life, color over life, flame, fire."
 license: MIT
 ---
 
@@ -60,7 +60,8 @@ 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.
+between. For a colour that changes over each particle's life, use
+`tintOverLife` (below) rather than drawing one frame per colour.
 
 Frame dimensions must be positive integers that fit inside the image, and an
 explicit `frames` sequence must be nonempty and contain valid integer indices.
@@ -69,6 +70,35 @@ Invalid configurations throw `RangeError` before changing an emitter during
 only future particles, so ones already alive finish with their original image,
 frame size and sequence.
 
+## Colour over life: `tintOverLife`
+
+`tintOverLife` is the list of tints a particle takes over its life: the first at
+birth, the last at the end, evenly spaced and blended in between. Give as many
+CSS colours as you like (repeat one to hold it longer); it replaces `tint`.
+
+```js
+// a flame: white hot, then orange, then deep red as it rises and dies
+const flame = new ParticleEmitter(x, y, {
+    image: softDot,                     // a white texture takes the tints as they are
+    tintOverLife: ["#fff3b0", "#ffc455", "#ff8a26", "#e45414", "#a0280c"],
+    textureAdditive: true,
+});
+```
+
+- **Colour only.** Opacity is still the built-in fade over the particle's life;
+  the alpha of a colour in the list is ignored. On an additive emitter, a darker
+  colour is a dimmer particle, so fold a "fainter" step into the colour itself.
+- **32 steps.** However many colours, the blend is taken in 32 steps, the same on
+  every renderer: a particle changes colour at most 32 times. That matters on
+  Canvas, which keeps a tinted copy of the texture for every colour it is asked
+  to draw: 32 at most per texture.
+- **Author the texture white.** `tint` multiplies, so a coloured texture muddies
+  every step.
+- It works alongside sprite-sheet `frames` (one picks the image, the other the
+  colour), and a list that is empty, not an array, or holds a non-string throws a
+  `TypeError` from the constructor or `reset()`, which then leaves the emitter as
+  it was. The list is copied: change it through `reset()`.
+
 ## Where particles are born
 
 `width` and `height` are the spawn AREA, and both default to `1` — so by
@@ -290,6 +320,7 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | symptom | cause |
 |---|---|
 | trail looks flat under a `Camera3d` | `Trail` is 2D; use `Trail3d` |
+| particles clutter a minimap or a second camera | every camera draws them: set the emitter's `visibilityLayer` to a layer that camera's `cullMask` leaves out (see `melonjs-camera-and-drawing`) |
 | `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 |
@@ -298,6 +329,9 @@ answer when you want discrete puffs rather than a continuous ribbon.
 | 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 |
 | one-shot emitters accumulate | missing `autoDestroyOnComplete: true` |
+| every particle of an emitter is the same colour all its life | `tint` is one value for the emitter: use `tintOverLife` for a colour that changes as it ages |
+| a `tintOverLife` colour's transparency has no effect | the list sets the colour only; opacity is the particle's fade |
+| `tintOverLife` colours look muddy | the texture is coloured; author it white so the tints come through as given |
 | 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` |

package/skills/melonjs-performance/SKILL.md

@@ -249,8 +249,12 @@ game does not use the preloader at all**, which is the one way to miss it — se
 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.
+start is covered, an object created and drawn in the same frame is not. Since
+20.10.1 a state change also holds the new stage's first frame until what its
+`onResetEvent` built is warmed, for at most 1.5s, so the opening frame no longer
+compiles them itself: a few milliseconds once the browser has compiled them
+before, longer on a first visit. None of this covers the rest of what a first
+frame pays for, below.
 
 How to tell them apart, all from the page:
 
@@ -369,6 +373,7 @@ In rough order for a typical 2D game:
 | 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 |
+| steady movement stutters while the frame rate reads 60 | not a cost: frame-time jitter gives a frame no update and the next two; set `syncToDisplay: true` (see `melonjs-display-and-scaling`) |
 
 ## Related skills
 

package/skills/melonjs-renderables/SKILL.md

@@ -96,9 +96,44 @@ world.addChild(sprite, 10);   // ✓ the only reliable form
 2. **Setting `depth` *before* `addChild` is overwritten.** With `autoDepth` on
    (the default), `addChild` without an explicit `z` assigns
    `child.pos.z = children.length` after the push, discarding whatever you set.
-3. **Setting `depth` *after* `addChild` does not reorder.** Containers sort when
-   a child is added (`autoSort`, deferred to the next tick), not when `pos.z`
-   changes. If you must change it later, call `container.sort()` yourself.
+3. **Setting `depth` *after* `addChild` does not reorder.** A `"z"` sort runs
+   when a child is added (`autoSort`, deferred to the next tick), not when
+   `pos.z` changes. If you must change it later, call `container.sort()`
+   yourself, or use `moveToTop` / `moveUp` / `moveDown` / `moveToBottom`, which
+   reorder the children themselves. (An `"x"` / `"y"` sort is different: see
+   below.)
+
+### Sorting on `"y"` (or `"x"`), and `sortOffset`
+
+A container with `sortOn = "y"` draws its children from the smallest `pos.y` to
+the largest, so whatever is lower on screen covers what is above it (top-down and
+isometric games). `"x"` does the same along x. A different `pos.z` still decides
+first, so keep the children that should interleave at one z.
+
+- **Moving a child re-sorts by itself.** With `autoSort` on (the default), the
+  container checks its order at the end of every update, after physics and the
+  children's own updates, and re-sorts when anything is out of place: a walking
+  character needs no `sort()` call. A frame where nothing moved costs one pass
+  over the children and does not cause a redraw. Turn `autoSort` off to keep
+  the children in the order you put them.
+- **Ties keep insertion order, and the child added LAST is drawn BEHIND.** A
+  torch placed at its wall's exact position disappears behind the wall.
+
+`sortOffset` changes the ORDER only, never where anything is: the child is lined
+up as if it stood that many pixels lower (positive) or higher (negative), and is
+drawn exactly where it was. Use it when `pos` is not the point to sort by:
+
+```js
+torch.sortOffset = 1;                        // win the tie with the wall it hangs on
+dust.sortOffset = door.pos.y - dust.pos.y;   // an emitter's pos is the top of its
+                                             // spawn area: line it up with the door
+prop.sortOffset = prop.height;               // sort by the bottom of the image
+```
+
+A container that keeps itself sorted picks a change up at its next update (with
+`autoSort` off, call its `sort()`). `"z"` and `"depth"` sorting ignore it. It must be a finite number (a string
+or `NaN` throws, rather than scrambling every sibling), and a pooled renderable
+starts again at `0`.
 
 The exception: under `Camera3d` the world's `sortOn` is `"depth"`, and the
 camera calls `container.sortNow(true)` every frame. Note that mode does **not**
@@ -262,6 +297,10 @@ other correct ending.
 - `floating = true` pins a renderable to the screen rather than the world, which
   is what you want for HUD elements. It opts the object out of camera transforms
   and out of ancestor position accumulation.
+- `visibilityLayer` decides which cameras draw a renderable: a camera draws it
+  only if it shares a bit with the camera's `cullMask` (every camera, by
+  default). See `melonjs-camera-and-drawing` for keeping something off a
+  minimap.
 
 ## Prefer built-in features
 

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

@@ -45,6 +45,13 @@ 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.
 
+`onResetEvent` runs when the switch is made. The first frame, `STATE_CHANGE` and
+a transition's reveal follow once the shaders the stage queued are ready, which
+is a few milliseconds once the browser has compiled them before, and at most
+1.5s on a first visit. So build the stage in `onResetEvent`: an object a
+`STATE_CHANGE` listener adds is not waited for, and its first draw may still
+compile what it needs.
+
 `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.

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

@@ -59,6 +59,10 @@ 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
+hero.setCurrentAnimation("use", { next: "idle", onComplete: fn }); // call fn, then chain to idle
+hero.setCurrentAnimation("run", { onFrame: (frame) => {            // each frame playback reaches
+    if (frame === 3 || frame === 8) footstep();
+} });
 
 if (hero.isCurrentAnimation("walk")) { /* … */ }
 ```
@@ -71,13 +75,25 @@ 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,
+`{ loop, next, speed, onComplete, onFrame }`, 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.
 
+`onFrame(frame)` is called with frame 0 when the animation starts, then with each
+frame playback reaches, so a footstep or a hit lands on its frame without polling
+`getCurrentAnimationFrame()`. A long tick reports every frame it goes past. It is
+not called for a frame set with `setAnimationFrame`, nor for the frame 0 a
+play-once animation would wrap to. Keep the callback in a field when you call
+`setCurrentAnimation` every frame: re-selecting keeps the first one anyway.
+
+With both `next` and `onComplete`, the callback runs first and the chained
+animation starts with none of its own, so a one-off action (a pickup, an
+attack) needs no manual switch back to idle.
+
 Re-selecting the animation that is already current is a no-op, so calling
-`setCurrentAnimation` every frame is safe. An unknown id throws.
+`setCurrentAnimation` every frame is safe, and an `isCurrentAnimation` check
+around it adds nothing. An unknown id throws.
 
 ## Texture atlases
 

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 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."
+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, TMXObject, resolvedProperty, resolvedProperties, tile class, tile properties."
 license: MIT
 ---
 
@@ -72,7 +72,8 @@ 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"`,
+Tiled **class**, then its **name**, then, for a tile object with no class of
+its own, its **tile's class**, then the structural fallbacks `"text"`,
 `"tile"` and `"shape"`.
 
 ```js
@@ -122,6 +123,53 @@ 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.
 
+### Classes and properties set on tiles
+
+In Tiled, a tile can carry a class and custom properties (tileset editor), and
+every object placed from that tile shows them as its own. melonJS follows:
+
+- **The tile's class.** A tile object with no class is built by the class
+  registered under its tile's class, so a designer sets "Chest" once on the
+  chest tile and every chest dropped in the map is a `Chest`. The object's
+  own class or registered name still comes first, and a tile classed like a
+  built-in (`Sprite`, `Trigger`, `shape`...) stays a plain tile.
+- **The tile's properties.** Read them with `settings.resolvedProperty(name)`
+  or `settings.resolvedProperties()`, which merge the tile's properties under
+  the object's own, as Tiled's scripting API of the same names does. They are
+  **not** set on `settings` by name: only the object's own properties are,
+  as before, so a tile property named like a sprite setting never reaches a
+  plain tile sprite.
+
+```ts
+import { registerTiledObjectClass, Sprite, type TMXObject } from "melonjs";
+
+// the custom properties set on the object itself, by name
+interface DoorSettings extends TMXObject {
+    locked?: boolean;
+}
+
+class Door extends Sprite {
+    locked: boolean;
+    facing: string;
+    constructor(x: number, y: number, settings: DoorSettings) {
+        super(x, y, { image: "door" });
+        this.locked = settings.locked ?? false;
+        // on the object, or else on the door tile in the tileset
+        this.facing = settings.resolvedProperty("facing") ?? "N";
+    }
+}
+registerTiledObjectClass("Door", Door);   // and give the door tile the class "Door"
+```
+
+`TMXObject` is the type of the `settings` a registered class (or factory)
+receives: the object as read from the map, with `tile` (a `Tile`) on a tile
+object. Extend it with the properties your class reads.
+
+For a class that is not a `Sprite` itself (a `Container` holding the tile and
+something else, say), `settings.tile.getRenderable()` returns the tile's sprite
+as a plain tile object would get it: from a tileset image, an image collection
+or an animated tile alike, with no region names to build by hand.
+
 melonJS pre-registers `Renderable`, `Sprite`, `NineSliceSprite`, `Text`,
 `BitmapText`, `ImageLayer`, `ColorLayer`, `Light2d`, `Collectable`, `Trigger`
 and `Entity` as Tiled classes, so `Collectable` and `Trigger` work out of the
@@ -157,7 +205,9 @@ opposite of `level.load`'s.
 
 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.
+points all work. On an isometric map they are projected with the map's tile
+ratio; a circle stays an `Ellipse`, but any other ellipse comes out tilted and
+becomes a `Polygon`, so code that checks a shape's type should expect either.
 
 The contract is the **layer name**: melonJS lowercases it and checks whether it
 *contains* `"collision"` (so `collision`, `Collision`, `world collision` all
@@ -171,7 +221,10 @@ An object that matches no factory and carries no text or tile data falls to the
 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.
+on the settings object passed to your entity's constructor. Properties set on
+the object's tile are read with `settings.resolvedProperty(name)`. One is also
+applied to the object the map creates: an `int` property named
+`visibilityLayer` sets which cameras draw it (see `melonjs-camera-and-drawing`).
 
 ## Map orientations
 
@@ -183,10 +236,69 @@ Isometric maps need y-sorting so objects overlap correctly:
 app.world.sortOn = "y";       // after level.load
 ```
 
+The world then keeps its objects in order as they move (`autoSort`, on by
+default): a character walking around passes in front of and behind the scenery
+with no `sort()` call.
+
 `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.
 
+### What the y-sort can and cannot sort
+
+`sortOn = "y"` sorts **objects**, never tiles. A tile layer is a single
+renderable drawn in one piece, so a character ends up in front of all of it or
+behind all of it. Anything a character walks both in front of and behind
+(walls, trees, furniture) has to be on an **object layer, as tile objects**,
+and in the **same** object layer as the characters: each Tiled layer gets its
+own `z`, and the y-sort compares `z` before `y`. Keep the floor on a tile layer
+below them. This holds for any y-sorted map, isometric or a top-down
+orthogonal one.
+
+```
+floor      tile layer     the ground, drawn first
+dungeon    object layer   walls, props, chests, doors, the hero
+collision  object layer   the shapes (not drawn)
+```
+
+Tile objects with no class are built for you: each one is a `Sprite` with its
+default body, static, over its whole image box and typed `ENEMY_OBJECT`. A
+character keeping the default `collisionMask` (every type) collides with all of
+them, so when the scenery's real collision is drawn in the collision layer,
+mask the character to it:
+
+```js
+this.body.setCollisionMask(collision.types.WORLD_SHAPE);
+```
+
+Give the objects with behaviour a Tiled class and register it, as above.
+
+The `y` it sorts on is `pos.y`, and Tiled objects default to a `(0, 0)` anchor,
+so that is the **top** of each image. Sorting by the top only matches sorting by
+the feet when every image is the same height and stands on the bottom of its
+box, the usual layout of an isometric pack. A shorter image sorts in front of
+things it stands behind. Either pad the art to one height, or line every object
+up by the bottom of its image with `sortOffset`, which changes the order and
+never the position:
+
+```js
+level.load("map1");
+app.world.sortOn = "y";
+for (const child of app.world.getChildren()) {
+    child.sortOffset = child.height;   // sort by the bottom of each image
+}
+```
+
+A character you create in code follows the same convention as the scenery: by
+the top of a frame as tall as the scenery's (`anchorPoint` `(0, 0)`), or by its
+feet when everything sorts by the bottom.
+
+Two equal positions keep insertion order, and the one added **last** is drawn
+**behind**: a decoration placed at its wall's exact position disappears. Give
+it `sortOffset = 1`. A `Container` or a particle emitter is sorted by its top
+left corner (an emitter's by the top of its spawn area); give it the offset to
+the point it belongs with, such as `door.pos.y - dust.pos.y`.
+
 ## Image layers
 
 `ImageLayer` gives parallax backgrounds with a ratio per axis, set in Tiled or in
@@ -241,7 +353,17 @@ unanimated layer into the offscreen-bake path instead.
 | `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"` |
+| a character is always in front of (or behind) every wall | the walls are on a tile layer, or on another object layer than the character: each layer has its own `z`, compared before `y` |
+| a small prop draws over a character standing in front of it | images of different heights: the y-sort uses `pos.y`, the top of a Tiled object's image. Pad the art, or set `sortOffset = height` on every object to sort by the bottom |
+| a decoration placed at the same position as a wall disappears behind it | a tie keeps insertion order and draws the later one behind: `sortOffset = 1` |
+| particles (or a container) at the foot of something draw over a character standing in front of it | they sort by the top of their spawn area (or the container's top left): set `sortOffset` to line them up with what they belong to |
+| a character is stopped short of walls and props placed as tile objects | it collides with their default bodies (static, `ENEMY_OBJECT`, the whole image box); mask it to `collision.types.WORLD_SHAPE` when the collision layer holds the real shapes |
+| a property set on a tile is undefined on the object's `settings` | tile properties are not copied onto `settings`: read them with `settings.resolvedProperty(name)` |
+| objects placed from a classed tile come out as plain sprites | that class is not registered, it is a built-in name, or the object has a class or a registered name of its own, which come first |
 | missing tiles or a blank map | the `.tsx` or tileset image was not preloaded |
+| a tileset's transparent color (`trans`) still shows (the console says it could not be applied) | the image cannot be read back: one from another origin needs CORS headers on the server and `loader.setOptions({ crossOrigin: "anonymous" })` (without them WebGL and WebGPU cannot draw it at all), and a compressed texture cannot be changed: export it with an alpha channel instead |
+| changing tiles at runtime is slow on a pre-rendered layer | outside an orthogonal map whose tiles fit their cells, a changed tile re-bakes the whole layer before it next draws: keep layers you edit often off `preRender` |
+| thin lines between tiles on the Canvas renderer, with smoothing on | filtering blends in the next tile of the tileset or its spacing, which a canvas cannot prevent: set `antiAlias: false`, or `preRender` the layer. WebGL and WebGPU keep each tile to itself |
 | tilemap slow on some machines | layer fell back off the shader path — check the console warning for the reason |
 
 ## Related skills