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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ melonJS is designed so you can **focus on making games, not on graphics plumbing

- **Complete engine, minimal footprint** — Physics, tilemaps, audio, input, cameras, tweens, particles, UI — a full game stack in a single tree-shakeable ES module. No dependency sprawl, no library stitching.

- **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, animated tilesets, collision shapes, object properties, compressed formats, with GPU-accelerated tile rendering on the GPU backends — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.
- **Scenes, loaded in one call** — `level.load(name)` brings an authored scene straight into your world. [Tiled](https://www.mapeditor.org) is a first-class citizen for **2D** — orthogonal, isometric, hexagonal & staggered maps, all four rendered on the GPU (a whole tile layer in a single draw, on WebGPU and WebGL 2), animated tilesets, collision shapes, object properties, compressed formats — and **glTF / GLB** is the equivalent for **3D scenes**: author in Blender (or any DCC tool), export a `.glb`, and the whole scene — meshes, materials, cameras, lights, and node animation — loads under a `Camera3d`, no per-mesh wiring. Animated models play back through the same animation API as a 2D `Sprite`.

- **Batteries included, hackable by design** — Get started in minutes with minimal setup. When you need to go deeper: modern class-based architecture, a plugin system for engine extensions, and a clean architecture that's easy to extend without fighting the framework.

Expand Down Expand Up @@ -117,7 +117,7 @@ UI
Scenes
- Load a scene in one call with `level.load(name)` — 2D Tiled maps and 3D glTF scenes alike, auto-registered on preload
- [Tiled](https://www.mapeditor.org) map format [up to 1.12](https://doc.mapeditor.org/en/stable/reference/tmx-changelog/) built-in support for easy level design
- **GPU-accelerated tile rendering** for orthogonal maps on the GPU backends (WebGL 2 and WebGPU) — each layer draws as a single quad with no per-tile loop, ~5–8× faster than the legacy CPU renderer on dense maps. Honors animated tiles, flip bits, per-layer opacity/tint/blend, and oversized bottom-aligned tiles; falls back transparently to the CPU renderer on isometric/staggered/hexagonal layers or under the Canvas renderer
- **GPU-accelerated tile rendering** for orthogonal, isometric, staggered and hexagonal maps on the GPU backends (WebGL 2 and WebGPU) — each layer draws as a single quad with no per-tile loop, so its cost on the main thread stays flat however many tiles are in view: 85% to 98% less than the CPU renderer on a dense map. Honors animated and flipped tiles, per-layer opacity and tint, tiles larger than the grid and tileset offsets, and `setTile` at run time; falls back transparently to the CPU renderer for a layer it cannot draw (the console says why), on oblique maps and under the Canvas renderer
- Uncompressed and [compressed](https://github.com/melonjs/melonJS/tree/master/packages/tiled-inflate-plugin) Plain, Base64, CSV and JSON encoded XML tilemap loading
- Orthogonal, Isometric, Hexagonal (both normal and staggered) and Oblique maps
- Multiple layers with per-layer alpha, tinting and blend modes (multiple background/foreground, collision and Image layers)
Expand Down
11 changes: 11 additions & 0 deletions packages/melonjs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,19 @@

### 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))
- Tiled: isometric maps are rendered by the GPU on WebGL and WebGPU, as orthogonal ones are, and so are staggered and hexagonal maps. Nothing to enable: a tile layer whose tiles come from one tileset takes it by itself, and any other is drawn as before, the console saying why ([#1897](https://github.com/melonjs/melonJS/issues/1897))

### Performance
- Tiled: thanks to the GPU renderer, drawing an isometric tile layer takes about **90%** less of the main thread's time with 1200 tiles in view (0.68 to 0.07 ms a frame) and about **98%** less with 4000 (2.0 to 0.04 ms), and no longer grows with the number of tiles shown. Staggered and hexagonal maps gain the same
- Tiled: for reference, orthogonal tile layers, on the GPU since 19.4, measure about **85%** less with 1000 tiles in view (0.62 to 0.09 ms) and about **97%** less with 3600 (1.9 to 0.06 ms)

### Fixed
- Tiled: a tile layer follows its offset in Tiled, and its own `pos` when the game moves it: its tiles are drawn there, and `getTile()` finds them there. Both were ignored; a map whose tile layers have an offset now looks as it does in Tiled
- Tiled: tiles larger than a cell are drawn wherever they are in view. They were cut off or left out along the edges of the view, above and right of the map, on a map centred in the screen, and once the map itself had scrolled out of view
- Tiled: staggered and hexagonal maps are drawn where Tiled draws them: a tile larger than its cell stands on it, a tileset's `tileoffset` moves its tiles, and maps of odd sizes stay on whole pixels
- Tiled: orthogonal layers drawn by the GPU show the soft edges of large tiles over the tiles behind them, lay large tiles over each other in the map's order, and read a tileset with a `margin` right
- Tiled: an isometric, staggered or hexagonal layer with an `opacity` below 1 fades as one picture on WebGL and WebGPU; each tile showed through the one in front of it
- Tiled: a tile layer removed from its container and added again, and a tile missing from its tileset's image, no longer throw
- `NineSliceSprite` blinks with `flicker()`, as a `Sprite` does; it ignored it
- Text: a stroked multi-line label with `textBaseline: "hanging"` keeps the top of its outline on macOS, where Helvetica's hanging metrics made the ink padding exactly as tall as the ink, shearing its first row off the canvas ([#1870](https://github.com/melonjs/melonJS/issues/1870))
- glTF: a model compressed with Draco or meshopt, which the loader cannot decode, says so in the console, naming the extension, instead of failing on an accessor error that did not mention it
Expand Down
51 changes: 46 additions & 5 deletions packages/melonjs/skills/melonjs-tilemaps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,17 @@ collision: solid ground comes from collision object layers (below), so a tile
set or cleared changes what is drawn and what `cellAt` returns, not what a body
runs into. Keep a layer you edit often off `preRender` (see the symptom table).
A tile layer moves with its `pos`. It starts where its offset in Tiled puts
it (Layer → Offset), and the game moves it from there; its tiles are drawn
where it is, and `getTile(x, y)` answers for where they are drawn. Move it
by a difference, not to a point: `pos` is not (0, 0) to begin with on every
map (an infinite one, an oblique one).
```js
board.pos.y -= 8; // the whole layer, 8 pixels up
board.getTile(pointer.x, pointer.y); // still the tile under the pointer
```
The map's own custom properties (Map → Map Properties in Tiled) are set on the
map object, which `level.getCurrentLevel()` returns once it is loaded: a
`theme` string property is `level.getCurrentLevel().theme`. They are set
Expand Down Expand Up @@ -453,11 +464,32 @@ per-pixel GID lookup in the fragment shader. It requires **all** of:

- a renderer that reports GPU tile-layer support (WebGL 2 / WebGPU — not Canvas),
- `world.gpuTilemap !== false` (the `gpuTilemap` application setting, default `true`),
- an **orthogonal** layer — isometric, hexagonal, staggered and oblique always
fall back,
- no collection-of-image tileset, no non-zero `tileoffset`, a tileset tile
render size of "Tile size" (`tilerendersize`, not "Map grid size"), and tile
overflow within the shader's 4-cell limit.
- an **orthogonal**, **isometric**, **staggered** or **hexagonal** layer —
oblique always falls back,
- no collection-of-image tileset, and a tileset tile render size of "Tile
size" (`tilerendersize`, not "Map grid size"),
- on an orthogonal map: no non-zero `tileoffset`, and tiles that reach at most
4 cells past their own; a layer of tiles **larger than a cell** takes them
from one tileset, on a map in the default render order ("right-down"),
- on an isometric, staggered or hexagonal map: every tile of the layer from
**one tileset** (tiles overlap, and their order is kept within a tileset,
not across two: split floor and walls into a layer each, which a map
usually does already), tiles at most 4 cells wide and 8 tall, a grid of
even size (64 × 32, not 65 × 33; a hexagon side of even length), and the
normal blend mode. A `tileoffset` is fine,
- no tile that is not square flipped diagonally (rotated, in Tiled), and no
more columns or rows than the largest texture has pixels (4096 on the
smallest devices).

A tile set at run time with `setTile` that breaks one of these moves the layer
back to `"perTile"`, with a warning. The two paths draw the same picture, with
one difference: a layer with `opacity` below 1 is faded as one flat picture on
the shader path (as `preRender` does), where tile by tile each tile is faded
over the ones behind it, which shows where tiles overlap.

The gain is main-thread time: tile by tile, every tile in view is found and
placed in JavaScript each frame (about 2 ms for 4000 tiles); the shader path
draws one quad whatever is in view.

When a layer falls back, melonJS `console.warn`s the reason each time the
layer is activated (once per page when the renderer has no GPU tile support at
Expand Down Expand Up @@ -508,7 +540,16 @@ layer into the offscreen-bake path instead.
| the level's `name` is not its id after loading | a map custom property named `name` replaced it: map properties are set over the map's own fields |
| 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 |
| a tile layer given an offset in Tiled (a roof nudged up, a shadow shifted) is drawn where the others are | before 20.17 a tile layer ignored its offset, and its `pos`; only image layers followed theirs: update |
| after updating to 20.17 a tile layer sits away from where it did | it has an offset in Tiled that was ignored until then, and now moves it as in the editor: clear the layer's Offset in Tiled if it was not meant |
| a map smaller than the screen (centred by `level.load`) had the tops of its tall tiles cut on WebGL or WebGPU | before 20.17 a layer read the camera's view as if it stood at the world's origin, and so did a layer in a container the game had moved: update |
| the tops of tall tiles vanish when the map itself scrolls out of view | before 20.17 a layer was skipped once its grid left the view, though tiles larger than a cell (or moved by a `tileoffset`) still reached in: update |
| an orthogonal layer warns `tiles larger than the grid, of more than one tileset in a layer` | tiles larger than a cell overlap, and the shader path keeps their order within one tileset: put each tileset's large tiles on a layer of their own (trees apart from the ground they stand on) |
| tilemap slow on some machines | layer fell back off the shader path — check the console warning for the reason |
| a staggered or hexagonal map sits higher than before 20.17, by how much its tiles are taller than a cell (or by its tileset's `tileoffset`) | it is drawn as Tiled draws it: until then a tile hung from the top of its cell and the offset was ignored, away from the map's objects |
| an isometric (staggered, hexagonal) layer warns `tiles of more than one tileset in an isometric layer` and is slow | the shader path draws such a layer with one tileset: put the tiles of each tileset on a layer of their own, or pack them into one tileset |
| a half-transparent isometric (staggered, hexagonal) layer of tall tiles looks flatter than before 20.17 | on the shader path a layer fades as one picture, and a tile no longer shows through the one in front: set that layer's `renderMode` to `"perTile"` (a `renderMode` custom property in Tiled) for the old look |
| the soft edges of tiles larger than the grid showed a thin dark outline on the shader path | before 20.17 the edge of such a tile was not blended over the tile behind it: update |
## Related skills
Expand Down
21 changes: 12 additions & 9 deletions packages/melonjs/src/application/settings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -476,15 +476,18 @@ export type ApplicationSettings = {
physic: PhysicsType;

/**
* Enable the GPU procedural shader path for orthogonal tile layers
* (backends advertising `renderer.supportsShaderTileLayers` — WebGL 2
* and WebGPU). When `true` (default), eligible layers render via a
* single quad per tileset + a fragment shader doing per-fragment GID
* lookup, bypassing the per-tile draw loop entirely. Layers that
* don't qualify (Canvas renderer, non-orthogonal,
* collection-of-image tilesets, tilerendersize "grid", non-zero
* tileoffset, oversampled beyond the shader's overflow window) fall
* back to the legacy path automatically.
* Enable the GPU procedural shader path for orthogonal, isometric,
* staggered and hexagonal tile layers (backends advertising
* `renderer.supportsShaderTileLayers` — WebGL 2 and WebGPU). When
* `true` (default), eligible layers render via a single quad per
* tileset + a fragment shader doing per-fragment GID lookup, bypassing
* the per-tile draw loop entirely. Layers that don't qualify fall
* back to the legacy path automatically, saying why in the console:
* among them the Canvas renderer, an oblique map, collection-of-image
* tilesets, tilerendersize "grid", tiles larger than the shader walks;
* on an orthogonal map a non-zero tileoffset; on the others tiles of
* several tilesets in one layer, a grid of odd size, or a blend mode
* other than the normal one.
* Set to `false` to disable globally.
* @default true
*/
Expand Down
10 changes: 8 additions & 2 deletions packages/melonjs/src/camera/camera2d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1091,8 +1091,14 @@ export default class Camera2d extends Renderable {
);
}
// non-floating objects use world coordinates, check against
// the camera's visible world area (accounts for position and zoom)
return obj.getBounds().overlaps(this.worldView);
// the camera's visible world area (accounts for position and zoom).
// What a renderable draws can reach past its bounds (a tile layer's
// tiles, taller than their cell, stand above its grid): it says so
// with `getDrawBounds`
const drawn = (
obj as Renderable & { getDrawBounds?: () => Bounds }
).getDrawBounds?.();
return (drawn ?? obj.getBounds()).overlaps(this.worldView);
}

/**
Expand Down
Loading
Loading