@codexo/exojs-ldtk 0.15.3 → 0.16.0

package/dist/esm/ldtkToMapWorld.js

@@ -0,0 +1,76 @@
+import { getLdtkLevelEntries } from "./ldtkLevelEntries.js";
+import { buildLdtkLevelProperties } from "./ldtkToTileMap.js";
+import { MapLevelSide, MapWorld } from "@codexo/exojs-tilemap";
+
+//#region src/ldtkToMapWorld.ts
+/**
+* LDtk direction codes, as emitted in `__neighbours[].dir`. The cardinal four
+* have always existed; the depth relations arrived with LDtk 1.x.
+*/
+const SIDE_BY_DIR = Object.freeze({
+	n: MapLevelSide.North,
+	s: MapLevelSide.South,
+	e: MapLevelSide.East,
+	w: MapLevelSide.West,
+	o: MapLevelSide.Overlap,
+	"<": MapLevelSide.Below,
+	">": MapLevelSide.Above
+});
+const convertNeighbours = (level) => {
+	const raw = level.__neighbours;
+	if (raw === void 0 || raw === null || raw.length === 0) return [];
+	return raw.map((neighbour) => ({
+		id: neighbour.levelIid,
+		side: SIDE_BY_DIR[neighbour.dir] ?? MapLevelSide.Unknown
+	}));
+};
+const convertLevel = (level, worldIid, index) => ({
+	id: level.iid,
+	name: level.identifier,
+	index,
+	bounds: {
+		x: level.worldX,
+		y: level.worldY,
+		width: level.pxWid,
+		height: level.pxHei
+	},
+	external: Boolean(level.externalRelPath),
+	neighbours: convertNeighbours(level),
+	properties: buildLdtkLevelProperties(level, worldIid)
+});
+/**
+* Build the format-neutral world model for an LDtk document: one
+* {@link MapWorld} per LDtk world, in document order.
+*
+* A single-world project - the overwhelmingly common shape - yields exactly one
+* unnamed world. A multi-world project yields one per entry of `worlds[]`, each
+* named by its identifier, and they stay separate on purpose: LDtk worlds have independent coordinate spaces, so merging them
+* would make {@link MapWorld.bounds} and {@link MapWorld.getLevelsInBounds}
+* report overlaps that do not exist.
+*
+* {@link MapLevel.index} counts across the whole document, matching the
+* flattened order {@link import('./LdtkMap').LdtkMap.levels} uses.
+*
+* Level metadata only: no layer payload is read, so this is safe to call on a
+* document whose external levels have not been fetched.
+*/
+const ldtkToMapWorld = (data) => {
+	const entries = getLdtkLevelEntries(data);
+	if (data.worlds && data.worlds.length > 0) {
+		const worlds = [];
+		let index = 0;
+		for (const world of data.worlds) {
+			const levels = world.levels.map((level) => convertLevel(level, world.iid, index++));
+			worlds.push(new MapWorld({
+				name: world.identifier,
+				levels
+			}));
+		}
+		return Object.freeze(worlds);
+	}
+	return Object.freeze([new MapWorld({ levels: entries.map((entry, index) => convertLevel(entry.level, entry.worldIid, index)) })]);
+};
+
+//#endregion
+export { ldtkToMapWorld };
+//# sourceMappingURL=ldtkToMapWorld.js.map

package/dist/esm/ldtkToMapWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ldtkToMapWorld.js","names":[],"sources":["../../src/ldtkToMapWorld.ts"],"sourcesContent":["import type { MapLevel, MapLevelNeighbour } from '@codexo/exojs-tilemap';\nimport { MapLevelSide, MapWorld } from '@codexo/exojs-tilemap';\n\nimport type { LdtkData, LdtkLevel } from './LdtkData';\nimport { getLdtkLevelEntries } from './ldtkLevelEntries';\nimport { buildLdtkLevelProperties } from './ldtkToTileMap';\n\n/**\n * LDtk direction codes, as emitted in `__neighbours[].dir`. The cardinal four\n * have always existed; the depth relations arrived with LDtk 1.x.\n */\nconst SIDE_BY_DIR: Readonly<Record<string, MapLevelSide>> = Object.freeze({\n  n: MapLevelSide.North,\n  s: MapLevelSide.South,\n  e: MapLevelSide.East,\n  w: MapLevelSide.West,\n  o: MapLevelSide.Overlap,\n  '<': MapLevelSide.Below,\n  '>': MapLevelSide.Above,\n});\n\nconst convertNeighbours = (level: LdtkLevel): readonly MapLevelNeighbour[] => {\n  const raw = level.__neighbours;\n  if (raw === undefined || raw === null || raw.length === 0) return [];\n\n  return raw.map(neighbour => ({\n    id: neighbour.levelIid,\n    // An unrecognised code still means the levels are adjacent, so the edge is\n    // kept and only its side degrades - dropping it would lose real data if a\n    // future LDtk adds a direction.\n    side: SIDE_BY_DIR[neighbour.dir] ?? MapLevelSide.Unknown,\n  }));\n};\n\nconst convertLevel = (level: LdtkLevel, worldIid: string | undefined, index: number): MapLevel => ({\n  id: level.iid,\n  name: level.identifier,\n  index,\n  bounds: { x: level.worldX, y: level.worldY, width: level.pxWid, height: level.pxHei },\n  external: Boolean(level.externalRelPath),\n  neighbours: convertNeighbours(level),\n  properties: buildLdtkLevelProperties(level, worldIid),\n});\n\n/**\n * Build the format-neutral world model for an LDtk document: one\n * {@link MapWorld} per LDtk world, in document order.\n *\n * A single-world project - the overwhelmingly common shape - yields exactly one\n * unnamed world. A multi-world project yields one per entry of `worlds[]`, each\n * named by its identifier, and they stay separate on purpose: LDtk worlds have independent coordinate spaces, so merging them\n * would make {@link MapWorld.bounds} and {@link MapWorld.getLevelsInBounds}\n * report overlaps that do not exist.\n *\n * {@link MapLevel.index} counts across the whole document, matching the\n * flattened order {@link import('./LdtkMap').LdtkMap.levels} uses.\n *\n * Level metadata only: no layer payload is read, so this is safe to call on a\n * document whose external levels have not been fetched.\n */\nexport const ldtkToMapWorld = (data: LdtkData): readonly MapWorld[] => {\n  const entries = getLdtkLevelEntries(data);\n\n  if (data.worlds && data.worlds.length > 0) {\n    const worlds: MapWorld[] = [];\n    let index = 0;\n\n    for (const world of data.worlds) {\n      const levels = world.levels.map(level => convertLevel(level, world.iid, index++));\n      worlds.push(new MapWorld({ name: world.identifier, levels }));\n    }\n\n    return Object.freeze(worlds);\n  }\n\n  return Object.freeze([new MapWorld({ levels: entries.map((entry, index) => convertLevel(entry.level, entry.worldIid, index)) })]);\n};\n"],"mappings":";;;;;;;;;AAWA,MAAM,cAAsD,OAAO,OAAO;CACxE,GAAG,aAAa;CAChB,GAAG,aAAa;CAChB,GAAG,aAAa;CAChB,GAAG,aAAa;CAChB,GAAG,aAAa;CAChB,KAAK,aAAa;CAClB,KAAK,aAAa;AACpB,CAAC;AAED,MAAM,qBAAqB,UAAmD;CAC5E,MAAM,MAAM,MAAM;CAClB,IAAI,QAAQ,UAAa,QAAQ,QAAQ,IAAI,WAAW,GAAG,OAAO,CAAC;CAEnE,OAAO,IAAI,KAAI,eAAc;EAC3B,IAAI,UAAU;EAId,MAAM,YAAY,UAAU,QAAQ,aAAa;CACnD,EAAE;AACJ;AAEA,MAAM,gBAAgB,OAAkB,UAA8B,WAA6B;CACjG,IAAI,MAAM;CACV,MAAM,MAAM;CACZ;CACA,QAAQ;EAAE,GAAG,MAAM;EAAQ,GAAG,MAAM;EAAQ,OAAO,MAAM;EAAO,QAAQ,MAAM;CAAM;CACpF,UAAU,QAAQ,MAAM,eAAe;CACvC,YAAY,kBAAkB,KAAK;CACnC,YAAY,yBAAyB,OAAO,QAAQ;AACtD;;;;;;;;;;;;;;;;;AAkBA,MAAa,kBAAkB,SAAwC;CACrE,MAAM,UAAU,oBAAoB,IAAI;CAExC,IAAI,KAAK,UAAU,KAAK,OAAO,SAAS,GAAG;EACzC,MAAM,SAAqB,CAAC;EAC5B,IAAI,QAAQ;EAEZ,KAAK,MAAM,SAAS,KAAK,QAAQ;GAC/B,MAAM,SAAS,MAAM,OAAO,KAAI,UAAS,aAAa,OAAO,MAAM,KAAK,OAAO,CAAC;GAChF,OAAO,KAAK,IAAI,SAAS;IAAE,MAAM,MAAM;IAAY;GAAO,CAAC,CAAC;EAC9D;EAEA,OAAO,OAAO,OAAO,MAAM;CAC7B;CAEA,OAAO,OAAO,OAAO,CAAC,IAAI,SAAS,EAAE,QAAQ,QAAQ,KAAK,OAAO,UAAU,aAAa,MAAM,OAAO,MAAM,UAAU,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;AAClI"}

package/dist/esm/ldtkToTileMap.d.ts

@@ -1,6 +1,6 @@
-import type { TileSet } from '@codexo/exojs-tilemap';
-import { TILE_TRANSFORM_IDENTITY, TileLayer } from '@codexo/exojs-tilemap';
-import type { LdtkData, LdtkIntGridValueDef } from './LdtkData';
+import type { TileCellSource, TileProperties, TileSet } from '@codexo/exojs-tilemap';
+import { TILE_TRANSFORM_IDENTITY, TileLayer, TileMap } from '@codexo/exojs-tilemap';
+import type { LdtkData, LdtkIntGridValueDef, LdtkLevel } from './LdtkData';
 import { LdtkMap } from './LdtkMap';
 /**
  * Options for {@link ldtkToTileMap}.
@@ -16,7 +16,7 @@ export interface LdtkToTileMapOptions {
      *
      * 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
+     * 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
@@ -29,7 +29,7 @@ export interface LdtkToTileMapOptions {
  * 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
+ * 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.
  *
@@ -37,11 +37,28 @@ export interface LdtkToTileMapOptions {
  * conversion (useful in unit tests that do not need textures).
  *
  * Transparently handles both LDtk root shapes via {@link getLdtkLevelEntries}:
- * single-world (`data.levels`) and multi-world (`data.worlds[].levels`) — in
+ * single-world (`data.levels`) and multi-world (`data.worlds[].levels`) - in
  * the latter case every converted level's `TileMap.properties` is additionally
  * tagged with its owning world's iid under the reserved `ldtkWorldIid` key.
  */
-export declare function ldtkToTileMap(data: LdtkData, options?: LdtkToTileMapOptions): LdtkMap;
+export declare const ldtkToTileMap: (data: LdtkData, options?: LdtkToTileMapOptions) => LdtkMap;
+/**
+ * Convert one already-resolved LDtk level into its runtime {@link TileMap}.
+ *
+ * `level.layerInstances` must be present: an externalized level has to have its
+ * `.ldtkl` payload merged in first, or the result is an empty map.
+ * @internal
+ */
+export declare const ldtkLevelToTileMap: (level: LdtkLevel, worldIid: string | undefined, levelIndex: number, data: LdtkData, tilesets: ReadonlyMap<number, TileSet>) => TileMap;
+/**
+ * The property bag a level contributes to its runtime representation - user
+ * fields first, then the reserved LDtk keys, so a same-named user field can
+ * never clobber them. `ldtkWorldIid` is added only for multi-world documents;
+ * a single-world document's properties stay exactly as they were before
+ * multi-world support existed.
+ * @internal
+ */
+export declare const buildLdtkLevelProperties: (level: LdtkLevel, worldIid: string | undefined) => TileProperties;
 /**
  * Reserved {@link TileLayer.properties} key holding the JSON-encoded raw
  * IntGrid CSV array (`readonly number[]`) for a `TileLayer` converted from an
@@ -52,7 +69,7 @@ export declare const ldtkIntGridCsvProperty = "ldtkIntGridCsv";
 /**
  * Reserved {@link TileLayer.properties} key holding the JSON-encoded
  * {@link LdtkIntGridValueDef} array for a `TileLayer` converted from an LDtk
- * `IntGrid` layer instance — the raw-int → named/coloured mapping declared on
+ * `IntGrid` layer instance - the raw-int → named/coloured mapping declared on
  * the owning layer definition (`data.defs.layers[].intGridValues`).
  * Prefer {@link getLdtkIntGridValueAt} over reading this directly.
  */
@@ -67,8 +84,29 @@ export declare const ldtkIntGridValuesProperty = "ldtkIntGridValues";
  * via {@link ldtkIntGridCsvProperty} / {@link ldtkIntGridValuesProperty}).
  *
  * The underlying JSON-encoded CSV/value-defs properties are parsed once per
- * layer and cached (see {@link getParsedIntGridData}) — safe to call from a
+ * layer and cached (see {@link getParsedIntGridData}) - safe to call from a
  * hot path (e.g. per-cell or per-frame collision/classification checks).
  */
-export declare function getLdtkIntGridValueAt(layer: TileLayer, x: number, y: number): LdtkIntGridValueDef | undefined;
+export declare const getLdtkIntGridValueAt: (layer: TileLayer, x: number, y: number) => LdtkIntGridValueDef | undefined;
+/**
+ * Per-cell collision classification for a `TileLayer` converted from an LDtk
+ * `IntGrid` layer instance, or `undefined` when the layer carries no IntGrid
+ * data (not converted from an IntGrid layer instance, or unbounded).
+ *
+ * The classification is the value's LDtk-authored identifier, falling back to
+ * the raw integer as a string when the value definition declares none. Cells
+ * whose raw value is `0` (empty) classify as `null`. Distinct IntGrid values
+ * stay distinct strings: what they mean - solid, water, hazard - is the
+ * caller's to decide, and an unrecognised value is data, not an error.
+ *
+ * The result reads the layer's frozen IntGrid data, so it is stable for the
+ * lifetime of the layer and safe to hand to a consumer that samples it while
+ * building geometry.
+ *
+ * ```ts
+ * const geometry = buildTileCollisionGeometry(layer, { cells: createLdtkIntGridCellSource(layer) });
+ * ```
+ */
+export declare const createLdtkIntGridCellSource: (layer: TileLayer) => TileCellSource | undefined;
 export { TILE_TRANSFORM_IDENTITY };
+//# sourceMappingURL=ldtkToTileMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ldtkToTileMap.d.ts","sourceRoot":"","sources":["../../src/ldtkToTileMap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAiB,cAAc,EAAqB,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACvH,OAAO,EAAe,uBAAuB,EAAE,SAAS,EAAE,OAAO,EAAoB,MAAM,uBAAuB,CAAC;AAEnH,OAAO,KAAK,EAAE,QAAQ,EAAyC,mBAAmB,EAAqB,SAAS,EAAgB,MAAM,YAAY,CAAC;AAGnJ,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,QAAQ,EAAE,UAAU,oBAAoB,KAAG,OAO9E,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,SAAS,EAChB,UAAU,MAAM,GAAG,SAAS,EAC5B,YAAY,MAAM,EAClB,MAAM,QAAQ,EACd,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,KACrC,OAAoE,CAAC;AAoDxE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,SAAS,EAAE,UAAU,MAAM,GAAG,SAAS,KAAG,cAOxF,CAAC;AAuHH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAiE7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,SAAS,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,mBAAmB,GAAG,SAepG,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,SAAS,KAAG,cAAc,GAAG,SAuB/E,CAAC;AA8KF,OAAO,EAAE,uBAAuB,EAAE,CAAC"}