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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { App, Plugin } from '../app/app';
import { engineApi, worldEngineApi } from '../ecs/bridge/engineApi';
import { Transform, TilemapLayer, Sprite, Canvas, RuntimeOnly, Marker, type TilemapLayerData } from '../ecs/component';
import { Schedule } from '../ecs/system';
import { defineResource } from '../ecs/resource';
import type { SystemDef } from '../ecs/system';
import { initTilemapAPI, shutdownTilemapAPI, createTilemapAPI, Tilemaps } from './tilemapAPI';
import { Tilemap } from './components';
import { registerWorldSceneComponentCodec } from '../scene/scene';
import { tilemapSource, resolvedTileset, type LoadedTilemapSource } from './tilesetCache';
import { resolveTilesetModel } from './tilesetResolve';
import { isCollisionPaletteRef, buildCollisionPaletteModel, parseCollisionMaterial } from './collisionPalette';
import { _bindTileCollisionLookup, type LayerCollisionTable } from './tileQuery';
import type { ResolvedTileCollision } from './tilesetResolve';
import {
chunkColliderPlan, exposedCollisionTiles,
spawnObjectRegion, isCollisionObjectGroup, decodeTiledGid, tiledLayerComponent, tiledGridLayout,
} from './tiledLoader';
import { decodeTilemapChunks, type DecodedChunk } from './chunkCodec';
import { readCollisionChunks, type CollisionChunkSnapshot } from './nativeCollisionChunks';
import { Assets, type AssetsData } from '../asset/AssetPlugin';
import { resolveAssetKey } from '../asset/resolveAssetKey';
import { LazyTilesetLoads } from './lazyTilesetLoads';
import { Time } from '../ecs/resource';
import { playModeOnly } from '../ecs/env';
import { log } from '../util/logger';
import type { Entity } from '../types';
import type { World } from '../ecs/world';
import { TilemapOrientation, usesStagger } from './tileGeometry';
interface CollisionInputs {
outline: boolean;
gridKey: string;
originX: number;
originY: number;
generation: number | undefined;
revision: number | undefined;
native: Map<string, CollisionChunkSnapshot> | null;
width: number;
height: number;
pixelsPerUnit: number;
ids: number[] | undefined;
shapes: Map<number, ResolvedTileCollision> | undefined;
}
/**
* One app's tilemap runtime: every derived layer, collider, animation and
* resolved tileset it is holding.
*
* All of it is entity-keyed, so it belongs to one World. Two apps count their
* entities from 1, and a shared instance cannot tell them apart.
*/
export class TilemapRuntime {
private toolkit_: ReturnType<typeof createTilemapAPI> | null = null;
private unregisterCodec_: (() => void) | null = null;
private collisionInputs_ = new Map<number, CollisionInputs>();
private applyTilesetRefs_: ((entity: number, refs: readonly string[]) => void) | null = null;
private initializedLayers_ = new Set<number>();
/** Last applied dimensions, compared separately so fractional sizes cannot alias. */
private appliedCellSize_ = new Map<number, { x: number; y: number }>();
/** TilemapLayer entity → the grid params last pushed (orientation|side|axis|index).
* Grid type + stagger/hex params live in the C++ LayerData; the component is the
* authority, so an orientation edit (or a cellSize re-init, which resets LayerData)
* must re-push — otherwise the drawn/hit grid diverges from the authored one. */
private appliedGrid_ = new Map<number, string>();
private animatedLayers_ = new Set<number>();
/** Tilemap(source) entity → the RuntimeOnly child layer entities derived from its `.tmj`. */
private sourceLayerEntities_ = new Map<number, Entity[]>();
private derivedLayers_ = new Set<number>();
/** Tilemap(source) entity → the cached source OBJECT its children were derived
* from. Identity is the change detector: a `source` field edit resolves to a
* different object, a hot reload re-registers a fresh one, an invalidation
* leaves none — all must tear down + re-derive (the old sync derived once
* and rendered the stale parse forever). */
private sourceDerivedFrom_ = new Map<number, LoadedTilemapSource>();
/** tilemap entity → the static collider entities derived from its collidable tiles (play-mode only). */
private collisionEntities_ = new Map<number, Set<Entity>>();
private collisionChunks_ = new Map<number, Map<string, { chunk: DecodedChunk; colliders: Map<string, Entity> }>>();
/** Layers whose plain boxes are generated for exposed tiles only. */
private collisionOutlines_ = new Set<number>();
/** Layer → the `.estileset` property keys last pushed per tile, so a swap can blank the old ones. */
private appliedTileProperties_ = new Map<number, Map<number, Record<string, string>>>();
/** TilemapLayer entity → its baked collidable tile ids (out-of-band scene data; drives native collision). */
private nativeCollisionIds_ = new Map<number, number[]>();
/** TilemapLayer entity → per-tile rich collision shapes (global id → resolved
* polygon/circle/box-with-modifier), spawned one collider each. */
private nativeTileShapes_ = new Map<number, Map<number, ResolvedTileCollision>>();
/** TilemapLayer entity → its `.estileset` refs, in firstId order (out-of-band; the
* whole list resolves live → multi-slot table/collision/anim). One entry = the
* common single-tileset layer. */
private tilesetRefs_ = new Map<number, string[]>();
/** Entities whose `.estileset` has been resolved+applied (so we do it once per load). */
private liveResolved_ = new Set<number>();
private lazyTilesetLoads_ = new LazyTilesetLoads();
/** Tiled DERIVED child layer → its collision query table (see tileQuery). */
private derivedQueryTables_ = new Map<number, LayerCollisionTable>();
/** Painted-layer query-table cache, invalidated by source-map identity. */
private queryTableCache_ = new Map<number, {
ids: number[] | undefined;
shapes: Map<number, ResolvedTileCollision> | undefined;
table: LayerCollisionTable;
}>();
install(app: App): void {
// Whichever core is present (the wasm module on the web, the native host's
// bindings on a device). A core built without ES_ENABLE_TILEMAP answers
// none of these, and says so once instead of throwing on the first tile.
const engine = engineApi(app);
if (!engine || typeof engine.tilemap_initLayer !== 'function') {
log.warn('tilemap', 'this engine core has no tilemap support — layers will not render');
return;
}
initTilemapAPI(engine, this);
// And this app's own toolkit over its own core: `Res(Tilemaps)` must not
// answer with whichever engine initialised the module seam last.
const TilemapAPI = createTilemapAPI(engine);
this.toolkit_ = TilemapAPI;
app.insertResource(Tilemaps, TilemapAPI);
// Tile chunks live in a C++ blob, not the component's field record, so
// teach the scene (de)serializer to carry them out-of-band instead of
// hardcoding TilemapLayer knowledge in scene.ts.
const nativeCollisionIds = this.nativeCollisionIds_;
const nativeTileShapes = this.nativeTileShapes_;
const tilesetRefs = this.tilesetRefs_;
const liveResolved = this.liveResolved_;
const lazyTilesetLoads = this.lazyTilesetLoads_;
let tilesetRefsChanged = true;
let observedAssets: AssetsData | null | undefined;
let tilesetVersion = -1;
// The single writer of a layer's `.estileset` ref list: point the render table
// at `refs` and mark it for re-resolve next sync. Shared by the scene codec
// (full load) AND the editor's live push (TilemapLiveSync) so both routes carry
// the SAME meaning — no second source of truth for what tilesets a layer uses.
const applyTilesetRefs = (entity: number, refs: readonly string[]): void => {
tilesetRefsChanged = true;
const clean = refs.filter((r): r is string => typeof r === 'string' && r !== '');
if (clean.length > 0) tilesetRefs.set(entity, clean.slice());
else {
if (tilesetRefs.has(entity)) {
nativeCollisionIds.delete(entity);
nativeTileShapes.delete(entity);
}
tilesetRefs.delete(entity);
}
liveResolved.delete(entity);
};
this.applyTilesetRefs_ = applyTilesetRefs;
// Tile-collision queries (tileCollisionAt / isTileSolid): resolve a layer to
// its collision vocabulary — a derived Tiled child's table, or a painted
// layer's live-resolved/baked sets (cached per source identity).
_bindTileCollisionLookup((layer) => {
const derived = this.derivedQueryTables_.get(layer);
if (derived) return derived;
const ids = this.nativeCollisionIds_.get(layer);
const shapes = this.nativeTileShapes_.get(layer);
if (!ids && !shapes) return null;
const cached = this.queryTableCache_.get(layer);
if (cached && cached.ids === ids && cached.shapes === shapes) return cached.table;
const table: LayerCollisionTable = { boxIds: new Set(ids ?? []), shapes: shapes ?? new Map() };
this.queryTableCache_.set(layer, { ids, shapes, table });
return table;
}, this);
this.unregisterCodec_ = registerWorldSceneComponentCodec(app.world, 'TilemapLayer', {
exportData: (entity, data) => {
const blob = TilemapAPI.exportChunks(entity);
if (blob) data.chunks = blob;
// Carry the baked collidable tile-id set out-of-band (like chunks) so the
// runtime can derive collision; it isn't a C++ component field.
const ids = nativeCollisionIds.get(entity);
if (ids && ids.length > 0) data.collidableTileIds = ids.slice();
const refs = tilesetRefs.get(entity);
if (refs && refs.length > 0) {
data.tilesetAssets = refs.slice();
// Back-compat: keep the singular field (first tileset) so an older
// runtime still renders the primary tileset.
data.tilesetAsset = refs[0];
}
},
outOfBandFields: ['chunks', 'collidableTileIds', 'tilesetAsset', 'tilesetAssets'],
importData: (entity, outOfBand) => {
const blob = outOfBand.chunks;
if (typeof blob === 'string' && blob !== '') {
// The engine refuses a map written under another cell
// encoding rather than decoding it into other tiles, and
// the only way that refusal is heard is here.
if (!TilemapAPI.importChunks(entity, blob)) {
log.error('tilemap', 'the saved map was refused — it is damaged, or was'
+ ' painted under a different cell encoding. The layer loads empty.');
}
}
const ids = outOfBand.collidableTileIds;
if (Array.isArray(ids) && ids.length > 0) {
nativeCollisionIds.set(entity, ids.map(Number).filter((n) => Number.isInteger(n)));
} else {
nativeCollisionIds.delete(entity);
}
// The `.estileset` reference(s): resolved live in the sync (multi-slot
// table + collision + animations). Accept the new `tilesetAssets` list;
// fall back to the singular `tilesetAsset` (old scenes).
const list = outOfBand.tilesetAssets;
const single = outOfBand.tilesetAsset;
const refs = Array.isArray(list)
? list.filter((r): r is string => typeof r === 'string' && r !== '')
: (typeof single === 'string' && single !== '' ? [single] : []);
applyTilesetRefs(entity, refs);
},
});
const world = app.world;
const initializedLayers = this.initializedLayers_;
const appliedCellSize = this.appliedCellSize_;
const appliedGrid = this.appliedGrid_;
const animatedLayers = this.animatedLayers_;
const sourceLayerEntities = this.sourceLayerEntities_;
const collisionEntities = this.collisionEntities_;
const tilemapSyncSystem: SystemDef = {
_id: Symbol('TilemapSyncSystem'),
_name: 'TilemapSyncSystem',
_params: [],
_fn: () => {
// Tile colliders are runtime-only artifacts (never in the edit world,
// never serialized): generate them in play mode, drop them on stop so the
// next Play regenerates from the current tiles.
const playMode = playModeOnly();
const assets = app.getResource(Assets);
const version = assets?.registryAssetVersion?.('tileset') ?? 0;
if (assets !== observedAssets || version !== tilesetVersion) {
liveResolved.clear();
observedAssets = assets;
tilesetVersion = version;
}
// Physics half-extents are metres; tile sizes are pixels. Divide by the
// scene's pixelsPerUnit (Canvas, default 100) when spawning tile colliders.
let pixelsPerUnit = 100;
for (const ce of world.getEntitiesWithComponents([Canvas])) {
const c = world.tryGet(ce, Canvas) as { pixelsPerUnit?: number } | null;
if (c?.pixelsPerUnit) { pixelsPerUnit = c.pixelsPerUnit; break; }
}
if (!playMode && collisionEntities.size > 0) {
for (const entity of collisionEntities.keys()) this.clearLayerCollision_(world, entity);
}
const layerEntities = world.getEntitiesWithComponents(
[TilemapLayer, Transform],
);
for (const entity of initializedLayers) {
if (!world.valid(entity as Entity) || !world.has(entity as Entity, TilemapLayer)
|| !world.has(entity as Entity, Transform)) {
TilemapAPI.destroyLayer(entity);
initializedLayers.delete(entity);
this.clearLayerCollision_(world, entity);
appliedCellSize.delete(entity);
appliedGrid.delete(entity);
nativeCollisionIds.delete(entity);
nativeTileShapes.delete(entity);
tilesetRefs.delete(entity);
tilesetRefsChanged = true;
liveResolved.delete(entity);
// Without these, a destroyed animated layer stays in the
// per-frame tick set (advanceAnimations on a dead layer,
// and a wrong one after id reuse) and leaks its query table.
animatedLayers.delete(entity);
this.queryTableCache_.delete(entity);
this.derivedLayers_.delete(entity);
this.collisionOutlines_.delete(entity);
this.appliedTileProperties_.delete(entity);
}
}
if (lazyTilesetLoads.size > 0 && tilesetRefsChanged) {
const active = new Set<string>();
for (const entity of layerEntities) {
for (const ref of tilesetRefs.get(entity) ?? []) active.add(resolveAssetKey(assets, ref));
}
lazyTilesetLoads.prune(active);
tilesetRefsChanged = false;
}
for (const entity of layerEntities) {
const layerData = world.tryGet(entity, TilemapLayer) as TilemapLayerData | null;
if (!layerData) continue;
const refs = tilesetRefs.get(entity);
// A layer needs either a copied texture (legacy) or .estileset ref(s).
if (!this.derivedLayers_.has(entity) && !layerData.tileset && (!refs || refs.length === 0)) {
this.clearLayerCollision_(world, entity);
continue;
}
// RC2a: the TilemapLayer component is the single source of visual
// metadata; the C++ renderer reads tint/opacity/tileset/columns/
// renderLayer/parallax/visible straight off the component each frame.
// No per-frame push into LayerData anymore — we only init the layer's
// chunk store (the heavy data) and let the renderer pull the rest.
// Keep the C++ layer's tile size equal to the component `cellSize`
// (the authority). The scene loader's importChunks pre-creates the
// layer at a placeholder size, and a user can edit cellSize after
// init; initInfiniteLayer is idempotent (keeps chunks), so re-push
// whenever the applied size drifts. Stale dims misplace every tile
// relative to the paint grid (renderer + worldToTile read tile_width).
const cellSize = layerData.cellSize;
const appliedSize = appliedCellSize.get(entity);
let reinit = false;
if (!initializedLayers.has(entity)) {
TilemapAPI.initInfiniteLayer(
entity, layerData.cellSize.x, layerData.cellSize.y,
);
TilemapAPI.setOriginEntity(entity, entity);
initializedLayers.add(entity);
appliedCellSize.set(entity, { x: cellSize.x, y: cellSize.y });
reinit = true;
} else if (appliedSize?.x !== cellSize.x || appliedSize.y !== cellSize.y) {
TilemapAPI.initInfiniteLayer(
entity, layerData.cellSize.x, layerData.cellSize.y,
);
appliedCellSize.set(entity, { x: cellSize.x, y: cellSize.y });
reinit = true;
}
// Grid orientation + stagger/hex params from the component (the
// authority): push on an orientation edit, or after a (re)init that
// reset the C++ LayerData grid state. Staggered (2) and hexagonal (3)
// both read the stagger axis/index; orthogonal/isometric ignore them.
// Same worldToTile/renderer path the imported .tmj layers use, so a
// painted iso/hex map places tiles exactly like an imported one.
const gridKey = `${layerData.orientation ?? 0}|${layerData.hexSideLength ?? 0}`
+ `|${layerData.staggerAxis ?? 0}|${layerData.staggerIndex ?? 0}`;
if (reinit || appliedGrid.get(entity) !== gridKey) {
TilemapAPI.setGridType(entity, layerData.orientation ?? 0);
TilemapAPI.setHexParams(
entity, layerData.hexSideLength ?? 0,
(layerData.staggerAxis ?? 0) === 1, (layerData.staggerIndex ?? 0) === 1,
);
appliedGrid.set(entity, gridKey);
}
// Collision (obstacle) layer: the sentinel `builtin:collision` ref means
// this layer paints from the fixed collision palette, not an `.estileset`.
// Install its collision model directly — NO render slots (nothing draws)
// and no atlas load — so the same spawn + overlay path handles it as any
// painted collision. The gate above passed because refs is non-empty.
if (refs && refs.length > 0 && isCollisionPaletteRef(refs) && !liveResolved.has(entity)) {
const model = buildCollisionPaletteModel(parseCollisionMaterial(refs));
if (model.collidableTileIds.length > 0) nativeCollisionIds.set(entity, model.collidableTileIds);
else nativeCollisionIds.delete(entity);
if (model.tileShapes.size > 0) nativeTileShapes.set(entity, model.tileShapes);
else nativeTileShapes.delete(entity);
liveResolved.add(entity);
}
// Live tileset(s): when ALL the layer's `.estileset` refs have loaded,
// derive its multi-slot render table + animations + collision LIVE (once
// per load) — replacing copied columns + the baked collidableTileIds. The
// whole list must resolve together so firstId ranges are contiguous.
else if (refs && refs.length > 0 && !liveResolved.has(entity)) {
const resolvedList = [];
for (const ref of refs) {
const key = resolveAssetKey(assets, ref);
const r = resolvedTileset(assets, ref);
if (r) {
resolvedList.push(r);
} else if (assets) {
lazyTilesetLoads.request(assets, ref, key);
}
}
if (resolvedList.length === refs.length) {
const model = resolveTilesetModel(resolvedList);
TilemapAPI.setTilesets(entity, model.slots);
// A re-resolve (tileset swap) replaces the whole table —
// clear the old animations/collision first, then set the
// new ones unconditionally, or stale ids from the previous
// tileset keep animating / generating colliders.
TilemapAPI.clearTileAnimations(entity);
for (const [tileId, frames] of model.animations) {
TilemapAPI.setTileAnimation(entity, tileId, frames);
animatedLayers.add(entity);
}
if (model.animations.size === 0) animatedLayers.delete(entity);
this.applyTileProperties_(TilemapAPI, entity, model.tileProperties ?? new Map());
if (model.collidableTileIds.length > 0) {
nativeCollisionIds.set(entity, model.collidableTileIds);
} else {
nativeCollisionIds.delete(entity);
}
if (model.tileShapes.size > 0) {
nativeTileShapes.set(entity, model.tileShapes);
} else {
nativeTileShapes.delete(entity);
}
liveResolved.add(entity);
}
}
this.syncLayerCollision_(world, entity, layerData, pixelsPerUnit, playMode);
}
const tilemapEntities = world.getEntitiesWithComponents(
[Tilemap, Transform],
);
for (const entity of tilemapEntities) {
if (world.tryGet(entity, TilemapLayer)) continue;
const tilemap = world.tryGet(entity, Tilemap) as { source: string } | null;
// This app's realm, by the ref the component carries: the slot
// answers to that spelling and to the path it resolved to.
const cached = tilemap?.source ? tilemapSource(assets, tilemap.source) : undefined;
// Derived children must mirror the CURRENT source. A cleared field,
// an invalidated cache entry (hot reload), or different source data
// (live `source` edit / fresh registration) all tear down here; the
// derive below rebuilds from whatever is cached now.
if (sourceLayerEntities.has(entity) && this.sourceDerivedFrom_.get(entity) !== cached) {
this.teardownDerived_(world, entity);
}
if (!cached) continue;
if (!sourceLayerEntities.has(entity)) {
const children: Entity[] = [];
const layout = tiledGridLayout(cached), gridType = layout.orientation;
for (let i = 0; i < cached.layers.length; i++) {
const layer = cached.layers[i];
// Each Tiled layer is a REAL child entity carrying a
// TilemapLayer component, so the renderer reads its
// metadata exactly like a painted layer's — one metadata
// model, no synthetic-key shadow layers. The children are
// world-only projections of the .tmj, re-derived from the
// 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,
tiledLayerComponent(layer, cached.tileWidth, cached.tileHeight, i, layout));
world.insert(child, RuntimeOnly, {});
world.setParent(child, entity);
if (layer.infinite) {
TilemapAPI.initInfiniteLayer(
child, cached.tileWidth, cached.tileHeight,
);
for (const chunk of layer.chunks) {
TilemapAPI.setChunkTiles(
child, chunk.x, chunk.y,
chunk.tiles, chunk.width, chunk.height,
);
}
} else {
TilemapAPI.initLayer(
child, layer.width, layer.height,
cached.tileWidth, cached.tileHeight,
);
if (layer.tiles.length > 0) {
TilemapAPI.setTiles(child, layer.tiles);
}
}
TilemapAPI.setOriginEntity(child, child);
if (gridType !== 0) {
TilemapAPI.setGridType(child, gridType);
}
// Staggered + hexagonal both read the stagger axis/index (the
// half-cell shift). Staggered iso ignores the side length.
if (usesStagger(gridType)) {
TilemapAPI.setHexParams(
child, cached.hexSideLength ?? 0,
cached.staggerAxis === 'x', cached.staggerIndex === 'even',
);
}
if (cached.tileAnimations) {
for (const [tileId, frames] of cached.tileAnimations) {
TilemapAPI.setTileAnimation(child, tileId, frames);
}
if (cached.tileAnimations.size > 0) {
animatedLayers.add(child);
}
}
if (cached.tileProperties) {
for (const [tileId, props] of cached.tileProperties) {
for (const [k, v] of props) {
TilemapAPI.setTileProperty(child, tileId, k, v);
}
}
}
// Multi-tileset: push the full tileset table (firstId +
// texture + columns). The renderer batches per texture and
// derives UVs from texture size; the remaining visual
// metadata (tint/opacity/renderLayer/...) is read off the
// 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,
margin: t.margin, spacing: t.spacing,
}));
if (slots.length > 0) {
TilemapAPI.setTilesets(child, slots);
} else if (cached.tilesets.length > 0) {
// Every tileset texture is dead (handle 0): the map parsed
// and its collision generates, but nothing will draw. Say
// so ONCE, loudly — silently-invisible-but-solid levels
// cost a real debugging session to diagnose from pixels.
log.error('tilemap',
`Tiled map on entity ${entity}: none of its ${cached.tilesets.length} `
+ 'tileset texture(s) loaded — tiles will NOT render (collision still '
+ 'works). See earlier [tilemap] load errors for the failing image path(s).');
}
// The child answers tile-collision queries with the
// source map's vocabulary (same table as the spawn path).
if ((cached.collisionTileIds?.length ?? 0) > 0 || (cached.tileShapes?.size ?? 0) > 0) {
this.derivedQueryTables_.set(child, {
boxIds: new Set(cached.collisionTileIds ?? []),
shapes: cached.tileShapes ?? new Map(),
});
}
children.push(child);
initializedLayers.add(child);
this.derivedLayers_.add(child);
appliedCellSize.set(child, { x: cached.tileWidth, y: cached.tileHeight });
if (cached.collisionTileIds?.length) nativeCollisionIds.set(child, cached.collisionTileIds);
if (cached.tileShapes?.size) nativeTileShapes.set(child, cached.tileShapes);
this.syncLayerCollision_(world, child, world.get(child, TilemapLayer), pixelsPerUnit, playMode);
}
// Tile (GID) objects — a positioned tile rendered as a Sprite,
// in edit + play mode like the tile layers. Parented to the
// tilemap entity, so the sprite's local position is the object's
// offset within the map (pixels). H/V flip → flipX/flipY;
// diagonal (D) flip = transpose, decomposed as an extra 90° CW
// quad rotation with the flip axes exchanged (source H → display
// Y with the rotation's inversion baked in, source V → display X)
// and the sprite size swapped so the rotated quad fills the
// object's authored width×height box (whose centre is
// rotation-invariant). Pixel-verified against Tiled's rendering.
for (const group of cached.objectGroups ?? []) {
if (group.visible === false) continue;
// A `collision` group's shapes are SOLID geometry (walls/floors);
// every other group's shapes are trigger REGIONS (sensors). Both
// derive through the SAME region path below — edit+play visible.
const isCollision = isCollisionObjectGroup(group);
for (const obj of group.objects) {
if (obj.visible === false) continue;
// Non-tile objects converge to real, parented, RuntimeOnly
// entities (re-derived from the .tmj each load, like the
// tile-object sprites), so imported and hand-authored objects
// share ONE `Query(Marker)` surface + collider gizmo: a POINT →
// a Marker (spawn point / waypoint); a rect/ellipse/polygon/
// polyline → a Region (Marker + collider, sensor unless the
// group is `collision`, in which case solid geometry).
if (obj.gid === undefined) {
if (obj.shape === 'point') {
// Carry the Tiled object's custom properties (stringified) so
// imported markers hold the same per-object data as hand-authored.
const props: Record<string, string> = {};
for (const [k, v] of obj.properties) props[k] = String(v);
const markerChild = world.spawn(obj.name || `Marker_${obj.id}`);
world.insert(markerChild, Transform, { position: { x: obj.x, y: -obj.y, z: 0 } });
world.insert(markerChild, Marker, { type: obj.type || '', properties: props });
world.insert(markerChild, RuntimeOnly, {});
world.setParent(markerChild, entity);
children.push(markerChild);
} else {
const region = spawnObjectRegion(world, obj, entity, pixelsPerUnit, !isCollision);
if (region != null) children.push(region);
}
continue;
}
const dec = decodeTiledGid(obj.gid);
// Resolve the tileset by global id (largest firstId <= id).
let ts: (typeof cached.tilesets)[number] | undefined;
for (const cand of cached.tilesets) {
if (cand.textureHandle && cand.firstId <= dec.globalId &&
(!ts || cand.firstId > ts.firstId)) ts = cand;
}
if (!ts) continue;
const localId = dec.globalId - ts.firstId;
const cols = ts.columns || 1;
const rows = ts.rows || 1;
const uvW = 1 / cols, uvH = 1 / rows;
const col = localId % cols;
const row = Math.floor(localId / cols);
const w = obj.width || cached.tileWidth;
const h = obj.height || cached.tileHeight;
// Tiled tile-objects anchor BOTTOM-LEFT, y-down, and rotate
// CW about that anchor. Rotate the centre offset (w/2,-h/2)
// about the anchor and set the sprite's rotation to match
// (mirrors generateObjectCollision); world Y is up.
const rad = (obj.rotation || 0) * (Math.PI / 180);
const rc = Math.cos(rad), rs = Math.sin(rad);
const px = obj.x + (w / 2) * rc - (-h / 2) * rs;
const py = -(obj.y + (w / 2) * rs + (-h / 2) * rc);
// The box centre above uses the authored rotation only;
// D adds content rotation on top of it.
const quadRad = dec.flipD ? rad + Math.PI / 2 : rad;
const tileChild = world.spawn(obj.name || `TileObject_${obj.id}`);
world.insert(tileChild, Transform, quadRad !== 0
? { position: { x: px, y: py, z: 0 }, rotation: { w: Math.cos(-quadRad / 2), x: 0, y: 0, z: Math.sin(-quadRad / 2) } }
: { position: { x: px, y: py, z: 0 } });
world.insert(tileChild, Sprite, {
texture: ts.textureHandle,
size: dec.flipD ? { x: h, y: w } : { x: w, y: h },
uvOffset: { x: col * uvW, y: 1 - (row + 1) * uvH },
uvScale: { x: uvW, y: uvH },
flipX: dec.flipD ? dec.flipV : dec.flipH,
flipY: dec.flipD ? !dec.flipH : dec.flipV,
layer: cached.layers.length,
});
world.insert(tileChild, RuntimeOnly, {});
world.setParent(tileChild, entity);
children.push(tileChild);
}
}
sourceLayerEntities.set(entity, children);
this.sourceDerivedFrom_.set(entity, cached);
}
}
for (const entity of [...sourceLayerEntities.keys()]) {
if (!world.valid(entity as Entity) || !world.has(entity as Entity, Tilemap)
|| world.has(entity as Entity, TilemapLayer)) this.teardownDerived_(world, entity);
}
},
};
// Frame edits and fixed-step edits derive before physics. Animation
// advances once per rendered frame, independently of catch-up steps.
app.addSystemToSchedule(Schedule.First, tilemapSyncSystem);
app.addSystemToSchedule(Schedule.FixedUpdate, {
...tilemapSyncSystem, _id: Symbol('TilemapPhysicsSyncSystem'), _name: 'TilemapPhysicsSyncSystem',
}, { runBefore: ['CharacterController2DSystem', 'PhysicsStepSystem'], runIf: playModeOnly });
app.addSystemToSchedule(Schedule.PreUpdate, {
_id: Symbol('TilemapAnimationSystem'), _name: 'TilemapAnimationSystem', _params: [],
_fn: () => {
const dtMs = app.getResource(Time).delta * 1000;
for (const key of animatedLayers) {
if (world.isEntityActive(key as Entity)) TilemapAPI.advanceAnimations(key, dtMs);
}
},
});
}
private attachCollision_(world: World, owner: Entity, colliders: Entity[]): void {
for (const collider of colliders) {
if (!world.has(collider, RuntimeOnly)) world.insert(collider, RuntimeOnly, {});
world.setParent(collider, owner);
}
}
/** The native store has no way to forget a property, and an empty value reads the same as none. */
private applyTileProperties_(tiles: ReturnType<typeof createTilemapAPI>, entity: number, next: Map<number, Record<string, string>>): void {
for (const [tileId, props] of this.appliedTileProperties_.get(entity) ?? []) {
for (const key of Object.keys(props)) if (next.get(tileId)?.[key] === undefined) tiles.setTileProperty(entity, tileId, key, '');
}
for (const [tileId, props] of next) for (const [key, value] of Object.entries(props)) tiles.setTileProperty(entity, tileId, key, value);
if (next.size > 0) this.appliedTileProperties_.set(entity, next);
else this.appliedTileProperties_.delete(entity);
}
private syncLayerCollision_(world: World, entity: Entity, layer: TilemapLayerData, ppu: number, playMode: boolean): void {
if (!playMode || !this.toolkit_) return;
const ids = this.nativeCollisionIds_.get(entity), shapes = this.nativeTileShapes_.get(entity);
const outline = this.collisionOutlines_.has(entity) && (layer.orientation ?? 0) === TilemapOrientation.Orthogonal;
const hasBoxes = !!ids?.length, hasShapes = !!shapes?.size;
const current = this.collisionEntities_.get(entity);
if (!hasBoxes && !hasShapes) {
this.clearLayerCollision_(world, entity);
return;
}
const engine = worldEngineApi(world), tiles = this.toolkit_;
if (!engine) return;
const generation = engine.tilemap_getGeneration?.(entity);
const revision = engine.tilemap_getEditRevision?.(entity);
const gridKey = `${layer.orientation ?? 0}|${layer.hexSideLength ?? 0}|${layer.staggerAxis ?? 0}|${layer.staggerIndex ?? 0}`;
const originX = layer.originOffset?.x ?? 0, originY = layer.originOffset?.y ?? 0;
const previous = this.collisionInputs_.get(entity);
const rebuild = !previous || previous.generation !== generation || previous.outline !== outline
|| previous.gridKey !== gridKey || previous.width !== layer.cellSize.x || previous.height !== layer.cellSize.y
|| previous.pixelsPerUnit !== ppu || previous.ids !== ids || previous.shapes !== shapes;
const sameContent = previous && generation !== undefined && revision !== undefined
&& previous.generation === generation && previous.revision === revision;
const moved = !!previous && (previous.originX !== originX || previous.originY !== originY);
if (!rebuild && sameContent && !moved) return;
const retained = previous && generation !== undefined && previous.generation === generation
&& revision !== undefined && previous.revision !== undefined && revision >= previous.revision ? previous.native : null;
const native = sameContent ? previous.native : readCollisionChunks(engine, entity, retained);
const oldChunks = this.collisionChunks_.get(entity);
const chunks = sameContent && oldChunks ? [...oldChunks.values()].map(value => value.chunk)
: native ? [...native.values()].filter(chunk => chunk.tiles.length > 0) : decodeTilemapChunks(tiles.exportChunks(entity));
if (rebuild) this.clearLayerCollision_(world, entity);
else if (current && moved) {
const dx = originX - previous.originX, dy = originY - previous.originY;
for (const collider of current) world.update(collider, Transform, value => {
value.position.x += dx; value.position.y += dy;
});
}
const layout = { orientation: layer.orientation ?? 0, hexSideLength: layer.hexSideLength ?? 0,
staggerAxisX: layer.staggerAxis === 1, staggerIndexEven: layer.staggerIndex === 1 };
const groups = this.collisionChunks_.get(entity) ?? new Map<string, { chunk: DecodedChunk; colliders: Map<string, Entity> }>();
const all = this.collisionEntities_.get(entity) ?? new Set<Entity>();
const remove = (collider: Entity) => { all.delete(collider); if (world.valid(collider)) world.despawn(collider); };
const live = new Map<string, DecodedChunk>(chunks.map(chunk => [`${chunk.x},${chunk.y}`, chunk]));
const dirty = new Set<string>();
for (const [key, chunk] of live) {
const old = groups.get(key);
if (old && (old.chunk.tiles === chunk.tiles || old.chunk.tiles.length === chunk.tiles.length
&& old.chunk.tiles.every((value, index) => value === chunk.tiles[index]))) continue;
dirty.add(key);
}
for (const key of groups.keys()) if (!live.has(key)) dirty.add(key);
// Whether a chunk's edge tile is buried is the next chunk's answer too.
if (outline) for (const key of [...dirty]) {
const [x, y] = key.split(',').map(Number) as [number, number];
dirty.add(`${x - 1},${y}`); dirty.add(`${x + 1},${y}`); dirty.add(`${x},${y - 1}`); dirty.add(`${x},${y + 1}`);
}
const boxIds = new Set(hasBoxes ? ids : []), richShapes = hasShapes ? shapes! : new Map<number, ResolvedTileCollision>();
for (const key of dirty) {
const chunk = live.get(key), old = groups.get(key);
if (!chunk) {
if (old) { for (const collider of old.colliders.values()) remove(collider); groups.delete(key); }
continue;
}
const boxTiles = outline
? exposedCollisionTiles(chunk, boxIds, (cx, cy) => live.get(`${cx},${cy}`)?.tiles) : chunk.tiles;
const plan = chunkColliderPlan(chunk, boxTiles, boxIds, richShapes, layer.cellSize.x, layer.cellSize.y, originX, originY, ppu, layout);
const colliders = new Map<string, Entity>(), spawned: Entity[] = [];
for (const [shape, collider] of old?.colliders ?? []) {
if (plan.has(shape)) colliders.set(shape, collider); else remove(collider);
}
for (const [shape, spawn] of plan) {
if (colliders.has(shape)) continue;
const collider = spawn(world);
colliders.set(shape, collider); spawned.push(collider); all.add(collider);
}
this.attachCollision_(world, entity, spawned);
groups.set(key, { chunk, colliders });
}
this.collisionChunks_.set(entity, groups);
this.collisionEntities_.set(entity, all);
this.collisionInputs_.set(entity, { outline, generation, revision, gridKey, originX, originY,
width: layer.cellSize.x, height: layer.cellSize.y, pixelsPerUnit: ppu, ids, shapes, native });
}
private clearLayerCollision_(world: { valid(e: Entity): boolean; despawn(e: Entity): void }, entity: number): void {
for (const collider of this.collisionEntities_.get(entity) ?? []) if (world.valid(collider)) world.despawn(collider);
this.collisionEntities_.delete(entity); this.collisionInputs_.delete(entity); this.collisionChunks_.delete(entity);
}
/** Drop ONE tilemap entity's derived artifacts (child layer entities +
* play-mode colliders + bookkeeping) so the sync can re-derive — or not,
* if its source is gone. Fires when the Tilemap component disappears AND
* when the source it derived from stops being current. */
private teardownDerived_(
world: { valid(e: Entity): boolean; despawn(e: Entity): void },
entity: number,
): void {
for (const child of this.sourceLayerEntities_.get(entity) ?? []) {
if (this.initializedLayers_.has(child)) {
this.toolkit_?.destroyLayer(child);
this.initializedLayers_.delete(child);
}
this.animatedLayers_.delete(child);
this.derivedQueryTables_.delete(child);
this.derivedLayers_.delete(child);
this.nativeCollisionIds_.delete(child); this.nativeTileShapes_.delete(child);
this.collisionEntities_.delete(child); this.collisionInputs_.delete(child);
this.collisionChunks_.delete(child); this.collisionOutlines_.delete(child);
this.appliedCellSize_.delete(child); this.appliedGrid_.delete(child);
// An owner despawn cascades to its children; only a component
// removal leaves them alive to clean up here.
if (world.valid(child)) world.despawn(child);
}
this.sourceLayerEntities_.delete(entity);
this.sourceDerivedFrom_.delete(entity);
}
/**
* The editor's out-of-band push: a layer's `.estileset` ref list changed.
* Reached through THIS app's runtime, so an editor world and a play world
* cannot answer for each other — which a module-level "active plugin"
* pointer decided by whoever built last.
*/
setLayerTilesets(entity: number, refs: readonly string[]): void {
this.applyTilesetRefs_?.(entity, refs);
}
/**
* Generates a layer's plain boxes for exposed tiles only, so ground dug far below a surface leaves the surface's colliders alone and solid ground costs no bodies.
* Nothing stops a body placed inside the ground, since the shell is all there is. Only orthogonal layers follow it.
*/
setCollisionOutline(entity: number, outline: boolean): void {
if (outline) this.collisionOutlines_.add(entity);
else this.collisionOutlines_.delete(entity);
}
resetLayers(): void {
for (const entity of this.initializedLayers_) {
this.toolkit_?.destroyLayer(entity);
}
this.initializedLayers_.clear();
this.appliedCellSize_.clear();
this.appliedGrid_.clear();
this.animatedLayers_.clear();
this.sourceLayerEntities_.clear();
this.derivedLayers_.clear();
this.sourceDerivedFrom_.clear();
// Collider entities die with the world on reset/teardown; just drop our bookkeeping.
this.collisionEntities_.clear();
this.collisionInputs_.clear();
this.collisionChunks_.clear();
this.collisionOutlines_.clear();
this.appliedTileProperties_.clear();
this.nativeCollisionIds_.clear();
this.nativeTileShapes_.clear();
this.tilesetRefs_.clear();
this.liveResolved_.clear();
this.lazyTilesetLoads_.reset();
this.derivedQueryTables_.clear();
this.queryTableCache_.clear();
}
dispose(): void {
this.resetLayers();
this.toolkit_ = null;
this.unregisterCodec_?.();
this.unregisterCodec_ = null;
this.applyTilesetRefs_ = null;
_bindTileCollisionLookup(null, this);
shutdownTilemapAPI(this);
}
}
/** @internal One per App, created by the plugin's build. */
export const TilemapRuntimeState = defineResource<TilemapRuntime>(null!, 'TilemapRuntime');
/**
* Installs the tilemap runtime into an app. Stateless on purpose: what it
* installs is per app, and this object is a singleton that several apps share.
*/
export class TilemapPlugin implements Plugin {
name = 'tilemap';
/** Layers to sync, animate and give colliders; the frame after the last one goes still tears them down. */
readonly activeWhen = [TilemapLayer, Tilemap];
build(app: App): void {
const runtime = new TilemapRuntime();
app.insertResource(TilemapRuntimeState, runtime);
runtime.install(app);
}
cleanup(app?: App): void {
if (app?.hasResource(TilemapRuntimeState)) app.getResource(TilemapRuntimeState).dispose();
}
}
export const tilemapPlugin = new TilemapPlugin();