@codexo/exojs-tiled 0.12.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/README.md

@@ -0,0 +1,130 @@
+# @codexo/exojs-tiled
+
+Official ExoJS extension for loading [Tiled](https://mapeditor.org) maps (`.tmj` JSON format).
+
+## Installation
+
+```sh
+npm install @codexo/exojs @codexo/exojs-tiled
+```
+
+This package requires `@codexo/exojs` as a peer dependency. Both must be the same version.
+
+## Core compatibility
+
+| `@codexo/exojs-tiled` | `@codexo/exojs` |
+|---|---|
+| 0.12.x | 0.12.x |
+
+## Supported Tiled scope
+
+- Tiled JSON map format (`.tmj`)
+- Orthogonal tile layers
+- Object layers (basic)
+- External tilesets (`.tsj`) referenced from `.tmj`
+- Multiple tile layers per map
+
+## Not supported in 0.12.x
+
+- TMX (XML) format — use `.tmj` export from Tiled
+- Isometric and hexagonal maps
+- Image layers
+- Wangsets
+- Custom class / enum properties
+
+## Usage — side-effect-free root entry
+
+```ts
+import { Application } from '@codexo/exojs';
+import { TiledMap, tiledExtension } from '@codexo/exojs-tiled';
+
+const app = new Application({
+    extensions: [tiledExtension],
+});
+```
+
+Importing from the root entry does **not** register the extension globally.
+
+## Extension descriptor
+
+`tiledExtension` is the default descriptor. It registers the `TiledMap` asset type with the following bindings:
+
+- Constructor load: `loader.load(TiledMap, url)`
+- Extension routing: `.tmj` files auto-route to `TiledMap`
+- Type-name load: `loader.load('tiledMap', url)`
+
+## Loading a Tiled map
+
+```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);
+}
+```
+
+## `/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.
+
+```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';
+```
+
+**Note:** `/register` does not use automatic discovery. It explicitly calls `ExtensionRegistry.register(tiledExtension)` at module evaluation time.
+
+## Texture and sub-asset ownership
+
+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.
+
+## Minimal working example
+
+```ts
+import { Application, Scene } from '@codexo/exojs';
+import { TiledMap, tiledExtension } from '@codexo/exojs-tiled';
+
+const app = new Application({ extensions: [tiledExtension] });
+document.body.append(app.canvas);
+
+class GameScene extends Scene {
+    map!: TiledMap;
+
+    override async load(loader) {
+        await loader.load(TiledMap, { level1: '/maps/level1.tmj' });
+    }
+
+    override create(loader) {
+        this.map = loader.get(TiledMap, 'level1');
+        this.addChild(this.map);
+    }
+}
+
+app.scenes.start(GameScene);
+```
+
+## 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)
+
+## License
+
+MIT

package/dist/esm/TiledMap.d.ts

@@ -0,0 +1,88 @@
+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;
+}
+/**
+ * Runtime representation of a loaded Tiled map.
+ *
+ * Exposes map metadata, layers, and tileset textures. Tileset textures
+ * are owned by the Loader cache — `TiledMap.destroy()` does NOT destroy them.
+ *
+ * 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.
+ */
+export declare class TiledMap {
+    readonly data: TiledMapData;
+    readonly tilesetTextures: readonly Texture[];
+    readonly width: number;
+    readonly height: number;
+    readonly tileWidth: number;
+    readonly tileHeight: number;
+    readonly layers: readonly TiledLayer[];
+    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[];
+    /**
+     * Destroy this TiledMap. Does NOT destroy tileset textures — they are
+     * owned by the Loader's cache and may be shared with other callers.
+     */
+    destroy(): void;
+}

package/dist/esm/TiledMap.js

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// TiledMap runtime object
+// ---------------------------------------------------------------------------
+/**
+ * Runtime representation of a loaded Tiled map.
+ *
+ * Exposes map metadata, layers, and tileset textures. Tileset textures
+ * are owned by the Loader cache — `TiledMap.destroy()` does NOT destroy them.
+ *
+ * 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.
+ */
+class TiledMap {
+    data;
+    tilesetTextures;
+    width;
+    height;
+    tileWidth;
+    tileHeight;
+    layers;
+    tilesets;
+    constructor(data, tilesetTextures) {
+        this.data = data;
+        this.tilesetTextures = tilesetTextures;
+        this.width = data.width;
+        this.height = data.height;
+        this.tileWidth = data.tilewidth;
+        this.tileHeight = data.tileheight;
+        this.layers = data.layers;
+        this.tilesets = data.tilesets;
+    }
+    /** Tile layers only. */
+    get tileLayers() {
+        return this.layers.filter(l => l.type === 'tilelayer');
+    }
+    /** Object group layers only. */
+    get objectLayers() {
+        return this.layers.filter(l => l.type === 'objectgroup');
+    }
+    /**
+     * Destroy this TiledMap. Does NOT destroy tileset textures — they are
+     * owned by the Loader's cache and may be shared with other callers.
+     */
+    destroy() {
+        // Intentionally empty: tileset textures are Loader-owned.
+    }
+}
+
+export { TiledMap };
+//# sourceMappingURL=TiledMap.js.map

package/dist/esm/TiledMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TiledMap.js","sources":["../../../src/TiledMap.ts"],"sourcesContent":[null],"names":[],"mappings":"AAoEA;AACA;AACA;AAEA;;;;;;;;;AASG;MACU,QAAQ,CAAA;AACH,IAAA,IAAI;AACJ,IAAA,eAAe;AAEf,IAAA,KAAK;AACL,IAAA,MAAM;AACN,IAAA,SAAS;AACT,IAAA,UAAU;AAEV,IAAA,MAAM;AACN,IAAA,QAAQ;IAExB,WAAA,CAAmB,IAAkB,EAAE,eAAmC,EAAA;AACxE,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;AAChB,QAAA,IAAI,CAAC,eAAe,GAAG,eAAe;AACtC,QAAA,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;AACvB,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;AACzB,QAAA,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS;AAC/B,QAAA,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU;AACjC,QAAA,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM;AACzB,QAAA,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ;IAC/B;;AAGA,IAAA,IAAW,UAAU,GAAA;AACnB,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC;IACxD;;AAGA,IAAA,IAAW,YAAY,GAAA;AACrB,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC;IAC1D;AAEA;;;AAGG;IACI,OAAO,GAAA;;IAEd;AACD;;;;"}

package/dist/esm/index.d.ts

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

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { tiledExtension } from './tiledExtension.js';
+export { tiledBuildInfo } from './tiledBuildInfo.js';
+export { TiledMap } from './TiledMap.js';
+//# 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/public.d.ts

@@ -0,0 +1,6 @@
+export type { Extension, AssetBinding, AssetHandler, AssetLoadRequest } from '@codexo/exojs/extensions';
+export { tiledExtension } from './tiledExtension';
+export type { TiledBuildInfo } from './tiledBuildInfo';
+export { tiledBuildInfo } from './tiledBuildInfo';
+export { TiledMap } from './TiledMap';
+export type { TiledLayer, TiledMapData, TiledObject, TiledProperty, TiledTileset } from './TiledMap';

package/dist/esm/register.d.ts

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

package/dist/esm/register.js

@@ -0,0 +1,14 @@
+import { ExtensionRegistry } from '@codexo/exojs/extensions';
+import { tiledExtension } from './tiledExtension.js';
+export { tiledBuildInfo } from './tiledBuildInfo.js';
+export { TiledMap } from './TiledMap.js';
+
+// @codexo/exojs-tiled/register — explicit registration entry.
+// Importing this entry registers the default tiledExtension descriptor
+// in the global ExtensionRegistry. Subsequently constructed Applications
+// that use global defaults will receive the Tiled extension.
+// This is the only side-effectful entry in this package.
+ExtensionRegistry.register(tiledExtension);
+
+export { tiledExtension };
+//# 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,cAAc,CAAC;;;;"}

package/dist/esm/tiledBuildInfo.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Immutable compile-time build metadata for `@codexo/exojs-tiled`.
+ *
+ * `development` mirrors the `__DEV__` compile-time constant and is statically
+ * replaced before tree shaking. `version` is the exact `package.json` version
+ * of the Tiled package at build time. `revision` is the short
+ * source-control revision (appended with `-dirty` when uncommitted changes are
+ * present) or `"unknown"` when no revision information is available.
+ */
+export interface TiledBuildInfo {
+    readonly version: string;
+    readonly revision: string;
+    readonly development: boolean;
+}
+export declare const tiledBuildInfo: TiledBuildInfo;

package/dist/esm/tiledBuildInfo.js

@@ -0,0 +1,8 @@
+const tiledBuildInfo = Object.freeze({
+    version: "0.12.0",
+    revision: "599bc56",
+    development: false,
+});
+
+export { tiledBuildInfo };
+//# sourceMappingURL=tiledBuildInfo.js.map

package/dist/esm/tiledBuildInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiledBuildInfo.js","sources":["../../../src/tiledBuildInfo.ts"],"sourcesContent":[null],"names":[],"mappings":"AAeO,MAAM,cAAc,GAAmB,MAAM,CAAC,MAAM,CAAC;AAC1D,IAAA,OAAO,EAAE,QAAW;AACpB,IAAA,QAAQ,EAAE,SAAY;AACtB,IAAA,WAAW,EAAE,KAAO;AACrB,CAAA;;;;"}

package/dist/esm/tiledExtension.d.ts

@@ -0,0 +1,7 @@
+import type { Extension } from '@codexo/exojs/extensions';
+/**
+ * Default immutable Tiled extension descriptor.
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-tiled/register'` for global auto-registration.
+ */
+export declare const tiledExtension: Extension;

package/dist/esm/tiledExtension.js

@@ -0,0 +1,60 @@
+import { Texture } from '@codexo/exojs';
+import { TiledMap } from './TiledMap.js';
+
+/**
+ * Resolve a tileset image reference relative to the map's source path.
+ * `new URL(ref, source)` only works when `source` is an absolute URL; the
+ * loader is frequently called with relative paths, so fall back to a synthetic
+ * base and strip it.
+ */
+function resolveRelative(ref, source) {
+    try {
+        return new URL(ref, source).href;
+    }
+    catch {
+        const base = 'https://exojs.invalid/';
+        return new URL(ref, base + source.replace(/^\/+/, '')).href.slice(base.length);
+    }
+}
+const tiledBinding = {
+    type: TiledMap,
+    typeNames: ['tiledMap'],
+    extensions: ['tmj'],
+    create(loader) {
+        return {
+            async load({ source }, context) {
+                const data = await context.fetchJson(source);
+                if (!data || typeof data !== 'object' || !Array.isArray(data.tilesets)) {
+                    throw new Error(`TiledMap: invalid or unsupported map file at "${source}".`);
+                }
+                if (data.infinite === true) {
+                    throw new Error(`TiledMap: infinite maps are not supported (at "${source}").`);
+                }
+                if (data.orientation !== undefined && data.orientation !== 'orthogonal') {
+                    throw new Error(`TiledMap: only orthogonal orientation is supported (got "${data.orientation}" at "${source}").`);
+                }
+                // Load tileset textures. Sub-assets are owned by the Loader cache —
+                // TiledMap must NOT destroy them.
+                const tilesetTextures = (await Promise.all(data.tilesets
+                    .filter(ts => ts.image !== undefined)
+                    .map(ts => loader.load(Texture, resolveRelative(ts.image, source)))));
+                return new TiledMap(data, tilesetTextures);
+            },
+            destroy() {
+                // This handler holds no loader-local resources.
+            },
+        };
+    },
+};
+/**
+ * Default immutable Tiled extension descriptor.
+ * Use with `ApplicationOptions.extensions` or call
+ * `import '@codexo/exojs-tiled/register'` for global auto-registration.
+ */
+const tiledExtension = Object.freeze({
+    id: '@codexo/exojs-tiled',
+    assets: [tiledBinding],
+});
+
+export { tiledExtension };
+//# sourceMappingURL=tiledExtension.js.map

package/dist/esm/tiledExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiledExtension.js","sources":["../../../src/tiledExtension.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAMA;;;;;AAKG;AACH,SAAS,eAAe,CAAC,GAAW,EAAE,MAAc,EAAA;AAClD,IAAA,IAAI;QACF,OAAO,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,IAAI;IAClC;AAAE,IAAA,MAAM;QACN,MAAM,IAAI,GAAG,wBAAwB;QACrC,OAAO,IAAI,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;IAChF;AACF;AAEA,MAAM,YAAY,GAA2B;AAC3C,IAAA,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,CAAC,UAAU,CAAC;IACvB,UAAU,EAAE,CAAC,KAAK,CAAC;AACnB,IAAA,MAAM,CAAC,MAAc,EAAA;QACnB,OAAO;AACL,YAAA,MAAM,IAAI,CAAC,EAAE,MAAM,EAAoB,EAAE,OAA2B,EAAA;gBAClE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,SAAS,CAAe,MAAM,CAAC;AAE1D,gBAAA,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE;AACtE,oBAAA,MAAM,IAAI,KAAK,CAAC,iDAAiD,MAAM,CAAA,EAAA,CAAI,CAAC;gBAC9E;AAEA,gBAAA,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,EAAE;AAC1B,oBAAA,MAAM,IAAI,KAAK,CAAC,kDAAkD,MAAM,CAAA,GAAA,CAAK,CAAC;gBAChF;AAEA,gBAAA,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,KAAK,YAAY,EAAE;oBACvE,MAAM,IAAI,KAAK,CAAC,CAAA,yDAAA,EAA4D,IAAI,CAAC,WAAW,CAAA,MAAA,EAAS,MAAM,CAAA,GAAA,CAAK,CAAC;gBACnH;;;gBAIA,MAAM,eAAe,IAAI,MAAM,OAAO,CAAC,GAAG,CACxC,IAAI,CAAC;qBACF,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,KAAK,SAAS;qBACnC,GAAG,CAAC,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,CAAC,KAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CACvE,CAAc;AAEf,gBAAA,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;YAC5C,CAAC;YACD,OAAO,GAAA;;YAEP,CAAC;SACF;IACH,CAAC;CACF;AAED;;;;AAIG;AACI,MAAM,cAAc,GAAc,MAAM,CAAC,MAAM,CAAC;AACrD,IAAA,EAAE,EAAE,qBAAqB;IACzB,MAAM,EAAE,CAAC,YAAY,CAAC;AACvB,CAAA;;;;"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@codexo/exojs-tiled",
+  "version": "0.12.0",
+  "description": "Tiled map format asset extension for ExoJS.",
+  "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.12.x"
+  },
+  "devDependencies": {
+    "@codexo/exojs": "0.12.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-tiled"
+  }
+}