@codexo/exojs-tiled 0.12.0 → 0.14.0

package/README.md

@@ -1,6 +1,7 @@
 # @codexo/exojs-tiled
 
-Official ExoJS extension for loading [Tiled](https://mapeditor.org) maps (`.tmj` JSON format).
+Official ExoJS extension for loading [Tiled](https://mapeditor.org) maps (`.tmj` JSON format)
+into a generic runtime `TileMap` or a typed parsed source model.
 
 ## Installation
 
@@ -8,120 +9,182 @@ Official ExoJS extension for loading [Tiled](https://mapeditor.org) maps (`.tmj`
 npm install @codexo/exojs @codexo/exojs-tiled
 ```
 
-This package requires `@codexo/exojs` as a peer dependency. Both must be the same version.
+`@codexo/exojs` is a peer dependency. `@codexo/exojs-tilemap` is a regular dependency and is
+installed transitively by `@codexo/exojs-tiled` — you do not need to install it manually.
 
-## Core compatibility
+If you want the generic tilemap runtime without the Tiled adapter:
 
-| `@codexo/exojs-tiled` | `@codexo/exojs` |
-|---|---|
-| 0.12.x | 0.12.x |
-
-## Supported Tiled scope
+```sh
+npm install @codexo/exojs @codexo/exojs-tilemap
+```
 
-- Tiled JSON map format (`.tmj`)
-- Orthogonal tile layers
-- Object layers (basic)
-- External tilesets (`.tsj`) referenced from `.tmj`
-- Multiple tile layers per map
+## What this package provides
 
-## Not supported in 0.12.x
+- `TileMap` (re-exported from `@codexo/exojs-tilemap`) — generic runtime tilemap; the common-case result of `loader.load(TileMap, url)`
+- `TileMapNode` / `TileLayerNode` (re-exported from `@codexo/exojs-tilemap`) — scene nodes that render a loaded `TileMap` on WebGL2/WebGPU
+- `TileMapView` / `TileMapBand` (re-exported from `@codexo/exojs-tilemap`) — group a map's layers into independently placeable bands for interleaving actors between tile layers; same class identity, so `instanceof` holds across both import paths (the canonical view/band docs live in the [`@codexo/exojs-tilemap` README](https://www.npmjs.com/package/@codexo/exojs-tilemap))
+- `TiledMap` — parsed Tiled source model; advanced/diagnostic use via `loader.load(TiledMap, url)`
+- `TiledTileset` — parsed tileset (atlas-image or collection-of-images); holds resolved textures
+- `TiledLayer` hierarchy — `TiledTileLayer`, `TiledObjectLayer`, `TiledImageLayer`, `TiledGroupLayer`
+- `TiledObject` — parsed object (point, ellipse, polygon, polyline, text, tile-ref, rectangle)
+- `TiledFormatError` — typed error thrown on any structural problem in `.tmj`/`.tsj` data
+- `tiledExtension` — extension descriptor; depends on `tilemapExtension` automatically
 
-- TMX (XML) format — use `.tmj` export from Tiled
-- Isometric and hexagonal maps
-- Image layers
-- Wangsets
-- Custom class / enum properties
+## Usage — common case
 
-## Usage — side-effect-free root entry
+Register the extension, load a `.tmj` map into a generic runtime `TileMap`, and render it. One
+extension enables **both** loading and rendering — `tiledExtension` depends on `tilemapExtension`,
+so the tile chunk renderer bindings are materialised automatically (no manual `tilemapExtension`
+registration):
 
 ```ts
 import { Application } from '@codexo/exojs';
-import { TiledMap, tiledExtension } from '@codexo/exojs-tiled';
+import { TileMap, TileMapNode, tiledExtension } from '@codexo/exojs-tiled';
 
-const app = new Application({
-    extensions: [tiledExtension],
-});
-```
+const app = new Application({ extensions: [tiledExtension] });
 
-Importing from the root entry does **not** register the extension globally.
+const map = await app.loader.load(TileMap, 'maps/world.tmj');
+// map is a @codexo/exojs-tilemap TileMap
 
-## Extension descriptor
+app.scene.root.addChild(new TileMapNode(map));
+```
 
-`tiledExtension` is the default descriptor. It registers the `TiledMap` asset type with the following bindings:
+`TileMapNode` and `TileLayerNode` are the same classes exported by `@codexo/exojs-tilemap` (see its
+[README](https://www.npmjs.com/package/@codexo/exojs-tilemap) for the rendering/culling model and
+actor interleaving). `instanceof TileMap` holds across both import paths.
 
-- Constructor load: `loader.load(TiledMap, url)`
-- Extension routing: `.tmj` files auto-route to `TiledMap`
-- Type-name load: `loader.load('tiledMap', url)`
+## Usage — advanced parsed-source case
 
-## Loading a Tiled map
+Load the fully resolved Tiled source model and convert it manually:
 
 ```ts
 import { TiledMap } from '@codexo/exojs-tiled';
 
-// Inside a Scene:
-override async load(loader) {
-    // By constructor (explicit)
-    await loader.load(TiledMap, { myMap: '/maps/level1.tmj' });
-
-    // By file extension (auto-routed)
-    await loader.load('/maps/level1.tmj');
-
-    // By type name
-    await loader.load('tiledMap', { myMap: '/maps/level1.tmj' });
-}
-
-override create(loader) {
-    const map = loader.get(TiledMap, 'myMap');
-    this.addChild(map);
-}
+const source = await app.loader.load(TiledMap, 'maps/world.tmj');
+const map = source.toTileMap();
 ```
 
+Both paths are semantically equivalent. The runtime binding (`TileMap`) uses the Loader-managed
+source-model sub-load internally, so concurrent or duplicate loads are deduplicated.
+
 ## `/register` convenience entry
 
-Importing `/register` registers the default `tiledExtension` descriptor in the global `ExtensionRegistry`. Subsequently created Applications that use global defaults will automatically receive the Tiled extension.
+Importing `/register` registers `tiledExtension` (and its `tilemapExtension` dependency) in the
+global `ExtensionRegistry`. Subsequently created Applications that use global defaults will
+receive both extensions automatically.
 
 ```ts
 // Side effect: registers tiledExtension in the global ExtensionRegistry.
 import '@codexo/exojs-tiled/register';
 
-// All named exports are re-exported from /register:
-import { TiledMap, tiledExtension } from '@codexo/exojs-tiled/register';
+// All named exports are also re-exported from /register:
+import { TileMap, TiledMap, tiledExtension } from '@codexo/exojs-tiled/register';
 ```
 
-**Note:** `/register` does not use automatic discovery. It explicitly calls `ExtensionRegistry.register(tiledExtension)` at module evaluation time.
+## Extension dependency
+
+`tiledExtension.dependencies` includes `tilemapExtension` from `@codexo/exojs-tilemap`.
+Registering `tiledExtension` is sufficient — `buildSnapshot` and `ExtensionRegistry.register`
+traverse the dependency graph automatically.
 
-## Texture and sub-asset ownership
+## Asset loading
 
-Tilesets referenced from a Tiled map are loaded as sub-assets and stored in the Loader cache. The `TiledMap` does **not** own or destroy tileset textures — the Loader cache owns them. Do not call `tileset.destroy()` from your code; let the Loader handle cleanup when the scene is destroyed.
+`loader.load(TileMap, url)` (common path) and `loader.load(TiledMap, url)` (advanced path) both:
 
-## Minimal working example
+1. Fetch and validate the `.tmj` file.
+2. Resolve each tileset entry (fetches external `.tsj` files via the Loader cache).
+3. Load atlas images (`tileset.image`) and per-tile images (collection-of-images tilesets)
+   via `loader.load(Texture, …)` — the Loader deduplicates identical URLs.
+4. Validate GID ranges (no duplicates, no overlaps, all layer GIDs covered) — throws
+   `TiledFormatError` on any inconsistency.
+
+The runtime binding additionally calls `TiledMap.toTileMap()` to produce the generic `TileMap`.
+
+### Load options
 
 ```ts
-import { Application, Scene } from '@codexo/exojs';
-import { TiledMap, tiledExtension } from '@codexo/exojs-tiled';
+// `.tmj`/`.tsj` are recognised by extension; a format hint is only needed for
+// Tiled data served from a generic `.json` path:
+await loader.load(TileMap, 'maps/world.json', { format: 'tiled' });
+```
 
-const app = new Application({ extensions: [tiledExtension] });
-document.body.append(app.canvas);
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `format` | `'tiled'` | `'tiled'` | Format hint for ambiguous `.json` paths. `.tmj`/`.tsj` are recognised by extension. `'tiled'` is the only accepted value (a foreign format is a compile error). Participates in the asset identity key. |
 
-class GameScene extends Scene {
-    map!: TiledMap;
+Options are optional. Parsing is always strict: `validateTiledMapData` throws a `TiledFormatError` on any malformed *known* field, and silently preserves *unknown* fields (so real-world Tiled files using features ExoJS does not model still load).
 
-    override async load(loader) {
-        await loader.load(TiledMap, { level1: '/maps/level1.tmj' });
-    }
+## Parsed API overview
 
-    override create(loader) {
-        this.map = loader.get(TiledMap, 'level1');
-        this.addChild(this.map);
-    }
-}
+### `TiledMap`
 
-app.scenes.start(GameScene);
+```ts
+map.source            // resolved URL this map was loaded from
+map.width             // map width in tiles
+map.height            // map height in tiles
+map.tileWidth         // tile grid cell width in pixels
+map.tileHeight        // tile grid cell height in pixels
+map.orientation       // 'orthogonal' | 'isometric' | 'staggered' | 'hexagonal'
+map.renderOrder       // 'right-down' | 'right-up' | 'left-down' | 'left-up' | undefined
+map.infinite          // true for infinite maps (layers use chunks, not flat data)
+map.backgroundColor   // optional CSS color string
+map.layers            // TiledLayer[] — parsed layer hierarchy
+map.tilesets          // TiledTileset[] — sorted by firstGid ascending
+map.properties        // TiledPropertyData[] — custom properties
+map.findTilesetForGid(gid)  // → TiledTileset | undefined (masks flip bits automatically)
+map.getProperty(name)       // → TiledPropertyData | undefined
+map.toTileMap()             // → TileMap — synchronous runtime conversion
+map.destroy()               // no-op; textures are Loader-owned
+```
+
+### `TiledTileset`
+
+```ts
+tileset.firstGid      // first GID in this tileset's range (inclusive)
+tileset.lastGid       // last GID in this tileset's range (inclusive)
+tileset.name
+tileset.tileWidth / tileHeight
+tileset.tileCount / columns / spacing / margin
+tileset.source        // resolved .tsj URL (undefined for embedded tilesets)
+tileset.imageUrl      // resolved atlas image URL (undefined for collection-of-images)
+tileset.texture       // Texture loaded for imageUrl (Loader-owned)
+tileset.tileTextures  // Map<localId, Texture> for collection-of-images tilesets (Loader-owned)
+tileset.tiles         // TiledTileData[] — per-tile animation/property/collision data
+tileset.getTile(localId)    // → TiledTileData | undefined
+tileset.getProperty(name)   // → TiledPropertyData | undefined
 ```
 
+### `TiledLayer` subclasses
+
+All layers extend `TiledLayer` (base: `id`, `name`, `class`, `visible`, `opacity`, `x`, `y`,
+`offsetX/Y`, `parallaxX/Y`, `tintColor`, `properties`, `getProperty(name)`).
+
+| Subclass | `type` | Extra fields |
+|---|---|---|
+| `TiledTileLayer` | `'tilelayer'` | `width`, `height`, `data?: number[]` (finite), `chunks?` (infinite) |
+| `TiledObjectLayer` | `'objectgroup'` | `drawOrder`, `objects: TiledObject[]` |
+| `TiledImageLayer` | `'imagelayer'` | `image`, `repeatX`, `repeatY` |
+| `TiledGroupLayer` | `'group'` | `layers: TiledLayer[]` |
+
+### `TiledObject`
+
+Shape discriminants: `point` (boolean), `ellipse` (boolean), `polygon`, `polyline`, `text`,
+`gid` (tile object). If none are set, the object is a plain rectangle.
+
+## Texture ownership
+
+Textures for tileset images are loaded via the Loader and remain in the Loader cache.
+`TiledMap.destroy()` releases the parsed source model's reference but does **not** unload textures.
+The Loader handles texture lifecycle (including deduplication across maps that share tilesets).
+
+## Core compatibility
+
+| `@codexo/exojs-tiled` | `@codexo/exojs` |
+|---|---|
+| 0.13.x | 0.13.x |
+
 ## Links
 
-- [Official ExoJS Tiled guide](https://exojs.dev/guides/extensions/tiled)
 - [API reference](https://exojs.dev/api/exojs-tiled)
 - [Tiled map editor](https://mapeditor.org)
 

package/dist/esm/TiledLayer.d.ts

@@ -0,0 +1,72 @@
+import type { TiledChunkData, TiledGroupLayerData, TiledImageLayerData, TiledLayerData, TiledLayerDataBase, TiledObjectLayerData, TiledPropertyData, TiledTileLayerData } from './data';
+import { TiledObject } from './TiledObject';
+/** Discriminant shared by every {@link TiledLayer} subclass, mirroring {@link TiledLayerData}'s `type`. */
+export type TiledLayerType = TiledLayerData['type'];
+/**
+ * Base class for the four parsed Tiled layer types. Holds the fields shared
+ * by every layer (`tilelayer`, `objectgroup`, `imagelayer`, `group`).
+ *
+ * Use {@link TiledLayer.type} (or `instanceof`) to discriminate between
+ * {@link TiledTileLayer}, {@link TiledObjectLayer}, {@link TiledImageLayer},
+ * and {@link TiledGroupLayer}.
+ */
+export declare abstract class TiledLayer {
+    abstract readonly type: TiledLayerType;
+    readonly id: number;
+    readonly name: string;
+    readonly class: string;
+    readonly visible: boolean;
+    readonly opacity: number;
+    readonly x: number;
+    readonly y: number;
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly parallaxX: number;
+    readonly parallaxY: number;
+    readonly tintColor?: string | undefined;
+    readonly properties: readonly TiledPropertyData[];
+    protected constructor(data: TiledLayerDataBase);
+    /** Looks up a custom property by name. */
+    getProperty(name: string): TiledPropertyData | undefined;
+}
+/**
+ * A tile layer. On a finite map, {@link data} holds the flat row-major array
+ * of GIDs (`width * height` entries). On an infinite map, {@link chunks}
+ * holds the sparse list of tile chunks instead; exactly one of the two is
+ * defined, matching the owning {@link TiledMap}'s `infinite` flag.
+ */
+export declare class TiledTileLayer extends TiledLayer {
+    readonly type: "tilelayer";
+    readonly width: number;
+    readonly height: number;
+    readonly data?: readonly number[] | undefined;
+    readonly chunks?: readonly TiledChunkData[] | undefined;
+    constructor(data: TiledTileLayerData);
+}
+/** An object layer: a flat list of {@link TiledObject}s. */
+export declare class TiledObjectLayer extends TiledLayer {
+    readonly type: "objectgroup";
+    readonly drawOrder: NonNullable<TiledObjectLayerData['draworder']>;
+    readonly objects: readonly TiledObject[];
+    constructor(data: TiledObjectLayerData);
+}
+/**
+ * An image layer. {@link image} is the path to the layer's image exactly as
+ * written in the Tiled JSON (relative to the map's location); resolving it
+ * against the owning {@link TiledMap}'s `source` is left to the consumer.
+ */
+export declare class TiledImageLayer extends TiledLayer {
+    readonly type: "imagelayer";
+    readonly image: string;
+    readonly repeatX: boolean;
+    readonly repeatY: boolean;
+    constructor(data: TiledImageLayerData);
+}
+/** A group layer, recursively containing further parsed layers. */
+export declare class TiledGroupLayer extends TiledLayer {
+    readonly type: "group";
+    readonly layers: readonly TiledLayer[];
+    constructor(data: TiledGroupLayerData);
+}
+/** Constructs the appropriate {@link TiledLayer} subclass for `data.type`. */
+export declare function createTiledLayer(data: TiledLayerData): TiledLayer;

package/dist/esm/TiledLayer.js

@@ -0,0 +1,117 @@
+import { TiledObject } from './TiledObject.js';
+
+/**
+ * Base class for the four parsed Tiled layer types. Holds the fields shared
+ * by every layer (`tilelayer`, `objectgroup`, `imagelayer`, `group`).
+ *
+ * Use {@link TiledLayer.type} (or `instanceof`) to discriminate between
+ * {@link TiledTileLayer}, {@link TiledObjectLayer}, {@link TiledImageLayer},
+ * and {@link TiledGroupLayer}.
+ */
+class TiledLayer {
+    id;
+    name;
+    class;
+    visible;
+    opacity;
+    x;
+    y;
+    offsetX;
+    offsetY;
+    parallaxX;
+    parallaxY;
+    tintColor;
+    properties;
+    constructor(data) {
+        this.id = data.id;
+        this.name = data.name;
+        this.class = data.class ?? '';
+        this.visible = data.visible;
+        this.opacity = data.opacity;
+        this.x = data.x;
+        this.y = data.y;
+        this.offsetX = data.offsetx ?? 0;
+        this.offsetY = data.offsety ?? 0;
+        this.parallaxX = data.parallaxx ?? 1;
+        this.parallaxY = data.parallaxy ?? 1;
+        this.tintColor = data.tintcolor;
+        this.properties = data.properties ?? [];
+    }
+    /** Looks up a custom property by name. */
+    getProperty(name) {
+        return this.properties.find(property => property.name === name);
+    }
+}
+/**
+ * A tile layer. On a finite map, {@link data} holds the flat row-major array
+ * of GIDs (`width * height` entries). On an infinite map, {@link chunks}
+ * holds the sparse list of tile chunks instead; exactly one of the two is
+ * defined, matching the owning {@link TiledMap}'s `infinite` flag.
+ */
+class TiledTileLayer extends TiledLayer {
+    type = 'tilelayer';
+    width;
+    height;
+    data;
+    chunks;
+    constructor(data) {
+        super(data);
+        this.width = data.width;
+        this.height = data.height;
+        this.data = data.data;
+        this.chunks = data.chunks;
+    }
+}
+/** An object layer: a flat list of {@link TiledObject}s. */
+class TiledObjectLayer extends TiledLayer {
+    type = 'objectgroup';
+    drawOrder;
+    objects;
+    constructor(data) {
+        super(data);
+        this.drawOrder = data.draworder ?? 'topdown';
+        this.objects = data.objects.map(object => new TiledObject(object));
+    }
+}
+/**
+ * An image layer. {@link image} is the path to the layer's image exactly as
+ * written in the Tiled JSON (relative to the map's location); resolving it
+ * against the owning {@link TiledMap}'s `source` is left to the consumer.
+ */
+class TiledImageLayer extends TiledLayer {
+    type = 'imagelayer';
+    image;
+    repeatX;
+    repeatY;
+    constructor(data) {
+        super(data);
+        this.image = data.image;
+        this.repeatX = data.repeatx ?? false;
+        this.repeatY = data.repeaty ?? false;
+    }
+}
+/** A group layer, recursively containing further parsed layers. */
+class TiledGroupLayer extends TiledLayer {
+    type = 'group';
+    layers;
+    constructor(data) {
+        super(data);
+        this.layers = data.layers.map(createTiledLayer);
+    }
+}
+/** Constructs the appropriate {@link TiledLayer} subclass for `data.type`. */
+function createTiledLayer(data) {
+    switch (data.type) {
+        case 'tilelayer':
+            return new TiledTileLayer(data);
+        case 'objectgroup':
+            return new TiledObjectLayer(data);
+        case 'imagelayer':
+            return new TiledImageLayer(data);
+        case 'group':
+            return new TiledGroupLayer(data);
+    }
+}
+
+export { TiledGroupLayer, TiledImageLayer, TiledLayer, TiledObjectLayer, TiledTileLayer, createTiledLayer };
+//# sourceMappingURL=TiledLayer.js.map

package/dist/esm/TiledLayer.js.map

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

package/dist/esm/TiledMap.d.ts

@@ -1,88 +1,73 @@
-import type { Texture } from '@codexo/exojs';
-export interface TiledTileset {
-    readonly firstgid: number;
-    readonly source?: string;
-    readonly image?: string;
-    readonly name?: string;
-    readonly tilewidth?: number;
-    readonly tileheight?: number;
-    readonly columns?: number;
-    readonly tilecount?: number;
-    readonly spacing?: number;
-    readonly margin?: number;
-}
-export interface TiledLayer {
-    readonly id: number;
-    readonly name: string;
-    readonly type: 'tilelayer' | 'objectgroup' | 'imagelayer' | 'group';
-    readonly visible: boolean;
-    readonly x: number;
-    readonly y: number;
-    readonly width?: number;
-    readonly height?: number;
-    readonly data?: number[];
-    readonly objects?: TiledObject[];
-    readonly opacity: number;
-}
-export interface TiledObject {
-    readonly id: number;
-    readonly name: string;
-    readonly type: string;
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-    readonly rotation: number;
-    readonly visible: boolean;
-    readonly gid?: number;
-    readonly properties?: TiledProperty[];
-}
-export interface TiledProperty {
-    readonly name: string;
-    readonly type: string;
-    readonly value: unknown;
-}
-/** Raw data shape parsed from a Tiled JSON (.tmj) file. */
-export interface TiledMapData {
-    readonly width: number;
-    readonly height: number;
-    readonly tilewidth: number;
-    readonly tileheight: number;
-    readonly infinite?: boolean;
-    readonly orientation?: string;
-    readonly renderorder?: string;
-    readonly layers: readonly TiledLayer[];
-    readonly tilesets: readonly TiledTileset[];
-    readonly version?: string | number;
-    readonly type?: string;
-}
+import { TileMap } from '@codexo/exojs-tilemap';
+import type { TiledMapData, TiledOrientation, TiledPropertyData, TiledRenderOrder } from './data';
+import { type TiledLayer } from './TiledLayer';
+import type { TiledTileset } from './TiledTileset';
 /**
- * Runtime representation of a loaded Tiled map.
+ * A parsed and validated Tiled map (`.tmj`).
  *
- * Exposes map metadata, layers, and tileset textures. Tileset textures
- * are owned by the Loader cache — `TiledMap.destroy()` does NOT destroy them.
+ * `TiledMap` represents the parsed Tiled source format. `TileMap` is the
+ * format-independent ExoJS runtime map used for rendering, queries, and
+ * mutation.
  *
- * Only the initial proof scope is implemented: orthogonal tile layers,
- * basic tilesets, and basic object layers. TMX/XML, infinite maps, and
- * world streaming are not supported.
+ * Construction validates that {@link tilesets} cover a non-overlapping,
+ * duplicate-free range of global tile ids, and that every GID referenced by
+ * {@link layers} (tile layer cells, infinite-map chunks, and tile object
+ * `gid`s) falls within one of those ranges. Both checks throw
+ * {@link TiledFormatError} on failure.
  */
 export declare class TiledMap {
+    /** Resolved URL this map was loaded from. */
+    readonly source: string;
+    /** The validated raw map data this instance was built from. */
     readonly data: TiledMapData;
-    readonly tilesetTextures: readonly Texture[];
+    readonly orientation: TiledOrientation;
+    readonly renderOrder?: TiledRenderOrder | undefined;
+    readonly class: string;
+    /** Map width in tiles. */
     readonly width: number;
+    /** Map height in tiles. */
     readonly height: number;
+    /** Tile grid cell width in pixels. */
     readonly tileWidth: number;
+    /** Tile grid cell height in pixels. */
     readonly tileHeight: number;
+    readonly infinite: boolean;
+    readonly backgroundColor?: string | undefined;
     readonly layers: readonly TiledLayer[];
+    /** Tilesets used by this map, sorted by {@link TiledTileset.firstGid} ascending. */
     readonly tilesets: readonly TiledTileset[];
-    constructor(data: TiledMapData, tilesetTextures: readonly Texture[]);
-    /** Tile layers only. */
-    get tileLayers(): readonly TiledLayer[];
-    /** Object group layers only. */
-    get objectLayers(): readonly TiledLayer[];
+    readonly properties: readonly TiledPropertyData[];
+    constructor(source: string, data: TiledMapData, tilesets: readonly TiledTileset[]);
+    /**
+     * Returns the tileset that owns `gid`, or `undefined` if `gid` is `0`
+     * (the empty-cell sentinel) or is not covered by any tileset.
+     *
+     * Flip/rotation flag bits are masked off before the range lookup, so the
+     * raw GID values found in {@link TiledTileLayer.data}/`chunks` and
+     * {@link TiledObject.gid} can be passed directly.
+     */
+    findTilesetForGid(gid: number): TiledTileset | undefined;
+    /** Looks up a custom property by name. */
+    getProperty(name: string): TiledPropertyData | undefined;
+    /**
+     * Convert this parsed Tiled source model into a format-independent runtime
+     * {@link TileMap} from `@codexo/exojs-tilemap`.
+     *
+     * Only finite orthogonal maps with atlas tilesets are supported. A
+     * non-orthogonal or infinite map, or a collection-of-images tileset, throws
+     * {@link TiledFormatError} rather than silently producing wrong (misplaced)
+     * or empty geometry. Tile layers become renderable `TileLayer`s and object
+     * groups become data-only `ObjectLayer`s; group layer children are flattened
+     * in document order. Image layers are not yet converted.
+     *
+     * The returned `TileMap` does **not** own the tileset textures — they remain
+     * in the Loader cache. Destroying the returned map does not unload textures.
+     */
+    toTileMap(): TileMap;
     /**
-     * Destroy this TiledMap. Does NOT destroy tileset textures — they are
-     * owned by the Loader's cache and may be shared with other callers.
+     * Releases this map's reference to its parsed source. Tileset textures are
+     * Loader-owned and may be shared with other maps; this does NOT destroy
+     * them.
      */
     destroy(): void;
 }