Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(tilemap): honor tileset margin and spacing

esengine28dab612af52
diff --git a/desktop/package.json b/desktop/package.json
index a2e61ad85..13eefcccd 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -37,6 +37,7 @@
"verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:transform": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-transform.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-transform.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,255,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,0,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:multiset": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-multiset.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-multiset.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
+ "verify:render:tilemap:spacing": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-spacing.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-spacing.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:gidobj": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-gidobj.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-gidobj.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 ESTELLA_VERIFY_EXPECT='[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.5,\"y\":0.12,\"rgb\":[0,0,0],\"tol\":30},{\"x\":0.8125,\"y\":0.375,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.9375,\"y\":0.375,\"rgb\":[255,255,0],\"tol\":40},{\"x\":0.875,\"y\":0.8125,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.875,\"y\":0.9375,\"rgb\":[255,255,0],\"tol\":40}]' electron scripts/headless-verify.mjs",
"verify:render:material": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:ktx2": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ktx2-sprite.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ktx2-sprite.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,180,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",
diff --git a/desktop/public/scenes/tilemap-spacing.esscene b/desktop/public/scenes/tilemap-spacing.esscene
new file mode 100644
index 000000000..7022252e1
--- /dev/null
+++ b/desktop/public/scenes/tilemap-spacing.esscene
@@ -0,0 +1,28 @@
+{
+ "version": "1.0",
+ "name": "TilemapSpacing",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 16, "y": -16, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 40, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Tilemap", "data": { "source": "/scenes/tilemap-spacing/map.tmj" } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/tilemap-spacing.textures.json b/desktop/public/scenes/tilemap-spacing.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/tilemap-spacing.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/tilemap-spacing/atlas.png b/desktop/public/scenes/tilemap-spacing/atlas.png
new file mode 100644
index 000000000..e4db6ee27
Binary files /dev/null and b/desktop/public/scenes/tilemap-spacing/atlas.png differ
diff --git a/desktop/public/scenes/tilemap-spacing/map.tmj b/desktop/public/scenes/tilemap-spacing/map.tmj
new file mode 100644
index 000000000..b27a1bc20
--- /dev/null
+++ b/desktop/public/scenes/tilemap-spacing/map.tmj
@@ -0,0 +1,37 @@
+{
+ "type": "map",
+ "version": "1.10",
+ "orientation": "orthogonal",
+ "renderorder": "right-down",
+ "width": 2,
+ "height": 2,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "infinite": false,
+ "layers": [
+ {
+ "type": "tilelayer",
+ "name": "main",
+ "width": 2,
+ "height": 2,
+ "visible": true,
+ "opacity": 1,
+ "data": [1, 2, 3, 4]
+ }
+ ],
+ "tilesets": [
+ {
+ "firstgid": 1,
+ "name": "spaced",
+ "image": "atlas.png",
+ "imagewidth": 48,
+ "imageheight": 48,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "columns": 2,
+ "tilecount": 4,
+ "margin": 4,
+ "spacing": 8
+ }
+ ]
+}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 5257c85f3..2b2b1073a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -3434,7 +3434,9 @@ tilesets: LoadedTilemapTileset[]
```
columns: number
firstId: number
+margin: number
rows: number
+spacing: number
textureHandle: number
```
@@ -6542,7 +6544,9 @@ collectionTiles: TiledCollectionTile[] | undefined
columns: number
firstGid: number
image: string
+margin: number | undefined
name: string
+spacing: number | undefined
tileCount: number
tileHeight: number
tileWidth: number
@@ -6555,7 +6559,7 @@ ComponentDef<TilemapData>
## TilemapAPI — const
```
-{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
+{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
```
## TilemapData — interface
@@ -6603,7 +6607,7 @@ static prototype: TilemapPlugin
## Tilemaps — const
```
-ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
+ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
```
## TilesetAnimFrame — interface
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5ebc6018a..02e3c9170 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3429,7 +3429,9 @@ tilesets: LoadedTilemapTileset[]
```
columns: number
firstId: number
+margin: number
rows: number
+spacing: number
textureHandle: number
```
@@ -6537,7 +6539,9 @@ collectionTiles: TiledCollectionTile[] | undefined
columns: number
firstGid: number
image: string
+margin: number | undefined
name: string
+spacing: number | undefined
tileCount: number
tileHeight: number
tileWidth: number
@@ -6550,7 +6554,7 @@ ComponentDef<TilemapData>
## TilemapAPI — const
```
-{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
+{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
```
## TilemapData — interface
@@ -6598,7 +6602,7 @@ static prototype: TilemapPlugin
## Tilemaps — const
```
-ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
+ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
```
## TilesetAnimFrame — interface
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b8561a908..f3a46114e 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3436,7 +3436,9 @@ tilesets: LoadedTilemapTileset[]
```
columns: number
firstId: number
+margin: number
rows: number
+spacing: number
textureHandle: number
```
@@ -6544,7 +6546,9 @@ collectionTiles: TiledCollectionTile[] | undefined
columns: number
firstGid: number
image: string
+margin: number | undefined
name: string
+spacing: number | undefined
tileCount: number
tileHeight: number
tileWidth: number
@@ -6557,7 +6561,7 @@ ComponentDef<TilemapData>
## TilemapAPI — const
```
-{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
+{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }
```
## TilemapData — interface
@@ -6605,7 +6609,7 @@ static prototype: TilemapPlugin
## Tilemaps — const
```
-ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
+ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>
```
## TilesetAnimFrame — interface
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index 6daf54ccb..11fd41b7d 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -56,7 +56,10 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
+ 'path and is imported into the project.', e);
}
const rows = ts.columns > 0 ? Math.max(1, Math.ceil(ts.tileCount / ts.columns)) : 1;
- tilesets.push({ textureHandle, columns: ts.columns, rows, firstId: ts.firstGid });
+ tilesets.push({
+ textureHandle, columns: ts.columns, rows, firstId: ts.firstGid,
+ margin: ts.margin ?? 0, spacing: ts.spacing ?? 0,
+ });
}
registerTilemapSource(path, {
@@ -117,7 +120,8 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
}));
const grid = packCollectionGrid(tiles, mapData.tileWidth, mapData.tileHeight);
const tex = await ctx.createTextureFromPixels(grid.width, grid.height, grid.pixels, true);
- return { textureHandle: tex.handle, columns: grid.columns, rows: grid.rows, firstId: ts.firstGid };
+ // A folded image-collection atlas is packed gapless, so no margin/spacing.
+ return { textureHandle: tex.handle, columns: grid.columns, rows: grid.rows, firstId: ts.firstGid, margin: 0, spacing: 0 };
}
unload(_asset: TilemapResult): void {
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index 0925ca102..58d64b3b0 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -76,6 +76,9 @@ export interface TiledTilesetData {
tileHeight: number;
columns: number;
tileCount: number;
+ /** Atlas border before the first tile, and gap between tiles (px, Tiled). */
+ margin?: number;
+ spacing?: number;
/** Image-collection tileset (Tiled "collection of images"): one image per
* tile, no top-level `image`. The loader folds these into ONE grid atlas
* at load time, so the renderer never sees the difference. Local ids may
@@ -302,6 +305,8 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
tileHeight: (ts.tileheight as number) ?? tileHeight,
columns: (ts.columns as number) ?? 1,
tileCount: (ts.tilecount as number) ?? 0,
+ margin: (ts.margin as number) ?? 0,
+ spacing: (ts.spacing as number) ?? 0,
...(collectionTiles?.length ? { collectionTiles } : {}),
});
}
diff --git a/sdk/src/tilemap/tilemapAPI.ts b/sdk/src/tilemap/tilemapAPI.ts
index cb01c807b..8a1c242f4 100644
--- a/sdk/src/tilemap/tilemapAPI.ts
+++ b/sdk/src/tilemap/tilemapAPI.ts
@@ -114,14 +114,17 @@ export const TilemapAPI = {
},
/** Replace the layer's multi-tileset table. Empty array reverts to single-tileset. */
- setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number }[]): void {
+ setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number }[]): void {
const m = module_;
if (!m) return;
- const packed = new Uint32Array(slots.length * 3);
+ const STRIDE = 5;
+ const packed = new Uint32Array(slots.length * STRIDE);
for (let i = 0; i < slots.length; i++) {
- packed[i * 3] = slots[i].firstId;
- packed[i * 3 + 1] = slots[i].textureHandle;
- packed[i * 3 + 2] = slots[i].columns;
+ packed[i * STRIDE] = slots[i].firstId;
+ packed[i * STRIDE + 1] = slots[i].textureHandle;
+ packed[i * STRIDE + 2] = slots[i].columns;
+ packed[i * STRIDE + 3] = slots[i].margin ?? 0;
+ packed[i * STRIDE + 4] = slots[i].spacing ?? 0;
}
withMalloc(m, packed.byteLength, ptr => {
new Uint32Array(m.HEAPU8.buffer, ptr, packed.length).set(packed);
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index bd6d817e1..7bb5f2dc2 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -454,7 +454,10 @@ export class TilemapPlugin implements Plugin {
// child's TilemapLayer component like any painted layer.
const slots = cached.tilesets
.filter(t => t.textureHandle)
- .map(t => ({ firstId: t.firstId, textureHandle: t.textureHandle, columns: t.columns }));
+ .map(t => ({
+ firstId: t.firstId, textureHandle: t.textureHandle, columns: t.columns,
+ margin: t.margin, spacing: t.spacing,
+ }));
if (slots.length > 0) {
TilemapAPI.setTilesets(child, slots);
} else if (cached.tilesets.length > 0) {
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index 313e26aaf..b1edc996f 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -27,6 +27,9 @@ export interface LoadedTilemapTileset {
* UV cell size (1/columns × 1/rows) for tile (GID) objects. */
rows: number;
firstId: number; // global tile-id at which this tileset begins (Tiled firstgid)
+ /** Atlas border before the first tile, and gap between tiles (px, Tiled). */
+ margin: number;
+ spacing: number;
}
export interface LoadedTilemapSource {
diff --git a/sdk/src/tilemap/tilesetResolve.ts b/sdk/src/tilemap/tilesetResolve.ts
index 2e62c1047..b4c755154 100644
--- a/sdk/src/tilemap/tilesetResolve.ts
+++ b/sdk/src/tilemap/tilesetResolve.ts
@@ -34,6 +34,9 @@ export interface TilesetModelSlot {
firstId: number;
textureHandle: number;
columns: number;
+ /** Atlas border (px) before the first tile, and gap (px) between tiles (Tiled). */
+ margin: number;
+ spacing: number;
}
/**
@@ -131,7 +134,10 @@ export function resolveTilesetModel(tilesets: ResolvedTileset[]): TilesetModel {
let firstId = 1;
for (const { asset, textureHandle, textureHeight } of tilesets) {
- slots.push({ firstId, textureHandle, columns: asset.columns });
+ slots.push({
+ firstId, textureHandle, columns: asset.columns,
+ margin: asset.margin || 0, spacing: asset.spacing || 0,
+ });
const tw = asset.tileWidth || 1;
const th = asset.tileHeight || 1;
diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.ts
index 6f25925e4..316ada058 100644
--- a/sdk/tests/tilemap.test.ts
+++ b/sdk/tests/tilemap.test.ts
@@ -173,7 +173,7 @@ describe('image-collection tilesets fold into a grid atlas', () => {
await loader.load('maps/level.tmj', ctx);
expect(uploads).toEqual([{ width: 4, height: 2 }]); // ONE folded 2x1 page
const src = getTilemapSource('maps/level.tmj')!;
- expect(src.tilesets[0]).toEqual({ textureHandle: 77, columns: 2, rows: 1, firstId: 5 });
+ expect(src.tilesets[0]).toEqual({ textureHandle: 77, columns: 2, rows: 1, firstId: 5, margin: 0, spacing: 0 });
});
it('a collection tile off the map grid fails loud with the fix', async () => {
@@ -1036,6 +1036,7 @@ describe('parseTmjJson — group layers, infinite chunks, external tilesets', ()
expect(result.tilesets[0]).toEqual({
name: 'terrain', image: 'textures/terrain.png', firstGid: 1,
tileWidth: 16, tileHeight: 16, columns: 8, tileCount: 64,
+ margin: 0, spacing: 0,
});
expect(result.collisionTileIds).toEqual([3]);
expect(result.tileAnimations.get(4)).toEqual([
diff --git a/sdk/tests/tileset-resolve.test.ts b/sdk/tests/tileset-resolve.test.ts
index d7a1fbbc2..42b5e781a 100644
--- a/sdk/tests/tileset-resolve.test.ts
+++ b/sdk/tests/tileset-resolve.test.ts
@@ -21,7 +21,7 @@ describe('resolveTilesetModel', () => {
}),
};
const m = resolveTilesetModel([rt]);
- expect(m.slots).toEqual([{ firstId: 1, textureHandle: 100, columns: 4 }]);
+ expect(m.slots).toEqual([{ firstId: 1, textureHandle: 100, columns: 4, margin: 0, spacing: 0 }]);
// box tiles greedy-merge (collidableTileIds); polygon tiles carry their own shape.
expect(m.collidableTileIds).toEqual([2]);
expect(m.tileShapes.get(7)?.shape).toEqual({ type: 'polygon', points: [[0, 1], [1, 1], [0, 0]] }); // normalized
@@ -40,13 +40,22 @@ describe('resolveTilesetModel', () => {
const m = resolveTilesetModel([a, b]);
// tileset B starts at firstId 1 + 8 = 9
expect(m.slots).toEqual([
- { firstId: 1, textureHandle: 100, columns: 4 },
- { firstId: 9, textureHandle: 200, columns: 4 },
+ { firstId: 1, textureHandle: 100, columns: 4, margin: 0, spacing: 0 },
+ { firstId: 9, textureHandle: 200, columns: 4, margin: 0, spacing: 0 },
]);
// A local 2 → global 2; B locals 1,2 → globals 9,10
expect(m.collidableTileIds).toEqual([2, 9, 10]);
});
+ it('carries the tileset margin/spacing into the render slot', () => {
+ const rt: ResolvedTileset = {
+ textureHandle: 100,
+ asset: tileset({ columns: 4, tileCount: 8, margin: 4, spacing: 8 }),
+ };
+ const m = resolveTilesetModel([rt]);
+ expect(m.slots).toEqual([{ firstId: 1, textureHandle: 100, columns: 4, margin: 4, spacing: 8 }]);
+ });
+
it('animations re-key both the tile and its frames to global ids', () => {
const a: ResolvedTileset = { textureHandle: 1, asset: tileset({ tileCount: 8 }) };
const b: ResolvedTileset = {
diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cpp
index a014f9166..b0cf89b24 100644
--- a/src/esengine/bindings/TilemapBindings.cpp
+++ b/src/esengine/bindings/TilemapBindings.cpp
@@ -87,15 +87,17 @@ void tilemap_setTiles(u32 entity, uintptr_t tilesPtr, u32 count) {
void tilemap_setTilesets(u32 entity, uintptr_t dataPtr, u32 count) {
auto e = Entity::fromRaw(entity);
if (e == INVALID_ENTITY || !getTilemapSystem().hasLayer(e)) return;
- const auto* d = count ? boundarySpan<u32>(dataPtr, static_cast<u64>(count) * 3, "tilemap_setTilesets") : nullptr;
+ const auto* d = count ? boundarySpan<u32>(dataPtr, static_cast<u64>(count) * 5, "tilemap_setTilesets") : nullptr;
if (count && !d) return;
std::vector<tilemap::TilesetSlot> slots;
slots.reserve(count);
for (u32 i = 0; i < count; ++i) {
tilemap::TilesetSlot slot;
- slot.first_id = static_cast<u16>(d[i * 3 + 0]);
- slot.texture_handle = d[i * 3 + 1];
- slot.columns = d[i * 3 + 2];
+ slot.first_id = static_cast<u16>(d[i * 5 + 0]);
+ slot.texture_handle = d[i * 5 + 1];
+ slot.columns = d[i * 5 + 2];
+ slot.margin = d[i * 5 + 3];
+ slot.spacing = d[i * 5 + 4];
slots.push_back(slot);
}
getTilemapSystem().setTilesets(e, std::move(slots));
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
index 4e550b115..b76e7f907 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
@@ -104,12 +104,15 @@ void TilemapRenderPlugin::rebuildChunk(
worldY = -static_cast<f32>(ty) * layer.tile_height - hh;
}
- // Base tile UV rect (GL v increases upward, so vBottom < vTop),
- // inset half a texel per edge so samples stay inside this tile.
- f32 uMin = static_cast<f32>(tileCol) * uvTileW + resolved[slotIndex].insetU;
- f32 uMax = uMin + uvTileW - 2.0f * resolved[slotIndex].insetU;
- f32 vBottom = 1.0f - static_cast<f32>(tileRow + 1) * uvTileH + resolved[slotIndex].insetV;
- f32 vTop = vBottom + uvTileH - 2.0f * resolved[slotIndex].insetV;
+ // Base tile UV rect (GL v increases upward, so vBottom < vTop), with
+ // the atlas margin + spacing folded into offset/step so a Tiled tileset
+ // with gaps samples the right cell; inset half a texel per edge so
+ // samples stay inside this tile.
+ const ResolvedSlot& rs = resolved[slotIndex];
+ f32 uMin = rs.uvOffsetX + static_cast<f32>(tileCol) * rs.uvStepX + rs.insetU;
+ f32 uMax = uMin + uvTileW - 2.0f * rs.insetU;
+ f32 vBottom = 1.0f - rs.uvOffsetY - static_cast<f32>(tileRow) * rs.uvStepY - uvTileH + rs.insetV;
+ f32 vTop = vBottom + uvTileH - 2.0f * rs.insetV;
// Map a corner's normalized (s,t) in {0,1}^2 to its texture UV, applying
// the tile flip flags. Tiled order — diagonal (transpose) first, then H,
@@ -218,6 +221,12 @@ void TilemapRenderPlugin::collect(RenderCollectContext& collect_ctx) {
resolved[i].glTexId = tex->getId();
resolved[i].uvW = layer.tile_width / tw;
resolved[i].uvH = layer.tile_height / th;
+ f32 margin = static_cast<f32>(slots[i].margin);
+ f32 spacing = static_cast<f32>(slots[i].spacing);
+ resolved[i].uvOffsetX = margin / tw;
+ resolved[i].uvOffsetY = margin / th;
+ resolved[i].uvStepX = (layer.tile_width + spacing) / tw;
+ resolved[i].uvStepY = (layer.tile_height + spacing) / th;
resolved[i].insetU = 0.5f / tw;
resolved[i].insetV = 0.5f / th;
anySlotValid = true;
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
index 0cbe01230..65515076d 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
@@ -53,6 +53,14 @@ private:
u32 glTexId = 0;
f32 uvW = 0.0f;
f32 uvH = 0.0f;
+ // Atlas margin (border before the first tile) and per-tile step
+ // (tileSize + spacing), in UV units. For a gapless atlas offset=0 and
+ // step==uvW/uvH; a Tiled tileset with margin/spacing shifts each cell so
+ // it samples its own texels instead of the adjacent tile's.
+ f32 uvOffsetX = 0.0f;
+ f32 uvStepX = 0.0f;
+ f32 uvOffsetY = 0.0f;
+ f32 uvStepY = 0.0f;
// Half a texel in UV space. Tile-corner UVs are inset by this so
// interpolated samples never cross into the neighboring atlas tile —
// the classic packed-atlas seam fix, for both linear and nearest
diff --git a/src/esengine/tilemap/TilesetTable.hpp b/src/esengine/tilemap/TilesetTable.hpp
index d05c79516..dc1b72f99 100644
--- a/src/esengine/tilemap/TilesetTable.hpp
+++ b/src/esengine/tilemap/TilesetTable.hpp
@@ -21,6 +21,8 @@ struct TilesetSlot {
uint16_t first_id = 1; // global tile-id at which this tileset begins (Tiled firstgid)
uint32_t texture_handle = 0; // resource::TextureHandle id
uint32_t columns = 1; // tiles per row in the tileset texture
+ uint32_t margin = 0; // atlas border in px before the first tile (Tiled margin)
+ uint32_t spacing = 0; // gap in px between adjacent tiles (Tiled spacing)
};
/**