@codexo/exojs-ldtk 0.15.3 → 0.16.0

package/dist/esm/ldtkToTileMap.js

@@ -1,400 +1,423 @@
-import { ObjectLayer, TileMap, TileLayer, TilePropertyKind } from '@codexo/exojs-tilemap';
-export { TILE_TRANSFORM_IDENTITY } from '@codexo/exojs-tilemap';
-import { ldtkFlipY, ldtkFlipX } from './LdtkData.js';
-import { getLdtkLevelEntries } from './ldtkLevelEntries.js';
-import { LdtkMap } from './LdtkMap.js';
+import { getLdtkLevelEntries } from "./ldtkLevelEntries.js";
+import { LDTK_FLIP_X, LDTK_FLIP_Y } from "./LdtkData.js";
+import { resolveLdtkLayerParallax } from "./ldtkParallax.js";
+import { LdtkMap } from "./LdtkMap.js";
+import { ObjectLayer, TileLayer, TileMap, TilePropertyKind } from "@codexo/exojs-tilemap";
 
+//#region src/ldtkToTileMap.ts
 /**
- * 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).
- *
- * Transparently handles both LDtk root shapes via {@link getLdtkLevelEntries}:
- * 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.
- */
-function ldtkToTileMap(data, options) {
-    const source = options?.source ?? '';
-    const tilesets = options?.tilesets ?? new Map();
-    const levels = getLdtkLevelEntries(data).map((entry, levelIndex) => convertLevel(entry.level, entry.worldIid, levelIndex, data, tilesets));
-    return new LdtkMap(source, data, levels);
-}
-// ── Level conversion ──────────────────────────────────────────────────────────
-// eslint-disable-next-line complexity
-function convertLevel(level, worldIid, 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 intGridProperties = buildIntGridProperties(layerInst, data);
-                const rLayer = makeTileLayer(layerInst, layerId, runtimeTilesets, intGridProperties);
-                // IntGrid layers may carry auto-tiles when "Auto-layer" rules are
-                // configured. Use those for rendering; raw intGridCsv is exposed as
-                // data-only layer properties (see buildIntGridProperties).
-                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,
-        // Convert user-defined level fields first, then apply the reserved keys
-        // last so a same-named user field can never clobber them. ldtkWorldIid is
-        // only added for multi-world documents (worldIid !== undefined) — a
-        // single-world document's properties must stay exactly as they were
-        // before multi-world support existed.
-        properties: {
-            ...convertFieldInstances(level.fieldInstances ?? []),
-            ldtkUid: level.uid,
-            ldtkIid: level.iid,
-            worldX: level.worldX,
-            worldY: level.worldY,
-            ...(worldIid !== undefined && { ldtkWorldIid: worldIid }),
-        },
-    });
-}
-// ── Helpers: TileLayer ────────────────────────────────────────────────────────
-function makeTileLayer(layerInst, layerId, tilesets, properties) {
-    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,
-        ...(properties && { properties }),
-    });
-}
-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: IntGrid ──────────────────────────────────────────────────────────
+* 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).
+*
+* Transparently handles both LDtk root shapes via {@link getLdtkLevelEntries}:
+* 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.
+*/
+const ldtkToTileMap = (data, options) => {
+	const source = options?.source ?? "";
+	const tilesets = options?.tilesets ?? /* @__PURE__ */ new Map();
+	const levels = getLdtkLevelEntries(data).map((entry, levelIndex) => convertLevel(entry.level, entry.worldIid, levelIndex, data, tilesets));
+	return new LdtkMap(source, data, levels);
+};
 /**
- * Reserved {@link TileLayer.properties} key holding the JSON-encoded raw
- * IntGrid CSV array (`readonly number[]`) for a `TileLayer` converted from an
- * LDtk `IntGrid` layer instance. Index = `y * layer.width + x`; `0` = empty.
- * Prefer {@link getLdtkIntGridValueAt} over reading this directly.
- */
-const ldtkIntGridCsvProperty = 'ldtkIntGridCsv';
+* 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
+*/
+const ldtkLevelToTileMap = (level, worldIid, levelIndex, data, tilesets) => convertLevel(level, worldIid, levelIndex, data, tilesets);
+const convertLevel = (level, worldIid, levelIndex, data, tilesets) => {
+	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 = [];
+	const layerInstances = level.layerInstances ?? [];
+	let entityCounter = 0;
+	for (const layerInst of layerInstances) {
+		const layerId = layerInst.layerDefUid;
+		const parallax = resolveLdtkLayerParallax(data, layerInst);
+		switch (layerInst.__type) {
+			case "Tiles":
+			case "AutoLayer":
+				runtimeLayers.push(convertTilesOrAutoLayer(layerInst, layerId, runtimeTilesets, tilesets, parallax));
+				break;
+			case "IntGrid":
+				runtimeLayers.push(convertIntGridLayer(layerInst, layerId, runtimeTilesets, tilesets, data, parallax));
+				break;
+			case "Entities":
+				runtimeObjectLayers.push(convertEntitiesLayer(layerInst, layerId, levelIndex, entityCounter, parallax));
+				entityCounter += layerInst.entityInstances?.length ?? 0;
+		}
+	}
+	return new TileMap({
+		name: level.identifier,
+		width: mapWidth,
+		height: mapHeight,
+		tileWidth: gridSize,
+		tileHeight: gridSize,
+		tilesets: runtimeTilesets,
+		layers: runtimeLayers,
+		objectLayers: runtimeObjectLayers,
+		properties: buildLdtkLevelProperties(level, worldIid)
+	});
+};
 /**
- * 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
- * the owning layer definition (`data.defs.layers[].intGridValues`).
- * Prefer {@link getLdtkIntGridValueAt} over reading this directly.
- */
-const ldtkIntGridValuesProperty = 'ldtkIntGridValues';
+* 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
+*/
+const buildLdtkLevelProperties = (level, worldIid) => ({
+	...convertFieldInstances(level.fieldInstances ?? []),
+	ldtkUid: level.uid,
+	ldtkIid: level.iid,
+	worldX: level.worldX,
+	worldY: level.worldY,
+	...worldIid !== void 0 && { ldtkWorldIid: worldIid }
+});
+/** Convert a `Tiles`/`AutoLayer` LDtk layer instance into a runtime {@link TileLayer}. */
+const convertTilesOrAutoLayer = (layerInst, layerId, runtimeTilesets, tilesets, parallax) => {
+	const rLayer = makeTileLayer(layerInst, layerId, runtimeTilesets, parallax);
+	const tiles = layerInst.__type === "Tiles" ? layerInst.gridTiles ?? [] : layerInst.autoLayerTiles ?? [];
+	const tsUid = layerInst.__tilesetDefUid;
+	if (tsUid !== void 0 && tsUid !== null) {
+		const rts = tilesets.get(tsUid);
+		if (rts) populateTileLayer(rLayer, tiles, rts, layerInst.__gridSize);
+	}
+	return rLayer;
+};
+/** Convert an `IntGrid` LDtk layer instance into a runtime {@link TileLayer}. */
+const convertIntGridLayer = (layerInst, layerId, runtimeTilesets, tilesets, data, parallax) => {
+	const intGridProperties = buildIntGridProperties(layerInst, data);
+	const rLayer = makeTileLayer(layerInst, layerId, runtimeTilesets, parallax, intGridProperties);
+	const autoTiles = layerInst.autoLayerTiles ?? [];
+	const tsUid = layerInst.__tilesetDefUid;
+	if (autoTiles.length > 0 && tsUid !== void 0 && tsUid !== null) {
+		const rts = tilesets.get(tsUid);
+		if (rts) populateTileLayer(rLayer, autoTiles, rts, layerInst.__gridSize);
+	}
+	return rLayer;
+};
+/** Convert an `Entities` LDtk layer instance into a runtime {@link ObjectLayer}. */
+const convertEntitiesLayer = (layerInst, layerId, levelIndex, entityCounter, parallax) => {
+	const objects = convertEntityLayer(layerInst, layerInst.__gridSize, levelIndex, entityCounter);
+	return new ObjectLayer({
+		id: layerId,
+		name: layerInst.__identifier,
+		visible: layerInst.visible,
+		opacity: layerInst.opacity ?? 1,
+		offsetX: parallax.offsetX + (layerInst.pxOffsetX ?? 0),
+		offsetY: parallax.offsetY + (layerInst.pxOffsetY ?? 0),
+		parallaxX: parallax.parallaxX,
+		parallaxY: parallax.parallaxY,
+		parallaxScale: parallax.parallaxScale,
+		objects
+	});
+};
+const makeTileLayer = (layerInst, layerId, tilesets, parallax, properties) => 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: parallax.offsetX + (layerInst.pxOffsetX ?? 0),
+	offsetY: parallax.offsetY + (layerInst.pxOffsetY ?? 0),
+	parallaxX: parallax.parallaxX,
+	parallaxY: parallax.parallaxY,
+	parallaxScale: parallax.parallaxScale,
+	...properties && { properties }
+});
+const 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 & 1) !== 0,
+				flipY: (f & 2) !== 0,
+				diagonal: false
+			}
+		});
+	}
+};
 /**
- * Build the reserved IntGrid properties for a `TileLayer` from an LDtk
- * `IntGrid` layer instance, or `undefined` when the layer carries no
- * `intGridCsv` data (nothing to expose).
- *
- * {@link TileLayer.properties} values are scalar-only, so the raw CSV array
- * and the value-definition mapping are JSON-encoded into two reserved string
- * properties rather than stored as nested structures — the same
- * `properties`-bag mechanism the Tiled adapter already uses for per-layer
- * metadata, just serialized to fit its scalar-only value type.
- */
-function buildIntGridProperties(layerInst, data) {
-    const csv = layerInst.intGridCsv;
-    if (!csv || csv.length === 0)
-        return undefined;
-    const layerDef = data.defs.layers.find(def => def.uid === layerInst.layerDefUid);
-    const values = layerDef?.intGridValues ?? [];
-    return Object.freeze({
-        [ldtkIntGridCsvProperty]: JSON.stringify(csv),
-        [ldtkIntGridValuesProperty]: JSON.stringify(values),
-    });
-}
+* Reserved {@link TileLayer.properties} key holding the JSON-encoded raw
+* IntGrid CSV array (`readonly number[]`) for a `TileLayer` converted from an
+* LDtk `IntGrid` layer instance. Index = `y * layer.width + x`; `0` = empty.
+* Prefer {@link getLdtkIntGridValueAt} over reading this directly.
+*/
+const ldtkIntGridCsvProperty = "ldtkIntGridCsv";
 /**
- * Per-`TileLayer` cache of parsed IntGrid CSV/value-defs data, populated
- * lazily on first {@link getLdtkIntGridValueAt} lookup for a given layer.
- *
- * Keyed by the `TileLayer` instance itself (`WeakMap`), so an entry is
- * naturally garbage-collected once the layer it was derived from is no
- * longer referenced — no manual invalidation needed since
- * {@link TileLayer.properties} is frozen and copied at construction time and
- * can never change afterwards.
- */
-const intGridCache = new WeakMap();
+* 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
+* the owning layer definition (`data.defs.layers[].intGridValues`).
+* Prefer {@link getLdtkIntGridValueAt} over reading this directly.
+*/
+const ldtkIntGridValuesProperty = "ldtkIntGridValues";
 /**
- * Parse (or retrieve from {@link intGridCache}) the IntGrid CSV/value-defs
- * data attached to `layer`, or `undefined` when `layer` carries no such data
- * (not converted from an IntGrid layer instance).
- */
-function getParsedIntGridData(layer) {
-    const cached = intGridCache.get(layer);
-    if (cached)
-        return cached;
-    const csvRaw = layer.properties[ldtkIntGridCsvProperty];
-    const valuesRaw = layer.properties[ldtkIntGridValuesProperty];
-    if (typeof csvRaw !== 'string' || typeof valuesRaw !== 'string')
-        return undefined;
-    const parsed = {
-        csv: JSON.parse(csvRaw),
-        values: JSON.parse(valuesRaw),
-    };
-    intGridCache.set(layer, parsed);
-    return parsed;
-}
+* Build the reserved IntGrid properties for a `TileLayer` from an LDtk
+* `IntGrid` layer instance, or `undefined` when the layer carries no
+* `intGridCsv` data (nothing to expose).
+*
+* {@link TileLayer.properties} values are scalar-only, so the raw CSV array
+* and the value-definition mapping are JSON-encoded into two reserved string
+* properties rather than stored as nested structures - the same
+* `properties`-bag mechanism the Tiled adapter already uses for per-layer
+* metadata, just serialized to fit its scalar-only value type.
+*/
+const buildIntGridProperties = (layerInst, data) => {
+	const csv = layerInst.intGridCsv;
+	if (!csv || csv.length === 0) return void 0;
+	const values = data.defs.layers.find((def) => def.uid === layerInst.layerDefUid)?.intGridValues ?? [];
+	return Object.freeze({
+		[ldtkIntGridCsvProperty]: JSON.stringify(csv),
+		[ldtkIntGridValuesProperty]: JSON.stringify(values)
+	});
+};
 /**
- * Look up the named/coloured {@link LdtkIntGridValueDef} at a tile coordinate
- * on a `TileLayer` converted from an LDtk `IntGrid` layer instance.
- *
- * Returns `undefined` when the coordinate is out of bounds, the cell's raw
- * value is `0` (empty), the raw value has no matching definition, or `layer`
- * was not converted from an IntGrid layer instance (no IntGrid data attached
- * 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
- * hot path (e.g. per-cell or per-frame collision/classification checks).
- */
-function getLdtkIntGridValueAt(layer, x, y) {
-    if (!layer.inBounds(x, y))
-        return undefined;
-    const parsed = getParsedIntGridData(layer);
-    if (!parsed)
-        return undefined;
-    const raw = parsed.csv[y * layer.width + x];
-    if (raw === undefined || raw === 0)
-        return undefined;
-    return parsed.values.find(v => v.value === raw);
-}
-// ── 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) {
-    // entity.px is the pivot-adjusted anchor, not the bounding box's top-left
-    // corner — undo the pivot offset to recover the corner TileMapObject expects.
-    const x = entity.px[0] - entity.width * entity.__pivot[0];
-    const y = entity.px[1] - entity.height * entity.__pivot[1];
-    return {
-        kind: 'rectangle',
-        id,
-        name: entity.__identifier,
-        type: entity.__identifier,
-        x,
-        y,
-        width: entity.width,
-        height: entity.height,
-        rotation: 0,
-        visible: true,
-        properties: convertFieldInstances(entity.fieldInstances),
-    };
-}
+* Per-`TileLayer` cache of parsed IntGrid CSV/value-defs data, populated
+* lazily on first {@link getLdtkIntGridValueAt} lookup for a given layer.
+*
+* Keyed by the `TileLayer` instance itself (`WeakMap`), so an entry is
+* naturally garbage-collected once the layer it was derived from is no
+* longer referenced - no manual invalidation needed since
+* {@link TileLayer.properties} is frozen and copied at construction time and
+* can never change afterwards.
+*/
+const intGridCache = /* @__PURE__ */ new WeakMap();
 /**
- * Project LDtk field instances to a flat {@link TileProperties} bag.
- * Every LDtk field type maps to a canonical {@link TilePropertyValue}
- * (scalars pass through; `Point`/`EntityRef`/`Tile` become their tagged
- * structured variants; `Array<T>` fields recursively convert each element).
- * A field whose raw `__value` is `null` (LDtk's "not set" convention) is
- * omitted from the bag entirely, matching the property-absent case rather
- * than a present-but-null value.
- */
-function convertFieldInstances(fields) {
-    if (fields.length === 0)
-        return Object.freeze({});
-    const out = {};
-    for (const field of fields) {
-        const value = convertField(field);
-        if (value !== undefined) {
-            out[field.__identifier] = value;
-        }
-    }
-    return Object.freeze(out);
-}
+* Parse (or retrieve from {@link intGridCache}) the IntGrid CSV/value-defs
+* data attached to `layer`, or `undefined` when `layer` carries no such data
+* (not converted from an IntGrid layer instance).
+*/
+const getParsedIntGridData = (layer) => {
+	const cached = intGridCache.get(layer);
+	if (cached) return cached;
+	const csvRaw = layer.properties[ldtkIntGridCsvProperty];
+	const valuesRaw = layer.properties[ldtkIntGridValuesProperty];
+	if (typeof csvRaw !== "string" || typeof valuesRaw !== "string") return void 0;
+	const parsed = {
+		csv: JSON.parse(csvRaw),
+		values: JSON.parse(valuesRaw)
+	};
+	intGridCache.set(layer, parsed);
+	return parsed;
+};
 /**
- * Type guard narrowing to the `Array<T>` member of {@link LdtkFieldInstance}.
- * `String.prototype.startsWith` alone does not narrow a template-literal
- * union member for the compiler; a predicate on `field` itself does.
- */
-function isLdtkArrayField(field) {
-    return field.__type.startsWith('Array<');
-}
+* Look up the named/coloured {@link LdtkIntGridValueDef} at a tile coordinate
+* on a `TileLayer` converted from an LDtk `IntGrid` layer instance.
+*
+* Returns `undefined` when the coordinate is out of bounds, the cell's raw
+* value is `0` (empty), the raw value has no matching definition, or `layer`
+* was not converted from an IntGrid layer instance (no IntGrid data attached
+* 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
+* hot path (e.g. per-cell or per-frame collision/classification checks).
+*/
+const getLdtkIntGridValueAt = (layer, x, y) => {
+	if (!layer.inBounds(x, y) || layer.width === void 0) return void 0;
+	const parsed = getParsedIntGridData(layer);
+	if (!parsed) return void 0;
+	const raw = parsed.csv[y * layer.width + x];
+	if (raw === void 0 || raw === 0) return void 0;
+	return parsed.values.find((v) => v.value === raw);
+};
+/**
+* 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) });
+* ```
+*/
+const createLdtkIntGridCellSource = (layer) => {
+	const parsed = getParsedIntGridData(layer);
+	const width = layer.width;
+	if (!parsed || width === void 0) return void 0;
+	const identifiers = /* @__PURE__ */ new Map();
+	for (const value of parsed.values) identifiers.set(value.value, value.identifier ?? String(value.value));
+	return (tx, ty) => {
+		if (!layer.inBounds(tx, ty)) return null;
+		const raw = parsed.csv[ty * width + tx];
+		if (raw === void 0 || raw === 0) return null;
+		return identifiers.get(raw) ?? String(raw);
+	};
+};
+const 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 === void 0) continue;
+		const id = levelIndex * 1e6 + baseCounter + i;
+		objects.push(convertEntity(entity, id));
+	}
+	return objects;
+};
+const convertEntity = (entity, id) => {
+	const x = entity.px[0] - entity.width * entity.__pivot[0];
+	const y = entity.px[1] - entity.height * entity.__pivot[1];
+	return {
+		kind: "rectangle",
+		id,
+		sourceId: entity.iid,
+		name: entity.__identifier,
+		type: entity.__identifier,
+		x,
+		y,
+		width: entity.width,
+		height: entity.height,
+		rotation: 0,
+		visible: true,
+		properties: convertFieldInstances(entity.fieldInstances),
+		source: entity
+	};
+};
+/**
+* Project LDtk field instances to a flat {@link TileProperties} bag.
+* Every LDtk field type maps to a canonical {@link TilePropertyValue}
+* (scalars pass through; `Point`/`EntityRef`/`Tile` become their tagged
+* structured variants; `Array<T>` fields recursively convert each element).
+* A field whose raw `__value` is `null` (LDtk's "not set" convention) is
+* omitted from the bag entirely, matching the property-absent case rather
+* than a present-but-null value.
+*/
+const convertFieldInstances = (fields) => {
+	if (fields.length === 0) return Object.freeze({});
+	const out = {};
+	for (const field of fields) {
+		const value = convertField(field);
+		if (value !== void 0) out[field.__identifier] = value;
+	}
+	return Object.freeze(out);
+};
+/**
+* Type guard narrowing to the `Array<T>` member of {@link LdtkFieldInstance}.
+* `String.prototype.startsWith` alone does not narrow a template-literal
+* union member for the compiler; a predicate on `field` itself does.
+*/
+const isLdtkArrayField = (field) => field.__type.startsWith("Array<");
 /** Convert one {@link LdtkFieldInstance} to its canonical {@link TilePropertyValue}, or `undefined` for a `null` (unset) field. */
-function convertField(field) {
-    switch (field.__type) {
-        case 'Int':
-        case 'Float':
-        case 'Bool':
-        case 'String':
-        case 'Multilines':
-        case 'Color':
-        case 'FilePath':
-        case 'Enum':
-        case 'Point':
-        case 'EntityRef':
-        case 'Tile':
-            return mapLdtkFieldValue(field.__type, field.__value);
-    }
-    if (isLdtkArrayField(field)) {
-        if (field.__value === null)
-            return undefined;
-        const elementType = field.__type.slice('Array<'.length, -1);
-        const elements = [];
-        for (const raw of field.__value) {
-            const converted = mapLdtkFieldValue(elementType, raw);
-            if (converted !== undefined)
-                elements.push(converted);
-        }
-        return Object.freeze(elements);
-    }
-    throw new Error(`convertFieldInstances: unrecognised LDtk field type "${field.__type}".`);
-}
+const convertField = (field) => {
+	switch (field.__type) {
+		case "Int":
+		case "Float":
+		case "Bool":
+		case "String":
+		case "Multilines":
+		case "Color":
+		case "FilePath":
+		case "Enum":
+		case "Point":
+		case "EntityRef":
+		case "Tile": return mapLdtkFieldValue(field.__type, field.__value);
+	}
+	if (isLdtkArrayField(field)) {
+		if (field.__value === null) return void 0;
+		const elementType = field.__type.slice(6, -1);
+		const elements = [];
+		for (const raw of field.__value) {
+			const converted = mapLdtkFieldValue(elementType, raw);
+			if (converted !== void 0) elements.push(converted);
+		}
+		return Object.freeze(elements);
+	}
+	throw new Error(`convertFieldInstances: unrecognised LDtk field type "${field.__type}".`);
+};
 /**
- * Map a single raw LDtk field value (or array element) to its canonical
- * {@link TilePropertyValue}, given the LDtk type name it was declared with.
- * Shared by {@link convertField} (top-level fields) and array-element
- * conversion (`typeName` is the `T` extracted from an `Array<T>` field).
- * Returns `undefined` for a `null` value or an unrecognised `typeName`.
- */
-function mapLdtkFieldValue(typeName, value) {
-    if (value === null || value === undefined)
-        return undefined;
-    switch (typeName) {
-        case 'Int':
-        case 'Float':
-        case 'Bool':
-        case 'String':
-        case 'Multilines':
-        case 'Color':
-        case 'FilePath':
-        case 'Enum':
-            return value;
-        case 'Point': {
-            const v = value;
-            return { kind: TilePropertyKind.Point, cx: v.cx, cy: v.cy };
-        }
-        case 'EntityRef': {
-            const v = value;
-            return {
-                kind: TilePropertyKind.ObjectRef,
-                id: v.entityIid,
-                layerIid: v.layerIid,
-                levelIid: v.levelIid,
-                worldIid: v.worldIid,
-            };
-        }
-        case 'Tile': {
-            const v = value;
-            return { kind: TilePropertyKind.TileRef, tilesetUid: v.tilesetUid, x: v.x, y: v.y, w: v.w, h: v.h };
-        }
-        default:
-            // Unknown/unsupported array element type (e.g. a future LDtk type
-            // inside Array<T>) — skip rather than throw, since this path is not
-            // compiler-exhaustive (element types are plain runtime strings).
-            return undefined;
-    }
-}
-// ── 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;
-}
+* Map a single raw LDtk field value (or array element) to its canonical
+* {@link TilePropertyValue}, given the LDtk type name it was declared with.
+* Shared by {@link convertField} (top-level fields) and array-element
+* conversion (`typeName` is the `T` extracted from an `Array<T>` field).
+* Returns `undefined` for a `null` value or an unrecognised `typeName`.
+*/
+const mapLdtkFieldValue = (typeName, value) => {
+	if (value === null || value === void 0) return void 0;
+	switch (typeName) {
+		case "Int":
+		case "Float":
+		case "Bool":
+		case "String":
+		case "Multilines":
+		case "Color":
+		case "FilePath":
+		case "Enum": return value;
+		case "Point": {
+			const v = value;
+			return {
+				kind: TilePropertyKind.Point,
+				cx: v.cx,
+				cy: v.cy
+			};
+		}
+		case "EntityRef": {
+			const v = value;
+			return {
+				kind: TilePropertyKind.ObjectRef,
+				id: v.entityIid,
+				layerIid: v.layerIid,
+				levelIid: v.levelIid,
+				worldIid: v.worldIid
+			};
+		}
+		case "Tile": {
+			const v = value;
+			return {
+				kind: TilePropertyKind.TileRef,
+				tilesetUid: v.tilesetUid,
+				x: v.x,
+				y: v.y,
+				w: v.w,
+				h: v.h
+			};
+		}
+		default: return;
+	}
+};
+const 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 { getLdtkIntGridValueAt, ldtkIntGridCsvProperty, ldtkIntGridValuesProperty, ldtkToTileMap };
-//# sourceMappingURL=ldtkToTileMap.js.map
+//#endregion
+export { buildLdtkLevelProperties, createLdtkIntGridCellSource, getLdtkIntGridValueAt, ldtkIntGridCsvProperty, ldtkIntGridValuesProperty, ldtkLevelToTileMap, ldtkToTileMap };
+//# sourceMappingURL=ldtkToTileMap.js.map