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.

fix(tilemap): a layer hidden in Tiled is hidden in the game

esengine988acb23f96b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2adf489dc..4ec356012 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -355,6 +355,12 @@ published separately; it ships inside the editor.
### Fixed
+- **A layer hidden in Tiled stays hidden.** A map placed with the Tilemap
+ component drew every layer at full strength, in the editor and in every
+ package: the asset loader kept a layer's tiles and size and dropped what Tiled
+ says about drawing it — visibility, opacity, tint and parallax. They now reach
+ the layer, through the same mapping the older `loadTiledMap` path already used.
+
- **An editor an agent started closes when the agent does.** The editor the MCP
server launches outlived it: an agent that exited, crashed or was killed left
its editor running, and an unattended one with unsaved edits sat at the
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b05021469..61083f731 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -4909,21 +4909,16 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## LoadedTilemapLayer — interface @experimental
+## LoadedTilemapLayer — type @experimental
```
-chunks: LoadedTilemapChunk[]
-height: number
-infinite: boolean
-name: string
-tiles: Uint16Array<ArrayBufferLike>
-width: number
+TiledLayerData
```
## LoadedTilemapSource — interface @experimental
```
collisionTileIds: number[] | undefined
hexSideLength: number | undefined
-layers: LoadedTilemapLayer[]
+layers: TiledLayerData[]
objectGroups: TiledObjectGroupData[] | undefined
orientation: string | undefined
staggerAxis: string | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index bcd50c5f4..748dcb3f5 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -4917,21 +4917,16 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## LoadedTilemapLayer — interface @experimental
+## LoadedTilemapLayer — type @experimental
```
-chunks: LoadedTilemapChunk[]
-height: number
-infinite: boolean
-name: string
-tiles: Uint16Array<ArrayBufferLike>
-width: number
+TiledLayerData
```
## LoadedTilemapSource — interface @experimental
```
collisionTileIds: number[] | undefined
hexSideLength: number | undefined
-layers: LoadedTilemapLayer[]
+layers: TiledLayerData[]
objectGroups: TiledObjectGroupData[] | undefined
orientation: string | undefined
staggerAxis: string | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index f7997aa68..b26746218 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4904,21 +4904,16 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## LoadedTilemapLayer — interface @experimental
+## LoadedTilemapLayer — type @experimental
```
-chunks: LoadedTilemapChunk[]
-height: number
-infinite: boolean
-name: string
-tiles: Uint16Array<ArrayBufferLike>
-width: number
+TiledLayerData
```
## LoadedTilemapSource — interface @experimental
```
collisionTileIds: number[] | undefined
hexSideLength: number | undefined
-layers: LoadedTilemapLayer[]
+layers: TiledLayerData[]
objectGroups: TiledObjectGroupData[] | undefined
orientation: string | undefined
staggerAxis: string | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 634e5e871..792e35629 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4904,21 +4904,16 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## LoadedTilemapLayer — interface @experimental
+## LoadedTilemapLayer — type @experimental
```
-chunks: LoadedTilemapChunk[]
-height: number
-infinite: boolean
-name: string
-tiles: Uint16Array<ArrayBufferLike>
-width: number
+TiledLayerData
```
## LoadedTilemapSource — interface @experimental
```
collisionTileIds: number[] | undefined
hexSideLength: number | undefined
-layers: LoadedTilemapLayer[]
+layers: TiledLayerData[]
objectGroups: TiledObjectGroupData[] | undefined
orientation: string | undefined
staggerAxis: string | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f7458ec2b..2f894c81a 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4911,21 +4911,16 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## LoadedTilemapLayer — interface @experimental
+## LoadedTilemapLayer — type @experimental
```
-chunks: LoadedTilemapChunk[]
-height: number
-infinite: boolean
-name: string
-tiles: Uint16Array<ArrayBufferLike>
-width: number
+TiledLayerData
```
## LoadedTilemapSource — interface @experimental
```
collisionTileIds: number[] | undefined
hexSideLength: number | undefined
-layers: LoadedTilemapLayer[]
+layers: TiledLayerData[]
objectGroups: TiledObjectGroupData[] | undefined
orientation: string | undefined
staggerAxis: string | undefined
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index 11610f5b8..80f036142 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -88,14 +88,7 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
hexSideLength: mapData.hexSideLength,
staggerAxis: mapData.staggerAxis,
staggerIndex: mapData.staggerIndex,
- layers: mapData.layers.map(l => ({
- name: l.name,
- width: l.width,
- height: l.height,
- tiles: l.tiles,
- chunks: l.chunks ?? [],
- infinite: l.infinite ?? false,
- })),
+ layers: mapData.layers,
tilesets,
collisionTileIds: mapData.collisionTileIds,
tileShapes: mapData.tileShapes,
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index 234bb344c..092aacf0f 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -4,7 +4,7 @@ import { TilemapAPI } from './tilemapAPI';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import { TilemapLayer } from './components';
-import { Transform, Marker, RuntimeOnly } from '../ecs/component';
+import { Transform, Marker, RuntimeOnly, type TilemapLayerData } from '../ecs/component';
// Matches TilemapSystem::CHUNK_SIZE on the C++ side.
const TILEMAP_CHUNK_SIZE = 16;
@@ -1195,6 +1195,20 @@ export function generateLayerTileShapes(
return entities;
}
+/** The TilemapLayer a Tiled layer becomes: its lattice, and what Tiled says about drawing it. */
+export function tiledLayerComponent(
+ layer: TiledLayerData, tileWidth: number, tileHeight: number, renderLayer: number,
+): Pick<TilemapLayerData, 'cellSize' | 'renderLayer' | 'visible' | 'opacity' | 'tintColor' | 'parallaxFactor'> {
+ return {
+ cellSize: { x: tileWidth, y: tileHeight },
+ renderLayer,
+ visible: layer.visible,
+ opacity: layer.opacity,
+ tintColor: { ...layer.tintColor },
+ parallaxFactor: { x: layer.parallaxX, y: layer.parallaxY },
+ };
+}
+
export function loadTiledMap(
world: World,
mapData: TiledMapData,
@@ -1217,14 +1231,9 @@ export function loadTiledMap(
const columns = firstTileset?.columns ?? 1;
world.insert(entity, TilemapLayer, {
- cellSize: { x: mapData.tileWidth, y: mapData.tileHeight },
+ ...tiledLayerComponent(layer, mapData.tileWidth, mapData.tileHeight, layerIndex),
tileset: textureHandle,
tilesetColumns: columns,
- renderLayer: layerIndex,
- tintColor: { ...layer.tintColor },
- opacity: layer.opacity,
- visible: layer.visible,
- parallaxFactor: { x: layer.parallaxX, y: layer.parallaxY },
});
TilemapAPI.initInfiniteLayer(entity, mapData.tileWidth, mapData.tileHeight);
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index a08dc1887..a2e168aba 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -16,7 +16,7 @@ import { _bindTileCollisionLookup, type LayerCollisionTable } from './tileQuery'
import type { ResolvedTileCollision } from './tilesetResolve';
import {
generateLayerCollision, generateLayerTileShapes, generateChunkCollision, generateChunkTileShapes,
- spawnObjectRegion, isCollisionObjectGroup, decodeTiledGid,
+ spawnObjectRegion, isCollisionObjectGroup, decodeTiledGid, tiledLayerComponent,
} from './tiledLoader';
import { decodeTilemapChunks } from './chunkCodec';
import { Assets } from '../asset/AssetPlugin';
@@ -425,10 +425,8 @@ export class TilemapRuntime {
// source on every load and never serialized (RuntimeOnly).
const child = world.spawn(layer.name || `TiledLayer_${i}`);
world.insert(child, Transform, { position: { x: 0, y: 0, z: 0 } });
- world.insert(child, TilemapLayer, {
- cellSize: { x: cached.tileWidth, y: cached.tileHeight },
- renderLayer: i,
- });
+ world.insert(child, TilemapLayer,
+ tiledLayerComponent(layer, cached.tileWidth, cached.tileHeight, i));
world.insert(child, RuntimeOnly, {});
world.setParent(child, entity);
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index d56d59083..89b2eb2f8 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -1,25 +1,12 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { ResolvedTileset, ResolvedTileCollision } from './tilesetResolve';
-import type { TiledObjectGroupData } from './tiledLoader';
+import type { TiledObjectGroupData, TiledLayerData, TiledChunkData } from './tiledLoader';
import type { AssetsData } from '../asset/AssetPlugin';
-export interface LoadedTilemapChunk {
- x: number;
- y: number;
- width: number;
- height: number;
- tiles: Uint16Array;
-}
-
-export interface LoadedTilemapLayer {
- name: string;
- width: number;
- height: number;
- tiles: Uint16Array;
- chunks: LoadedTilemapChunk[];
- infinite: boolean;
-}
+/** A layer as its map was parsed, whole: what it draws with is part of what it is. */
+export type LoadedTilemapLayer = TiledLayerData;
+export type LoadedTilemapChunk = TiledChunkData;
export interface LoadedTilemapTileset {
textureHandle: number;
diff --git a/sdk/tests/tiled-layer-drawing.test.ts b/sdk/tests/tiled-layer-drawing.test.ts
new file mode 100644
index 000000000..2758cbf50
--- /dev/null
+++ b/sdk/tests/tiled-layer-drawing.test.ts
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file tiled-layer-drawing.test.ts
+ * @brief What Tiled says about drawing a layer survives into the layer that draws it.
+ *
+ * @details A layer hidden in Tiled drew in the editor and in every package: the
+ * asset loader copied a layer's tiles and size and left `visible`,
+ * `opacity`, the tint and the parallax behind, so the Tilemap component
+ * had nothing to hand its layers but a cell size.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import { Catalog } from '../src/asset/Catalog';
+import type { Backend } from '../src/asset/Backend';
+import type { PublishedTilemap } from '../src/tilemap/tilesetCache';
+import { tiledLayerComponent } from '../src/tilemap/tiledLoader';
+
+vi.mock('../src/wasm/resourceManager', () => ({
+ requireResourceManager: () => ({ releaseTexture: vi.fn(), invalidateTexturePath: vi.fn(() => false) }),
+ getResourceManager: () => null,
+ evictTextureDimensions: vi.fn(),
+}));
+
+const PATH = 'assets/maps/level.tmj';
+
+const MAP = JSON.stringify({
+ width: 1, height: 1, tilewidth: 16, tileheight: 12, tilesets: [],
+ layers: [
+ { type: 'tilelayer', name: 'ground', width: 1, height: 1, data: [0] },
+ {
+ type: 'tilelayer', name: 'water', width: 1, height: 1, data: [0],
+ visible: false, opacity: 0.5, tintcolor: '#ff8000', parallaxx: 0.25, parallaxy: 0.75,
+ },
+ ],
+});
+
+async function loadedLayers() {
+ const assets = Assets.create({
+ backend: {
+ fetchBinary: vi.fn(async () => new ArrayBuffer(0)),
+ fetchText: vi.fn(async () => MAP),
+ resolveUrl: (p: string) => p,
+ } as unknown as Backend,
+ catalog: Catalog.empty(),
+ module: null as never,
+ });
+ await assets.acquireTyped('tilemap', PATH);
+ return assets.resolveRegistryAsset<PublishedTilemap>('tilemap', PATH)!.source.layers;
+}
+
+describe('a Tiled layer draws the way Tiled says', () => {
+ it('keeps what the map says about drawing each layer through the asset load', async () => {
+ const [ground, water] = await loadedLayers();
+ expect(ground.visible).toBe(true);
+ expect(water.visible).toBe(false);
+ expect(water.opacity).toBe(0.5);
+ expect(water.parallaxX).toBe(0.25);
+ expect(water.parallaxY).toBe(0.75);
+ expect(water.tintColor.r).toBeCloseTo(1);
+ expect(water.tintColor.g).toBeCloseTo(128 / 255);
+ });
+
+ it('hands the layer component all of it', async () => {
+ const [, water] = await loadedLayers();
+ expect(tiledLayerComponent(water, 16, 12, 1)).toEqual({
+ cellSize: { x: 16, y: 12 },
+ renderLayer: 1,
+ visible: false,
+ opacity: 0.5,
+ tintColor: water.tintColor,
+ parallaxFactor: { x: 0.25, y: 0.75 },
+ });
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index b8f9f6d75..0a33cdf71 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(tilemap): a layer hidden in Tiled is hidden in the game':
+ { note: 'A layer hidden in Tiled stays hidden.' },
+
'fix(play): a realm that misses its deadline is asked where it is, and a replaced one is not heard':
{ note: 'A Play that never comes up says how far it got.' },