import { Component } from "../components/component.js";
import { Tileset } from "./tileset.js";
import { ResourceReferenceError } from "../core/scene.js";
const TILE_METADATA_FIELDS = new Set(["walkable", "terrain", "collision", "damage", "slowdown", "movementCost", "interaction", "transition"]);
function validateGameplayMetadata(metadata, label) {
if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
throw new TypeError(`${label} metadata must be an object`);
}
for (const key of Object.keys(metadata)) {
if (!TILE_METADATA_FIELDS.has(key)) throw new TypeError(`Unknown ${label.toLowerCase()} metadata field: ${key}`);
}
if (metadata.walkable !== undefined && typeof metadata.walkable !== "boolean") {
throw new TypeError(`${label} metadata walkable must be a boolean`);
}
if (metadata.terrain !== undefined && typeof metadata.terrain !== "string") {
throw new TypeError(`${label} metadata terrain must be a string`);
}
if (metadata.collision !== undefined && typeof metadata.collision !== "boolean") {
throw new TypeError(`${label} metadata collision must be a boolean`);
}
for (const field of ["damage", "slowdown", "movementCost"]) {
if (metadata[field] !== undefined && (!Number.isFinite(metadata[field]) || metadata[field] < 0)) {
throw new TypeError(`${label} metadata ${field} must be a finite non-negative number`);
}
}
for (const field of ["interaction", "transition"]) {
if (metadata[field] !== undefined && metadata[field] !== null &&
(typeof metadata[field] !== "object" || Array.isArray(metadata[field]))) {
throw new TypeError(`${label} metadata ${field} must be an object or null`);
}
}
}
/**
* Tilemap component renders a grid of tiles from a tileset.
* @class Tilemap
* @extends Component
*/
export class Tilemap extends Component {
/**
* @param {Tileset} tileset - The tileset to use.
* @param {number} width - Map width in tiles.
* @param {number} height - Map height in tiles.
*/
constructor(tileset, width = 10, height = 10) {
super();
if (!(tileset instanceof Tileset)) {
throw new ResourceReferenceError("tileset", tileset, "tilemap.tileset", "reference is not a Tileset instance", "a compatible Tileset instance");
}
if (!Number.isInteger(width) || width < 0 || !Number.isInteger(height) || height < 0) {
throw new ResourceReferenceError("tilemap", tileset.imagePath, "tilemap.dimensions", "width and height must be non-negative integers", "valid tilemap dimensions");
}
this.tileset = tileset;
this.width = width;
this.height = height;
this.scale = 1;
this.data = new Array(width * height).fill(-1); // -1 = empty
this.metadata = new Map();
this.cellMetadata = new Map();
this.layers = [];
this.occupants = new Map();
this.occupantCells = new Map();
}
/** Register another traversable map layer, ordered by render order then insertion. */
addLayer(name, tilemap, renderOrder = 0) {
if (typeof name !== "string" || name.length === 0) {
throw new TypeError("Tilemap layer name must be a non-empty string");
}
if (!(tilemap instanceof Tilemap) || tilemap === this) {
throw new TypeError("Tilemap layer must be a different Tilemap instance");
}
if (!Number.isFinite(renderOrder)) {
throw new TypeError("Tilemap layer renderOrder must be finite");
}
if (this.layers.some(layer => layer.name === name)) {
throw new Error(`Tilemap layer '${name}' already exists`);
}
this.layers.push({ name, tilemap, renderOrder });
return tilemap;
}
getLayer(name) {
return this.layers.find(layer => layer.name === name)?.tilemap;
}
/** Set validated gameplay metadata for a tile ID. */
setTileMetadata(tileId, metadata) {
if (!Number.isInteger(tileId) || tileId < 0) {
throw new TypeError("Tile metadata requires a non-negative integer tileId");
}
validateGameplayMetadata(metadata, "Tile");
this.metadata.set(tileId, structuredClone(metadata));
return this.getTileMetadata(tileId);
}
/** Return a defensive copy of metadata for a tile ID, or null when unset. */
getTileMetadata(tileId) {
const metadata = this.metadata.get(tileId);
return metadata ? structuredClone(metadata) : null;
}
/** Set validated metadata for one row-major cell, overriding tile defaults. */
setCellMetadata(x, y, metadata) {
const index = this.gridIndex(x, y);
if (index === null) throw new RangeError("Cell metadata coordinates are outside the tilemap");
validateGameplayMetadata(metadata, "Cell");
this.cellMetadata.set(index, structuredClone(metadata));
return this.getCellMetadata(x, y);
}
/** Return a defensive copy of cell metadata, or null when unset/out of bounds. */
getCellMetadata(x, y) {
const index = this.gridIndex(x, y);
if (index === null) return null;
const metadata = this.cellMetadata.get(index);
return metadata ? structuredClone(metadata) : null;
}
/** Resolve tile defaults with cell-specific metadata taking precedence. */
getResolvedMetadata(x, y) {
const tileId = this.getTile(x, y);
const tileMetadata = tileId >= 0 ? this.metadata.get(tileId) : null;
const cellMetadata = this.getCellMetadata(x, y);
if (!tileMetadata && !cellMetadata) return null;
return structuredClone({ ...(tileMetadata || {}), ...(cellMetadata || {}) });
}
/** Convert tile coordinates to a stable row-major grid index, or null out of bounds. */
gridIndex(x, y) {
return Number.isInteger(x) && Number.isInteger(y) && x >= 0 && x < this.width && y >= 0 && y < this.height
? y * this.width + x : null;
}
/** Place or move an occupant; each occupant may occupy only one cell. */
occupy(x, y, occupant) {
const index = this.gridIndex(x, y);
if (index === null) throw new RangeError("Occupancy coordinates are outside the tilemap");
if (occupant === undefined || occupant === null) throw new TypeError("Occupant must be a non-null value");
if (!this.isWalkable(x, y, occupant)) return false;
const previousCell = this.occupantCells.get(occupant);
if (previousCell !== undefined) this.occupants.delete(previousCell);
this.occupants.set(index, occupant);
this.occupantCells.set(occupant, index);
return true;
}
/** Move an occupied actor by one cardinal tile, leaving state unchanged on failure. */
moveOccupant(occupant, x, y) {
if (occupant === undefined || occupant === null) throw new TypeError("Occupant must be a non-null value");
const currentIndex = this.occupantCells.get(occupant);
if (currentIndex === undefined) return false;
const fromX = currentIndex % this.width;
const fromY = Math.floor(currentIndex / this.width);
if (Math.abs(x - fromX) + Math.abs(y - fromY) !== 1) return false;
if (!this.isWalkable(x, y, occupant)) return false;
const nextIndex = this.gridIndex(x, y);
this.occupants.delete(currentIndex);
this.occupants.set(nextIndex, occupant);
this.occupantCells.set(occupant, nextIndex);
return true;
}
/** Follow a shortest path by one step toward a destination; returns the new cell or null. */
moveOccupantToward(occupant, goalX, goalY) {
const currentIndex = this.occupantCells.get(occupant);
if (currentIndex === undefined) return null;
const x = currentIndex % this.width;
const y = Math.floor(currentIndex / this.width);
const path = this.findPath(x, y, goalX, goalY, occupant);
if (!path?.length) return path ? { x, y } : null;
const step = path[0];
return this.moveOccupant(occupant, step.x, step.y) ? step : null;
}
vacate(occupant) {
const index = this.occupantCells.get(occupant);
if (index === undefined) return null;
this.occupantCells.delete(occupant);
this.occupants.delete(index);
return { x: index % this.width, y: Math.floor(index / this.width) };
}
getOccupant(x, y) {
const index = this.gridIndex(x, y);
return index === null ? null : (this.occupants.get(index) ?? null);
}
isWalkable(x, y, mover = null) {
const index = this.gridIndex(x, y);
if (index === null) return false;
const tileId = this.getTile(x, y);
const metadata = this.getResolvedMetadata(x, y);
if (metadata?.walkable === false || (tileId >= 0 && metadata?.walkable !== true)) return false;
const occupant = this.occupants.get(index);
return occupant === undefined || occupant === mover;
}
/** Deterministic minimum-cost four-way path; returns coordinates excluding start, or null. */
findPath(startX, startY, goalX, goalY, mover = null) {
if (this.gridIndex(startX, startY) === null || this.gridIndex(goalX, goalY) === null ||
!this.isWalkable(startX, startY, mover) || !this.isWalkable(goalX, goalY, mover)) return null;
if (startX === goalX && startY === goalY) return [];
const key = (x, y) => y * this.width + x;
const start = key(startX, startY);
const distances = new Map([[start, 0]]);
const previous = new Map([[start, null]]);
const settled = new Set();
const queue = [];
let insertionOrder = 0;
const compare = (a, b) => a.distance - b.distance || a.order - b.order;
const push = (entry) => {
queue.push(entry);
let index = queue.length - 1;
while (index > 0) {
const parent = Math.floor((index - 1) / 2);
if (compare(queue[parent], entry) <= 0) break;
queue[index] = queue[parent];
index = parent;
}
queue[index] = entry;
};
const pop = () => {
const first = queue[0];
const last = queue.pop();
if (queue.length && last) {
let index = 0;
while (true) {
const left = index * 2 + 1;
const right = left + 1;
if (left >= queue.length) break;
const child = right < queue.length && compare(queue[right], queue[left]) < 0 ? right : left;
if (compare(queue[child], last) >= 0) break;
queue[index] = queue[child];
index = child;
}
queue[index] = last;
}
return first;
};
push({ index: start, distance: 0, order: insertionOrder++ });
const directions = [[0, -1], [1, 0], [0, 1], [-1, 0]];
while (queue.length) {
const current = pop();
if (!current || settled.has(current.index) || current.distance !== distances.get(current.index)) continue;
if (current.index === key(goalX, goalY)) {
const path = [];
let step = current.index;
while (step !== start) {
path.push({ x: step % this.width, y: Math.floor(step / this.width) });
step = previous.get(step);
}
return path.reverse();
}
settled.add(current.index);
const x = current.index % this.width;
const y = Math.floor(current.index / this.width);
for (const [dx, dy] of directions) {
const nx = x + dx, ny = y + dy, next = key(nx, ny);
if (this.gridIndex(nx, ny) === null || settled.has(next) || !this.isWalkable(nx, ny, mover)) continue;
const movementCost = this.getResolvedMetadata(nx, ny)?.movementCost ?? 1;
const distance = current.distance + movementCost;
if (distance >= (distances.get(next) ?? Infinity)) continue;
distances.set(next, distance);
previous.set(next, current.index);
push({ index: next, distance, order: insertionOrder++ });
}
}
return null;
}
/**
* Set a tile at position.
* @param {number} x - X position in tiles.
* @param {number} y - Y position in tiles.
* @param {number} tileId - Tile ID from tileset (-1 for empty).
*/
setTile(x, y, tileId) {
if (!Number.isInteger(tileId) || tileId < -1) {
throw new ResourceReferenceError("tileset", this.tileset.imagePath, `tilemap.data[${x},${y}]`, "tile id must be -1 or a non-negative integer", "a valid tile id");
}
if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
this.data[y * this.width + x] = tileId;
}
}
/**
* Get a tile at position.
* @param {number} x - X position in tiles.
* @param {number} y - Y position in tiles.
* @returns {number} Tile ID or -1 if empty/out of bounds.
*/
getTile(x, y) {
if (x >= 0 && x < this.width && y >= 0 && y < this.height) {
return this.data[y * this.width + x];
}
return -1;
}
/**
* Load tilemap from 2D array.
* @param {number[][]} data - 2D array of tile IDs.
*/
loadFromArray(data) {
if (!Array.isArray(data) || (data.length > 0 && !Array.isArray(data[0]))) {
throw new ResourceReferenceError("tilemap", this.tileset.imagePath, "tilemap.data", "data must be a two-dimensional array", "a two-dimensional tile data array");
}
this.height = data.length;
this.width = data[0]?.length || 0;
this.data = new Array(this.width * this.height);
for (let y = 0; y < this.height; y++) {
if (!Array.isArray(data[y]) || data[y].length !== this.width) {
throw new ResourceReferenceError("tilemap", this.tileset.imagePath, `tilemap.data[${y}]`, "rows must have the same width", "a rectangular two-dimensional tile data array");
}
for (let x = 0; x < this.width; x++) {
const tileId = data[y][x];
if (tileId === undefined || tileId === null) {
this.data[y * this.width + x] = -1;
} else if (!Number.isInteger(tileId) || tileId < -1) {
throw new ResourceReferenceError("tileset", this.tileset.imagePath, `tilemap.data[${y}][${x}]`, "tile id must be -1 or a non-negative integer", "a valid tile id");
} else {
this.data[y * this.width + x] = tileId;
}
}
}
}
/**
* Get pixel width of the tilemap.
*/
get pixelWidth() {
return this.width * this.tileset.tileWidth * this.scale;
}
/**
* Get pixel height of the tilemap.
*/
get pixelHeight() {
return this.height * this.tileset.tileHeight * this.scale;
}
/**
* Convert world position to tile position.
* @param {number} worldX
* @param {number} worldY
* @returns {{ x: number, y: number }}
*/
worldToTile(worldX, worldY) {
return {
x: Math.floor(worldX / (this.tileset.tileWidth * this.scale)),
y: Math.floor(worldY / (this.tileset.tileHeight * this.scale))
};
}
/**
* Check if a tile is solid (non-empty).
* @param {number} x
* @param {number} y
* @returns {boolean}
*/
isSolid(x, y) {
const tileId = this.getTile(x, y);
const collision = this.getResolvedMetadata(x, y)?.collision;
return tileId >= 0 ? collision !== false : collision === true;
}
/**
* Draw the tilemap.
* @param {CanvasRenderingContext2D} ctx
* @param {number} offsetX - Camera offset X.
* @param {number} offsetY - Camera offset Y.
*/
draw(ctx, offsetX = 0, offsetY = 0) {
this.#drawTiles(ctx, offsetX, offsetY);
const visited = new Set([this]);
const layers = [...this.layers].sort((a, b) => a.renderOrder - b.renderOrder);
const drawLayer = (tilemap) => {
if (visited.has(tilemap)) return;
visited.add(tilemap);
tilemap.#drawTiles(ctx, offsetX, offsetY);
for (const layer of [...tilemap.layers].sort((a, b) => a.renderOrder - b.renderOrder)) {
drawLayer(layer.tilemap);
}
};
for (const layer of layers) drawLayer(layer.tilemap);
}
#drawTiles(ctx, offsetX, offsetY) {
const tw = this.tileset.tileWidth * this.scale;
const th = this.tileset.tileHeight * this.scale;
for (let y = 0; y < this.height; y++) {
for (let x = 0; x < this.width; x++) {
const tileId = this.data[y * this.width + x];
if (tileId >= 0) {
this.tileset.drawTile(
ctx,
tileId,
x * tw - offsetX,
y * th - offsetY,
this.scale
);
}
}
}
}
}