Merge pull request #1323 from melonjs/feature/tilerendersize-fillmode

Support Tiled 1.9+ tilerendersize/fillmode, bump to 1.10

Author: obiot

README.md

@@ -81,7 +81,7 @@ UI
 - Text buttons with built-in styling
 
 Level Editor
-- [Tiled](https://www.mapeditor.org) map format version +1.0 built-in support for easy level design
+- [Tiled](https://www.mapeditor.org) map format [up to 1.10+](https://doc.mapeditor.org/en/stable/reference/tmx-changelog/) built-in support for easy level design
     - 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 and Hexagonal maps (both normal and staggered)
     - Multiple layers (multiple background/foreground, collision and Image layers)

packages/melonjs/CHANGELOG.md

@@ -12,6 +12,7 @@
 - TMX: support Tiled 1.12+ per-object opacity and visibility
 - TMX: support Tiled 1.12+ layer blend modes (`mode` attribute on tile layers, image layers, and object groups)
 - TMX: support Tiled 1.9+ tile sub-rectangles (`x`, `y`, `width`, `height` on `<tile>` elements for defining sub-regions within a tileset image)
+- TMX: support Tiled 1.9+ `tilerendersize` and `fillmode` tileset attributes for controlling how oversize tiles render relative to the map grid
 - CanvasRenderer: add support for additional CSS blend modes (`overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`) when supported by the browser
 - WebGLRenderer: add `darken` and `lighten` blend modes via `gl.MIN`/`gl.MAX` (WebGL2 only)
 

packages/melonjs/src/level/tiled/TMXTileMap.js

@@ -100,8 +100,8 @@ function readImageLayer(map, data, z) {
  * read the tileset Data
  * @ignore
  */
-function readTileset(data) {
-	return new TMXTileset(data);
+function readTileset(data, mapTilewidth, mapTileheight) {
+	return new TMXTileset(data, mapTilewidth, mapTileheight);
 }
 
 /**
@@ -307,7 +307,9 @@ export default class TMXTileMap {
 		if (typeof data.tilesets !== "undefined") {
 			const tilesets = data.tilesets;
 			for (let i = 0, len = tilesets.length; i < len; i++) {
-				this.tilesets.add(readTileset(tilesets[i]));
+				this.tilesets.add(
+					readTileset(tilesets[i], this.tilewidth, this.tileheight),
+				);
 			}
 		}
 

packages/melonjs/src/level/tiled/TMXTileset.js

@@ -11,8 +11,10 @@ import { renderer } from "../../video/video.js";
 export default class TMXTileset {
 	/**
 	 *  @param {object} tileset - tileset data in JSON format ({@link http://docs.mapeditor.org/en/stable/reference/tmx-map-format/#tileset})
+	 *  @param {number} [mapTilewidth] - the map's tile grid width in pixels
+	 *  @param {number} [mapTileheight] - the map's tile grid height in pixels
 	 */
-	constructor(tileset) {
+	constructor(tileset, mapTilewidth, mapTileheight) {
 		/**
 		 * per-tile properties indexed by gid
 		 * @type {Map<number, object>}
@@ -103,10 +105,70 @@ export default class TMXTileset {
 		this.isCollection = false;
 
 		/**
-		 * the tileset class (since Tiled 1.9)
+		 * the tileset class (since Tiled 1.9, renamed back to type on tile/object in 1.10)
 		 * @type {string}
 		 */
-		this.class = tileset.class;
+		this.class = tileset.class ?? tileset.type;
+
+		/**
+		 * how tiles render relative to the grid (since Tiled 1.9)
+		 * @type {string}
+		 * @default "tile"
+		 */
+		this.tilerendersize = tileset.tilerendersize ?? "tile";
+
+		/**
+		 * fill mode when tiles are not rendered at native size (since Tiled 1.9)
+		 * @type {string}
+		 * @default "stretch"
+		 */
+		this.fillmode = tileset.fillmode ?? "stretch";
+
+		/**
+		 * the map's tile grid width (used for tilerendersize="grid")
+		 * @type {number}
+		 * @ignore
+		 */
+		this.mapTilewidth = mapTilewidth ?? this.tilewidth;
+
+		/**
+		 * the map's tile grid height (used for tilerendersize="grid")
+		 * @type {number}
+		 * @ignore
+		 */
+		this.mapTileheight = mapTileheight ?? this.tileheight;
+
+		/**
+		 * precomputed render scale for tilerendersize="grid" (spritesheet only)
+		 * @private
+		 */
+		this._renderScaleX = 1;
+		this._renderScaleY = 1;
+		this._renderDw = this.tilewidth;
+		this._renderDh = this.tileheight;
+		this._renderDyOffset = 0;
+		this._renderDxCenter = 0;
+		this._renderDyCenter = 0;
+
+		if (this.tilerendersize === "grid") {
+			this._renderScaleX = this.mapTilewidth / this.tilewidth;
+			this._renderScaleY = this.mapTileheight / this.tileheight;
+
+			if (this.fillmode === "preserve-aspect-fit") {
+				const minScale = Math.min(this._renderScaleX, this._renderScaleY);
+				this._renderScaleX = minScale;
+				this._renderScaleY = minScale;
+			}
+
+			this._renderDw = this.tilewidth * this._renderScaleX;
+			this._renderDh = this.tileheight * this._renderScaleY;
+			this._renderDyOffset = this.tileheight - this._renderDh;
+
+			if (this.fillmode === "preserve-aspect-fit") {
+				this._renderDxCenter = (this.mapTilewidth - this._renderDw) / 2;
+				this._renderDyCenter = -(this.mapTileheight - this._renderDh) / 2;
+			}
+		}
 
 		/**
 		 * per-tile sub-rectangles (Tiled 1.9+), indexed by local tile id
@@ -401,6 +463,43 @@ export default class TMXTileset {
 	 * @ignore
 	 */
 	drawTile(renderer, dx, dy, tmxTile) {
+		let dw, dh;
+
+		if (this.isCollection) {
+			// collection tiles can have varying sizes; compute scale per-tile
+			if (this.tilerendersize === "grid") {
+				let scaleX = this.mapTilewidth / tmxTile.width;
+				let scaleY = this.mapTileheight / tmxTile.height;
+
+				if (this.fillmode === "preserve-aspect-fit") {
+					const scale = Math.min(scaleX, scaleY);
+					scaleX = scale;
+					scaleY = scale;
+				}
+
+				dw = tmxTile.width * scaleX;
+				dh = tmxTile.height * scaleY;
+
+				// bottom-align against tileset baseline (renderer uses tileset.tileheight)
+				dy += this.tileheight - dh;
+
+				if (this.fillmode === "preserve-aspect-fit") {
+					dx += (this.mapTilewidth - dw) / 2;
+					dy -= (this.mapTileheight - dh) / 2;
+				}
+			} else {
+				dw = tmxTile.width;
+				dh = tmxTile.height;
+			}
+		} else {
+			// spritesheet: use precomputed values
+			dw = this._renderDw;
+			dh = this._renderDh;
+			dy += this._renderDyOffset;
+			dx += this._renderDxCenter;
+			dy += this._renderDyCenter;
+		}
+
 		// check if any transformation is required
 		if (tmxTile.flipped) {
 			renderer.save();
@@ -422,8 +521,8 @@ export default class TMXTileset {
 				tmxTile.height,
 				dx,
 				dy,
-				tmxTile.width,
-				tmxTile.height,
+				dw,
+				dh,
 			);
 		} else {
 			// use the tileset texture atlas
@@ -436,8 +535,8 @@ export default class TMXTileset {
 				this.tileheight,
 				dx,
 				dy,
-				this.tilewidth + renderer.uvOffset,
-				this.tileheight + renderer.uvOffset,
+				dw + renderer.uvOffset,
+				dh + renderer.uvOffset,
 			);
 		}
 

packages/melonjs/src/level/tiled/constants.js

@@ -1,5 +1,5 @@
 // latest supported Tiled map format version
-export const TILED_SUPPORTED_VERSION = "1.9";
+export const TILED_SUPPORTED_VERSION = "1.10";
 
 // bitmask constants to check for flipped & rotated tiles
 export const TMX_FLIP_H = 0x80000000;

packages/melonjs/tests/tmxrenderer.spec.js

@@ -1,13 +1,31 @@
 import { beforeAll, describe, expect, it } from "vitest";
-import { boot } from "../src/index.js";
+import { boot, video } from "../src/index.js";
 import TMXHexagonalRenderer from "../src/level/tiled/renderer/TMXHexagonalRenderer.js";
 import TMXIsometricRenderer from "../src/level/tiled/renderer/TMXIsometricRenderer.js";
 import TMXOrthogonalRenderer from "../src/level/tiled/renderer/TMXOrthogonalRenderer.js";
 import TMXStaggeredRenderer from "../src/level/tiled/renderer/TMXStaggeredRenderer.js";
+import Tile from "../src/level/tiled/TMXTile.js";
+import TMXTileset from "../src/level/tiled/TMXTileset.js";
+import { imgList } from "../src/loader/cache.js";
+
+// helper to create a fake image in the loader cache
+function fakeImage(name, w = 64, h = 64) {
+	const canvas = document.createElement("canvas");
+	canvas.width = w;
+	canvas.height = h;
+	imgList[name] = canvas;
+	return canvas;
+}
 
 describe("TMX Renderers", () => {
 	beforeAll(() => {
 		boot();
+		video.init(128, 128, {
+			parent: "screen",
+			scale: "auto",
+			renderer: video.AUTO,
+		});
+		fakeImage("drawtest", 256, 256);
 	});
 
 	// mock map object for constructors
@@ -203,4 +221,154 @@ describe("TMX Renderers", () => {
 			expect(result1.y).toEqual(result2.y);
 		});
 	});
+
+	// ==============================================================
+	// drawTile with tilerendersize/fillmode across renderers
+	// ==============================================================
+	describe("drawTile with tilerendersize/fillmode", () => {
+		// spy renderer that captures drawImage calls
+		function spyRenderer() {
+			const calls = [];
+			return {
+				calls,
+				drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh) {
+					calls.push({ sx, sy, sw, sh, dx, dy, dw, dh });
+				},
+				save() {},
+				restore() {},
+				translate() {},
+				transform() {},
+				uvOffset: 0,
+			};
+		}
+
+		// create a tileset with given overrides and map grid size
+		function makeTileset(overrides, mapTw, mapTh) {
+			return new TMXTileset(
+				{
+					firstgid: 1,
+					name: "drawtest",
+					tilewidth: 48,
+					tileheight: 48,
+					spacing: 0,
+					margin: 0,
+					tilecount: 16,
+					columns: 4,
+					image: "drawtest.png",
+					...overrides,
+				},
+				mapTw,
+				mapTh,
+			);
+		}
+
+		describe("TMXOrthogonalRenderer.drawTile", () => {
+			it("should draw oversize tile at native size with tilerendersize='tile'", () => {
+				const ts = makeTileset({}, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const ortho = new TMXOrthogonalRenderer(mockMap());
+				ortho.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				// native tile size: 48x48
+				expect(spy.calls[0].dw).toEqual(48);
+				expect(spy.calls[0].dh).toEqual(48);
+			});
+
+			it("should scale tile to grid size with tilerendersize='grid' stretch", () => {
+				const ts = makeTileset({ tilerendersize: "grid" }, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const ortho = new TMXOrthogonalRenderer(mockMap());
+				ortho.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toBeCloseTo(32);
+				expect(spy.calls[0].dh).toBeCloseTo(32);
+			});
+
+			it("should use uniform scale with preserve-aspect-fit", () => {
+				// 48x48 tile on 32x16 grid → min(32/48, 16/48) = 1/3
+				const ts = makeTileset(
+					{ tilerendersize: "grid", fillmode: "preserve-aspect-fit" },
+					32,
+					16,
+				);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const ortho = new TMXOrthogonalRenderer(
+					mockMap({ tilewidth: 32, tileheight: 16 }),
+				);
+				ortho.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toBeCloseTo(16);
+				expect(spy.calls[0].dh).toBeCloseTo(16);
+			});
+		});
+
+		describe("TMXIsometricRenderer.drawTile", () => {
+			it("should draw at native size with tilerendersize='tile'", () => {
+				const ts = makeTileset({}, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const iso = new TMXIsometricRenderer(
+					mockMap({ orientation: "isometric" }),
+				);
+				iso.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toEqual(48);
+				expect(spy.calls[0].dh).toEqual(48);
+			});
+
+			it("should scale tile to grid size with tilerendersize='grid'", () => {
+				const ts = makeTileset({ tilerendersize: "grid" }, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const iso = new TMXIsometricRenderer(
+					mockMap({ orientation: "isometric" }),
+				);
+				iso.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toBeCloseTo(32);
+				expect(spy.calls[0].dh).toBeCloseTo(32);
+			});
+		});
+
+		describe("TMXHexagonalRenderer.drawTile", () => {
+			it("should draw at native size with tilerendersize='tile'", () => {
+				const ts = makeTileset({}, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const hex = new TMXHexagonalRenderer(
+					mockMap({
+						orientation: "hexagonal",
+						hexsidelength: 16,
+						staggeraxis: "y",
+						staggerindex: "odd",
+					}),
+				);
+				hex.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toEqual(48);
+				expect(spy.calls[0].dh).toEqual(48);
+			});
+
+			it("should scale tile to grid size with tilerendersize='grid'", () => {
+				const ts = makeTileset({ tilerendersize: "grid" }, 32, 32);
+				const tile = new Tile(0, 0, 1, ts);
+				const spy = spyRenderer();
+				const hex = new TMXHexagonalRenderer(
+					mockMap({
+						orientation: "hexagonal",
+						hexsidelength: 16,
+						staggeraxis: "y",
+						staggerindex: "odd",
+					}),
+				);
+				hex.drawTile(spy, 0, 0, tile);
+				expect(spy.calls.length).toEqual(1);
+				expect(spy.calls[0].dw).toBeCloseTo(32);
+				expect(spy.calls[0].dh).toBeCloseTo(32);
+			});
+		});
+	});
 });