@codexo/exojs-tilemap 0.13.0

package/dist/esm/TileLayerNode.js

@@ -0,0 +1,142 @@
+import { Container } from '@codexo/exojs';
+import { assertPixelSnapMode } from './pixelSnap.js';
+import { TileChunkNode } from './TileChunkNode.js';
+
+/**
+ * A scene node that renders one generic {@link TileLayer} as a
+ * {@link Container} of per-chunk {@link TileChunkNode} drawables.
+ *
+ * Each non-empty loaded chunk becomes one child positioned at its pixel
+ * origin, so the engine's existing per-node culling drops individual chunks and
+ * the render-plan optimiser batches them by tileset texture. The layer's pixel
+ * `offset` is applied to this node's transform; `visible` and `opacity` are
+ * read live from the runtime layer on every frame (no rebuild required).
+ *
+ * The node references — but never owns — the {@link TileLayer}: destroying it
+ * frees its chunk nodes and their cached geometry but leaves the layer, map,
+ * and Loader-owned textures intact.
+ *
+ * Structural changes to the layer (tiles written into previously-empty chunks)
+ * are reflected only after {@link TileLayerNode.refresh}; in-place edits to
+ * existing chunks are picked up automatically via chunk revisions.
+ *
+ * @advanced
+ */
+class TileLayerNode extends Container {
+    _layer;
+    _cullChunks;
+    _chunkNodes = [];
+    _syncedOpacity = -1;
+    _pixelSnapMode = 'none';
+    constructor(layer, options) {
+        super();
+        this._layer = layer;
+        this._cullChunks = options?.cullable ?? true;
+        this.setPosition(layer.offsetX, layer.offsetY);
+        this._buildChunkNodes();
+    }
+    /** The runtime layer this node renders. */
+    get layer() {
+        return this._layer;
+    }
+    /**
+     * Render-only pixel-snap mode applied to every chunk node in this layer (and
+     * to chunks rebuilt later by {@link refresh}). Each chunk's rendered origin is
+     * snapped to the active render target's device-pixel grid; because chunk
+     * origins are integer multiples of the integer tile pitch from the same layer
+     * origin, the whole grid stays exact and adjacent chunks cannot drift apart.
+     *
+     * Purely visual: tile data, the layer offset, chunk content revisions, and
+     * culling bounds are never changed. `'geometry'` and `'position'` both resolve
+     * to coherent origin snapping for tile chunks (chunk quads are already on the
+     * integer pixel grid by construction). Setting the current value is a no-op;
+     * an invalid value throws and leaves the prior mode unchanged.
+     *
+     * @default 'none'
+     * @stable
+     */
+    get pixelSnapMode() {
+        return this._pixelSnapMode;
+    }
+    set pixelSnapMode(mode) {
+        if (mode === this._pixelSnapMode) {
+            return;
+        }
+        assertPixelSnapMode(mode);
+        this._pixelSnapMode = mode;
+        for (const chunk of this._chunkNodes) {
+            chunk.pixelSnapMode = mode;
+        }
+    }
+    /**
+     * Rebuild the chunk-node children from the layer's current loaded chunks.
+     * Call after structural mutation that creates or empties chunks. In-place
+     * tile edits to existing chunks do not need a refresh.
+     */
+    refresh() {
+        const previous = [...this._chunkNodes];
+        this.removeChildren();
+        this._chunkNodes.length = 0;
+        for (const child of previous) {
+            child.destroy();
+        }
+        this._syncedOpacity = -1;
+        this._buildChunkNodes();
+        return this;
+    }
+    /** The chunk render nodes owned by this layer node, in build order. @internal */
+    get chunkNodes() {
+        return this._chunkNodes;
+    }
+    getLocalBounds() {
+        const bounds = super.getLocalBounds();
+        bounds.set(0, 0, this._layer.pixelWidth, this._layer.pixelHeight);
+        return bounds;
+    }
+    /** @internal */
+    _collectContent(builder) {
+        if (!this._layer.visible) {
+            return;
+        }
+        this._syncOpacity();
+        super._collectContent(builder);
+    }
+    destroy() {
+        const children = [...this._chunkNodes];
+        this._chunkNodes.length = 0;
+        super.destroy();
+        for (const child of children) {
+            child.destroy();
+        }
+    }
+    _buildChunkNodes() {
+        const layer = this._layer;
+        for (const chunk of layer.loadedChunks()) {
+            if (chunk.empty) {
+                continue;
+            }
+            const node = new TileChunkNode(chunk, layer.tilesets, layer.tileWidth, layer.tileHeight, layer.chunkWidth, layer.chunkHeight);
+            node.cullable = this._cullChunks;
+            if (this._pixelSnapMode !== 'none') {
+                node.pixelSnapMode = this._pixelSnapMode;
+            }
+            this._chunkNodes.push(node);
+            this.addChild(node);
+        }
+        this._syncOpacity();
+    }
+    /** Propagate the layer's live opacity onto the chunk tints if it changed. */
+    _syncOpacity() {
+        const opacity = this._layer.opacity;
+        if (opacity === this._syncedOpacity) {
+            return;
+        }
+        for (const child of this._chunkNodes) {
+            child.tint.a = opacity;
+        }
+        this._syncedOpacity = opacity;
+    }
+}
+
+export { TileLayerNode };
+//# sourceMappingURL=TileLayerNode.js.map

package/dist/esm/TileLayerNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileLayerNode.js","sources":["../../../src/TileLayerNode.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAsBA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,MAAO,aAAc,SAAQ,SAAS,CAAA;AACzB,IAAA,MAAM;AACN,IAAA,WAAW;IACX,WAAW,GAAoB,EAAE;IAC1C,cAAc,GAAG,EAAE;IACnB,cAAc,GAAkB,MAAM;IAE9C,WAAA,CAAmB,KAAgB,EAAE,OAA8B,EAAA;AACjE,QAAA,KAAK,EAAE;AAEP,QAAA,IAAI,CAAC,MAAM,GAAG,KAAK;QACnB,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI;QAE5C,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;QAC9C,IAAI,CAAC,gBAAgB,EAAE;IACzB;;AAGA,IAAA,IAAW,KAAK,GAAA;QACd,OAAO,IAAI,CAAC,MAAM;IACpB;AAEA;;;;;;;;;;;;;;;AAeG;AACH,IAAA,IAAW,aAAa,GAAA;QACtB,OAAO,IAAI,CAAC,cAAc;IAC5B;IAEA,IAAW,aAAa,CAAC,IAAmB,EAAA;AAC1C,QAAA,IAAI,IAAI,KAAK,IAAI,CAAC,cAAc,EAAE;YAChC;QACF;QAEA,mBAAmB,CAAC,IAAI,CAAC;AACzB,QAAA,IAAI,CAAC,cAAc,GAAG,IAAI;AAE1B,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE;AACpC,YAAA,KAAK,CAAC,aAAa,GAAG,IAAI;QAC5B;IACF;AAEA;;;;AAIG;IACI,OAAO,GAAA;QACZ,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QAEtC,IAAI,CAAC,cAAc,EAAE;AACrB,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;AAE3B,QAAA,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE;YAC5B,KAAK,CAAC,OAAO,EAAE;QACjB;AAEA,QAAA,IAAI,CAAC,cAAc,GAAG,EAAE;QACxB,IAAI,CAAC,gBAAgB,EAAE;AAEvB,QAAA,OAAO,IAAI;IACb;;AAGA,IAAA,IAAW,UAAU,GAAA;QACnB,OAAO,IAAI,CAAC,WAAW;IACzB;IAEgB,cAAc,GAAA;AAC5B,QAAA,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,EAAE;AAErC,QAAA,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;AAEjE,QAAA,OAAO,MAAM;IACf;;AAGmB,IAAA,eAAe,CAAC,OAA0B,EAAA;AAC3D,QAAA,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;YACxB;QACF;QAEA,IAAI,CAAC,YAAY,EAAE;AAEnB,QAAA,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC;IAChC;IAEgB,OAAO,GAAA;QACrB,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;AAEtC,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;QAE3B,KAAK,CAAC,OAAO,EAAE;AAEf,QAAA,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE;YAC5B,KAAK,CAAC,OAAO,EAAE;QACjB;IACF;IAEQ,gBAAgB,GAAA;AACtB,QAAA,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM;QAEzB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,YAAY,EAAE,EAAE;AACxC,YAAA,IAAI,KAAK,CAAC,KAAK,EAAE;gBACf;YACF;YAEA,MAAM,IAAI,GAAG,IAAI,aAAa,CAC5B,KAAK,EACL,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,SAAS,EACf,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,WAAW,CAClB;AAED,YAAA,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW;AAEhC,YAAA,IAAI,IAAI,CAAC,cAAc,KAAK,MAAM,EAAE;AAClC,gBAAA,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,cAAc;YAC1C;AAEA,YAAA,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;AAC3B,YAAA,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB;QAEA,IAAI,CAAC,YAAY,EAAE;IACrB;;IAGQ,YAAY,GAAA;AAClB,QAAA,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO;AAEnC,QAAA,IAAI,OAAO,KAAK,IAAI,CAAC,cAAc,EAAE;YACnC;QACF;AAEA,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE;AACpC,YAAA,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO;QACxB;AAEA,QAAA,IAAI,CAAC,cAAc,GAAG,OAAO;IAC/B;AACD;;;;"}

package/dist/esm/TileMap.d.ts

@@ -0,0 +1,178 @@
+import { type TileLayer } from './TileLayer';
+import type { TileMapViewOptions } from './TileMapView';
+import { TileMapView } from './TileMapView';
+import { type TileSet } from './TileSet';
+import type { ResolvedTile, TileProperties } from './types';
+/**
+ * Options for constructing a {@link TileMap}.
+ * @advanced
+ */
+export interface TileMapOptions {
+    /** Map name (for debugging). */
+    readonly name?: string;
+    /** Map width in tiles. */
+    readonly width: number;
+    /** Map height in tiles. */
+    readonly height: number;
+    /** Width of each tile in pixels. */
+    readonly tileWidth: number;
+    /** Height of each tile in pixels. */
+    readonly tileHeight: number;
+    /** Tilesets available to this map. */
+    readonly tilesets?: readonly TileSet[];
+    /** Layers (constructed externally and owned by the map after construction). */
+    readonly layers?: readonly TileLayer[];
+    /** Chunk width for layers (default 32). */
+    readonly chunkWidth?: number;
+    /** Chunk height for layers (default 32). */
+    readonly chunkHeight?: number;
+    /** Map-level properties (copied and frozen). */
+    readonly properties?: TileProperties;
+}
+/**
+ * A generic, format-independent tile map.
+ *
+ * Owns a finite grid of {@link TileLayer}s and a shared set of {@link TileSet}s.
+ * Tile data is stored in compact chunked arrays — no per-tile heap objects.
+ *
+ * The map does NOT own tileset textures (those are Loader-owned) and does
+ * NOT own SceneNode children (the future TileMapNode will own those).
+ *
+ * Multiple tilesets are supported: each cell stores a packed tileset index
+ * and local tile ID, so different tilesets may have different tile dimensions.
+ *
+ * @advanced
+ */
+export declare class TileMap {
+    /** Map name (debug). */
+    readonly name: string;
+    /** Map width in tiles. */
+    readonly width: number;
+    /** Map height in tiles. */
+    readonly height: number;
+    /** Tile width in pixels. */
+    readonly tileWidth: number;
+    /** Tile height in pixels. */
+    readonly tileHeight: number;
+    /** Pixel width. */
+    get pixelWidth(): number;
+    /** Pixel height. */
+    get pixelHeight(): number;
+    /** Default chunk width for layers. */
+    readonly chunkWidth: number;
+    /** Default chunk height for layers. */
+    readonly chunkHeight: number;
+    /** Map-level properties (immutable). */
+    readonly properties: TileProperties;
+    private readonly _tilesets;
+    private readonly _layers;
+    private readonly _layerById;
+    private _revision;
+    private _destroyed;
+    /**
+     * @throws When dimensions or other options are invalid.
+     */
+    constructor(options: TileMapOptions);
+    /** Immutable list of tilesets available to this map. */
+    get tilesets(): readonly TileSet[];
+    /**
+     * Add a tileset. Tilesets must have unique names.
+     * @throws If a tileset with the same name already exists, or the map is destroyed.
+     */
+    addTileset(tileset: TileSet): void;
+    /**
+     * Get a tileset by name, or undefined.
+     */
+    getTileset(name: string): TileSet | undefined;
+    /** Immutable snapshot of layers (ordered). */
+    get layers(): readonly TileLayer[];
+    private _addLayer;
+    /**
+     * Add a layer after construction.
+     * @throws If a layer with the same ID already exists.
+     */
+    addLayer(layer: TileLayer): void;
+    /**
+     * Get a layer by ID.
+     */
+    getLayerById(id: number): TileLayer | undefined;
+    /**
+     * Get a layer by name. Returns the first match in insertion order.
+     */
+    getLayerByName(name: string): TileLayer | undefined;
+    /**
+     * Get a tile layer by name. Convenience alias for {@link getLayerByName}.
+     */
+    getTileLayer(name: string): TileLayer | undefined;
+    /**
+     * Remove a layer by ID. The layer is destroyed.
+     * @returns true if the layer was found and removed.
+     */
+    removeLayer(id: number): boolean;
+    /**
+     * Create a new {@link TileMapView} that groups this map's layers into
+     * independently placeable band / layer scene nodes for interleaving
+     * application actors between tile layers.
+     *
+     * Each call returns a fresh, independent view — the map does **not** cache a
+     * single global view, so multiple coexisting views of the same map are
+     * allowed. The view references this map but never owns it: destroying the
+     * view frees only its generated layer/band nodes — never the map, its layers,
+     * tileset textures, or any application actors.
+     *
+     * @advanced
+     */
+    createView(options?: TileMapViewOptions): TileMapView;
+    /**
+     * Get a resolved tile from a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.getTileAt(tx, ty)`.
+     * Returns null for an empty cell, out-of-bounds, or missing layer.
+     */
+    getTileAt(layerId: number, tx: number, ty: number): ResolvedTile | null;
+    /**
+     * Set a tile on a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.setTileAt(tx, ty, tile)`.
+     * @throws If the layer does not exist, coordinates are out of bounds,
+     *         or the tile reference is invalid.
+     */
+    setTileAt(layerId: number, tx: number, ty: number, tile: ResolvedTile): void;
+    /**
+     * Clear a tile on a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.clearTileAt(tx, ty)`.
+     * @throws If the layer does not exist or coordinates are out of bounds.
+     */
+    clearTileAt(layerId: number, tx: number, ty: number): void;
+    /**
+     * Convert a tile coordinate to the pixel position of its top-left corner
+     * in map-local space (ignoring layer offsets).
+     */
+    tileToPixel(tx: number, ty: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Convert a pixel position in map-local space to the tile coordinate
+     * that contains it. Uses `floor`. May return coordinates outside map bounds.
+     */
+    pixelToTile(px: number, py: number): {
+        tx: number;
+        ty: number;
+    };
+    /**
+     * Monotonic map revision counter. Increments on structural changes only
+     * (add/remove layer, add tileset). Cell mutations are tracked per-chunk
+     * and per-layer; the renderer reads chunk-level revisions directly.
+     * @advanced
+     */
+    get revision(): number;
+    /** Whether the map has been destroyed. */
+    get destroyed(): boolean;
+    private _checkDestroyed;
+    /**
+     * Destroy the map and all owned layers and chunk storage.
+     *
+     * Is idempotent. Does NOT destroy tileset textures (Loader-owned) or
+     * any SceneNodes (those do not exist yet in this slice).
+     */
+    destroy(): void;
+}

package/dist/esm/TileMap.js

@@ -0,0 +1,262 @@
+import { validatePositiveInteger } from './types.js';
+import { TileMapView } from './TileMapView.js';
+
+/**
+ * A generic, format-independent tile map.
+ *
+ * Owns a finite grid of {@link TileLayer}s and a shared set of {@link TileSet}s.
+ * Tile data is stored in compact chunked arrays — no per-tile heap objects.
+ *
+ * The map does NOT own tileset textures (those are Loader-owned) and does
+ * NOT own SceneNode children (the future TileMapNode will own those).
+ *
+ * Multiple tilesets are supported: each cell stores a packed tileset index
+ * and local tile ID, so different tilesets may have different tile dimensions.
+ *
+ * @advanced
+ */
+class TileMap {
+    /** Map name (debug). */
+    name;
+    /** Map width in tiles. */
+    width;
+    /** Map height in tiles. */
+    height;
+    /** Tile width in pixels. */
+    tileWidth;
+    /** Tile height in pixels. */
+    tileHeight;
+    /** Pixel width. */
+    get pixelWidth() { return this.width * this.tileWidth; }
+    /** Pixel height. */
+    get pixelHeight() { return this.height * this.tileHeight; }
+    /** Default chunk width for layers. */
+    chunkWidth;
+    /** Default chunk height for layers. */
+    chunkHeight;
+    /** Map-level properties (immutable). */
+    properties;
+    _tilesets;
+    _layers = [];
+    _layerById = new Map();
+    _revision = 0;
+    _destroyed = false;
+    /**
+     * @throws When dimensions or other options are invalid.
+     */
+    constructor(options) {
+        validatePositiveInteger(options.width, 'map.width');
+        validatePositiveInteger(options.height, 'map.height');
+        validatePositiveInteger(options.tileWidth, 'map.tileWidth');
+        validatePositiveInteger(options.tileHeight, 'map.tileHeight');
+        const chunkWidth = options.chunkWidth ?? 32;
+        const chunkHeight = options.chunkHeight ?? 32;
+        validatePositiveInteger(chunkWidth, 'chunkWidth');
+        validatePositiveInteger(chunkHeight, 'chunkHeight');
+        this.name = options.name ?? 'TileMap';
+        this.width = options.width;
+        this.height = options.height;
+        this.tileWidth = options.tileWidth;
+        this.tileHeight = options.tileHeight;
+        this.chunkWidth = chunkWidth;
+        this.chunkHeight = chunkHeight;
+        this._tilesets = options.tilesets ? [...options.tilesets] : [];
+        this.properties = options.properties
+            ? Object.freeze({ ...options.properties })
+            : Object.freeze({});
+        if (options.layers) {
+            for (const layer of options.layers) {
+                this._addLayer(layer);
+            }
+        }
+    }
+    // ── Tilesets ──────────────────────────────────────────────────────────
+    /** Immutable list of tilesets available to this map. */
+    get tilesets() {
+        return this._tilesets;
+    }
+    /**
+     * Add a tileset. Tilesets must have unique names.
+     * @throws If a tileset with the same name already exists, or the map is destroyed.
+     */
+    addTileset(tileset) {
+        this._checkDestroyed();
+        if (this._tilesets.some(ts => ts.name === tileset.name)) {
+            throw new Error(`Tileset "${tileset.name}" already exists in map "${this.name}".`);
+        }
+        this._tilesets.push(tileset);
+        this._revision++;
+    }
+    /**
+     * Get a tileset by name, or undefined.
+     */
+    getTileset(name) {
+        return this._tilesets.find(ts => ts.name === name);
+    }
+    // ── Layers ────────────────────────────────────────────────────────────
+    /** Immutable snapshot of layers (ordered). */
+    get layers() {
+        return this._layers;
+    }
+    _addLayer(layer) {
+        if (this._layerById.has(layer.id)) {
+            throw new Error(`Layer ID ${layer.id} already exists in map "${this.name}".`);
+        }
+        this._layerById.set(layer.id, layer);
+        this._layers.push(layer);
+    }
+    /**
+     * Add a layer after construction.
+     * @throws If a layer with the same ID already exists.
+     */
+    addLayer(layer) {
+        this._checkDestroyed();
+        this._addLayer(layer);
+        this._revision++;
+    }
+    /**
+     * Get a layer by ID.
+     */
+    getLayerById(id) {
+        return this._layerById.get(id);
+    }
+    /**
+     * Get a layer by name. Returns the first match in insertion order.
+     */
+    getLayerByName(name) {
+        return this._layers.find(l => l.name === name);
+    }
+    /**
+     * Get a tile layer by name. Convenience alias for {@link getLayerByName}.
+     */
+    getTileLayer(name) {
+        return this.getLayerByName(name);
+    }
+    /**
+     * Remove a layer by ID. The layer is destroyed.
+     * @returns true if the layer was found and removed.
+     */
+    removeLayer(id) {
+        this._checkDestroyed();
+        const layer = this._layerById.get(id);
+        if (!layer)
+            return false;
+        this._layers.splice(this._layers.indexOf(layer), 1);
+        this._layerById.delete(id);
+        layer.destroy();
+        this._revision++;
+        return true;
+    }
+    // ── Scene composition ─────────────────────────────────────────────────
+    /**
+     * Create a new {@link TileMapView} that groups this map's layers into
+     * independently placeable band / layer scene nodes for interleaving
+     * application actors between tile layers.
+     *
+     * Each call returns a fresh, independent view — the map does **not** cache a
+     * single global view, so multiple coexisting views of the same map are
+     * allowed. The view references this map but never owns it: destroying the
+     * view frees only its generated layer/band nodes — never the map, its layers,
+     * tileset textures, or any application actors.
+     *
+     * @advanced
+     */
+    createView(options) {
+        return new TileMapView(this, options);
+    }
+    // ── Queries ───────────────────────────────────────────────────────────
+    /**
+     * Get a resolved tile from a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.getTileAt(tx, ty)`.
+     * Returns null for an empty cell, out-of-bounds, or missing layer.
+     */
+    getTileAt(layerId, tx, ty) {
+        const layer = this._layerById.get(layerId);
+        if (!layer)
+            return null;
+        return layer.getTileAt(tx, ty);
+    }
+    /**
+     * Set a tile on a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.setTileAt(tx, ty, tile)`.
+     * @throws If the layer does not exist, coordinates are out of bounds,
+     *         or the tile reference is invalid.
+     */
+    setTileAt(layerId, tx, ty, tile) {
+        const layer = this._layerById.get(layerId);
+        if (!layer)
+            throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
+        layer.setTileAt(tx, ty, tile);
+    }
+    /**
+     * Clear a tile on a given layer at tile coordinates.
+     * Convenience for `map.getLayerById(id)?.clearTileAt(tx, ty)`.
+     * @throws If the layer does not exist or coordinates are out of bounds.
+     */
+    clearTileAt(layerId, tx, ty) {
+        const layer = this._layerById.get(layerId);
+        if (!layer)
+            throw new Error(`Layer ${layerId} not found in map "${this.name}".`);
+        layer.clearTileAt(tx, ty);
+    }
+    // ── Coordinate conversion (base layer) ────────────────────────────────
+    /**
+     * Convert a tile coordinate to the pixel position of its top-left corner
+     * in map-local space (ignoring layer offsets).
+     */
+    tileToPixel(tx, ty) {
+        return {
+            x: tx * this.tileWidth,
+            y: ty * this.tileHeight,
+        };
+    }
+    /**
+     * Convert a pixel position in map-local space to the tile coordinate
+     * that contains it. Uses `floor`. May return coordinates outside map bounds.
+     */
+    pixelToTile(px, py) {
+        return {
+            tx: Math.floor(px / this.tileWidth),
+            ty: Math.floor(py / this.tileHeight),
+        };
+    }
+    // ── Revision / lifecycle ──────────────────────────────────────────────
+    /**
+     * Monotonic map revision counter. Increments on structural changes only
+     * (add/remove layer, add tileset). Cell mutations are tracked per-chunk
+     * and per-layer; the renderer reads chunk-level revisions directly.
+     * @advanced
+     */
+    get revision() {
+        return this._revision;
+    }
+    /** Whether the map has been destroyed. */
+    get destroyed() {
+        return this._destroyed;
+    }
+    _checkDestroyed() {
+        if (this._destroyed) {
+            throw new Error(`TileMap "${this.name}" has been destroyed.`);
+        }
+    }
+    /**
+     * Destroy the map and all owned layers and chunk storage.
+     *
+     * Is idempotent. Does NOT destroy tileset textures (Loader-owned) or
+     * any SceneNodes (those do not exist yet in this slice).
+     */
+    destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        for (const layer of this._layers) {
+            layer.destroy();
+        }
+        this._layers.length = 0;
+        this._layerById.clear();
+        this._tilesets.length = 0;
+    }
+}
+
+export { TileMap };
+//# sourceMappingURL=TileMap.js.map

package/dist/esm/TileMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileMap.js","sources":["../../../src/TileMap.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}