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 { TilemapAPI } from './tilemapAPI';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import { TilemapLayer } from './components';
import { Transform, Marker, RuntimeOnly, type TilemapLayerData } from '../ecs/component';
// Matches TilemapSystem::CHUNK_SIZE on the C++ side.
const TILEMAP_CHUNK_SIZE = 16;
function uploadTiledLayerTiles(entity: Entity, layer: TiledLayerData): void {
if (layer.infinite) {
for (const chunk of layer.chunks) {
TilemapAPI.setChunkTiles(entity, chunk.x, chunk.y, chunk.tiles, chunk.width, chunk.height);
}
return;
}
const { width, height, tiles } = layer;
if (width <= 0 || height <= 0 || tiles.length === 0) return;
const chunksX = Math.ceil(width / TILEMAP_CHUNK_SIZE);
const chunksY = Math.ceil(height / TILEMAP_CHUNK_SIZE);
const buf = new Uint16Array(TILEMAP_CHUNK_SIZE * TILEMAP_CHUNK_SIZE);
for (let cy = 0; cy < chunksY; cy++) {
for (let cx = 0; cx < chunksX; cx++) {
buf.fill(0);
const regionW = Math.min(TILEMAP_CHUNK_SIZE, width - cx * TILEMAP_CHUNK_SIZE);
const regionH = Math.min(TILEMAP_CHUNK_SIZE, height - cy * TILEMAP_CHUNK_SIZE);
for (let ly = 0; ly < regionH; ly++) {
const gy = cy * TILEMAP_CHUNK_SIZE + ly;
for (let lx = 0; lx < regionW; lx++) {
const gx = cx * TILEMAP_CHUNK_SIZE + lx;
buf[ly * TILEMAP_CHUNK_SIZE + lx] = tiles[gy * width + gx];
}
}
TilemapAPI.setChunkTiles(entity, cx, cy, buf, regionW, regionH);
}
}
}
import { RigidBody2D, BoxCollider2D, CircleCollider2D, PolygonCollider2D, ChainCollider2D, OneWayPlatform2D, BodyType } from '../physics/PhysicsComponents';
import type { Collider2DShape } from '../physics/ColliderShape2D';
import type { ResolvedTileCollision } from './tilesetResolve';
import { collisionBoxes, collisionGrid } from './collisionBoxes';
import { tileCellCenter, TilemapOrientation, type TileGridLayout, type TileGridParams } from './tileGeometry';
import { CHUNK_SIZE } from './chunkCodec';
import { tileIdOf, tileFlagsOf } from './tileBits';
import { log } from '../util/logger';
import { resolveRelativePath, resolveDocumentRef, resolveTiledRef, isLogicalAssetRef } from '../asset/documentRef';
export interface TiledChunkData {
x: number;
y: number;
width: number;
height: number;
tiles: Uint16Array;
}
export interface TiledLayerData {
name: string;
width: number;
height: number;
visible: boolean;
tiles: Uint16Array;
chunks: TiledChunkData[];
infinite: boolean;
opacity: number;
tintColor: { r: number; g: number; b: number; a: number };
parallaxX: number;
parallaxY: number;
}
export interface TiledTilesetData {
name: string;
image: string;
firstGid: number; // global tile-id at which this tileset begins
tileWidth: number;
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
* be sparse (deleted tiles leave holes). */
collectionTiles?: TiledCollectionTile[];
}
export interface TiledCollectionTile {
/** Local tile id (gid = firstGid + id). */
id: number;
/** Image ref, document-relative like a grid tileset's `image`. */
image: string;
/** Declared size (0 when the document omits it — the decode is the truth). */
width: number;
height: number;
}
export type TiledObjectShape = 'rect' | 'ellipse' | 'polygon' | 'polyline' | 'point';
export interface TiledObjectData {
/** Tiled's per-map unique object id. */
id: number;
name: string;
/** The object's class (the field Tiled called `type` before 1.9). */
type: string;
visible: boolean;
shape: TiledObjectShape;
x: number;
y: number;
width: number;
height: number;
rotation: number;
vertices: number[] | null;
properties: Map<string, unknown>;
/** A tile (GID) object: the raw Tiled global tile id + flip flags. When set, the
* object is a positioned tile rendered as a sprite (see decodeTiledGid); absent
* for the shape objects (rect/ellipse/polygon/polyline/point). */
gid?: number;
}
export interface TiledObjectGroupData {
name: string;
visible: boolean;
properties: Map<string, unknown>;
objects: TiledObjectData[];
}
export interface TiledAnimFrame {
tileId: number;
duration: number;
}
export interface TiledMapData {
width: number;
height: number;
tileWidth: number;
tileHeight: number;
orientation: string;
/** Hexagonal maps: Tiled's hexsidelength / staggeraxis / staggerindex. */
hexSideLength: number;
staggerAxis: string;
staggerIndex: string;
layers: TiledLayerData[];
tilesets: TiledTilesetData[];
objectGroups: TiledObjectGroupData[];
collisionTileIds: number[];
/**
* Rich per-tile collision (global id → normalized shape + modifiers), read from
* Tiled's tile collision editor (`tiles[].objectgroup`) and tile properties —
* the same {@link ResolvedTileCollision} model `.estileset` tiles resolve to,
* so both asset paths spawn identical colliders.
*/
tileShapes: Map<number, ResolvedTileCollision>;
tileAnimations: Map<number, TiledAnimFrame[]>;
tileProperties: Map<number, Map<string, string>>;
}
export function tiledGridLayout(map: {
orientation?: string; hexSideLength?: number; staggerAxis?: string; staggerIndex?: string;
}): TileGridLayout {
const orientations: Record<string, number> = { orthogonal: TilemapOrientation.Orthogonal,
isometric: TilemapOrientation.Isometric, staggered: TilemapOrientation.Staggered, hexagonal: TilemapOrientation.Hexagonal };
return { orientation: orientations[map.orientation ?? 'orthogonal'] ?? 0,
hexSideLength: map.hexSideLength ?? 0, staggerAxisX: map.staggerAxis === 'x',
staggerIndexEven: map.staggerIndex === 'even' };
}
const TILED_FLIP_H = 0x80000000;
const TILED_FLIP_V = 0x40000000;
const TILED_FLIP_D = 0x20000000;
const TILED_GID_MASK = 0x1FFFFFFF;
const ENGINE_FLIP_H = 0x2000;
const ENGINE_FLIP_V = 0x4000;
const ENGINE_FLIP_D = 0x8000;
function parseTintColorU32(val: number): { r: number; g: number; b: number; a: number } {
if (val === 0) return { r: 1, g: 1, b: 1, a: 1 };
const a = ((val >>> 24) & 0xFF) / 255;
const r = ((val >>> 16) & 0xFF) / 255;
const g = ((val >>> 8) & 0xFF) / 255;
const b = (val & 0xFF) / 255;
return { r, g, b, a: a === 0 ? 1 : a };
}
function parseTintColor(hex: string | undefined): { r: number; g: number; b: number; a: number } {
if (!hex) return { r: 1, g: 1, b: 1, a: 1 };
const s = hex.startsWith('#') ? hex.slice(1) : hex;
if (s.length === 8) {
const a = parseInt(s.slice(0, 2), 16) / 255;
const r = parseInt(s.slice(2, 4), 16) / 255;
const g = parseInt(s.slice(4, 6), 16) / 255;
const b = parseInt(s.slice(6, 8), 16) / 255;
return { r, g, b, a };
}
if (s.length === 6) {
const r = parseInt(s.slice(0, 2), 16) / 255;
const g = parseInt(s.slice(2, 4), 16) / 255;
const b = parseInt(s.slice(4, 6), 16) / 255;
return { r, g, b, a: 1 };
}
return { r: 1, g: 1, b: 1, a: 1 };
}
// Keep the global GID as the engine tile-id (Tiled GIDs are contiguous across
// tilesets); the runtime tileset table resolves it to (tileset, local). For a
// single-tileset map (firstgid 1) this equals the old local id + 1.
function convertGid(gid: number): number {
if (gid === 0) return 0;
let flags = 0;
if (gid & TILED_FLIP_H) flags |= ENGINE_FLIP_H;
if (gid & TILED_FLIP_V) flags |= ENGINE_FLIP_V;
if (gid & TILED_FLIP_D) flags |= ENGINE_FLIP_D;
const globalId = (gid & TILED_GID_MASK) & 0x1FFF;
return globalId | flags;
}
/** Split a Tiled tile-object GID into its global tile id + H/V/D flip flags. Unlike
* convertGid (which truncates to the engine's 13-bit tile-layer id), this keeps the
* full 29-bit global id so the object's tileset can be resolved by firstgid. */
export function decodeTiledGid(gid: number): { globalId: number; flipH: boolean; flipV: boolean; flipD: boolean } {
return {
globalId: gid & TILED_GID_MASK,
flipH: (gid & TILED_FLIP_H) !== 0,
flipV: (gid & TILED_FLIP_V) !== 0,
flipD: (gid & TILED_FLIP_D) !== 0,
};
}
/**
* Flatten Tiled `group` layers (which nest child layers) into one list, in
* document order — matching how tile/object layers are consumed.
*/
function flattenTmjLayers(rawLayers: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
const out: Array<Record<string, unknown>> = [];
for (const layer of rawLayers) {
if (layer.type === 'group') {
const children = layer.layers as Array<Record<string, unknown>> | undefined;
if (children) out.push(...flattenTmjLayers(children));
} else {
out.push(layer);
}
}
return out;
}
/**
* Re-chunk a Tiled infinite-layer chunk (tile-coordinate anchored, arbitrary
* size) into the engine's CHUNK_SIZE grid, keyed by CHUNK INDICES — the
* coordinate space `TilemapAPI.setChunkTiles` expects. Handles negative tile
* coordinates (infinite maps grow in all directions) via floor division.
*/
function rechunkTiledLayer(rawChunks: Array<Record<string, unknown>>): TiledChunkData[] {
const engine = new Map<string, TiledChunkData>();
for (const chunk of rawChunks) {
const baseX = (chunk.x as number) ?? 0;
const baseY = (chunk.y as number) ?? 0;
const w = (chunk.width as number) ?? 0;
const h = (chunk.height as number) ?? 0;
const data = chunk.data as number[] | undefined;
if (!data) continue;
for (let ty = 0; ty < h; ty++) {
for (let tx = 0; tx < w; tx++) {
const gid = data[ty * w + tx];
if (!gid) continue;
const gx = baseX + tx;
const gy = baseY + ty;
const cx = Math.floor(gx / CHUNK_SIZE);
const cy = Math.floor(gy / CHUNK_SIZE);
const key = `${cx},${cy}`;
let target = engine.get(key);
if (!target) {
target = {
x: cx, y: cy, width: CHUNK_SIZE, height: CHUNK_SIZE,
tiles: new Uint16Array(CHUNK_SIZE * CHUNK_SIZE),
};
engine.set(key, target);
}
target.tiles[(gy - cy * CHUNK_SIZE) * CHUNK_SIZE + (gx - cx * CHUNK_SIZE)] = convertGid(gid);
}
}
}
return [...engine.values()];
}
export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null {
const width = json.width as number;
const height = json.height as number;
const tileWidth = (json.tilewidth as number) ?? 0;
const tileHeight = (json.tileheight as number) ?? 0;
if (!width || !height || !tileWidth || !tileHeight) return null;
const rawTilesets = json.tilesets as Array<Record<string, unknown>> | undefined;
const tilesets: TiledTilesetData[] = [];
if (rawTilesets) {
for (const ts of rawTilesets) {
// Image-collection tileset: no top-level image, per-tile images.
const rawTiles = ts.tiles as Array<Record<string, unknown>> | undefined;
const collectionTiles = !ts.image && rawTiles?.some((t) => typeof t.image === 'string')
? rawTiles
.filter((t) => typeof t.image === 'string' && t.image)
.map((t) => ({
id: (t.id as number) ?? 0,
image: t.image as string,
width: (t.imagewidth as number) ?? 0,
height: (t.imageheight as number) ?? 0,
}))
: undefined;
tilesets.push({
name: (ts.name as string) ?? '',
image: (ts.image as string) ?? '',
firstGid: (ts.firstgid as number) ?? 1,
tileWidth: (ts.tilewidth as number) ?? tileWidth,
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 } : {}),
});
}
}
const topLayers = json.layers as Array<Record<string, unknown>> | undefined;
const rawLayers = topLayers ? flattenTmjLayers(topLayers) : undefined;
const layers: TiledLayerData[] = [];
if (rawLayers) {
for (const layer of rawLayers) {
if (layer.type !== 'tilelayer') continue;
const lw = (layer.width as number) ?? width;
const lh = (layer.height as number) ?? height;
const visible = layer.visible !== false;
const rawData = layer.data as number[] | undefined;
const rawChunks = layer.chunks as Array<Record<string, unknown>> | undefined;
const infinite = !!rawChunks && rawChunks.length > 0;
const chunks = infinite ? rechunkTiledLayer(rawChunks!) : [];
const tiles = new Uint16Array(infinite ? 0 : lw * lh);
if (!infinite && rawData) {
for (let i = 0; i < rawData.length && i < tiles.length; i++) {
tiles[i] = convertGid(rawData[i]);
}
}
const opacity = typeof layer.opacity === 'number' ? layer.opacity : 1;
const rawTint = layer.tintcolor as string | undefined;
const tintColor = parseTintColor(rawTint);
const parallaxX = typeof layer.parallaxx === 'number' ? layer.parallaxx : 1;
const parallaxY = typeof layer.parallaxy === 'number' ? layer.parallaxy : 1;
layers.push({
name: (layer.name as string) ?? '',
width: lw,
height: lh,
visible,
tiles,
chunks,
infinite,
opacity,
tintColor,
parallaxX,
parallaxY,
});
}
}
const objectGroups: TiledObjectGroupData[] = [];
const collisionTileIds: number[] = [];
if (rawLayers) {
for (const layer of rawLayers) {
if (layer.type !== 'objectgroup') continue;
const objs = layer.objects as Array<Record<string, unknown>> | undefined;
if (!objs) continue;
const parsed: TiledObjectData[] = [];
for (const obj of objs) {
const props = new Map<string, unknown>();
const rawProps = obj.properties as Array<Record<string, unknown>> | undefined;
if (rawProps) {
for (const p of rawProps) {
props.set(p.name as string, p.value);
}
}
let shape: TiledObjectShape = 'rect';
let vertices: number[] | null = null;
if (obj.ellipse) {
shape = 'ellipse';
} else if (obj.point) {
shape = 'point';
} else if (obj.polygon) {
shape = 'polygon';
const polyPts = obj.polygon as Array<{ x: number; y: number }>;
vertices = [];
for (const pt of polyPts) {
vertices.push(pt.x, pt.y);
}
} else if (obj.polyline) {
shape = 'polyline';
const linePts = obj.polyline as Array<{ x: number; y: number }>;
vertices = [];
for (const pt of linePts) {
vertices.push(pt.x, pt.y);
}
}
parsed.push({
id: (obj.id as number) ?? 0,
name: (obj.name as string) ?? '',
type: (obj.type as string) ?? (obj.class as string) ?? '',
visible: obj.visible !== false,
shape,
x: (obj.x as number) ?? 0,
y: (obj.y as number) ?? 0,
width: (obj.width as number) ?? 0,
height: (obj.height as number) ?? 0,
rotation: (obj.rotation as number) ?? 0,
vertices,
properties: props,
gid: typeof obj.gid === 'number' ? obj.gid : undefined,
});
}
const groupProps = new Map<string, unknown>();
const rawGroupProps = layer.properties as Array<Record<string, unknown>> | undefined;
if (rawGroupProps) {
for (const p of rawGroupProps) {
groupProps.set(p.name as string, p.value);
}
}
objectGroups.push({
name: (layer.name as string) ?? '',
visible: layer.visible !== false,
properties: groupProps,
objects: parsed,
});
}
}
const tileAnimations = new Map<number, TiledAnimFrame[]>();
const tileProperties = new Map<number, Map<string, string>>();
const tileShapes = new Map<number, ResolvedTileCollision>();
if (rawTilesets) {
for (const ts of rawTilesets) {
const firstGid = (ts.firstgid as number) ?? 1;
const tsTw = (ts.tilewidth as number) || tileWidth || 1;
const tsTh = (ts.tileheight as number) || tileHeight || 1;
const rawTiles = ts.tiles as Array<Record<string, unknown>> | undefined;
if (rawTiles) {
for (const tile of rawTiles) {
const localId = (tile.id as number);
// Global engine id = tileset-local id + firstGid (matches the
// global GIDs stored in the layer). firstgid 1 -> localId + 1.
const engineId = localId + firstGid;
const rawAnim = tile.animation as Array<Record<string, unknown>> | undefined;
if (rawAnim && rawAnim.length > 0) {
const frames: TiledAnimFrame[] = rawAnim.map(f => ({
tileId: ((f.tileid as number) ?? 0) + firstGid,
duration: (f.duration as number) ?? 100,
}));
tileAnimations.set(engineId, frames);
}
const tileProps = tile.properties as Array<Record<string, unknown>> | undefined;
let legacyCollision = false;
if (tileProps) {
const propMap = new Map<string, string>();
for (const p of tileProps) {
const name = p.name as string;
if (name === 'collision' && p.value === true) legacyCollision = true;
propMap.set(name, String(p.value));
}
if (propMap.size > 0) {
tileProperties.set(engineId, propMap);
}
}
// Tiled's tile collision editor (objectgroup) or the legacy
// `collision=true` property, folded into the SAME resolved model
// `.estileset` tiles use — plain solid boxes stay merge-eligible
// (collisionTileIds), everything richer spawns one collider each.
const og = tile.objectgroup as Record<string, unknown> | undefined;
const shape = tiledObjectgroupShape(
og?.objects as Array<Record<string, unknown>> | undefined, tsTw, tsTh)
?? (legacyCollision ? { type: 'box' as const } : null);
if (shape) {
const rc: ResolvedTileCollision = { shape, ...tiledCollisionMods(tileProps) };
if (shape.type === 'box' && !rc.oneWay && !rc.sensor
&& rc.density === undefined && rc.friction === undefined && rc.restitution === undefined) {
collisionTileIds.push(engineId);
} else {
tileShapes.set(engineId, rc);
}
}
}
}
}
}
const orientation = (json.orientation as string) ?? 'orthogonal';
const hexSideLength = (json.hexsidelength as number) ?? 0;
const staggerAxis = (json.staggeraxis as string) ?? 'y';
const staggerIndex = (json.staggerindex as string) ?? 'odd';
return {
width, height, tileWidth, tileHeight, orientation,
hexSideLength, staggerAxis, staggerIndex,
layers, tilesets, objectGroups, collisionTileIds, tileShapes,
tileAnimations, tileProperties,
};
}
/**
* The first collision-editor object of a Tiled tile's `objectgroup`, as a
* normalized {@link ResolvedTileCollision} shape (tile-fraction coordinates, the
* same space `.estileset` collision resolves into). A full-cell rectangle folds
* to `box` (merge-eligible); a partial rectangle becomes its 4-corner polygon;
* an ellipse becomes the inscribed-average circle. Polylines/points are skipped.
*/
export function tiledObjectgroupShape(
objects: Array<Record<string, unknown>> | undefined,
tw: number,
th: number,
): ResolvedTileCollision['shape'] | null {
if (!objects) return null;
for (const o of objects) {
if (o.point === true || o.polyline) continue;
const x = (o.x as number) ?? 0;
const y = (o.y as number) ?? 0;
const w = (o.width as number) ?? 0;
const h = (o.height as number) ?? 0;
if (o.ellipse === true) {
if (w <= 0 || h <= 0) continue;
return { type: 'circle', cx: (x + w / 2) / tw, cy: (y + h / 2) / th, r: (w + h) / 4 / tw };
}
const poly = o.polygon as Array<{ x: number; y: number }> | undefined;
if (poly && poly.length >= 3) {
return { type: 'polygon', points: poly.map((p) => [(x + p.x) / tw, (y + p.y) / th]) };
}
if (w > 0 && h > 0) {
const eps = 0.5; // px — Tiled UI drags land on fractional coords
if (Math.abs(x) <= eps && Math.abs(y) <= eps && Math.abs(w - tw) <= eps && Math.abs(h - th) <= eps) {
return { type: 'box' };
}
return {
type: 'polygon',
points: [[x / tw, y / th], [(x + w) / tw, y / th], [(x + w) / tw, (y + h) / th], [x / tw, (y + h) / th]],
};
}
}
return null;
}
/**
* Collision modifiers from a Tiled tile's typed properties — the same vocabulary
* the `.estileset` modifier bar writes: `oneway` (bool, solid-top), `sensor`
* (bool), `friction` / `restitution` / `density` (float).
*/
export function tiledCollisionMods(
props: Array<Record<string, unknown>> | undefined,
): Partial<Pick<ResolvedTileCollision, 'oneWay' | 'sensor' | 'density' | 'friction' | 'restitution'>> {
const out: Partial<Pick<ResolvedTileCollision, 'oneWay' | 'sensor' | 'density' | 'friction' | 'restitution'>> = {};
if (!props) return out;
for (const p of props) {
const name = (p.name as string ?? '').toLowerCase();
const v = p.value;
if (name === 'oneway' && v === true) out.oneWay = { nx: 0, ny: 1 };
else if (name === 'sensor' && v === true) out.sensor = true;
else if ((name === 'friction' || name === 'restitution' || name === 'density') && typeof v === 'number') {
out[name] = v;
}
}
return out;
}
/**
* Parse a .tmj whose tilesets may be EXTERNAL references (`{firstgid, source}`
* pointing at a .tsj): fetch each source through `resolveExternal`, merge it
* inline (a .tsj carries the same tileset fields, minus firstgid) with its
* image path rewritten from tsj-relative to map-relative, then run the
* standard parse. Maps with only inline tilesets never invoke the resolver.
*/
export async function parseTmjWithExternals(
json: Record<string, unknown>,
resolveExternal: (source: string) => Promise<string>,
): Promise<TiledMapData | null> {
const rawTilesets = json.tilesets as Array<Record<string, unknown>> | undefined;
if (rawTilesets?.some((ts) => typeof ts.source === 'string')) {
const merged = await Promise.all(rawTilesets.map(async (ts) => {
if (typeof ts.source !== 'string') return ts;
let external = JSON.parse(await resolveExternal(ts.source)) as Record<string, unknown>;
if (typeof external.image === 'string' && external.image) {
external = { ...external, image: resolveTiledRef(ts.source, external.image) };
}
// Collection tilesets carry per-tile images — rewrite those too.
if (Array.isArray(external.tiles)) {
external = {
...external,
tiles: (external.tiles as Array<Record<string, unknown>>).map((t) =>
typeof t?.image === 'string' && t.image
? { ...t, image: resolveTiledRef(ts.source as string, t.image) }
: t),
};
}
return { ...external, firstgid: ts.firstgid };
}));
json = { ...json, tilesets: merged };
}
return parseTmjJson(json);
}
// The resolution lives in ../asset/documentRef (a dependency-free leaf) so the
// cook and every loader share it. Re-exported for existing importers.
export { resolveRelativePath, resolveDocumentRef, resolveTiledRef, isLogicalAssetRef };
export interface CollectionGridTile {
/** Local tile id — also the grid slot, so gid → cell stays the identity
* even when ids are sparse (deleted tiles leave transparent holes). */
id: number;
/** Top-first RGBA, exactly tileWidth × tileHeight. */
pixels: Uint8Array;
}
/**
* Fold an image-collection tileset's decoded tiles into ONE grid-atlas pixel
* buffer (near-square, one slot per local id, transparent holes for sparse
* ids). The result is indistinguishable from a hand-authored grid tileset, so
* the renderer's uv math needs no collection special case. Pure — unit-tested
* apart from the decode/upload plumbing.
*/
export function packCollectionGrid(
tiles: CollectionGridTile[], tileWidth: number, tileHeight: number,
): { pixels: Uint8Array; columns: number; rows: number; width: number; height: number } {
const slots = tiles.reduce((m, t) => Math.max(m, t.id), 0) + 1;
const columns = Math.max(1, Math.ceil(Math.sqrt(slots)));
const rows = Math.max(1, Math.ceil(slots / columns));
const width = columns * tileWidth;
const height = rows * tileHeight;
const pixels = new Uint8Array(width * height * 4);
const rowBytes = tileWidth * 4;
for (const t of tiles) {
const cellX = (t.id % columns) * tileWidth;
const cellY = Math.floor(t.id / columns) * tileHeight;
for (let y = 0; y < tileHeight; y++) {
pixels.set(
t.pixels.subarray(y * rowBytes, (y + 1) * rowBytes),
((cellY + y) * width + cellX) * 4,
);
}
}
return { pixels, columns, rows, width, height };
}
export interface TilemapLoadOptions {
generateObjectCollision?: boolean;
collisionTileIds?: number[];
}
const DEG_TO_RAD = Math.PI / 180;
/**
* True when a Tiled object group is authored as collision geometry: a
* `collision=true` group property (mirroring the tile-property convention) or
* the group being named `collision` (case-insensitive).
*/
export function isCollisionObjectGroup(group: TiledObjectGroupData): boolean {
return group.properties?.get('collision') === true
|| group.name.toLowerCase() === 'collision';
}
/**
* @brief Spawn static colliders for Tiled OBJECT layers (rect / ellipse / polygon / polyline).
*
* Same world convention as the tile-collision generators: the map's top-left corner sits at
* (originX, originY) and Tiled's y-down pixel coordinates descend from it
* (`world = (originX + px, originY - py)`). Rotation is Tiled's clockwise degrees about the
* object anchor (top-left for rects/ellipses, the vertex origin for polygons) — realized as
* the equivalent negative z-rotation on the collider entity, positioned at the true shape
* centre. Collider GEOMETRY is physics units (metres): pixel sizes divide by pixelsPerUnit,
* matching `BoxCollider2D.halfExtents` semantics (positions stay pixels; physics scales those).
*
* Shapes: rect → BoxCollider2D; ellipse → CircleCollider2D on the mean semi-axis (exact for
* circles); polygon ≤ 8 vertices → PolygonCollider2D (Box2D's vertex cap); polygon > 8 →
* bounding-box BoxCollider2D with a warning (predictably solid, never silently truncated);
* polyline → open ChainCollider2D (the physics layer requires ≥ 4 points); point → skipped
* (spawn/marker data, queryable from the parsed map).
*/
/**
* World transform of a Tiled object's shape centre at object-LOCAL offset (lx, ly).
* Tiled rotates clockwise about the object anchor in y-down pixel space, realized as
* a negative z-rotation with y flipped; `(ox, oy)` is the map origin (0 for the
* parented/local path). The single source of the object position/rotation math for
* both {@link generateObjectCollision} and {@link spawnObjectRegion}.
*/
function objectShapeTransform(
obj: TiledObjectData, ox: number, oy: number, lx: number, ly: number,
): { position: { x: number; y: number; z: number }; rotation?: { w: number; x: number; y: number; z: number } } {
const rad = obj.rotation * DEG_TO_RAD;
const cos = Math.cos(rad);
const sin = Math.sin(rad);
const position = { x: ox + obj.x + lx * cos - ly * sin, y: oy - (obj.y + lx * sin + ly * cos), z: 0 };
if (rad === 0) return { position };
const half = -rad * 0.5;
return { position, rotation: { w: Math.cos(half), x: 0, y: 0, z: Math.sin(half) } };
}
/**
* The shape → collider decision shared by both Tiled object paths: rect → BoxCollider2D,
* ellipse → CircleCollider2D on the mean semi-axis, polygon ≤ 8 verts → PolygonCollider2D
* (> 8 → bounding-box Box, never silently truncated), polyline → open ChainCollider2D.
* `spawn(lx, ly)` positions AND assembles the entity at the shape centre in the caller's
* space — world-placed bare collider vs parented Marker region — so only the collider
* geometry (metres = pixels ÷ ppu) lives here. Returns the entity, or null when the shape
* yields no collider: too few vertices, or a sensor polyline (an open chain has no sensor
* mode). Point / gid objects are pre-filtered by the caller.
*/
function attachObjectShape(
world: World, obj: TiledObjectData, pixelsPerUnit: number, sensor: boolean, groupName: string,
spawn: (lx: number, ly: number) => Entity,
): Entity | null {
if (obj.shape === 'rect') {
const e = spawn(obj.width * 0.5, obj.height * 0.5);
world.insert(e, BoxCollider2D, {
halfExtents: { x: obj.width * 0.5 / pixelsPerUnit, y: obj.height * 0.5 / pixelsPerUnit },
isSensor: sensor,
});
return e;
}
if (obj.shape === 'ellipse') {
const e = spawn(obj.width * 0.5, obj.height * 0.5);
world.insert(e, CircleCollider2D, { radius: (obj.width + obj.height) * 0.25 / pixelsPerUnit, isSensor: sensor });
return e;
}
if (!obj.vertices || obj.vertices.length < 4) return null;
// Local vertices flip Tiled's y-down into the body's y-up space; the entity's
// rotation carries the object angle. (binary subtraction: -v yields -0 for zeros)
const local: { x: number; y: number }[] = [];
for (let i = 0; i < obj.vertices.length; i += 2) {
local.push({ x: obj.vertices[i] / pixelsPerUnit, y: (0 - obj.vertices[i + 1]) / pixelsPerUnit });
}
if (obj.shape === 'polyline') {
if (sensor) return null;
const e = spawn(0, 0);
world.insert(e, ChainCollider2D, { points: local, isLoop: false });
return e;
}
if (local.length < 3) return null; // a polygon needs at least a triangle
if (local.length <= 8) {
const e = spawn(0, 0);
world.insert(e, PolygonCollider2D, { vertices: local, isSensor: sensor });
return e;
}
log.warn('tilemap', `object polygon in group '${groupName}' has ${local.length} vertices (Box2D max 8); using its bounding box`);
let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
for (let i = 0; i < obj.vertices.length; i += 2) {
const vx = obj.vertices[i], vy = obj.vertices[i + 1];
if (vx < minX) minX = vx;
if (vx > maxX) maxX = vx;
if (vy < minY) minY = vy;
if (vy > maxY) maxY = vy;
}
const e = spawn((minX + maxX) * 0.5, (minY + maxY) * 0.5);
world.insert(e, BoxCollider2D, {
halfExtents: { x: (maxX - minX) * 0.5 / pixelsPerUnit, y: (maxY - minY) * 0.5 / pixelsPerUnit },
isSensor: sensor,
});
return e;
}
export function generateObjectCollision(
world: World,
groups: TiledObjectGroupData[],
originX: number,
originY: number,
pixelsPerUnit: number = 1,
): Entity[] {
const entities: Entity[] = [];
for (const group of groups) {
for (const obj of group.objects) {
if (obj.shape === 'point') continue;
const e = attachObjectShape(world, obj, pixelsPerUnit, false, group.name, (lx, ly) => {
const entity = world.spawn();
const { position, rotation } = objectShapeTransform(obj, originX, originY, lx, ly);
world.insert(entity, Transform, rotation ? { position, rotation } : { position });
world.insert(entity, RigidBody2D, { bodyType: BodyType.Static });
return entity;
});
if (e) entities.push(e);
}
}
return entities;
}
/** A Tiled object's custom properties as a plain string→string record (Marker.properties). */
function objectPropsRecord(obj: TiledObjectData): Record<string, string> {
const props: Record<string, string> = {};
for (const [k, v] of obj.properties) props[k] = String(v);
return props;
}
/**
* @brief Project ONE Tiled SHAPE object (rect / ellipse / polygon / polyline) into a real
* REGION entity — the same shape a hand-authored Trigger Area preset builds:
* Transform + Marker{type,properties} + static RigidBody2D + a collider matching the
* shape. `sensor` picks the flavour: a non-collision group's regions are SENSORS
* (trigger zones), a `collision` group's regions are SOLID geometry (walls/floors) —
* one derivation for both, so every shape object becomes a queryable, gizmo-visible
* entity instead of an invisible play-only collider or unqueried `objectGroups` data.
*
* LOCAL coords (the tilemap parent carries the origin), mirroring the tile-object sprites;
* geometry is metres (÷ ppu) like {@link generateObjectCollision}. rect → Box, ellipse →
* Circle, polygon ≤8 verts → Polygon (>8 → bounding-box Box), polyline → open Chain.
* Point / gid objects project elsewhere (Marker / Sprite) → null.
*/
export function spawnObjectRegion(
world: World,
obj: TiledObjectData,
parent: Entity,
pixelsPerUnit: number,
sensor: boolean,
): Entity | null {
if (obj.gid !== undefined || obj.shape === 'point') return null;
// Local shape centre (parent carries the tilemap origin) → origin 0 in the shared
// transform; assemble the queryable, gizmo-visible region entity around each collider.
return attachObjectShape(world, obj, pixelsPerUnit, sensor, obj.name || `object ${obj.id}`, (lx, ly) => {
const e = world.spawn(obj.name || `Region_${obj.id}`);
const { position, rotation } = objectShapeTransform(obj, 0, 0, lx, ly);
world.insert(e, Transform, rotation ? { position, rotation } : { position });
world.insert(e, Marker, { type: obj.type || '', properties: objectPropsRecord(obj) });
world.insert(e, RigidBody2D, { bodyType: BodyType.Static });
world.insert(e, RuntimeOnly, {});
world.setParent(e, parent);
return e;
});
}
/**
* @brief Spawn static colliders for EVERY object group of a parsed map (the code-driven
* `loadTiledMap` path; the scene path filters by {@link isCollisionObjectGroup}).
*
* NOTE: behaviour fixed to the shared convention — origin at the map's TOP-left with world-y
* descending (was bottom-left/y-up, a full map-height off the tiles, the same latent bug the
* tile path had fixed) and metre-unit collider geometry via `pixelsPerUnit` (was raw pixels).
*/
export function loadTiledCollisionObjects(
world: World,
mapData: TiledMapData,
mapOriginX: number,
mapOriginY: number,
pixelsPerUnit: number = 1,
): Entity[] {
return generateObjectCollision(world, mapData.objectGroups, mapOriginX, mapOriginY, pixelsPerUnit);
}
/**
* Static boxes in layer pixels, relative to the supplied origin; extents use physics units.
* Layout defaults to orthogonal. Merging preserves the union of projected tile boxes.
*/
export function generateLayerCollision(
world: World,
tiles: ArrayLike<number>,
gridWidth: number,
gridHeight: number,
tileW: number,
tileH: number,
collisionIds: Set<number>,
originX: number,
originY: number,
pixelsPerUnit: number = 1,
layout?: TileGridLayout,
): Entity[] {
const grid = collisionGrid(tileW, tileH, layout), entities: Entity[] = [];
for (const box of collisionBoxes(tiles, gridWidth, gridHeight, collisionIds, grid)) {
const entity = world.spawn();
world.insert(entity, Transform, { position: { x: originX + box.center.x, y: originY + box.center.y, z: 0 } });
world.insert(entity, RigidBody2D, { bodyType: BodyType.Static });
world.insert(entity, BoxCollider2D, { halfExtents: { x: box.halfExtents.x / pixelsPerUnit, y: box.halfExtents.y / pixelsPerUnit } });
entities.push(entity);
}
return entities;
}
export function generateTileCollision(
world: World,
layer: TiledLayerData,
mapData: TiledMapData,
collisionIds: Set<number>,
originX: number,
originY: number,
): Entity[] {
return generateLayerCollision(
world, layer.tiles, layer.width, layer.height,
mapData.tileWidth, mapData.tileHeight, collisionIds,
originX, originY,
1, tiledGridLayout(mapData),
);
}
/**
* Static boxes from native chunks, with layout-aware placement and exact per-chunk merging.
* Positions use layer pixels; extents are divided by pixelsPerUnit for physics.
*/
export function generateChunkCollision(
world: World,
chunks: { x: number; y: number; tiles: Uint16Array }[],
collisionIds: Set<number>,
tileW: number,
tileH: number,
originX: number,
originY: number,
pixelsPerUnit: number = 1,
layout?: TileGridLayout,
): Entity[] {
const grid = collisionGrid(tileW, tileH, layout), entities: Entity[] = [];
for (const chunk of chunks) {
const boxes = collisionBoxes(chunk.tiles, CHUNK_SIZE, CHUNK_SIZE, collisionIds, grid, chunk.x * CHUNK_SIZE, chunk.y * CHUNK_SIZE);
for (const box of boxes) entities.push(spawnCollisionBox(world, box, originX, originY, pixelsPerUnit));
}
return entities;
}
function spawnCollisionBox(world: World, box: ReturnType<typeof collisionBoxes>[number], originX: number, originY: number, ppu: number): Entity {
const entity = world.spawn();
world.insert(entity, Transform, { position: { x: originX + box.center.x, y: originY + box.center.y, z: 0 } });
world.insert(entity, RigidBody2D, { bodyType: BodyType.Static });
world.insert(entity, BoxCollider2D, { halfExtents: { x: box.halfExtents.x / ppu, y: box.halfExtents.y / ppu } });
return entity;
}
/**
* The colliders one chunk should carry, by a key that names a collider's shape and place and nothing else. A rebuild keeps every collider whose key survives,
* so a body resting on one sees no contact end and nothing sleeping is woken. `boxTiles` is what the plain boxes merge over; the rich shapes always read `chunk.tiles`.
* @internal
*/
export function chunkColliderPlan(
chunk: { x: number; y: number; tiles: Uint16Array }, boxTiles: Uint16Array,
boxIds: ReadonlySet<number>, shapes: ReadonlyMap<number, ResolvedTileCollision>,
tileW: number, tileH: number, originX: number, originY: number, ppu: number, layout?: TileGridLayout,
): Map<string, (world: World) => Entity> {
const plan = new Map<string, (world: World) => Entity>();
const grid = collisionGrid(tileW, tileH, layout), baseX = chunk.x * CHUNK_SIZE, baseY = chunk.y * CHUNK_SIZE;
if (boxIds.size > 0) {
for (const box of collisionBoxes(boxTiles, CHUNK_SIZE, CHUNK_SIZE, boxIds as Set<number>, grid, baseX, baseY)) {
plan.set(`b${box.center.x},${box.center.y},${box.halfExtents.x},${box.halfExtents.y}`,
world => spawnCollisionBox(world, box, originX, originY, ppu));
}
}
if (shapes.size > 0) {
for (let i = 0; i < chunk.tiles.length; i++) {
const raw = chunk.tiles[i]!, rc = shapes.get(tileIdOf(raw));
if (!rc) continue;
const gx = baseX + (i % CHUNK_SIZE), gy = baseY + Math.floor(i / CHUNK_SIZE);
plan.set(`s${i},${raw}`, world => spawnTileShape(world, rc, raw, gx, gy, tileW, tileH, originX, originY, ppu || 1, grid));
}
}
return plan;
}
/**
* A chunk's tiles with its buried plain boxes cleared: a box every side of which another plain box covers can never be touched from outside.
* `neighbour` answers the chunks around it, so a chunk edge reads the next chunk's tiles rather than counting as open ground.
* @internal
*/
export function exposedCollisionTiles(
chunk: { x: number; y: number; tiles: Uint16Array }, boxIds: ReadonlySet<number>,
neighbour: (chunkX: number, chunkY: number) => Uint16Array | undefined,
): Uint16Array {
const out = chunk.tiles.slice();
const covers = (tiles: Uint16Array | undefined, index: number): boolean =>
tiles !== undefined && tiles.length > 0 && boxIds.has(tileIdOf(tiles[index]!));
const left = neighbour(chunk.x - 1, chunk.y), right = neighbour(chunk.x + 1, chunk.y);
const up = neighbour(chunk.x, chunk.y - 1), down = neighbour(chunk.x, chunk.y + 1);
const last = CHUNK_SIZE - 1;
for (let y = 0; y < CHUNK_SIZE; y++) for (let x = 0; x < CHUNK_SIZE; x++) {
const i = y * CHUNK_SIZE + x;
if (!boxIds.has(tileIdOf(chunk.tiles[i]!))) continue;
const buried = (x > 0 ? covers(chunk.tiles, i - 1) : covers(left, y * CHUNK_SIZE + last))
&& (x < last ? covers(chunk.tiles, i + 1) : covers(right, y * CHUNK_SIZE))
&& (y > 0 ? covers(chunk.tiles, i - CHUNK_SIZE) : covers(up, last * CHUNK_SIZE + x))
&& (y < last ? covers(chunk.tiles, i + CHUNK_SIZE) : covers(down, x));
if (buried) out[i] = 0;
}
return out;
}
/**
* Convert a tile's normalized polygon outline ([0,1], x right / y down) to entity-local
* vertices (origin = cell center, y up), applying the cell's flip flags so the collider
* matches the rendered tile. The flip is the inverse of the renderer's `applyTileFlip`
* (texture→quad): undo V, then H, then the diagonal swap.
*/
export function polygonLocalVerts(
norm: ReadonlyArray<readonly [number, number]>,
tileW: number,
tileH: number,
flipH: boolean,
flipV: boolean,
flipD: boolean,
): { x: number; y: number }[] {
return norm.map(([sx, syDown]) => {
let s = sx;
let t = 1 - syDown; // to texture-up normalized
if (flipV) t = 1 - t;
if (flipH) s = 1 - s;
if (flipD) { const tmp = s; s = t; t = tmp; }
return { x: (s - 0.5) * tileW, y: (t - 0.5) * tileH };
});
}
/**
* The pixel-space {@link Collider2DShape} for a resolved tile collision, the cell's flip
* flags applied (origin = cell center, y up). The SINGLE tile→geometry definition shared
* by the runtime spawn ({@link generateChunkTileShapes}, which divides by ppu into a
* collider component) and the editor's tile-collision overlay (which feeds it to
* `collider2DOutline`). A box is flip-symmetric so its geometry ignores the flags; a
* polygon and a circle's centre go through {@link polygonLocalVerts}, matching the render.
*/
export function tileColliderShape(
rc: ResolvedTileCollision,
tileW: number,
tileH: number,
flipH: boolean,
flipV: boolean,
flipD: boolean,
): Collider2DShape {
const s = rc.shape;
if (s.type === 'polygon') {
return { kind: 'polygon', vertices: polygonLocalVerts(s.points, tileW, tileH, flipH, flipV, flipD) };
}
if (s.type === 'circle') {
// Reuse the polygon transform on the single centre point to apply flips; the
// radius is a tile-width fraction (assumes square-ish cells).
const c = polygonLocalVerts([[s.cx, s.cy]], tileW, tileH, flipH, flipV, flipD)[0];
return { kind: 'circle', radius: s.r * tileW, offset: c };
}
return { kind: 'box', halfExtents: { x: tileW * 0.5, y: tileH * 0.5 }, offset: { x: 0, y: 0 } };
}
/**
* Spawn one static PolygonCollider2D per placed tile whose global id has a polygon shape
* (slopes / partial tiles). Box-shaped tiles are handled by {@link generateChunkCollision};
* the two run together. Flip flags on a cell flip its polygon to match the render.
*/
export function generateChunkPolygonCollision(
world: World,
chunks: { x: number; y: number; tiles: Uint16Array }[],
polygonShapes: Map<number, readonly [number, number][]>,
tileW: number,
tileH: number,
originX: number,
originY: number,
pixelsPerUnit: number = 1,
layout?: TileGridLayout,
): Entity[] {
const shapes = new Map<number, ResolvedTileCollision>();
for (const [id, points] of polygonShapes) shapes.set(id, { shape: { type: "polygon", points: Array.from(points) } });
return generateChunkTileShapes(world, chunks, shapes, tileW, tileH, originX, originY, pixelsPerUnit, layout);
}
/** A one-way solid-side normal (layer y-up; {0,1} = solid-top), reoriented by cell flips
* so a flipped platform's solid side follows the render. Shared with the editor overlay,
* so a flipped one-way tile's arrow matches the side a body actually lands on at Play. */
export function oneWayNormalWorld(nx: number, ny: number, fH: boolean, fV: boolean, fD: boolean): { x: number; y: number } {
let x = nx;
let y = ny;
if (fH) x = -x;
if (fV) y = -y;
if (fD) { const tmp = x; x = y; y = tmp; }
return { x, y };
}
/**
* Spawn ONE static collider for a rich-shaped tile at grid cell (gx, gy) — the
* per-cell core shared by the chunked (painted-layer) and finite (Tiled-layer)
* drivers, so both asset paths produce byte-identical collision entities.
*/
function spawnTileShape(
world: World,
rc: ResolvedTileCollision,
raw: number,
gx: number,
gy: number,
tileW: number,
tileH: number,
originX: number,
originY: number,
ppu: number,
grid: TileGridParams,
): Entity {
const f = tileFlagsOf(raw);
const center = tileCellCenter(grid, gx, gy);
const entity = world.spawn();
world.insert(entity, Transform, {
position: { x: originX + center.x, y: originY + center.y, z: 0 },
});
world.insert(entity, RigidBody2D, { bodyType: BodyType.Static });
// Only the material/sensor fields the tile overrode; the rest keep component defaults.
const mat: { density?: number; friction?: number; restitution?: number; isSensor?: boolean } = {};
if (rc.density !== undefined) mat.density = rc.density;
if (rc.friction !== undefined) mat.friction = rc.friction;
if (rc.restitution !== undefined) mat.restitution = rc.restitution;
if (rc.sensor) mat.isSensor = true;
// One pixel-space shape definition (flip-applied), scaled to physics units
// (÷ppu) into the matching collider component — the same geometry the editor
// overlay draws, so what you see out of Play is what spawns.
const shape = tileColliderShape(rc, tileW, tileH, f.flipH, f.flipV, f.flipD);
if (shape.kind === 'polygon') {
world.insert(entity, PolygonCollider2D, {
vertices: shape.vertices.map((v) => ({ x: v.x / ppu, y: v.y / ppu })),
...mat,
});
} else if (shape.kind === 'circle') {
world.insert(entity, CircleCollider2D, {
radius: shape.radius / ppu,
offset: { x: shape.offset.x / ppu, y: shape.offset.y / ppu },
...mat,
});
} else if (shape.kind === 'box') {
world.insert(entity, BoxCollider2D, {
halfExtents: { x: shape.halfExtents.x / ppu, y: shape.halfExtents.y / ppu },
...mat,
});
}
if (rc.oneWay) {
world.insert(entity, OneWayPlatform2D, {
normal: oneWayNormalWorld(rc.oneWay.nx, rc.oneWay.ny, f.flipH, f.flipV, f.flipD),
localSpace: true,
});
}
return entity;
}
/**
* Spawn one static collider per placed tile whose global id resolves to a RICH shape —
* polygon / circle, or a box carrying a one-way / sensor / material modifier — i.e. the
* tiles the plain-box greedy merge ({@link generateChunkCollision}) deliberately skips.
* Both run together over the same chunks. Flip flags reorient the shape (and the one-way
* normal) to match the rendered tile. Geometry is in physics units (÷ pixelsPerUnit).
*/
export function generateChunkTileShapes(
world: World,
chunks: { x: number; y: number; tiles: Uint16Array }[],
tileShapes: Map<number, ResolvedTileCollision>,
tileW: number,
tileH: number,
originX: number,
originY: number,
pixelsPerUnit: number = 1,
layout?: TileGridLayout,
): Entity[] {
const entities: Entity[] = [];
if (tileShapes.size === 0) return entities;
const ppu = pixelsPerUnit || 1;
const grid = collisionGrid(tileW, tileH, layout);
for (const chunk of chunks) {
const baseX = chunk.x * CHUNK_SIZE;
const baseY = chunk.y * CHUNK_SIZE;
for (let i = 0; i < chunk.tiles.length; i++) {
const raw = chunk.tiles[i];
const rc = tileShapes.get(tileIdOf(raw));
if (!rc) continue;
const gx = baseX + (i % CHUNK_SIZE);
const gy = baseY + Math.floor(i / CHUNK_SIZE);
entities.push(spawnTileShape(world, rc, raw, gx, gy, tileW, tileH, originX, originY, ppu, grid));
}
}
return entities;
}
/**
* Finite-layer sibling of {@link generateChunkTileShapes} — rich shapes for a flat
* Tiled layer array. Runs alongside {@link generateLayerCollision} the same way
* the chunk pair runs together on the painted path.
*/
export function generateLayerTileShapes(
world: World,
tiles: ArrayLike<number>,
gridWidth: number,
gridHeight: number,
tileShapes: Map<number, ResolvedTileCollision>,
tileW: number,
tileH: number,
originX: number,
originY: number,
pixelsPerUnit: number = 1,
layout?: TileGridLayout,
): Entity[] {
const entities: Entity[] = [];
if (tileShapes.size === 0) return entities;
const ppu = pixelsPerUnit || 1;
const grid = collisionGrid(tileW, tileH, layout);
const count = Math.min(tiles.length, gridWidth * gridHeight);
for (let i = 0; i < count; i++) {
const raw = tiles[i];
const rc = tileShapes.get(tileIdOf(raw));
if (!rc) continue;
entities.push(spawnTileShape(
world, rc, raw, i % gridWidth, Math.floor(i / gridWidth),
tileW, tileH, originX, originY, ppu, grid,
));
}
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,
layout?: TileGridLayout,
): Pick<TilemapLayerData, 'cellSize' | 'renderLayer' | 'visible' | 'opacity' | 'tintColor' | 'parallaxFactor'
| 'orientation' | 'hexSideLength' | 'staggerAxis' | 'staggerIndex'> {
return {
orientation: layout?.orientation ?? 0, hexSideLength: layout?.hexSideLength ?? 0,
staggerAxis: layout?.staggerAxisX ? 1 : 0, staggerIndex: layout?.staggerIndexEven ? 1 : 0,
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,
textureHandles: Map<string, number>,
options: TilemapLoadOptions = {},
): Entity[] {
const entities: Entity[] = [];
const firstTileset = mapData.tilesets[0];
const layout = tiledGridLayout(mapData);
let layerIndex = 0;
for (const layer of mapData.layers) {
if (!layer.visible) continue;
const entity = world.spawn();
world.insert(entity, Transform, {});
const textureHandle = firstTileset
? (textureHandles.get(firstTileset.image) ?? 0)
: 0;
const columns = firstTileset?.columns ?? 1;
world.insert(entity, TilemapLayer, {
...tiledLayerComponent(layer, mapData.tileWidth, mapData.tileHeight, layerIndex, layout),
tileset: textureHandle,
tilesetColumns: columns,
});
TilemapAPI.initInfiniteLayer(entity, mapData.tileWidth, mapData.tileHeight);
TilemapAPI.setOriginEntity(entity, entity);
TilemapAPI.setGridType(entity, layout.orientation);
TilemapAPI.setHexParams(entity, layout.hexSideLength ?? 0, !!layout.staggerAxisX, !!layout.staggerIndexEven);
uploadTiledLayerTiles(entity, layer);
entities.push(entity);
layerIndex++;
}
const generateCollision = options.generateObjectCollision !== false;
if (generateCollision && mapData.objectGroups.length > 0) {
const collisionEntities = loadTiledCollisionObjects(world, mapData, 0, 0);
entities.push(...collisionEntities);
}
const tileCollisionIds = new Set<number>(
options.collisionTileIds ?? mapData.collisionTileIds,
);
if (tileCollisionIds.size > 0) {
for (const layer of mapData.layers) {
if (!layer.visible) continue;
// Infinite layers are re-chunked to CHUNK_SIZE at parse — same generators
// as the painted path.
entities.push(...(layer.infinite
? generateChunkCollision(
world, layer.chunks, tileCollisionIds,
mapData.tileWidth, mapData.tileHeight, 0, 0, 1, layout)
: generateTileCollision(world, layer, mapData, tileCollisionIds, 0, 0)));
}
}
if (mapData.tileShapes && mapData.tileShapes.size > 0) {
for (const layer of mapData.layers) {
if (!layer.visible) continue;
entities.push(...(layer.infinite
? generateChunkTileShapes(
world, layer.chunks, mapData.tileShapes,
mapData.tileWidth, mapData.tileHeight, 0, 0, 1, layout)
: generateLayerTileShapes(
world, layer.tiles, layer.width, layer.height, mapData.tileShapes,
mapData.tileWidth, mapData.tileHeight, 0, 0, 1, layout)));
}
}
return entities;
}