@codexo/exojs-tilemap 0.13.0

package/dist/esm/TileChunkNode.js

@@ -0,0 +1,89 @@
+import { Drawable } from '@codexo/exojs/rendering';
+import { buildChunkPages } from './chunkGeometry.js';
+
+/**
+ * A single renderable tile chunk. One `TileChunkNode` is a {@link Drawable}
+ * that owns the batched quad geometry for exactly one {@link ReadonlyTileChunk}
+ * of one {@link import('./TileLayer').TileLayer}, positioned at the chunk's
+ * pixel origin within the owning {@link TileLayerNode}.
+ *
+ * Geometry is built lazily and cached against the source chunk's `revision`:
+ * the renderer reads {@link TileChunkNode.pages} on each visible frame, but a
+ * rebuild only happens when the underlying chunk actually changed. Off-screen
+ * chunks are culled by their accurate {@link getLocalBounds} before `render`
+ * is ever called, so a camera pan rebuilds nothing.
+ *
+ * The node references — but never owns — the runtime chunk, tilesets, and
+ * tileset textures. Destroying it releases only its cached CPU geometry; the
+ * `TileMap`/`TileLayer` data and Loader-owned textures are untouched.
+ *
+ * @internal Package-internal render node; the renderer is registered for this
+ * class. Applications use {@link TileMapNode} / {@link TileLayerNode}.
+ */
+class TileChunkNode extends Drawable {
+    _chunk;
+    _tilesets;
+    _tileWidth;
+    _tileHeight;
+    _pixelWidth;
+    _pixelHeight;
+    _pages = [];
+    _builtRevision = -1;
+    /**
+     * @param chunk          The readonly chunk this node renders.
+     * @param tilesets       The owning layer's tileset array.
+     * @param tileWidth      Map/layer tile cell width in pixels.
+     * @param tileHeight     Map/layer tile cell height in pixels.
+     * @param chunkWidthTiles  The layer's (unclamped) chunk width in tiles, used
+     *                         to compute the chunk's pixel origin. Edge chunks
+     *                         report a smaller `chunk.width`, but always start at
+     *                         `cx * chunkWidthTiles`.
+     * @param chunkHeightTiles The layer's (unclamped) chunk height in tiles.
+     */
+    constructor(chunk, tilesets, tileWidth, tileHeight, chunkWidthTiles, chunkHeightTiles) {
+        super();
+        this._chunk = chunk;
+        this._tilesets = tilesets;
+        this._tileWidth = tileWidth;
+        this._tileHeight = tileHeight;
+        this._pixelWidth = chunk.width * tileWidth;
+        this._pixelHeight = chunk.height * tileHeight;
+        this.setPosition(chunk.cx * chunkWidthTiles * tileWidth, chunk.cy * chunkHeightTiles * tileHeight);
+    }
+    /** The signed chunk coordinates this node renders. */
+    get chunkX() {
+        return this._chunk.cx;
+    }
+    get chunkY() {
+        return this._chunk.cy;
+    }
+    /**
+     * The revision-cached per-tileset page geometry. Rebuilt only when the source
+     * chunk's `revision` advances; otherwise the same arrays are returned.
+     * @internal Read by the per-backend tile chunk renderer.
+     */
+    get pages() {
+        if (this._builtRevision !== this._chunk.revision) {
+            this._pages = buildChunkPages(this._chunk, this._tilesets, this._tileWidth, this._tileHeight);
+            this._builtRevision = this._chunk.revision;
+        }
+        return this._pages;
+    }
+    /** `true` when the chunk has no drawable tiles (no geometry, no draw calls). */
+    get isEmpty() {
+        return this.pages.length === 0;
+    }
+    getLocalBounds() {
+        const bounds = super.getLocalBounds();
+        bounds.set(0, 0, this._pixelWidth, this._pixelHeight);
+        return bounds;
+    }
+    destroy() {
+        this._pages = [];
+        this._builtRevision = -1;
+        super.destroy();
+    }
+}
+
+export { TileChunkNode };
+//# sourceMappingURL=TileChunkNode.js.map

package/dist/esm/TileChunkNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileChunkNode.js","sources":["../../../src/TileChunkNode.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAQA;;;;;;;;;;;;;;;;;;AAkBG;AACG,MAAO,aAAc,SAAQ,QAAQ,CAAA;AACxB,IAAA,MAAM;AACN,IAAA,SAAS;AACT,IAAA,UAAU;AACV,IAAA,WAAW;AACX,IAAA,WAAW;AACX,IAAA,YAAY;IAErB,MAAM,GAAgB,EAAE;IACxB,cAAc,GAAG,EAAE;AAE3B;;;;;;;;;;AAUG;IACH,WAAA,CACE,KAAwB,EACxB,QAA4B,EAC5B,SAAiB,EACjB,UAAkB,EAClB,eAAuB,EACvB,gBAAwB,EAAA;AAExB,QAAA,KAAK,EAAE;AAEP,QAAA,IAAI,CAAC,MAAM,GAAG,KAAK;AACnB,QAAA,IAAI,CAAC,SAAS,GAAG,QAAQ;AACzB,QAAA,IAAI,CAAC,UAAU,GAAG,SAAS;AAC3B,QAAA,IAAI,CAAC,WAAW,GAAG,UAAU;QAC7B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,KAAK,GAAG,SAAS;QAC1C,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,UAAU;AAE7C,QAAA,IAAI,CAAC,WAAW,CACd,KAAK,CAAC,EAAE,GAAG,eAAe,GAAG,SAAS,EACtC,KAAK,CAAC,EAAE,GAAG,gBAAgB,GAAG,UAAU,CACzC;IACH;;AAGA,IAAA,IAAW,MAAM,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE;IACvB;AAEA,IAAA,IAAW,MAAM,GAAA;AACf,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE;IACvB;AAEA;;;;AAIG;AACH,IAAA,IAAW,KAAK,GAAA;QACd,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;YAChD,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC;YAC7F,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ;QAC5C;QAEA,OAAO,IAAI,CAAC,MAAM;IACpB;;AAGA,IAAA,IAAW,OAAO,GAAA;AAChB,QAAA,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;IAChC;IAEgB,cAAc,GAAA;AAC5B,QAAA,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,EAAE;AAErC,QAAA,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC;AAErD,QAAA,OAAO,MAAM;IACf;IAEgB,OAAO,GAAA;AACrB,QAAA,IAAI,CAAC,MAAM,GAAG,EAAE;AAChB,QAAA,IAAI,CAAC,cAAc,GAAG,EAAE;QAExB,KAAK,CAAC,OAAO,EAAE;IACjB;AACD;;;;"}

package/dist/esm/TileLayer.d.ts

@@ -0,0 +1,229 @@
+import type { ReadonlyTileChunk } from './TileChunk';
+import { TileChunk } from './TileChunk';
+import type { TileSet } from './TileSet';
+import type { TileProperties } from './types';
+import type { PackedTile, ResolvedTile } from './types';
+/**
+ * Options for constructing a {@link TileLayer}.
+ * @advanced
+ */
+export interface TileLayerOptions {
+    /** Stable layer ID (unique within the map). */
+    readonly id: number;
+    /** Display name (need not be unique). */
+    readonly name: string;
+    /** Layer width in tiles. */
+    readonly width: number;
+    /** Layer height in tiles. */
+    readonly height: number;
+    /** Chunk width in tiles (default 32). */
+    readonly chunkWidth?: number;
+    /** Chunk height in tiles (default 32). */
+    readonly chunkHeight?: number;
+    /** Tilesets available to this layer (shared with the map). */
+    readonly tilesets: readonly TileSet[];
+    /** Tile width in pixels (for coordinate conversion). */
+    readonly tileWidth: number;
+    /** Tile height in pixels (for coordinate conversion). */
+    readonly tileHeight: number;
+    /** Initial visibility. Default true. */
+    readonly visible?: boolean;
+    /** Opacity 0..1. Default 1. */
+    readonly opacity?: number;
+    /** Layer pixel offset X. Default 0. */
+    readonly offsetX?: number;
+    /** Layer pixel offset Y. Default 0. */
+    readonly offsetY?: number;
+    /** Layer properties (copied and frozen). */
+    readonly properties?: TileProperties;
+}
+/**
+ * A generic, format-independent tile layer with chunk-first storage.
+ *
+ * Tile data is stored in fixed-size {@link TileChunk}s indexed by signed
+ * chunk coordinates. For finite maps, only chunks that intersect the layer
+ * bounds exist.
+ *
+ * **Mutation must go through the layer's public APIs only.**
+ * `setTileAt` / `clearTileAt` validate coordinates, tileset references,
+ * and increment revision counters only when the stored value actually
+ * changes. Direct chunk mutation is not supported — the layer owns chunk
+ * storage and exposes only a {@link ReadonlyTileChunk} view.
+ *
+ * The layer is NOT a SceneNode — that integration lives in the future
+ * renderer slice.
+ *
+ * @advanced
+ */
+export declare class TileLayer {
+    /** Stable unique ID within the map. */
+    readonly id: number;
+    /** Display name (may not be unique). */
+    readonly name: string;
+    /** Width in tiles. */
+    readonly width: number;
+    /** Height in tiles. */
+    readonly height: number;
+    /** Chunk width (tiles). */
+    readonly chunkWidth: number;
+    /** Chunk height (tiles). */
+    readonly chunkHeight: 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;
+    /** Visibility flag (mutable). */
+    visible: boolean;
+    /** Opacity 0..1 (mutable). */
+    opacity: number;
+    /** Horizontal pixel offset (mutable). */
+    offsetX: number;
+    /** Vertical pixel offset (mutable). */
+    offsetY: number;
+    /** Immutable layer properties. */
+    readonly properties: TileProperties;
+    /** The tilesets available to this layer (shared array reference). */
+    readonly tilesets: readonly TileSet[];
+    /** Chunk storage: chunkKey → mutable TileChunk (internal). */
+    private readonly _chunks;
+    /**
+     * Monotonic layer revision counter.
+     * Increments on every cell mutation that actually changes a stored value.
+     * Does NOT increment on no-op writes or failed mutations.
+     */
+    private _revision;
+    /** Whether the layer has been destroyed. */
+    private _destroyed;
+    /**
+     * @throws When dimensions, chunk size, or other options are invalid.
+     */
+    constructor(options: TileLayerOptions);
+    /**
+     * Check whether a tile coordinate lies within the layer bounds.
+     * @advanced
+     */
+    inBounds(tx: number, ty: number): boolean;
+    /** Compute the range of chunk coordinates that intersect this layer. */
+    chunkRange(): {
+        minCx: number;
+        minCy: number;
+        maxCx: number;
+        maxCy: number;
+    };
+    private _chunkKey;
+    /**
+     * Get a readonly view of a chunk by signed chunk coordinates,
+     * or undefined if it does not exist (never been touched).
+     * @advanced
+     */
+    getChunk(cx: number, cy: number): ReadonlyTileChunk | undefined;
+    /**
+     * Get or create a chunk at the given coordinates.
+     * For finite layers, creation is only allowed within the valid chunk range.
+     *
+     * @internal Package-private: used by {@link setTileAt}, {@link fillRect},
+     *           and future adapter ingest. External users should not allocate
+     *           chunks — use {@link setTileAt} to populate tiles.
+     */
+    _ensureChunk(cx: number, cy: number): TileChunk;
+    /**
+     * Iterate over all loaded chunks in deterministic (cy, cx) ascending order.
+     * Returns readonly chunk views — callers cannot mutate storage.
+     * @advanced
+     */
+    loadedChunks(): IterableIterator<ReadonlyTileChunk>;
+    /**
+     * Get the raw packed tile word at (tx, ty). Returns 0 for empty or out-of-bounds.
+     * @advanced
+     */
+    getRawTileAt(tx: number, ty: number): PackedTile;
+    /**
+     * Query a resolved tile at (tx, ty). Returns null for empty or out-of-bounds.
+     * @advanced
+     */
+    getTileAt(tx: number, ty: number): ResolvedTile | null;
+    /**
+     * Validate a tile reference against the layer's tilesets.
+     * Returns the packed form or throws.
+     */
+    private _validateTileRef;
+    /**
+     * Set a tile at the given tile coordinates.
+     * No-op if the effective value is unchanged.
+     * @throws If coordinates are out of bounds or the tile reference is invalid.
+     * @advanced
+     */
+    setTileAt(tx: number, ty: number, tile: ResolvedTile): void;
+    /**
+     * Clear (erase) the tile at the given coordinates.
+     * No-op if the cell is already empty.
+     * @throws If coordinates are out of bounds.
+     * @advanced
+     */
+    clearTileAt(tx: number, ty: number): void;
+    /**
+     * Fill a rectangular region with a tile.
+     * @advanced
+     */
+    fillRect(x: number, y: number, w: number, h: number, tile: ResolvedTile): void;
+    /**
+     * Clear a rectangular region.
+     * @advanced
+     */
+    clearRect(x: number, y: number, w: number, h: number): void;
+    /**
+     * Iterate non-empty tiles within a rectangular region in row-major order.
+     * Yields (tx, ty, resolvedTile) tuples. Skips empty cells.
+     * @advanced
+     */
+    tilesInRect(x: number, y: number, w: number, h: number): Generator<{
+        tx: number;
+        ty: number;
+        tile: ResolvedTile;
+    }>;
+    /**
+     * Convert a tile coordinate to the pixel position of its top-left corner
+     * in the layer's local space.
+     * @advanced
+     */
+    tileToPixel(tx: number, ty: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Convert a local pixel position to the tile coordinate that contains it.
+     * Uses `floor`, so a point exactly on a tile boundary maps to the tile.
+     * May return coordinates outside layer bounds.
+     * @advanced
+     */
+    pixelToTile(px: number, py: number): {
+        tx: number;
+        ty: number;
+    };
+    /**
+     * Monotonic layer revision counter.
+     * Increments on every cell mutation that changes a stored value.
+     * No-op writes and failed mutations do NOT increment.
+     * @advanced
+     */
+    get revision(): number;
+    /** Whether the layer has been destroyed. */
+    get destroyed(): boolean;
+    private _checkDestroyed;
+    /**
+     * Destroy this layer: clear chunk storage and mark destroyed.
+     * Does NOT destroy tileset textures or external resources.
+     * Idempotent.
+     */
+    destroy(): void;
+    /**
+     * Total number of non-empty tiles across all chunks.
+     * Walk is cheap for dense layers; sparse layers benefit from empty-chunk fast path.
+     * @advanced
+     */
+    countNonEmptyTiles(): number;
+}