Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions packages/melonjs/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Changelog

## [20.17.0] (melonJS 2) - _unreleased_

### Added
- Transitions: a mask transition can be shaped like an image or a `Sprite`, close on the player with `center`, and fill the shape with `invert`, on `state.transition`, `MaskEffect` and `Trigger` ([#1399](https://github.com/melonjs/melonJS/issues/1399))

### Fixed
- `NineSliceSprite` blinks with `flicker()`, as a `Sprite` does; it ignored it

## [20.16.0] (melonJS 2) - _2026-11-17_

**Highlights:** a faster `Camera3d`, its work per frame up to **72%** faster with no change to your game, and real 3D physics: with the new `@melonjs/rapier3d-adapter`, bodies tumble, stack and topple in 3D, with collision shapes built straight from your models. Also new: skinned glTF characters with crossfades, mesh picking, an orthographic `Camera3d` for isometric views, and toon shading with outlines. The new features are opt-in: a game that sets none of them renders as before.
Expand Down
2 changes: 1 addition & 1 deletion packages/melonjs/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "melonjs",
"version": "20.16.0",
"version": "20.17.0",
"description": "A modern & fully featured HTML5 game engine (2D & 3D) for JavaScript/TypeScript, with WebGL/WebGPU rendering, built-in physics, Tiled map & glTF support and WebAudio.",
"homepage": "https://www.melonjs.org/",
"type": "module",
Expand Down
27 changes: 24 additions & 3 deletions packages/melonjs/skills/melonjs-camera-and-drawing/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: melonjs-camera-and-drawing
description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, zoom, roll, shake, fadeIn, fadeOut, CameraEffect, addCameraEffect, MaskEffect, PixelateTransitionEffect, worldToLocal, localToWorld, worldToScreen, screenToRay, screenToWorld, colorMatrix, renderer.fill, renderer.stroke, setGlobalAlpha, fillArc, Rect, Ellipse, Polygon, Line, Path2D, SVG path, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, orbit, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
description: "Use this skill for camera control and immediate-mode drawing in melonJS — following a target, viewport bounds, shake and fade, secondary cameras and what each one draws, and drawing shapes, lines and gradients inside a custom draw(). Covers world versus screen coordinate conversion, clipping and masking, baking with CanvasRenderTarget, and reading pixels back. Triggers on: Camera2d, viewport, follow, offset, look ahead, setBounds, minimap, second camera, split screen, cullMask, visibilityLayer, hide from a camera, zoom, roll, shake, fadeIn, fadeOut, CameraEffect, addCameraEffect, MaskEffect, iris, image mask, PixelateTransitionEffect, worldToLocal, localToWorld, worldToScreen, screenToRay, screenToWorld, colorMatrix, renderer.fill, renderer.stroke, setGlobalAlpha, fillArc, Rect, Ellipse, Polygon, Line, Path2D, SVG path, Gradient, clipRect, mask, CanvasRenderTarget, NoiseTexture2d, lookAt, setBasis, orbit, toImageData, getImageData, toBlob, toDataURL, screenshot, read pixels."
license: MIT
---

Expand Down Expand Up @@ -153,13 +153,32 @@ returns it), found with `getCameraEffect(Class)` and taken off with
|---|---|---|
| `ShakeEffect` | `intensity`, `duration`, `axis`, `onComplete` | jitters `offset`; what `shake()` adds. Several can run at once this way |
| `FadeEffect` | `color`, `duration` (1000), `direction: "in" \| "out"`, `onComplete` | what `fadeIn()` / `fadeOut()` add |
| `MaskEffect` | `shape`, `color`, `duration` (500), `direction: "hide" \| "reveal"`, `onComplete` | an iris or a wipe through a unit-sized `Ellipse` or `Polygon` centred on the origin |
| `MaskEffect` | `shape`, `color`, `duration` (500), `direction: "hide" \| "reveal"`, `center`, `invert`, `onComplete` | an iris (the default) or a wipe through a unit-sized `Ellipse` or `Polygon`, an image's silhouette (the image, or a preloaded one's name) or a `Sprite`'s current frame (a `NineSliceSprite` at its full size), closing on `center` (a renderable or a screen point; the screen's centre by default). `invert` fills the shape instead and grows it to cover. Plain images and fills: the same on Canvas, WebGL and WebGPU |
| `PixelateTransitionEffect` | `renderer`, `size` (32), `duration` (500), `direction: "hide" \| "reveal"`, `onComplete` | the view breaks into blocks up to `size` screen pixels, or comes back from them. A shader: on Canvas it keeps its timing and draws nothing |

```js
// the player's own silhouette closing on the player, then a heart image
// growing out of it until it covers the screen
camera.addCameraEffect(new MaskEffect(camera, {
shape: player, center: player, color: "#000", duration: 500,
}));
camera.addCameraEffect(new MaskEffect(camera, {
shape: "heart_mask", center: player, invert: true, color: "#000", duration: 400,
}));
```

A sprite or renderable is read once, when the effect is made: its frame, its
facing and its place on screen (not its scale or rotation: the shape is grown
to the screen's size anyway). The shape grows about its thickest part, which
sits on `center`. An image is read through a canvas, so a compressed texture
or a cross-origin image without CORS cannot shape a mask (it warns and uses an
iris).

`state.transition("fade" | "mask" | "pixelate", …)` drives the last three
for a state change (see `melonjs-scenes-and-state`). A `Trigger` that loads a
level transitions only with both a `color` and a `duration`, and takes only
`transition: "fade"` (the default) or `"mask"` with a `shape`: anything else,
`transition: "fade"` (the default) or `"mask"` with a `shape` (and `center`,
`invert`; `"touching"` for either is whoever walked in): anything else,
`"pixelate"` included, is a fade.

For an effect of your own, extend `CameraEffect`: `update(dt)` runs every
Expand Down Expand Up @@ -539,6 +558,8 @@ const data = await rt.toImageData(0, 0, w, h);
| a second `shake()` does nothing | one is still running: pass `force` (the fifth argument) to replace it |
| a `Trigger` with `transition: "pixelate"` fades instead | a trigger takes only `"fade"` or `"mask"`; add a `PixelateTransitionEffect` yourself |
| a `Trigger` loads its level with no transition | it needs both `color` and `duration` |
| an image or sprite `MaskEffect` is a plain circle, with a console warning | the shape could not be used: an unknown image name, a compressed texture, a cross-origin image without CORS, a fully transparent image or frame, a destroyed sprite, a renderable that is not a `Sprite`, or a value that is not a shape at all |
| a `MaskEffect` closes on the middle of the screen | it closes on `center`, the screen's centre by default: pass the renderable or point |
| a `rotate()` or `scale()` on the camera is lost | `roll` owns the camera's `currentTransform` and rebuilds it; use `roll` and `zoom` |
| an SVG path from an editor comes out scrambled | `parseSVGPath` reads absolute commands only, and `H` / `V` as offsets |
| a hole in a path fills in, on Canvas only | it is wound the same way as the outline; wind it the opposite way |
Expand Down
38 changes: 32 additions & 6 deletions packages/melonjs/skills/melonjs-scenes-and-state/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: melonjs-scenes-and-state
description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, pixelate, Trigger transition, retry level, play again, restart, state.reload, state.pause, pauseOnBlur, resumeOnFocus, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze, setFocusEvents, focusEvents, host or portal pause, YouTube Playables onPause, save, save.add, setStorage, createCloudStorage, flush, localStorage, cloud save, high score persistence."
description: "Use this skill for scene structure and game flow in melonJS — Stage subclasses, the state manager, transitions, pausing, the update loop, timers and tweens. Covers onResetEvent versus the constructor, state.set before state.change, the camera and world lifecycle per stage, and pause-aware timing. Triggers on: Tween, easing, fade out, flash, pulse, punch, shrink back, ease in, ease out, animate over time, countdown in update, Stage, state, state.set, state.change, state.transition, pixelate, iris, star wipe, Trigger transition, retry level, play again, restart, state.reload, state.pause, pauseOnBlur, resumeOnFocus, onResetEvent, onDestroyEvent, onActivateEvent, onDeactivateEvent, PLAY, MENU, LOADING, update loop, GAME_UPDATE, timer, setTimeout, setInterval, Tween, freeze, setFocusEvents, focusEvents, host or portal pause, YouTube Playables onPause, save, save.add, setStorage, createCloudStorage, flush, localStorage, cloud save, high score persistence."
license: MIT
---

Expand Down Expand Up @@ -133,6 +133,9 @@ included (before 20.13 the children's bodies were dropped by the reset).
```js
state.transition("fade", "#FFFFFF", 250);
state.transition("mask", "#000", 500, new Ellipse(0, 0, 1, 1)); // shape required
state.transition("mask", "#000", 500, "star_mask"); // a preloaded image's silhouette
state.transition("mask", "#000", 500, player, { center: player }); // the player's shape, closing on it
state.transition("mask", "#000", 400, new Ellipse(0, 0, 1, 1), { center: player, invert: true });
state.transition("pixelate", "#000", 300); // blocks up to 32px; a 4th argument sets the size
state.pause(); // freeze update, keep drawing
state.resume();
Expand All @@ -143,18 +146,39 @@ app.freeze(150); // brief hit-stop (proxies state.fr
`state.change`; `state.setTransition(id, false)` turns it off for changes
into one state.
The duration (1000 ms when omitted) is for each half: the cover, then the
reveal. The `"mask"` form needs its fourth argument, an `Ellipse` or
`Polygon`; without one it warns and falls back to a direct switch. The
reveal. The `"mask"` form needs its fourth argument, the shape: an `Ellipse`
or `Polygon` (unit-sized, centred on the origin), an image or the name of a
preloaded one (its silhouette: transparent pixels are covered, the rest shows
the scene; colours do not matter and gaps inside the outline are filled), or a
`Sprite` (the silhouette of the frame it shows, facing its way). Without a
shape it warns and falls back to a direct switch. Its fifth argument is
`{ center, invert }`: `center` is where the shape closes and the reveal opens,
a renderable (where it is drawn on screen as the transition starts) or a
screen point, the centre of the screen by default; `invert: true` makes the
shape the cover, filled with the colour and growing out of `center`. The
shape grows about its thickest part (a U or a sprite drawn off-centre in its
frame too), until the screen is wholly inside it, so the reveal ends with the
scene uncovered.

A sprite or renderable given here is read when the transition starts, and
the reveal reuses what the hide read, so the old stage destroying the player
in between is fine. It is then let go: the transition is sticky, but one
level's player is not the next one's, so later changes are an iris on the
centre of the screen until you set it again. Give it this level's player
right before each `state.change`. The
`"pixelate"` form breaks the screen up into blocks (its fourth argument is the
largest block size in pixels; the color is not used). It is a shader effect,
so on Canvas it does nothing and the state changes directly.

A level change is not a state change, so `state.transition` does not apply to
it. A Tiled `Trigger` that loads a level has a transition of its own, set on
the trigger: `color` and `duration` (both needed, or the level loads with
none), and `transition: "fade"` (the default) or `"mask"` with a `shape`.
A `"mask"` without a `shape` fades instead, without a warning, and there is
no pixelate form for a trigger. See `melonjs-tilemaps`.
none), and `transition: "fade"` (the default) or `"mask"` with a `shape`,
plus `center` and `invert` as above. On a trigger, `shape: "touching"` and
`center: "touching"` mean whoever walked in: the player's own silhouette
closing on the player, with no code to find it. A `"mask"` without a `shape`
fades instead, without a warning, and there is no pixelate form for a
trigger. See `melonjs-tilemaps`.

A `state.change` asked for while a transition covers the screen (Enter pressed
twice on a menu, a timer firing as the player skips a screen) needs no guard:
Expand Down Expand Up @@ -571,6 +595,8 @@ When `setStorage()` switches storage:
| a host's pause does nothing, after turning `pauseOnBlur` off so the tab would not pause the game | the flags apply to every `event.BLUR`, the host's included; keep them, and stop the window reporting with `device.setFocusEvents(false)` |
| `Undefined Stage for state 'N'` thrown | no `state.set` for that id first |
| `state.change(state.PLAY)` from `PLAY` does nothing ("Retry" ignored) | a change to the current state is a no-op — `state.reload()` (20.16), `level.reload()` for the map alone |
| a mask transition closes on the middle of the screen, not on the player | pass `{ center: player }` as the fifth argument; on a `Trigger`, `center: "touching"` |
| the first mask transition is the player's shape, later ones a plain iris on the middle of the screen | a sprite or renderable given to `state.transition` is used by one transition, then let go: set it again, with this level's player, right before each `state.change` |
| a level change through a `Trigger` ignores `state.transition` | it is a level change, not a state change: set `color` and `duration` (and `transition`) on the trigger |
| the game stops updating for good after one very slow update, such as a heavy first frame (20.12 and 20.13) | the loop could no longer save enough time to step the world: update |
| the game resumes under its own pause menu after a tab switch (before 20.9) | focus undid any pause; update, only the blur pause is undone |
Expand Down
10 changes: 10 additions & 0 deletions packages/melonjs/skills/melonjs-tilemaps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,16 @@ knowing before you spend an afternoon on a map that loads at the wrong scale.
`async` is excluded deliberately — the trigger needs to sequence its own
transition.

That transition is the trigger's own, and every part of it can be a property
of the trigger object in Tiled, with no code: `color` and `duration` (both, or
there is none), `transition` (`"fade"` or `"mask"`), and for a mask `shape`,
`center` and `invert`. A `shape` property is text, so it names a preloaded
image (its silhouette) or is `"touching"`; `center: "touching"` closes the
mask on whoever walked in. So a door that closes the player's own silhouette
onto the player is the properties `transition = mask`, `shape = touching`,
`center = touching`, `color = #000`, `duration = 400`. See
`melonjs-scenes-and-state` for the shapes and what `invert` does.

## Reading and changing tiles at run time

A tile layer is a live grid, not just a picture: read it as the game board,
Expand Down
4 changes: 3 additions & 1 deletion packages/melonjs/skills/melonjs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,9 @@ check for:
- **Art:** `TextureAtlas` (TexturePacker, ShoeBox, Aseprite),
`CanvasRenderTarget` for bake-once drawing, `NoiseTexture2d`.
- **Game flow:** `state.transition()` (`"fade"`, `"mask"` or `"pixelate"`)
between screens, `state.pause()` / `state.resume()` behind a pause menu,
between screens, with a mask shaped like an image or the player's own sprite
and closing on the player (`center`), and a `Trigger`'s own transition for a
level door (`shape: "touching"`, `center: "touching"`), `state.pause()` / `state.resume()` behind a pause menu,
`save` for localStorage-backed persistence, `createPool` / `getPool` for
recycling.
- **Levels:** Tiled tile layers read and changed with `cellAt` / `setTile`,
Expand Down
Loading
Loading