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
/**
* @file tilesetResolve.ts
* @brief Derive the runtime tileset model from `.estileset` assets — LIVE.
*
* The unification keystone: a `.estileset` (atlas grid + per-tile collision /
* animation) is the single source of truth. This turns one or more resolved
* `.estileset`s into the SAME runtime model the Tiled importer produces — a
* render table (`{firstId, textureHandle, columns}` per tileset), tile
* animations, and collidable tile ids — with NO columns copied onto the layer
* and NO collision baked at author-time. Edit the tileset, re-resolve, done.
*
* Tile ids are global and contiguous across tilesets (firstId[0]=1,
* firstId[i]=firstId[i-1]+count[i-1]), matching the multi-tileset render table
* (`TilesetTable`/`tilemap_setTilesets`) and the Tiled GID convention — so a
* single TilemapLayer can mix tilesets and painted/imported maps converge.
*/
import type { TilesetAsset, TilesetCollision } from './tilesetAsset';
/** A `.estileset` parsed + its atlas texture loaded (handle resolved by the caller). */
export interface ResolvedTileset {
asset: TilesetAsset;
textureHandle: number;
/** Atlas texture pixel size, when known — lets the tile count (and thus the
* multi-tileset firstId span) be derived from the grid without an explicit
* `tileCount` on the asset. */
textureWidth?: number;
textureHeight?: number;
}
/** One render-table slot: a tileset's global id base, atlas texture, and grid width. */
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;
/** Duplicated-edge border each cell carries; 0 = none. See `TilesetAsset.extrude`. */
extrude: number;
}
/**
* A tile's collision resolved into normalized ([0,1], x right / y down) tile space, ready
* to spawn one collider per placed cell. Shapes that a plain-box greedy-merge can't
* represent — polygon, circle, or a box carrying one-way / sensor / material — land here.
*/
export interface ResolvedTileCollision {
shape:
| { type: 'box' }
| { type: 'polygon'; points: [number, number][] }
| { type: 'circle'; cx: number; cy: number; r: number };
/** Solid-side normal in the layer's y-up frame; {0,1} = solid-top before layer rotation. */
oneWay?: { nx: number; ny: number };
sensor?: boolean;
density?: number;
friction?: number;
restitution?: number;
}
/** The runtime tileset model derived from `.estileset`(s) — global tile-id space. */
export interface TilesetModel {
/** Render table (sorted by firstId), fed to `tilemap_setTilesets`. */
slots: TilesetModelSlot[];
/** Animations keyed by GLOBAL tile id → frames (frame tile ids are global too). */
animations: Map<number, { tileId: number; duration: number }[]>;
/**
* Global tile ids that are a PLAIN solid box (default material, no one-way / sensor) —
* the only tiles a greedy rectangle merge may fuse. Sorted.
*/
collidableTileIds: number[];
/**
* Global tile id → its resolved collision, for tiles that spawn ONE collider each
* (polygon / circle / a box with a one-way, sensor, or material modifier). Kept
* separate from {@link collidableTileIds} so the fast merge path stays correctness-safe.
*/
tileShapes: Map<number, ResolvedTileCollision>;
/** Global tile id → its authored custom properties, as `getTileProperty` answers them. */
tileProperties?: Map<number, Record<string, string>>;
}
/** True for a tile the greedy box merge may fuse: a bare solid box, no modifiers. */
function isPlainBox(c: TilesetCollision): boolean {
return c.type === 'box' && !c.oneWay && !c.sensor
&& c.density === undefined && c.friction === undefined && c.restitution === undefined;
}
/** Resolve a tile's collision into normalized tile space (radius as a tile-width fraction). */
function resolveTileCollision(c: TilesetCollision, tw: number, th: number): ResolvedTileCollision {
let shape: ResolvedTileCollision['shape'];
if (c.type === 'polygon') {
shape = { type: 'polygon', points: c.points.map(([px, py]) => [px / tw, py / th]) };
} else if (c.type === 'circle') {
shape = { type: 'circle', cx: c.cx / tw, cy: c.cy / th, r: c.r / tw };
} else {
shape = { type: 'box' };
}
const out: ResolvedTileCollision = { shape };
if (c.oneWay) out.oneWay = c.oneWay;
if (c.sensor) out.sensor = true;
if (c.density !== undefined) out.density = c.density;
if (c.friction !== undefined) out.friction = c.friction;
if (c.restitution !== undefined) out.restitution = c.restitution;
return out;
}
/**
* Cells of `tileSize` along an atlas axis of `size`: n span `2*margin +
* n*tileSize + (n-1)*spacing`, Tiled's margin bordering both sides. The palette
* grid, the id spans below and the renderer's bounds check are all this one
* count — offering a cell the id space lacks paints another tileset's tile.
*
* @experimental
*/
export function atlasCells(size: number, margin: number, tileSize: number, spacing: number): number {
const step = tileSize + spacing;
if (step <= 0) return 0;
return Math.max(0, Math.floor((size - 2 * margin + spacing) / step));
}
/**
* Tiles in a tileset — the span its global ids occupy. Explicit `tileCount` wins;
* else derive `columns × rows` from the atlas texture height (the correct span for
* a full grid, so multiple tilesets get non-overlapping firstId ranges); else fall
* back to the highest authored tile id (single-tileset maps never hit the collision).
*/
function tilesetCount(asset: TilesetAsset, textureHeight?: number): number {
if (typeof asset.tileCount === 'number' && asset.tileCount > 0) return asset.tileCount;
if (typeof textureHeight === 'number' && textureHeight > 0) {
const rows = Math.max(1, atlasCells(
textureHeight, asset.margin || 0, asset.tileHeight || 1, asset.spacing || 0));
return Math.max(1, asset.columns * rows);
}
let max = 0;
for (const k of Object.keys(asset.tiles)) max = Math.max(max, Number(k));
return max; // local ids are 1-based, so the max id == count of the spanned range
}
/**
* Derive the runtime tileset model from resolved `.estileset`s. The per-tile
* collision/animation metadata is read straight off each `.estileset` (live) and
* re-keyed into the global id space.
*/
export function resolveTilesetModel(tilesets: ResolvedTileset[]): TilesetModel {
const slots: TilesetModelSlot[] = [];
const animations = new Map<number, { tileId: number; duration: number }[]>();
const collidable: number[] = [];
const tileShapes = new Map<number, ResolvedTileCollision>();
const tileProperties = new Map<number, Record<string, string>>();
let firstId = 1;
for (const { asset, textureHandle, textureHeight } of tilesets) {
slots.push({
firstId, textureHandle, columns: asset.columns,
margin: asset.margin || 0, spacing: asset.spacing || 0,
extrude: asset.extrude || 0,
});
const tw = asset.tileWidth || 1;
const th = asset.tileHeight || 1;
// Local tile ids are 1-based; global id = firstId + (localId - 1).
for (const key of Object.keys(asset.tiles)) {
const localId = Number(key);
if (!Number.isInteger(localId) || localId <= 0) continue;
const globalId = firstId + localId - 1;
const tile = asset.tiles[localId];
if (tile.properties && Object.keys(tile.properties).length > 0) tileProperties.set(globalId, tile.properties);
if (tile.collision) {
// Plain solid boxes greedy-merge; everything richer spawns per-tile.
if (isPlainBox(tile.collision)) collidable.push(globalId);
else tileShapes.set(globalId, resolveTileCollision(tile.collision, tw, th));
}
if (tile.animation && tile.animation.length > 0) {
animations.set(
globalId,
tile.animation.map((f) => ({
tileId: firstId + f.tile - 1,
duration: f.durationMs,
})),
);
}
}
firstId += Math.max(1, tilesetCount(asset, textureHeight));
}
collidable.sort((a, b) => a - b);
return { slots, animations, collidableTileIds: collidable, tileShapes, tileProperties };
}