@codexo/exojs-tilemap 0.15.3 → 0.16.0

package/dist/esm/TileMap.d.ts

@@ -12,10 +12,14 @@ import type { ResolvedTile, TileProperties } from './types';
 export interface TileMapOptions {
     /** Map name (for debugging). */
     readonly name?: string;
-    /** Map width in tiles. */
-    readonly width: number;
-    /** Map height in tiles. */
-    readonly height: number;
+    /**
+     * Map width in tiles. Omit together with {@link height} for an unbounded
+     * map - layers you add are then free to be unbounded too (this option
+     * does not constrain per-layer dimensions either way).
+     */
+    readonly width?: number;
+    /** Map height in tiles. Must be provided iff {@link width} is. */
+    readonly height?: number;
     /** Width of each tile in pixels. */
     readonly tileWidth: number;
     /** Height of each tile in pixels. */
@@ -36,7 +40,7 @@ export interface TileMapOptions {
     readonly class?: string;
     /**
      * Map background colour as a `0xRRGGBB` integer, or `null` (Tiled
-     * `backgroundcolor`). Informational — the renderer does not auto-clear to it.
+     * `backgroundcolor`). Informational - the renderer does not auto-clear to it.
      * Default `null`.
      */
     readonly backgroundColor?: number | null;
@@ -44,15 +48,42 @@ export interface TileMapOptions {
     readonly renderOrder?: string;
     /** Map-level properties (copied and frozen). */
     readonly properties?: TileProperties;
+    /**
+     * Combined document order across tile and image layers, as an ordered list
+     * of layer ids - exposed via {@link TileMap.renderableLayers}. Every tile
+     * and image layer passed to this map (via {@link layers} / {@link
+     * imageLayers}) must appear exactly once; an id that belongs to neither
+     * kind, or is listed more than once, throws. The list's length must also
+     * equal the total number of tile/image layer instances - nothing enforces
+     * unique ids across image layers, so two image layers sharing an id would
+     * otherwise both satisfy the id-based checks while one silently drops out
+     * of {@link TileMap.renderableLayers}; that mismatch throws too.
+     *
+     * A tile layer and an image layer sharing the same id makes the order
+     * ambiguous - that combination throws when `documentOrder` is provided.
+     * It is NOT rejected when this option is omitted: the fallback order below
+     * is unambiguous by construction (tile layers are always listed before
+     * image layers), so hand-built maps that predate this option are
+     * unaffected even if such an id collision exists.
+     *
+     * Omit to fall back to all tile layers in insertion order, followed by all
+     * image layers in insertion order - the map's implicit ordering before
+     * this option existed.
+     *
+     * Named `documentOrder` rather than `renderOrder` to avoid colliding with
+     * the unrelated {@link renderOrder} option above (Tiled's tile-draw-
+     * direction string, e.g. `'right-down'`).
+     */
+    readonly documentOrder?: readonly number[];
 }
 /**
  * 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.
+ * 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 — see {@link import('./TileMapNode').TileMapNode},
+ * NOT own SceneNode children - see {@link import('./TileMapNode').TileMapNode},
  * which owns those.
  *
  * Multiple tilesets are supported: each cell stores a packed tileset index
@@ -63,18 +94,20 @@ export interface TileMapOptions {
 export declare class TileMap {
     /** Map name (debug). */
     readonly name: string;
-    /** Map width in tiles. */
-    readonly width: number;
-    /** Map height in tiles. */
-    readonly height: number;
+    /** Map width in tiles, or `undefined` if unbounded. */
+    readonly width: number | undefined;
+    /** Map height in tiles, or `undefined` if unbounded. */
+    readonly height: number | undefined;
     /** Tile width in pixels. */
     readonly tileWidth: number;
     /** Tile height in pixels. */
     readonly tileHeight: number;
-    /** Pixel width. */
-    get pixelWidth(): number;
-    /** Pixel height. */
-    get pixelHeight(): number;
+    /** Pixel width, or `undefined` if unbounded. */
+    get pixelWidth(): number | undefined;
+    /** Pixel height, or `undefined` if unbounded. */
+    get pixelHeight(): number | undefined;
+    /** `true` if this map has a fixed width/height; `false` if unbounded. */
+    get bounded(): boolean;
     /** Default chunk width for layers. */
     readonly chunkWidth: number;
     /** Default chunk height for layers. */
@@ -92,12 +125,24 @@ export declare class TileMap {
     private readonly _layerById;
     private readonly _objectLayers;
     private readonly _imageLayers;
+    private readonly _documentOrder;
     private _revision;
     private _destroyed;
     /**
      * @throws When dimensions or other options are invalid.
      */
     constructor(options: TileMapOptions);
+    /**
+     * Validate an explicit `documentOrder` option against current tile/image
+     * layer membership and resolve it to layer instances, or compute the
+     * fallback order (tile layers in insertion order, then image layers) when
+     * omitted. The order stores instance references - not ids - so a
+     * cross-kind id collision in a fallback map can never resolve to the
+     * wrong layer.
+     * @throws Per the validation rules documented on {@link
+     *         TileMapOptions.documentOrder}.
+     */
+    private _buildDocumentOrder;
     /** Immutable list of tilesets available to this map. */
     get tilesets(): readonly TileSet[];
     /**
@@ -113,24 +158,22 @@ export declare class TileMap {
     get layers(): readonly TileLayer[];
     private _addLayer;
     /**
-     * Add a layer after construction.
+     * Add a layer after construction. Appended to the end of {@link
+     * renderableLayers}'s document order.
      * @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.
+     * Get a tile layer by ID.
      */
-    getLayerByName(name: string): TileLayer | undefined;
+    getTileLayerById(id: number): TileLayer | undefined;
     /**
-     * Get a tile layer by name. Convenience alias for {@link getLayerByName}.
+     * Get a tile layer by name. Returns the first match in insertion order.
      */
     getTileLayer(name: string): TileLayer | undefined;
     /**
-     * Remove a layer by ID. The layer is destroyed.
+     * Remove a layer by ID. The layer is destroyed and spliced out of {@link
+     * renderableLayers}'s document order.
      * @returns true if the layer was found and removed.
      */
     removeLayer(id: number): boolean;
@@ -145,7 +188,7 @@ export declare class TileMap {
      * Get an object layer by name (first match in insertion order), or undefined.
      *
      * Supply an {@link ObjectSchema} type argument `S` to obtain a typed view of
-     * the layer — `getObjectLayer<LevelObjects>('Entities')` returns an
+     * the layer - `getObjectLayer<LevelObjects>('Entities')` returns an
      * `ObjectLayer<LevelObjects>` whose {@link ObjectLayer.byType} / {@link
      * ObjectLayer.where} accessors narrow `properties`. The schema is a static
      * developer promise only; no runtime validation is performed and the call
@@ -166,6 +209,16 @@ export declare class TileMap {
     removeObjectLayer(id: number): boolean;
     /** Immutable snapshot of image layers (insertion order). */
     get imageLayers(): readonly ImageLayer[];
+    /**
+     * Add an image layer after construction. Appended to both {@link
+     * imageLayers} and the end of {@link renderableLayers}'s document order.
+     * @throws If an image layer with the same ID already exists. An ID shared
+     *   with a *tile* layer is permitted - the two kinds keep separate ID
+     *   spaces, and all internal bookkeeping is instance-based.
+     */
+    addImageLayer(layer: ImageLayer): void;
+    /** Shared by the constructor and {@link addImageLayer}: enforce ID uniqueness within the image-layer kind. */
+    private _addImageLayer;
     /**
      * Get an image layer by name (first match in insertion order), or undefined.
      */
@@ -175,19 +228,30 @@ export declare class TileMap {
      */
     getImageLayerById(id: number): ImageLayer | undefined;
     /**
-     * Remove an image layer by ID.
+     * Remove an image layer by ID. Spliced out of {@link renderableLayers}'s
+     * document order.
      * @returns true if the layer was found and removed.
      */
     removeImageLayer(id: number): boolean;
+    /**
+     * Tile and image layers combined into a single document order (see {@link
+     * TileMapOptions.documentOrder}), maintained live as membership changes.
+     * Reflects `addLayer` / `addImageLayer` / `removeLayer` /
+     * `removeImageLayer` calls made after construction. Holds instance
+     * references, so entries stay correct even when a tile layer and an image
+     * layer share an id in a fallback-ordered map. Object layers are
+     * data-only and never appear here.
+     */
+    get renderableLayers(): ReadonlyArray<TileLayer | ImageLayer>;
     /**
      * 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
+     * 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,
+     * view frees only its generated layer/band nodes - never the map, its layers,
      * tileset textures, or any application actors.
      *
      * @advanced
@@ -195,20 +259,20 @@ export declare class TileMap {
     createView(options?: TileMapViewOptions): TileMapView;
     /**
      * Get a resolved tile from a given layer at tile coordinates.
-     * Convenience for `map.getLayerById(id)?.getTileAt(tx, ty)`.
+     * Convenience for `map.getTileLayerById(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)`.
+     * Convenience for `map.getTileLayerById(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)`.
+     * Convenience for `map.getTileLayerById(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;
@@ -246,3 +310,4 @@ export declare class TileMap {
      */
     destroy(): void;
 }
+//# sourceMappingURL=TileMap.d.ts.map

package/dist/esm/TileMap.d.ts.map

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