@codexo/exojs-ldtk 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/LdtkData.d.ts

@@ -0,0 +1,175 @@
+/**
+ * TypeScript types for the LDtk JSON format (version 1.5.x).
+ *
+ * These interfaces model the root LDtk JSON document as produced by the LDtk
+ * level editor. Only the fields consumed by the ExoJS runtime adapter are
+ * declared here; unknown fields are not stripped at parse time.
+ *
+ * @see https://ldtk.io/json/
+ */
+/** Flip-bit constants for {@link LdtkTileData.f}. */
+export declare const ldtkFlipNone = 0;
+export declare const ldtkFlipX = 1;
+export declare const ldtkFlipY = 2;
+export declare const ldtkFlipXy = 3;
+/** A single tile placed in a Tiles or AutoLayer layer instance. */
+export interface LdtkTileData {
+    /** Pixel position `[x, y]` of this tile within the layer. */
+    readonly px: readonly [number, number];
+    /** Source position `[x, y]` in the tileset image (top-left of the tile). */
+    readonly src: readonly [number, number];
+    /**
+     * Flip bits: `0` = none, `1` = flipX, `2` = flipY, `3` = flipX + flipY.
+     * Use {@link LDTK_FLIP_X} / {@link LDTK_FLIP_Y} constants for clarity.
+     */
+    readonly f: number;
+    /** Local tile index in the owning tileset. */
+    readonly t: number;
+    /** Per-tile opacity in `[0, 1]`. Defaults to `1` when absent. */
+    readonly a?: number;
+}
+/** A field value on an entity or level instance. */
+export interface LdtkFieldInstance {
+    readonly __identifier: string;
+    readonly __type: string;
+    readonly __value: unknown;
+}
+/** An entity instance placed in an Entities layer. */
+export interface LdtkEntityInstance {
+    /** Entity definition identifier (class name). */
+    readonly __identifier: string;
+    /** Alias of `__identifier`, mirrors the entity definition type. */
+    readonly __type: string;
+    /** Pixel position `[x, y]` of the entity origin. */
+    readonly px: readonly [number, number];
+    readonly width: number;
+    readonly height: number;
+    readonly fieldInstances: readonly LdtkFieldInstance[];
+    /** Globally unique instance id (UUID string). */
+    readonly iid: string;
+    /** UID of the entity definition this instance was created from. */
+    readonly defUid: number;
+}
+/** Discriminant string for a layer instance type. */
+export type LdtkLayerType = 'Tiles' | 'IntGrid' | 'Entities' | 'AutoLayer';
+/** A layer instance within a level. */
+export interface LdtkLayerInstance {
+    /** Layer definition identifier. */
+    readonly __identifier: string;
+    /** Layer type discriminant. */
+    readonly __type: LdtkLayerType;
+    /** Layer width in grid cells. */
+    readonly __cWid: number;
+    /** Layer height in grid cells. */
+    readonly __cHei: number;
+    /** Grid / tile size in pixels. */
+    readonly __gridSize: number;
+    /** UID of the layer definition. */
+    readonly layerDefUid: number;
+    /** UID of the parent level. */
+    readonly levelId: number;
+    readonly visible: boolean;
+    /** Globally unique instance id (UUID string). */
+    readonly iid: string;
+    /**
+     * UID of the tileset used by this layer.
+     * Present for `Tiles`, `AutoLayer`, and `IntGrid` layers that use a tileset.
+     */
+    readonly __tilesetDefUid?: number;
+    /** Placed tiles for `Tiles` layer type. */
+    readonly gridTiles?: readonly LdtkTileData[];
+    /** Auto-computed tiles for `AutoLayer` (and `IntGrid` + auto-rules) layer types. */
+    readonly autoLayerTiles?: readonly LdtkTileData[];
+    /** Entity instances for `Entities` layer type. */
+    readonly entityInstances?: readonly LdtkEntityInstance[];
+    /**
+     * Flat CSV array of IntGrid values for `IntGrid` layer type.
+     * Index = `y * __cWid + x`. `0` = empty cell.
+     */
+    readonly intGridCsv?: readonly number[];
+    /** Horizontal pixel offset applied to the layer. */
+    readonly pxOffsetX?: number;
+    /** Vertical pixel offset applied to the layer. */
+    readonly pxOffsetY?: number;
+    /** Layer opacity in `[0, 1]`. */
+    readonly opacity?: number;
+}
+/** A level in the LDtk world. */
+export interface LdtkLevel {
+    /** Human-readable level identifier (unique within the world). */
+    readonly identifier: string;
+    readonly uid: number;
+    /** Globally unique instance id (UUID string). */
+    readonly iid: string;
+    /** World-space X position of the level's top-left corner in pixels. */
+    readonly worldX: number;
+    /** World-space Y position of the level's top-left corner in pixels. */
+    readonly worldY: number;
+    /** Level width in pixels. */
+    readonly pxWid: number;
+    /** Level height in pixels. */
+    readonly pxHei: number;
+    readonly bgColor?: string;
+    /**
+     * Layer instances in this level (top-to-bottom render order).
+     * `null` when the level is stored in a separate `.ldtkl` file and has not
+     * been loaded yet.
+     */
+    readonly layerInstances: readonly LdtkLayerInstance[] | null;
+    readonly fieldInstances?: readonly LdtkFieldInstance[];
+    /** Relative path to an external `.ldtkl` file for multi-world setups. */
+    readonly externalRelPath?: string;
+}
+/** Tileset definition from `defs.tilesets`. */
+export interface LdtkTilesetDef {
+    readonly uid: number;
+    /** Human-readable tileset identifier. */
+    readonly identifier: string;
+    /**
+     * Relative path to the tileset atlas image.
+     * `null` for internal / embedded tilesets with no image.
+     */
+    readonly relPath: string | null;
+    /** Tile grid size (both width and height) in pixels. */
+    readonly tileGridSize: number;
+    /** Tileset image width in pixels. */
+    readonly pxWid: number;
+    /** Tileset image height in pixels. */
+    readonly pxHei: number;
+    /** Pixel spacing between tiles in the atlas. */
+    readonly spacing?: number;
+    /** Pixel padding (margin) around the atlas edges. */
+    readonly padding?: number;
+}
+/** An IntGrid value definition (maps a raw int to a named, coloured entry). */
+export interface LdtkIntGridValueDef {
+    readonly value: number;
+    readonly identifier: string | null;
+    readonly color: string;
+}
+/** Layer definition from `defs.layers`. */
+export interface LdtkLayerDef {
+    readonly uid: number;
+    readonly identifier: string;
+    readonly type: LdtkLayerType;
+    /** UID of the default tileset for this layer. `null` or absent = none. */
+    readonly tilesetDefUid?: number | null;
+    readonly gridSize: number;
+    readonly intGridValues?: readonly LdtkIntGridValueDef[];
+}
+/** Top-level definitions block (`defs`). */
+export interface LdtkDefs {
+    readonly tilesets: readonly LdtkTilesetDef[];
+    readonly layers: readonly LdtkLayerDef[];
+}
+/** Root LDtk JSON document (`*.ldtk`). */
+export interface LdtkData {
+    /** LDtk JSON format version string (e.g. `"1.5.3"`). */
+    readonly jsonVersion: string;
+    readonly worldGridWidth?: number;
+    readonly worldGridHeight?: number;
+    readonly defaultGridSize?: number;
+    readonly bgColor?: string;
+    readonly defs: LdtkDefs;
+    readonly levels: readonly LdtkLevel[];
+}

package/dist/esm/LdtkData.js

@@ -0,0 +1,19 @@
+/**
+ * TypeScript types for the LDtk JSON format (version 1.5.x).
+ *
+ * These interfaces model the root LDtk JSON document as produced by the LDtk
+ * level editor. Only the fields consumed by the ExoJS runtime adapter are
+ * declared here; unknown fields are not stripped at parse time.
+ *
+ * @see https://ldtk.io/json/
+ */
+/* eslint-disable @typescript-eslint/naming-convention -- LDtk uses __ prefix for runtime fields */
+// ── Tile data ─────────────────────────────────────────────────────────────────
+/** Flip-bit constants for {@link LdtkTileData.f}. */
+const ldtkFlipNone = 0;
+const ldtkFlipX = 1;
+const ldtkFlipY = 2;
+const ldtkFlipXy = 3;
+
+export { ldtkFlipNone, ldtkFlipX, ldtkFlipXy, ldtkFlipY };
+//# sourceMappingURL=LdtkData.js.map

package/dist/esm/LdtkData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LdtkData.js","sources":["../../../src/LdtkData.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;AAQG;AAEH;AAEA;AAEA;AACO,MAAM,YAAY,GAAG;AACrB,MAAM,SAAS,GAAG;AAClB,MAAM,SAAS,GAAG;AAClB,MAAM,UAAU,GAAG;;;;"}

package/dist/esm/LdtkMap.d.ts

@@ -0,0 +1,43 @@
+import type { TileMap } from '@codexo/exojs-tilemap';
+import type { LdtkData } from './LdtkData';
+/**
+ * A parsed LDtk world document: holds the raw JSON data and the converted
+ * runtime {@link TileMap} for each level.
+ *
+ * `LdtkMap` is the parsed source model. Each LDtk level is independently
+ * convertible to a format-independent `TileMap`; access them via
+ * {@link levels} (by document order) or by name via {@link getLevelByName}.
+ *
+ * Construction is cheap — the runtime `TileMap[]` is supplied externally
+ * (built by {@link import('./ldtkToTileMap').ldtkToTileMap}). The map does
+ * **not** own tileset textures; those remain in the Loader cache.
+ */
+export declare class LdtkMap {
+    /** Resolved URL this map was loaded from. */
+    readonly source: string;
+    /** The raw parsed LDtk document. */
+    readonly data: LdtkData;
+    /**
+     * Runtime TileMaps — one per LDtk level, in document order.
+     *
+     * The index here corresponds to `data.levels[i]`. Levels for which
+     * conversion was skipped (e.g. external `.ldtkl` files not yet loaded)
+     * are `undefined` at that position.
+     */
+    readonly levels: readonly TileMap[];
+    constructor(source: string, data: LdtkData, levels: readonly TileMap[]);
+    /**
+     * Find a level's runtime {@link TileMap} by the LDtk level `identifier`,
+     * or `undefined` when no level with that name exists.
+     *
+     * The lookup is O(n) in the number of levels.
+     */
+    getLevelByName(identifier: string): TileMap | undefined;
+    /**
+     * Destroy all owned runtime TileMaps.
+     *
+     * Is idempotent. Does NOT destroy tileset textures (Loader-owned) or any
+     * SceneNodes — the application is responsible for those.
+     */
+    destroy(): void;
+}

package/dist/esm/LdtkMap.js

@@ -0,0 +1,57 @@
+/**
+ * A parsed LDtk world document: holds the raw JSON data and the converted
+ * runtime {@link TileMap} for each level.
+ *
+ * `LdtkMap` is the parsed source model. Each LDtk level is independently
+ * convertible to a format-independent `TileMap`; access them via
+ * {@link levels} (by document order) or by name via {@link getLevelByName}.
+ *
+ * Construction is cheap — the runtime `TileMap[]` is supplied externally
+ * (built by {@link import('./ldtkToTileMap').ldtkToTileMap}). The map does
+ * **not** own tileset textures; those remain in the Loader cache.
+ */
+class LdtkMap {
+    /** Resolved URL this map was loaded from. */
+    source;
+    /** The raw parsed LDtk document. */
+    data;
+    /**
+     * Runtime TileMaps — one per LDtk level, in document order.
+     *
+     * The index here corresponds to `data.levels[i]`. Levels for which
+     * conversion was skipped (e.g. external `.ldtkl` files not yet loaded)
+     * are `undefined` at that position.
+     */
+    levels;
+    constructor(source, data, levels) {
+        this.source = source;
+        this.data = data;
+        this.levels = levels;
+    }
+    /**
+     * Find a level's runtime {@link TileMap} by the LDtk level `identifier`,
+     * or `undefined` when no level with that name exists.
+     *
+     * The lookup is O(n) in the number of levels.
+     */
+    getLevelByName(identifier) {
+        const index = this.data.levels.findIndex(level => level.identifier === identifier);
+        if (index === -1)
+            return undefined;
+        return this.levels[index];
+    }
+    /**
+     * Destroy all owned runtime TileMaps.
+     *
+     * Is idempotent. Does NOT destroy tileset textures (Loader-owned) or any
+     * SceneNodes — the application is responsible for those.
+     */
+    destroy() {
+        for (const level of this.levels) {
+            level.destroy();
+        }
+    }
+}
+
+export { LdtkMap };
+//# sourceMappingURL=LdtkMap.js.map

package/dist/esm/LdtkMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LdtkMap.js","sources":["../../../src/LdtkMap.ts"],"sourcesContent":[null],"names":[],"mappings":"AAIA;;;;;;;;;;;AAWG;MACU,OAAO,CAAA;;AAEF,IAAA,MAAM;;AAEN,IAAA,IAAI;AACpB;;;;;;AAMG;AACa,IAAA,MAAM;AAEtB,IAAA,WAAA,CAAmB,MAAc,EAAE,IAAc,EAAE,MAA0B,EAAA;AAC3E,QAAA,IAAI,CAAC,MAAM,GAAG,MAAM;AACpB,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,MAAM,GAAG,MAAM;IACtB;AAEA;;;;;AAKG;AACI,IAAA,cAAc,CAAC,UAAkB,EAAA;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAAC;QAClF,IAAI,KAAK,KAAK,EAAE;AAAE,YAAA,OAAO,SAAS;AAClC,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B;AAEA;;;;;AAKG;IACI,OAAO,GAAA;AACZ,QAAA,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE;YAC/B,KAAK,CAAC,OAAO,EAAE;QACjB;IACF;AACD;;;;"}

package/dist/esm/index.d.ts

@@ -0,0 +1 @@
+export * from './public';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export { ldtkMapBinding } from './ldtkBinding.js';
+export { ldtkExtension } from './ldtkExtension.js';
+export { LdtkMap } from './LdtkMap.js';
+export { ldtkToTileMap } from './ldtkToTileMap.js';
+export { ldtkFlipNone, ldtkFlipX, ldtkFlipXy, ldtkFlipY } from './LdtkData.js';
+export { ObjectKind, ObjectLayer, TILE_TRANSFORM_IDENTITY, TileLayer, TileMap, TileMapView, TileSet, tilemapExtension } from '@codexo/exojs-tilemap';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}

package/dist/esm/ldtkBinding.d.ts

@@ -0,0 +1,22 @@
+import { LdtkMap } from './LdtkMap';
+/**
+ * Declarative asset binding for {@link LdtkMap}.
+ *
+ * Claims the `ldtk` file extension so that:
+ * - `loader.load(LdtkMap, 'world.ldtk')` — returns the parsed
+ *   {@link LdtkMap} with all levels pre-converted to runtime
+ *   {@link import('@codexo/exojs-tilemap').TileMap}s.
+ * - `loader.load('world.ldtk')` — auto-routed to `LdtkMap` via
+ *   the `ExtensionTypeMap` augmentation in `public.ts`.
+ *
+ * Each loaded level's TileMap is accessible via {@link LdtkMap.levels} or
+ * {@link LdtkMap.getLevelByName}.
+ */
+export declare const ldtkMapBinding: {
+    type: typeof LdtkMap;
+    typeNames: string[];
+    extensions: string[];
+    create(): {
+        load(req: import("@codexo/exojs").AssetLoadRequest<undefined>, ctx: import("@codexo/exojs").AssetLoaderContext): Promise<LdtkMap>;
+    };
+};

package/dist/esm/ldtkBinding.js

@@ -0,0 +1,31 @@
+import { LdtkMap } from './LdtkMap.js';
+import { loadLdtkMap } from './loadLdtkMap.js';
+
+/**
+ * Declarative asset binding for {@link LdtkMap}.
+ *
+ * Claims the `ldtk` file extension so that:
+ * - `loader.load(LdtkMap, 'world.ldtk')` — returns the parsed
+ *   {@link LdtkMap} with all levels pre-converted to runtime
+ *   {@link import('@codexo/exojs-tilemap').TileMap}s.
+ * - `loader.load('world.ldtk')` — auto-routed to `LdtkMap` via
+ *   the `ExtensionTypeMap` augmentation in `public.ts`.
+ *
+ * Each loaded level's TileMap is accessible via {@link LdtkMap.levels} or
+ * {@link LdtkMap.getLevelByName}.
+ */
+const ldtkMapBinding = {
+    type: LdtkMap,
+    typeNames: ['ldtkMap'],
+    extensions: ['ldtk'],
+    create() {
+        return {
+            async load(req, ctx) {
+                return loadLdtkMap(req.source, ctx);
+            },
+        };
+    },
+};
+
+export { ldtkMapBinding };
+//# sourceMappingURL=ldtkBinding.js.map

package/dist/esm/ldtkBinding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ldtkBinding.js","sources":["../../../src/ldtkBinding.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;AAYG;AACI,MAAM,cAAc,GAAG;AAC5B,IAAA,IAAI,EAAE,OAAO;IACb,SAAS,EAAE,CAAC,SAAS,CAAC;IACtB,UAAU,EAAE,CAAC,MAAM,CAAC;IACpB,MAAM,GAAA;QACJ,OAAO;AACL,YAAA,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,EAAA;gBACjB,OAAO,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC;YACrC,CAAC;SAC8B;IACnC,CAAC;;;;;"}

package/dist/esm/ldtkExtension.d.ts

@@ -0,0 +1,17 @@
+import type { Extension } from '@codexo/exojs/extensions';
+/**
+ * Default immutable LDtk extension descriptor.
+ *
+ * Registers one asset binding:
+ * - {@link ldtkMapBinding} — `loader.load(LdtkMap, 'world.ldtk')` → fetches
+ *   the `.ldtk` JSON, loads all referenced tileset images, and returns a
+ *   fully assembled {@link LdtkMap} with one runtime
+ *   {@link import('@codexo/exojs-tilemap').TileMap} per level.
+ *
+ * Depends on {@link tilemapExtension} so that snapshot construction always
+ * materialises the generic tilemap runtime before the LDtk adapter.
+ *
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-ldtk/register'` for global auto-registration.
+ */
+export declare const ldtkExtension: Extension;

package/dist/esm/ldtkExtension.js

@@ -0,0 +1,28 @@
+import { tilemapExtension } from '@codexo/exojs-tilemap';
+import { ldtkMapBinding } from './ldtkBinding.js';
+
+/**
+ * Default immutable LDtk extension descriptor.
+ *
+ * Registers one asset binding:
+ * - {@link ldtkMapBinding} — `loader.load(LdtkMap, 'world.ldtk')` → fetches
+ *   the `.ldtk` JSON, loads all referenced tileset images, and returns a
+ *   fully assembled {@link LdtkMap} with one runtime
+ *   {@link import('@codexo/exojs-tilemap').TileMap} per level.
+ *
+ * Depends on {@link tilemapExtension} so that snapshot construction always
+ * materialises the generic tilemap runtime before the LDtk adapter.
+ *
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-ldtk/register'` for global auto-registration.
+ */
+const ldtkExtension = Object.freeze({
+    id: '@codexo/exojs-ldtk',
+    dependencies: [tilemapExtension],
+    // Localized erasure cast: typed binding meets the untyped Extension.assets
+    // contract here. Runtime behaviour is unaffected.
+    assets: [ldtkMapBinding],
+});
+
+export { ldtkExtension };
+//# sourceMappingURL=ldtkExtension.js.map

package/dist/esm/ldtkExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ldtkExtension.js","sources":["../../../src/ldtkExtension.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAKA;;;;;;;;;;;;;;AAcG;AACI,MAAM,aAAa,GAAc,MAAM,CAAC,MAAM,CAAC;AACpD,IAAA,EAAE,EAAE,oBAAoB;IACxB,YAAY,EAAE,CAAC,gBAAgB,CAAC;;;IAGhC,MAAM,EAAE,CAAC,cAAc,CAA8B;AACtD,CAAA;;;;"}

package/dist/esm/ldtkToTileMap.d.ts

@@ -0,0 +1,40 @@
+import type { TileSet } from '@codexo/exojs-tilemap';
+import { TILE_TRANSFORM_IDENTITY } from '@codexo/exojs-tilemap';
+import type { LdtkData } from './LdtkData';
+import { LdtkMap } from './LdtkMap';
+/**
+ * Options for {@link ldtkToTileMap}.
+ */
+export interface LdtkToTileMapOptions {
+    /**
+     * Source URL of the loaded `.ldtk` file, used as {@link LdtkMap.source}.
+     * Defaults to an empty string when omitted (e.g. programmatic / test usage).
+     */
+    readonly source?: string;
+    /**
+     * Pre-loaded runtime {@link TileSet}s keyed by LDtk tileset UID.
+     *
+     * When provided, tile layers are populated with tile data from
+     * `gridTiles` / `autoLayerTiles`. Without this map, tile layers are created
+     * with the correct dimensions but no tiles are placed — only entity and
+     * object layers carry data.
+     *
+     * Populate via {@link import('./loadLdtkMap').loadLdtkMap} for asset-loading
+     * flows, or pass a hand-crafted map for testing.
+     */
+    readonly tilesets?: ReadonlyMap<number, TileSet>;
+}
+/**
+ * Convert a raw {@link LdtkData} document into an {@link LdtkMap} containing
+ * one runtime {@link TileMap} per LDtk level.
+ *
+ * Tile layers (`Tiles` / `AutoLayer`) become renderable `TileLayer`s. IntGrid
+ * layers become dimension-correct `TileLayer`s — tile data is placed only when
+ * the layer carries `autoLayerTiles`. Entity layers become data-only
+ * `ObjectLayer`s with entity position, size, and scalar field properties.
+ *
+ * Pass `options.tilesets` to populate tile data; omit it for structure-only
+ * conversion (useful in unit tests that do not need textures).
+ */
+export declare function ldtkToTileMap(data: LdtkData, options?: LdtkToTileMapOptions): LdtkMap;
+export { TILE_TRANSFORM_IDENTITY };

package/dist/esm/ldtkToTileMap.js

@@ -0,0 +1,200 @@
+import { ObjectLayer, TileMap, TileLayer } from '@codexo/exojs-tilemap';
+export { TILE_TRANSFORM_IDENTITY } from '@codexo/exojs-tilemap';
+import { ldtkFlipY, ldtkFlipX } from './LdtkData.js';
+import { LdtkMap } from './LdtkMap.js';
+
+/**
+ * Convert a raw {@link LdtkData} document into an {@link LdtkMap} containing
+ * one runtime {@link TileMap} per LDtk level.
+ *
+ * Tile layers (`Tiles` / `AutoLayer`) become renderable `TileLayer`s. IntGrid
+ * layers become dimension-correct `TileLayer`s — tile data is placed only when
+ * the layer carries `autoLayerTiles`. Entity layers become data-only
+ * `ObjectLayer`s with entity position, size, and scalar field properties.
+ *
+ * Pass `options.tilesets` to populate tile data; omit it for structure-only
+ * conversion (useful in unit tests that do not need textures).
+ */
+function ldtkToTileMap(data, options) {
+    const source = options?.source ?? '';
+    const tilesets = options?.tilesets ?? new Map();
+    const levels = data.levels.map((level, levelIndex) => convertLevel(level, levelIndex, data, tilesets));
+    return new LdtkMap(source, data, levels);
+}
+// ── Level conversion ──────────────────────────────────────────────────────────
+// eslint-disable-next-line complexity
+function convertLevel(level, levelIndex, data, tilesets) {
+    // Derive map-level tile size from the first non-entity layer, or fall back.
+    const gridSize = pickLevelGridSize(level, data.defaultGridSize ?? 16);
+    const mapWidth = Math.max(1, Math.ceil(level.pxWid / gridSize));
+    const mapHeight = Math.max(1, Math.ceil(level.pxHei / gridSize));
+    const runtimeTilesets = [...tilesets.values()];
+    const runtimeLayers = [];
+    const runtimeObjectLayers = [];
+    // LDtk stores layers top-to-bottom (first = top-most); preserve that order.
+    const layerInstances = level.layerInstances ?? [];
+    let entityCounter = 0;
+    for (const layerInst of layerInstances) {
+        const layerGridSize = layerInst.__gridSize;
+        // Layer IDs must be unique within a TileMap (= one level).
+        // Use layerDefUid directly — it is unique per layer definition in the file.
+        const layerId = layerInst.layerDefUid;
+        switch (layerInst.__type) {
+            case 'Tiles':
+            case 'AutoLayer': {
+                const rLayer = makeTileLayer(layerInst, layerId, runtimeTilesets);
+                const tiles = layerInst.__type === 'Tiles'
+                    ? (layerInst.gridTiles ?? [])
+                    : (layerInst.autoLayerTiles ?? []);
+                const tsUid = layerInst.__tilesetDefUid;
+                if (tsUid !== undefined) {
+                    const rts = tilesets.get(tsUid);
+                    if (rts)
+                        populateTileLayer(rLayer, tiles, rts, layerGridSize);
+                }
+                runtimeLayers.push(rLayer);
+                break;
+            }
+            case 'IntGrid': {
+                const rLayer = makeTileLayer(layerInst, layerId, runtimeTilesets);
+                // IntGrid layers may carry auto-tiles when "Auto-layer" rules are
+                // configured. Use those for rendering; raw intGridCsv is data-only.
+                const autoTiles = layerInst.autoLayerTiles ?? [];
+                const tsUid = layerInst.__tilesetDefUid;
+                if (autoTiles.length > 0 && tsUid !== undefined) {
+                    const rts = tilesets.get(tsUid);
+                    if (rts)
+                        populateTileLayer(rLayer, autoTiles, rts, layerGridSize);
+                }
+                runtimeLayers.push(rLayer);
+                break;
+            }
+            case 'Entities': {
+                const objects = convertEntityLayer(layerInst, layerGridSize, levelIndex, entityCounter);
+                entityCounter += layerInst.entityInstances?.length ?? 0;
+                runtimeObjectLayers.push(new ObjectLayer({
+                    id: layerId,
+                    name: layerInst.__identifier,
+                    visible: layerInst.visible,
+                    opacity: layerInst.opacity ?? 1,
+                    offsetX: layerInst.pxOffsetX ?? 0,
+                    offsetY: layerInst.pxOffsetY ?? 0,
+                    objects,
+                }));
+                break;
+            }
+        }
+    }
+    return new TileMap({
+        name: level.identifier,
+        width: mapWidth,
+        height: mapHeight,
+        tileWidth: gridSize,
+        tileHeight: gridSize,
+        tilesets: runtimeTilesets,
+        layers: runtimeLayers,
+        objectLayers: runtimeObjectLayers,
+        properties: {
+            ldtkUid: level.uid,
+            ldtkIid: level.iid,
+            worldX: level.worldX,
+            worldY: level.worldY,
+        },
+    });
+}
+// ── Helpers: TileLayer ────────────────────────────────────────────────────────
+function makeTileLayer(layerInst, layerId, tilesets) {
+    return new TileLayer({
+        id: layerId,
+        name: layerInst.__identifier,
+        width: layerInst.__cWid,
+        height: layerInst.__cHei,
+        tilesets,
+        tileWidth: layerInst.__gridSize,
+        tileHeight: layerInst.__gridSize,
+        visible: layerInst.visible,
+        opacity: layerInst.opacity ?? 1,
+        offsetX: layerInst.pxOffsetX ?? 0,
+        offsetY: layerInst.pxOffsetY ?? 0,
+    });
+}
+function populateTileLayer(layer, tiles, tileset, gridSize) {
+    for (const tile of tiles) {
+        const tx = Math.floor(tile.px[0] / gridSize);
+        const ty = Math.floor(tile.px[1] / gridSize);
+        if (!layer.inBounds(tx, ty))
+            continue;
+        const localTileId = tile.t;
+        if (localTileId < 0 || localTileId >= tileset.tileCount)
+            continue;
+        const f = tile.f;
+        layer.setTileAt(tx, ty, {
+            tileset,
+            localTileId,
+            transform: {
+                flipX: (f & ldtkFlipX) !== 0,
+                flipY: (f & ldtkFlipY) !== 0,
+                diagonal: false,
+            },
+        });
+    }
+}
+// ── Helpers: ObjectLayer ──────────────────────────────────────────────────────
+function convertEntityLayer(layerInst, _gridSize, levelIndex, baseCounter) {
+    const instances = layerInst.entityInstances ?? [];
+    const objects = [];
+    for (let i = 0; i < instances.length; i++) {
+        const entity = instances[i];
+        if (entity === undefined)
+            continue;
+        // Build a deterministic numeric id: (levelIndex * 1_000_000) + counter.
+        const id = levelIndex * 1_000_000 + baseCounter + i;
+        objects.push(convertEntity(entity, id));
+    }
+    return objects;
+}
+function convertEntity(entity, id) {
+    return {
+        kind: 'rectangle',
+        id,
+        name: entity.__identifier,
+        type: entity.__identifier,
+        x: entity.px[0],
+        y: entity.px[1],
+        width: entity.width,
+        height: entity.height,
+        rotation: 0,
+        visible: true,
+        properties: convertFieldInstances(entity.fieldInstances),
+    };
+}
+/**
+ * Project LDtk field instances to a flat {@link TileProperties} bag.
+ * Only scalar values (string, number, boolean) are forwarded; complex types
+ * (arrays, colours, enums-as-objects) are silently skipped.
+ */
+function convertFieldInstances(fields) {
+    if (fields.length === 0)
+        return Object.freeze({});
+    const out = {};
+    for (const field of fields) {
+        const v = field.__value;
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+            out[field.__identifier] = v;
+        }
+    }
+    return Object.freeze(out);
+}
+// ── Helpers: grid size ────────────────────────────────────────────────────────
+function pickLevelGridSize(level, fallback) {
+    const instances = level.layerInstances ?? [];
+    for (const layer of instances) {
+        if (layer.__type !== 'Entities' && layer.__gridSize > 0) {
+            return layer.__gridSize;
+        }
+    }
+    return fallback;
+}
+
+export { ldtkToTileMap };
+//# sourceMappingURL=ldtkToTileMap.js.map

package/dist/esm/ldtkToTileMap.js.map

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

package/dist/esm/loadLdtkMap.d.ts

@@ -0,0 +1,12 @@
+import { type AssetLoaderContext } from '@codexo/exojs';
+import type { LdtkMap } from './LdtkMap';
+/**
+ * Fetch a `.ldtk` file, load all referenced tileset images, and return a
+ * fully assembled {@link LdtkMap} with one runtime {@link import('@codexo/exojs-tilemap').TileMap}
+ * per level.
+ *
+ * Tilesets without an atlas image (`relPath = null`) are silently skipped;
+ * their tiles will not appear in the rendered output.
+ * @internal
+ */
+export declare function loadLdtkMap(source: string, context: AssetLoaderContext): Promise<LdtkMap>;

package/dist/esm/loadLdtkMap.js

@@ -0,0 +1,81 @@
+import { Texture, TextureRegion } from '@codexo/exojs';
+import { TileSet } from '@codexo/exojs-tilemap';
+import { ldtkToTileMap } from './ldtkToTileMap.js';
+
+// ── URL resolution ────────────────────────────────────────────────────────────
+/**
+ * Resolve a tileset-relative path against the base `.ldtk` URL.
+ * Mirrors the approach used by the Tiled adapter.
+ */
+function resolveLdtkUrl(relPath, baseUrl) {
+    return new URL(relPath, baseUrl).href;
+}
+// ── Tileset loading ───────────────────────────────────────────────────────────
+/**
+ * Load one LDtk tileset definition into a runtime {@link TileSet}.
+ * Returns `null` when the tileset has no atlas image (`relPath` is null or
+ * empty) — those entries are silently skipped and their tiles will not render.
+ */
+async function loadLdtkTileset(def, ldtkSource, context) {
+    if (!def.relPath)
+        return null;
+    const imageUrl = resolveLdtkUrl(def.relPath, ldtkSource);
+    const texture = (await context.loader.load(Texture, imageUrl));
+    const tileSize = def.tileGridSize;
+    const spacing = def.spacing ?? 0;
+    const margin = def.padding ?? 0;
+    // Compute columns / tileCount from atlas dimensions.
+    const innerWidth = def.pxWid - margin * 2;
+    const innerHeight = def.pxHei - margin * 2;
+    const columns = Math.floor((innerWidth + spacing) / (tileSize + spacing));
+    const rows = Math.floor((innerHeight + spacing) / (tileSize + spacing));
+    if (columns <= 0 || rows <= 0)
+        return null;
+    const tileCount = columns * rows;
+    const region = new TextureRegion(texture, {
+        x: 0,
+        y: 0,
+        width: def.pxWid,
+        height: def.pxHei,
+    });
+    return new TileSet({
+        name: def.identifier,
+        texture: region,
+        tileWidth: tileSize,
+        tileHeight: tileSize,
+        tileCount,
+        columns,
+        spacing,
+        margin,
+    });
+}
+// ── Public loader ─────────────────────────────────────────────────────────────
+/**
+ * Fetch a `.ldtk` file, load all referenced tileset images, and return a
+ * fully assembled {@link LdtkMap} with one runtime {@link import('@codexo/exojs-tilemap').TileMap}
+ * per level.
+ *
+ * Tilesets without an atlas image (`relPath = null`) are silently skipped;
+ * their tiles will not appear in the rendered output.
+ * @internal
+ */
+async function loadLdtkMap(source, context) {
+    const raw = await context.fetchJson(source);
+    // Cast without deep validation — structural errors surface as runtime
+    // exceptions when we access fields during conversion.
+    const data = raw;
+    // Load all referenced tilesets concurrently.
+    const tilesetEntries = await Promise.all(data.defs.tilesets.map(async (def) => {
+        const ts = await loadLdtkTileset(def, source, context);
+        return [def.uid, ts];
+    }));
+    const tilesets = new Map();
+    for (const [uid, ts] of tilesetEntries) {
+        if (ts !== null)
+            tilesets.set(uid, ts);
+    }
+    return ldtkToTileMap(data, { source, tilesets });
+}
+
+export { loadLdtkMap };
+//# sourceMappingURL=loadLdtkMap.js.map

package/dist/esm/loadLdtkMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadLdtkMap.js","sources":["../../../src/loadLdtkMap.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAOA;AAEA;;;AAGG;AACH,SAAS,cAAc,CAAC,OAAe,EAAE,OAAe,EAAA;IACtD,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI;AACvC;AAEA;AAEA;;;;AAIG;AACH,eAAe,eAAe,CAC5B,GAAmB,EACnB,UAAkB,EAClB,OAA2B,EAAA;IAE3B,IAAI,CAAC,GAAG,CAAC,OAAO;AAAE,QAAA,OAAO,IAAI;IAE7B,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC;AACxD,IAAA,MAAM,OAAO,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAY;AAEzE,IAAA,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY;AACjC,IAAA,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC;AAChC,IAAA,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC;;IAG/B,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC;IACzC,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,GAAG,MAAM,GAAG,CAAC;AAC1C,IAAA,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,CAAC;AACzE,IAAA,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,GAAG,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,CAAC;AAEvE,IAAA,IAAI,OAAO,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;AAAE,QAAA,OAAO,IAAI;AAE1C,IAAA,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI;AAChC,IAAA,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE;AACxC,QAAA,CAAC,EAAE,CAAC;AACJ,QAAA,CAAC,EAAE,CAAC;QACJ,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,KAAK;AAClB,KAAA,CAAC;IAEF,OAAO,IAAI,OAAO,CAAC;QACjB,IAAI,EAAE,GAAG,CAAC,UAAU;AACpB,QAAA,OAAO,EAAE,MAAM;AACf,QAAA,SAAS,EAAE,QAAQ;AACnB,QAAA,UAAU,EAAE,QAAQ;QACpB,SAAS;QACT,OAAO;QACP,OAAO;QACP,MAAM;AACP,KAAA,CAAC;AACJ;AAEA;AAEA;;;;;;;;AAQG;AACI,eAAe,WAAW,CAC/B,MAAc,EACd,OAA2B,EAAA;IAE3B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC;;;IAG3C,MAAM,IAAI,GAAG,GAAe;;AAG5B,IAAA,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,GAAG,CACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,GAAG,KAAI;QACnC,MAAM,EAAE,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC;AACtD,QAAA,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAU;IAC/B,CAAC,CAAC,CACH;AAED,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,cAAc,EAAE;QACtC,IAAI,EAAE,KAAK,IAAI;AAAE,YAAA,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC;IACxC;IAEA,OAAO,aAAa,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAClD;;;;"}

package/dist/esm/public.d.ts

@@ -0,0 +1,24 @@
+export { ldtkMapBinding } from './ldtkBinding';
+export { ldtkExtension } from './ldtkExtension';
+export { LdtkMap } from './LdtkMap';
+export type { LdtkToTileMapOptions } from './ldtkToTileMap';
+export { ldtkToTileMap } from './ldtkToTileMap';
+export type { LdtkData, LdtkDefs, LdtkEntityInstance, LdtkFieldInstance, LdtkIntGridValueDef, LdtkLayerDef, LdtkLayerInstance, LdtkLayerType, LdtkLevel, LdtkTileData, LdtkTilesetDef, } from './LdtkData';
+export { ldtkFlipNone, ldtkFlipX, ldtkFlipXy, ldtkFlipY } from './LdtkData';
+export type { ChunkCoord, EllipseObject, ObjectLayerOptions, ObjectPoint, ObjectQuery, ObjectSchema, PackedTile, PointObject, PolygonObject, PolylineObject, ReadonlyTileChunk, RectangleObject, ResolvedTile, TileDefinition, TileLayerOptions, TileMapObject, TileMapObjectKind, TileMapOptions, TileMapViewOptions, TileObject, TileProperties, TilePropertyValue, TileSetOptions, TileTransform, } from '@codexo/exojs-tilemap';
+export { ObjectKind, ObjectLayer, TILE_TRANSFORM_IDENTITY, TileLayer, TileMap, tilemapExtension, TileMapView, TileSet, } from '@codexo/exojs-tilemap';
+import type { LdtkMap } from './LdtkMap';
+declare module '@codexo/exojs' {
+    interface ExtensionTypeMap {
+        /** `.ldtk` path-only loads resolve to {@link LdtkMap}. */
+        ldtk: LdtkMap;
+    }
+    interface AssetDefinitions {
+        ldtkMap: {
+            resource: LdtkMap;
+            config: {
+                source: string;
+            };
+        };
+    }
+}

package/dist/esm/register.d.ts

@@ -0,0 +1 @@
+export * from './public';

package/dist/esm/register.js

@@ -0,0 +1,17 @@
+import { ExtensionRegistry } from '@codexo/exojs/extensions';
+import { ldtkExtension } from './ldtkExtension.js';
+export { ldtkMapBinding } from './ldtkBinding.js';
+export { LdtkMap } from './LdtkMap.js';
+export { ldtkToTileMap } from './ldtkToTileMap.js';
+export { ldtkFlipNone, ldtkFlipX, ldtkFlipXy, ldtkFlipY } from './LdtkData.js';
+export { ObjectKind, ObjectLayer, TILE_TRANSFORM_IDENTITY, TileLayer, TileMap, TileMapView, TileSet, tilemapExtension } from '@codexo/exojs-tilemap';
+
+// @codexo/exojs-ldtk/register — explicit registration entry.
+// Importing this entry registers the default ldtkExtension descriptor
+// in the global ExtensionRegistry. Subsequently constructed Applications
+// that use global defaults will receive the LDtk extension.
+// This is the only side-effectful entry in this package.
+ExtensionRegistry.register(ldtkExtension);
+
+export { ldtkExtension };
+//# sourceMappingURL=register.js.map

package/dist/esm/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sources":["../../../src/register.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;;AAAA;AACA;AACA;AACA;AACA;AAMA,iBAAiB,CAAC,QAAQ,CAAC,aAAa,CAAC;;;;"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@codexo/exojs-ldtk",
+  "version": "0.14.0",
+  "description": "LDtk level format asset extension for ExoJS.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Exoridus/ExoJS.git",
+    "directory": "packages/exojs-ldtk"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/esm/register.js"
+  ],
+  "main": "./dist/esm/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./register": {
+      "types": "./dist/esm/register.d.ts",
+      "import": "./dist/esm/register.js",
+      "default": "./dist/esm/register.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/esm/",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@codexo/exojs": "0.14.x"
+  },
+  "dependencies": {
+    "@codexo/exojs-tilemap": "0.14.0"
+  },
+  "devDependencies": {
+    "@codexo/exojs": "0.14.0",
+    "@codexo/exojs-config": "0.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx ../../node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:production",
+    "build:dev": "tsx ../../node_modules/rollup/dist/bin/rollup -c --environment EXOJS_ENV:development",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "test": "vitest run --root ../.. --project=exojs-ldtk"
+  }
+}