melonjs 20.10.1 → 20.11.0

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-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