@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/ImageLayer.js

@@ -1,67 +1,74 @@
+//#region src/ImageLayer.ts
 /**
- * A data-only image layer: a single image (texture + resolved URL) placed as a
- * background or foreground layer. Image layers are not rendered by the tile
- * renderer — they are exposed as data for a renderer or follow-up scene node to
- * consume.
- *
- * Parallax, opacity, tint, offset, and repeat flags are carried from the
- * source Tiled map.
- *
- * @advanced
- */
-class ImageLayer {
-    /** Layer-kind discriminant. */
-    kind = 'image';
-    /** Layer id (unique within the map). */
-    id;
-    /** Layer name. */
-    name;
-    /** Layer class string. */
-    class;
-    /** Resolved URL of the layer image. */
-    image;
-    /** Loaded texture for the image, or `null` if unavailable. */
-    texture;
-    /** Whether the layer is visible. */
-    visible;
-    /** Layer opacity in `[0, 1]`. */
-    opacity;
-    /** Layer pixel offset X. */
-    offsetX;
-    /** Layer pixel offset Y. */
-    offsetY;
-    /** Horizontal parallax factor. */
-    parallaxX;
-    /** Vertical parallax factor. */
-    parallaxY;
-    /** Tint colour as `0xRRGGBB`, or `null`. */
-    tintColor;
-    /** Whether the image repeats horizontally. */
-    repeatX;
-    /** Whether the image repeats vertically. */
-    repeatY;
-    /** Immutable layer properties. */
-    properties;
-    constructor(options) {
-        this.id = options.id;
-        this.name = options.name ?? '';
-        this.class = options.class ?? '';
-        this.image = options.image;
-        this.texture = options.texture ?? null;
-        this.visible = options.visible ?? true;
-        this.opacity = options.opacity ?? 1;
-        this.offsetX = options.offsetX ?? 0;
-        this.offsetY = options.offsetY ?? 0;
-        this.parallaxX = options.parallaxX ?? 1;
-        this.parallaxY = options.parallaxY ?? 1;
-        this.tintColor = options.tintColor ?? null;
-        this.repeatX = options.repeatX ?? false;
-        this.repeatY = options.repeatY ?? false;
-        this.properties = options.properties
-            ? Object.freeze({ ...options.properties })
-            : Object.freeze({});
-    }
-}
+* A data-only image layer: a single image (texture + resolved URL) placed as a
+* background or foreground layer. The layer itself holds no scene-graph state -
+* it is rendered by an {@link import('./ImageLayerNode').ImageLayerNode}, which
+* {@link import('./TileMapNode').TileMapNode} and
+* {@link import('./TileMapView').TileMapView} generate and interleave with tile
+* layers by the map's combined document order
+* ({@link import('./TileMap').TileMap.renderableLayers}).
+*
+* Parallax, opacity, tint, offset, and repeat flags are carried from the
+* source Tiled map.
+*
+* @advanced
+*/
+var ImageLayer = class {
+	/** Layer-kind discriminant. */
+	kind = "image";
+	/** Layer id (unique within the map). */
+	id;
+	/** Layer name. */
+	name;
+	/** Layer class string. */
+	class;
+	/** Resolved URL of the layer image. */
+	image;
+	/** Loaded texture for the image, or `null` if unavailable. */
+	texture;
+	/** Whether the layer is visible. */
+	visible;
+	/** Layer opacity in `[0, 1]`. */
+	opacity;
+	/** Layer pixel offset X. */
+	offsetX;
+	/** Layer pixel offset Y. */
+	offsetY;
+	/** Horizontal parallax factor. */
+	parallaxX;
+	/** Vertical parallax factor. */
+	parallaxY;
+	/** Uniform scale applied around the layer origin during parallax rendering. */
+	parallaxScale;
+	/** Tint colour as `0xRRGGBB`, or `null`. */
+	tintColor;
+	/** Whether the image repeats horizontally. */
+	repeatX;
+	/** Whether the image repeats vertically. */
+	repeatY;
+	/** Immutable layer properties. */
+	properties;
+	constructor(options) {
+		this.id = options.id;
+		this.name = options.name ?? "";
+		this.class = options.class ?? "";
+		this.image = options.image;
+		this.texture = options.texture ?? null;
+		this.visible = options.visible ?? true;
+		this.opacity = options.opacity ?? 1;
+		this.offsetX = options.offsetX ?? 0;
+		this.offsetY = options.offsetY ?? 0;
+		this.parallaxX = options.parallaxX ?? 1;
+		this.parallaxY = options.parallaxY ?? 1;
+		this.parallaxScale = options.parallaxScale ?? 1;
+		if (!Number.isFinite(this.parallaxScale) || this.parallaxScale <= 0) throw new Error("ImageLayer parallaxScale must be a positive finite number.");
+		this.tintColor = options.tintColor ?? null;
+		this.repeatX = options.repeatX ?? false;
+		this.repeatY = options.repeatY ?? false;
+		this.properties = options.properties ? Object.freeze({ ...options.properties }) : Object.freeze({});
+	}
+};
 
+//#endregion
 export { ImageLayer };
-//# sourceMappingURL=ImageLayer.js.map
+//# sourceMappingURL=ImageLayer.js.map

package/dist/esm/ImageLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"ImageLayer.js","sources":["../../../src/ImageLayer.ts"],"sourcesContent":[null],"names":[],"mappings":"AAsCA;;;;;;;;;;AAUG;MACU,UAAU,CAAA;;IAEL,IAAI,GAAG,OAAgB;;AAGvB,IAAA,EAAE;;AAEF,IAAA,IAAI;;AAEJ,IAAA,KAAK;;AAEL,IAAA,KAAK;;AAEL,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,SAAS;;AAET,IAAA,SAAS;;AAET,IAAA,SAAS;;AAET,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,UAAU;AAE1B,IAAA,WAAA,CAAmB,OAA0B,EAAA;AAC3C,QAAA,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE;QACpB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE;QAC9B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE;AAChC,QAAA,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK;QACvC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK;AACvC,QAAA,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;cACtB,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE;AACzC,cAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACvB;AACD;;;;"}
+{"version":3,"file":"ImageLayer.js","names":[],"sources":["../../src/ImageLayer.ts"],"sourcesContent":["import type { Texture } from '@codexo/exojs';\n\nimport type { TileProperties } from './types';\n\n/** Construction options for an {@link ImageLayer}. */\nexport interface ImageLayerOptions {\n  /** Layer id (unique within the map). */\n  readonly id: number;\n  /** Layer name. */\n  readonly name?: string;\n  /** Layer class string. */\n  readonly class?: string;\n  /** Resolved image URL. */\n  readonly image: string;\n  /** Loaded texture for the image, or `null` if unavailable. */\n  readonly texture?: Texture | null;\n  /** Whether the layer is visible. Default `true`. */\n  readonly visible?: boolean;\n  /** Layer opacity in `[0, 1]`. Default `1`. */\n  readonly opacity?: number;\n  /** Layer pixel offset X. Default `0`. */\n  readonly offsetX?: number;\n  /** Layer pixel offset Y. Default `0`. */\n  readonly offsetY?: number;\n  /** Horizontal parallax factor. Default `1`. */\n  readonly parallaxX?: number;\n  /** Vertical parallax factor. Default `1`. */\n  readonly parallaxY?: number;\n  /** Uniform parallax scale around the layer origin. Default `1`. */\n  readonly parallaxScale?: number;\n  /** Tint colour as `0xRRGGBB`, or `null`. Default `null`. */\n  readonly tintColor?: number | null;\n  /** Whether the image repeats horizontally. Default `false`. */\n  readonly repeatX?: boolean;\n  /** Whether the image repeats vertically. Default `false`. */\n  readonly repeatY?: boolean;\n  /** Layer properties (copied and frozen). */\n  readonly properties?: TileProperties;\n}\n\n/**\n * A data-only image layer: a single image (texture + resolved URL) placed as a\n * background or foreground layer. The layer itself holds no scene-graph state -\n * it is rendered by an {@link import('./ImageLayerNode').ImageLayerNode}, which\n * {@link import('./TileMapNode').TileMapNode} and\n * {@link import('./TileMapView').TileMapView} generate and interleave with tile\n * layers by the map's combined document order\n * ({@link import('./TileMap').TileMap.renderableLayers}).\n *\n * Parallax, opacity, tint, offset, and repeat flags are carried from the\n * source Tiled map.\n *\n * @advanced\n */\nexport class ImageLayer {\n  /** Layer-kind discriminant. */\n  public readonly kind = 'image' as const;\n\n  /** Layer id (unique within the map). */\n  public readonly id: number;\n  /** Layer name. */\n  public readonly name: string;\n  /** Layer class string. */\n  public readonly class: string;\n  /** Resolved URL of the layer image. */\n  public readonly image: string;\n  /** Loaded texture for the image, or `null` if unavailable. */\n  public readonly texture: Texture | null;\n  /** Whether the layer is visible. */\n  public readonly visible: boolean;\n  /** Layer opacity in `[0, 1]`. */\n  public readonly opacity: number;\n  /** Layer pixel offset X. */\n  public readonly offsetX: number;\n  /** Layer pixel offset Y. */\n  public readonly offsetY: number;\n  /** Horizontal parallax factor. */\n  public readonly parallaxX: number;\n  /** Vertical parallax factor. */\n  public readonly parallaxY: number;\n  /** Uniform scale applied around the layer origin during parallax rendering. */\n  public readonly parallaxScale: number;\n  /** Tint colour as `0xRRGGBB`, or `null`. */\n  public readonly tintColor: number | null;\n  /** Whether the image repeats horizontally. */\n  public readonly repeatX: boolean;\n  /** Whether the image repeats vertically. */\n  public readonly repeatY: boolean;\n  /** Immutable layer properties. */\n  public readonly properties: TileProperties;\n\n  public constructor(options: ImageLayerOptions) {\n    this.id = options.id;\n    this.name = options.name ?? '';\n    this.class = options.class ?? '';\n    this.image = options.image;\n    this.texture = options.texture ?? null;\n    this.visible = options.visible ?? true;\n    this.opacity = options.opacity ?? 1;\n    this.offsetX = options.offsetX ?? 0;\n    this.offsetY = options.offsetY ?? 0;\n    this.parallaxX = options.parallaxX ?? 1;\n    this.parallaxY = options.parallaxY ?? 1;\n    this.parallaxScale = options.parallaxScale ?? 1;\n    if (!Number.isFinite(this.parallaxScale) || this.parallaxScale <= 0) {\n      throw new Error('ImageLayer parallaxScale must be a positive finite number.');\n    }\n    this.tintColor = options.tintColor ?? null;\n    this.repeatX = options.repeatX ?? false;\n    this.repeatY = options.repeatY ?? false;\n    this.properties = options.properties ? Object.freeze({ ...options.properties }) : Object.freeze({});\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAsDA,IAAa,aAAb,MAAwB;;CAEtB,AAAgB,OAAO;;CAGvB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;;CAEhB,AAAgB;CAEhB,AAAO,YAAY,SAA4B;EAC7C,KAAK,KAAK,QAAQ;EAClB,KAAK,OAAO,QAAQ,QAAQ;EAC5B,KAAK,QAAQ,QAAQ,SAAS;EAC9B,KAAK,QAAQ,QAAQ;EACrB,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,YAAY,QAAQ,aAAa;EACtC,KAAK,YAAY,QAAQ,aAAa;EACtC,KAAK,gBAAgB,QAAQ,iBAAiB;EAC9C,IAAI,CAAC,OAAO,SAAS,KAAK,aAAa,KAAK,KAAK,iBAAiB,GAChE,MAAM,IAAI,MAAM,4DAA4D;EAE9E,KAAK,YAAY,QAAQ,aAAa;EACtC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,aAAa,QAAQ,aAAa,OAAO,OAAO,EAAE,GAAG,QAAQ,WAAW,CAAC,IAAI,OAAO,OAAO,CAAC,CAAC;CACpG;AACF"}

package/dist/esm/ImageLayerNode.d.ts

@@ -0,0 +1,89 @@
+import { Container } from '@codexo/exojs';
+import { PixelSnapMode, type RenderPlanBuilder } from '@codexo/exojs/renderer-sdk';
+import type { ImageLayer } from './ImageLayer';
+/**
+ * A scene node that renders one Tiled {@link ImageLayer} as a single
+ * {@link RepeatingSprite} wrapped in a {@link Container}.
+ *
+ * The layer's pixel `offset` becomes this node's position; `parallax` is
+ * resolved per frame in {@link _collectContent} by patching the node position
+ * against the camera centre (exactly like {@link import('./TileLayerNode').TileLayerNode}),
+ * then restoring it. When `repeatX`/`repeatY` is set the wrapped sprite is
+ * grown each frame to cover the visible view with a period-aligned origin, so
+ * the pattern tiles seamlessly and scrolls with parallax. A repeat axis or a
+ * `parallax` factor other than `1` both make this node's rendered position
+ * and/or size camera-dependent at collect time, so its static bounds cannot be
+ * culled against - such a node opts out of view culling (`cullable = false`).
+ *
+ * `visible`, `opacity`, and `tintColor` are applied **once at construction**:
+ * {@link ImageLayer} is immutable, so there is nothing to re-sync per frame.
+ * A layer whose `texture` is `null` (image failed to load / not yet available)
+ * produces an empty node with no children - it occupies its offset in the
+ * scene graph but draws nothing.
+ *
+ * The node references - but never owns - the {@link ImageLayer} and its
+ * Loader-owned texture: {@link destroy} frees the wrapped sprite but leaves the
+ * layer and texture intact. Image-layer nodes are band-selectable exactly like
+ * tile-layer nodes: list the image layer in a
+ * {@link import('./TileMapView').TileMapViewOptions.bands} definition and the
+ * band stacks it by the map's combined document order, or parent an unbanded
+ * node into the scene directly wherever the image belongs in draw order.
+ *
+ * For a `repeatX`/`repeatY` node, bounds and hit-test queries reflect the
+ * coverage geometry computed by the last {@link _collectContent} call (since
+ * that geometry is recomputed per collect, not maintained incrementally),
+ * which is also why such a node force-disables `cullable`. A repeating or
+ * parallax node also re-sizes its wrapped sprite as the camera crosses period
+ * boundaries, which content-dirties an enclosing retained group the same way
+ * a streamed layer does - give it the same treatment (its own
+ * `RetainedContainer`, or none).
+ *
+ * @advanced
+ */
+export declare class ImageLayerNode extends Container {
+    private readonly _layer;
+    private readonly _sprite;
+    private readonly _baseOffsetX;
+    private readonly _baseOffsetY;
+    private readonly _imageWidth;
+    private readonly _imageHeight;
+    private _pixelSnapMode;
+    private _covViewX;
+    private _covViewY;
+    private _covViewWidth;
+    private _covViewHeight;
+    private _covOriginX;
+    private _covOriginY;
+    constructor(layer: ImageLayer);
+    /** The runtime layer this node renders. */
+    get layer(): ImageLayer;
+    /**
+     * Render-only pixel-snap mode forwarded to the wrapped {@link RepeatingSprite}
+     * (which snaps its rendered origin, and - in `PixelSnapMode.Geometry` mode for
+     * axis-aligned transforms - its repeat-segment boundaries, to the render
+     * target's device-pixel grid). Purely visual: the layer offset, parallax, and
+     * repeat coverage are never changed.
+     *
+     * For a `null`-texture layer there is no drawable to forward to, so the mode
+     * is simply stored. Setting the current value is a no-op; an invalid value
+     * throws and leaves the prior mode unchanged.
+     *
+     * @default PixelSnapMode.None
+     * @stable
+     */
+    get pixelSnapMode(): PixelSnapMode;
+    set pixelSnapMode(mode: PixelSnapMode);
+    /** @internal */
+    protected _collectContent(builder: RenderPlanBuilder): void;
+    destroy(): void;
+    /**
+     * Grow the wrapped sprite along each repeating axis so it covers the visible
+     * view, with a period-aligned local origin so the pattern offset stays zero
+     * (seamless tiling). Non-repeating axes keep the natural image size at local
+     * `0`. Reads `this.x`/`this.y` after the parallax patch, so the pattern anchor
+     * follows the parallax-shifted origin. Skips the rebuild when neither the view
+     * span nor the patched origin changed since the last frame.
+     */
+    private _updateRepeatCoverage;
+}
+//# sourceMappingURL=ImageLayerNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ImageLayerNode.d.ts","sourceRoot":"","sources":["../../src/ImageLayerNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAmB,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,cAAc,CAAqC;IAI3D,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,WAAW,CAAc;gBAEd,KAAK,EAAE,UAAU;IAgDpC,2CAA2C;IAC3C,IAAW,KAAK,IAAI,UAAU,CAE7B;IAED;;;;;;;;;;;;;OAaG;IACH,IAAW,aAAa,IAAI,aAAa,CAExC;IAED,IAAW,aAAa,CAAC,IAAI,EAAE,aAAa,EAW3C;IAED,gBAAgB;cACG,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IA8CpD,OAAO,IAAI,IAAI;IAQ/B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;CA4D9B"}

package/dist/esm/ImageLayerNode.js

@@ -0,0 +1,205 @@
+import { assertPixelSnapMode } from "./pixelSnap.js";
+import { PixelSnapMode } from "@codexo/exojs/renderer-sdk";
+import { Container, RepeatingSprite } from "@codexo/exojs";
+
+//#region src/ImageLayerNode.ts
+/**
+* A scene node that renders one Tiled {@link ImageLayer} as a single
+* {@link RepeatingSprite} wrapped in a {@link Container}.
+*
+* The layer's pixel `offset` becomes this node's position; `parallax` is
+* resolved per frame in {@link _collectContent} by patching the node position
+* against the camera centre (exactly like {@link import('./TileLayerNode').TileLayerNode}),
+* then restoring it. When `repeatX`/`repeatY` is set the wrapped sprite is
+* grown each frame to cover the visible view with a period-aligned origin, so
+* the pattern tiles seamlessly and scrolls with parallax. A repeat axis or a
+* `parallax` factor other than `1` both make this node's rendered position
+* and/or size camera-dependent at collect time, so its static bounds cannot be
+* culled against - such a node opts out of view culling (`cullable = false`).
+*
+* `visible`, `opacity`, and `tintColor` are applied **once at construction**:
+* {@link ImageLayer} is immutable, so there is nothing to re-sync per frame.
+* A layer whose `texture` is `null` (image failed to load / not yet available)
+* produces an empty node with no children - it occupies its offset in the
+* scene graph but draws nothing.
+*
+* The node references - but never owns - the {@link ImageLayer} and its
+* Loader-owned texture: {@link destroy} frees the wrapped sprite but leaves the
+* layer and texture intact. Image-layer nodes are band-selectable exactly like
+* tile-layer nodes: list the image layer in a
+* {@link import('./TileMapView').TileMapViewOptions.bands} definition and the
+* band stacks it by the map's combined document order, or parent an unbanded
+* node into the scene directly wherever the image belongs in draw order.
+*
+* For a `repeatX`/`repeatY` node, bounds and hit-test queries reflect the
+* coverage geometry computed by the last {@link _collectContent} call (since
+* that geometry is recomputed per collect, not maintained incrementally),
+* which is also why such a node force-disables `cullable`. A repeating or
+* parallax node also re-sizes its wrapped sprite as the camera crosses period
+* boundaries, which content-dirties an enclosing retained group the same way
+* a streamed layer does - give it the same treatment (its own
+* `RetainedContainer`, or none).
+*
+* @advanced
+*/
+var ImageLayerNode = class extends Container {
+	_layer;
+	_sprite;
+	_baseOffsetX;
+	_baseOffsetY;
+	_imageWidth;
+	_imageHeight;
+	_pixelSnapMode = PixelSnapMode.None;
+	_covViewX = NaN;
+	_covViewY = NaN;
+	_covViewWidth = NaN;
+	_covViewHeight = NaN;
+	_covOriginX = NaN;
+	_covOriginY = NaN;
+	constructor(layer) {
+		super();
+		this._layer = layer;
+		this._baseOffsetX = layer.offsetX;
+		this._baseOffsetY = layer.offsetY;
+		this.setPosition(layer.offsetX, layer.offsetY);
+		this.visible = layer.visible;
+		const texture = layer.texture;
+		if (texture === null) {
+			this._sprite = null;
+			this._imageWidth = 0;
+			this._imageHeight = 0;
+			return;
+		}
+		this._imageWidth = texture.width;
+		this._imageHeight = texture.height;
+		const sprite = new RepeatingSprite(texture, {
+			modeX: layer.repeatX ? "repeat" : "stretch",
+			modeY: layer.repeatY ? "repeat" : "stretch",
+			width: texture.width,
+			height: texture.height
+		});
+		const tintColor = layer.tintColor;
+		const r = tintColor === null ? 255 : tintColor >> 16 & 255;
+		const g = tintColor === null ? 255 : tintColor >> 8 & 255;
+		const b = tintColor === null ? 255 : tintColor & 255;
+		sprite.tint.set(r, g, b, layer.opacity);
+		this._sprite = sprite;
+		this.addChild(sprite);
+		if (layer.repeatX || layer.repeatY || layer.parallaxX !== 1 || layer.parallaxY !== 1 || layer.parallaxScale !== 1) this.cullable = false;
+	}
+	/** The runtime layer this node renders. */
+	get layer() {
+		return this._layer;
+	}
+	/**
+	* Render-only pixel-snap mode forwarded to the wrapped {@link RepeatingSprite}
+	* (which snaps its rendered origin, and - in `PixelSnapMode.Geometry` mode for
+	* axis-aligned transforms - its repeat-segment boundaries, to the render
+	* target's device-pixel grid). Purely visual: the layer offset, parallax, and
+	* repeat coverage are never changed.
+	*
+	* For a `null`-texture layer there is no drawable to forward to, so the mode
+	* is simply stored. Setting the current value is a no-op; an invalid value
+	* throws and leaves the prior mode unchanged.
+	*
+	* @default PixelSnapMode.None
+	* @stable
+	*/
+	get pixelSnapMode() {
+		return this._pixelSnapMode;
+	}
+	set pixelSnapMode(mode) {
+		if (mode === this._pixelSnapMode) return;
+		assertPixelSnapMode(mode);
+		this._pixelSnapMode = mode;
+		if (this._sprite !== null) this._sprite.pixelSnapMode = mode;
+	}
+	/** @internal */
+	_collectContent(builder) {
+		if (this._sprite === null) {
+			super._collectContent(builder);
+			return;
+		}
+		const layer = this._layer;
+		const patchesPosition = layer.parallaxX !== 1 || layer.parallaxY !== 1;
+		const patchesScale = layer.parallaxScale !== 1;
+		if (patchesPosition || patchesScale) {
+			const camCenter = builder.view.center;
+			const prevX = this.x;
+			const prevY = this.y;
+			const prevScaleX = this.scale.x;
+			const prevScaleY = this.scale.y;
+			if (patchesPosition) {
+				this.x = this._baseOffsetX + camCenter.x * (1 - layer.parallaxX);
+				this.y = this._baseOffsetY + camCenter.y * (1 - layer.parallaxY);
+			}
+			if (patchesScale) this.setScale(prevScaleX * layer.parallaxScale, prevScaleY * layer.parallaxScale);
+			try {
+				this._updateRepeatCoverage(builder, layer.parallaxScale);
+				super._collectContent(builder);
+			} finally {
+				if (patchesPosition) this.setPosition(prevX, prevY);
+				if (patchesScale) this.setScale(prevScaleX, prevScaleY);
+			}
+		} else {
+			this._updateRepeatCoverage(builder);
+			super._collectContent(builder);
+		}
+	}
+	destroy() {
+		const sprite = this._sprite;
+		super.destroy();
+		sprite?.destroy();
+	}
+	/**
+	* Grow the wrapped sprite along each repeating axis so it covers the visible
+	* view, with a period-aligned local origin so the pattern offset stays zero
+	* (seamless tiling). Non-repeating axes keep the natural image size at local
+	* `0`. Reads `this.x`/`this.y` after the parallax patch, so the pattern anchor
+	* follows the parallax-shifted origin. Skips the rebuild when neither the view
+	* span nor the patched origin changed since the last frame.
+	*/
+	_updateRepeatCoverage(builder, parallaxScale = 1) {
+		const layer = this._layer;
+		const sprite = this._sprite;
+		if (sprite === null || !layer.repeatX && !layer.repeatY) return;
+		const bounds = builder.view.getBounds();
+		const originX = this.x;
+		const originY = this.y;
+		if (bounds.x === this._covViewX && bounds.y === this._covViewY && bounds.width === this._covViewWidth && bounds.height === this._covViewHeight && originX === this._covOriginX && originY === this._covOriginY) return;
+		this._covViewX = bounds.x;
+		this._covViewY = bounds.y;
+		this._covViewWidth = bounds.width;
+		this._covViewHeight = bounds.height;
+		this._covOriginX = originX;
+		this._covOriginY = originY;
+		let childX = 0;
+		let childY = 0;
+		let childWidth = this._imageWidth;
+		let childHeight = this._imageHeight;
+		if (layer.repeatX) {
+			const imgW = this._imageWidth;
+			const localViewMin = (bounds.x - originX) / parallaxScale;
+			const localViewWidth = bounds.width / parallaxScale;
+			const startLocal = Math.floor(localViewMin / imgW) * imgW;
+			const periods = Math.ceil((localViewMin + localViewWidth - startLocal) / imgW);
+			childX = startLocal;
+			childWidth = periods * imgW;
+		}
+		if (layer.repeatY) {
+			const imgH = this._imageHeight;
+			const localViewMin = (bounds.y - originY) / parallaxScale;
+			const localViewHeight = bounds.height / parallaxScale;
+			const startLocal = Math.floor(localViewMin / imgH) * imgH;
+			const periods = Math.ceil((localViewMin + localViewHeight - startLocal) / imgH);
+			childY = startLocal;
+			childHeight = periods * imgH;
+		}
+		sprite.setPosition(childX, childY);
+		sprite.setSize(childWidth, childHeight);
+	}
+};
+
+//#endregion
+export { ImageLayerNode };
+//# sourceMappingURL=ImageLayerNode.js.map

package/dist/esm/ImageLayerNode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageLayerNode.js","names":[],"sources":["../../src/ImageLayerNode.ts"],"sourcesContent":["import { Container, RepeatingSprite } from '@codexo/exojs';\nimport { PixelSnapMode, type RenderPlanBuilder } from '@codexo/exojs/renderer-sdk';\n\nimport type { ImageLayer } from './ImageLayer';\nimport { assertPixelSnapMode } from './pixelSnap';\n\n/**\n * A scene node that renders one Tiled {@link ImageLayer} as a single\n * {@link RepeatingSprite} wrapped in a {@link Container}.\n *\n * The layer's pixel `offset` becomes this node's position; `parallax` is\n * resolved per frame in {@link _collectContent} by patching the node position\n * against the camera centre (exactly like {@link import('./TileLayerNode').TileLayerNode}),\n * then restoring it. When `repeatX`/`repeatY` is set the wrapped sprite is\n * grown each frame to cover the visible view with a period-aligned origin, so\n * the pattern tiles seamlessly and scrolls with parallax. A repeat axis or a\n * `parallax` factor other than `1` both make this node's rendered position\n * and/or size camera-dependent at collect time, so its static bounds cannot be\n * culled against - such a node opts out of view culling (`cullable = false`).\n *\n * `visible`, `opacity`, and `tintColor` are applied **once at construction**:\n * {@link ImageLayer} is immutable, so there is nothing to re-sync per frame.\n * A layer whose `texture` is `null` (image failed to load / not yet available)\n * produces an empty node with no children - it occupies its offset in the\n * scene graph but draws nothing.\n *\n * The node references - but never owns - the {@link ImageLayer} and its\n * Loader-owned texture: {@link destroy} frees the wrapped sprite but leaves the\n * layer and texture intact. Image-layer nodes are band-selectable exactly like\n * tile-layer nodes: list the image layer in a\n * {@link import('./TileMapView').TileMapViewOptions.bands} definition and the\n * band stacks it by the map's combined document order, or parent an unbanded\n * node into the scene directly wherever the image belongs in draw order.\n *\n * For a `repeatX`/`repeatY` node, bounds and hit-test queries reflect the\n * coverage geometry computed by the last {@link _collectContent} call (since\n * that geometry is recomputed per collect, not maintained incrementally),\n * which is also why such a node force-disables `cullable`. A repeating or\n * parallax node also re-sizes its wrapped sprite as the camera crosses period\n * boundaries, which content-dirties an enclosing retained group the same way\n * a streamed layer does - give it the same treatment (its own\n * `RetainedContainer`, or none).\n *\n * @advanced\n */\nexport class ImageLayerNode extends Container {\n  private readonly _layer: ImageLayer;\n  private readonly _sprite: RepeatingSprite | null;\n  private readonly _baseOffsetX: number;\n  private readonly _baseOffsetY: number;\n  private readonly _imageWidth: number;\n  private readonly _imageHeight: number;\n  private _pixelSnapMode: PixelSnapMode = PixelSnapMode.None;\n\n  // Repeat-coverage cache: the view span and patched origin that last drove a\n  // resize. A static camera pays one comparison per frame and skips the rebuild.\n  private _covViewX = Number.NaN;\n  private _covViewY = Number.NaN;\n  private _covViewWidth = Number.NaN;\n  private _covViewHeight = Number.NaN;\n  private _covOriginX = Number.NaN;\n  private _covOriginY = Number.NaN;\n\n  public constructor(layer: ImageLayer) {\n    super();\n\n    this._layer = layer;\n    this._baseOffsetX = layer.offsetX;\n    this._baseOffsetY = layer.offsetY;\n\n    this.setPosition(layer.offsetX, layer.offsetY);\n    this.visible = layer.visible;\n\n    const texture = layer.texture;\n\n    if (texture === null) {\n      this._sprite = null;\n      this._imageWidth = 0;\n      this._imageHeight = 0;\n\n      return;\n    }\n\n    this._imageWidth = texture.width;\n    this._imageHeight = texture.height;\n\n    // Non-repeating axes use `'stretch'` so the axis shows exactly one un-tiled\n    // copy at its natural size; repeating axes use `'repeat'` and are grown to\n    // cover the view in `_collectContent`.\n    const sprite = new RepeatingSprite(texture, {\n      modeX: layer.repeatX ? 'repeat' : 'stretch',\n      modeY: layer.repeatY ? 'repeat' : 'stretch',\n      width: texture.width,\n      height: texture.height,\n    });\n\n    const tintColor = layer.tintColor;\n    const r = tintColor === null ? 255 : (tintColor >> 16) & 0xff;\n    const g = tintColor === null ? 255 : (tintColor >> 8) & 0xff;\n    const b = tintColor === null ? 255 : tintColor & 0xff;\n\n    sprite.tint.set(r, g, b, layer.opacity);\n\n    this._sprite = sprite;\n    this.addChild(sprite);\n\n    if (layer.repeatX || layer.repeatY || layer.parallaxX !== 1 || layer.parallaxY !== 1 || layer.parallaxScale !== 1) {\n      this.cullable = false;\n    }\n  }\n\n  /** The runtime layer this node renders. */\n  public get layer(): ImageLayer {\n    return this._layer;\n  }\n\n  /**\n   * Render-only pixel-snap mode forwarded to the wrapped {@link RepeatingSprite}\n   * (which snaps its rendered origin, and - in `PixelSnapMode.Geometry` mode for\n   * axis-aligned transforms - its repeat-segment boundaries, to the render\n   * target's device-pixel grid). Purely visual: the layer offset, parallax, and\n   * repeat coverage are never changed.\n   *\n   * For a `null`-texture layer there is no drawable to forward to, so the mode\n   * is simply stored. Setting the current value is a no-op; an invalid value\n   * throws and leaves the prior mode unchanged.\n   *\n   * @default PixelSnapMode.None\n   * @stable\n   */\n  public get pixelSnapMode(): PixelSnapMode {\n    return this._pixelSnapMode;\n  }\n\n  public set pixelSnapMode(mode: PixelSnapMode) {\n    if (mode === this._pixelSnapMode) {\n      return;\n    }\n\n    assertPixelSnapMode(mode);\n    this._pixelSnapMode = mode;\n\n    if (this._sprite !== null) {\n      this._sprite.pixelSnapMode = mode;\n    }\n  }\n\n  /** @internal */\n  protected override _collectContent(builder: RenderPlanBuilder): void {\n    if (this._sprite === null) {\n      super._collectContent(builder);\n\n      return;\n    }\n\n    const layer = this._layer;\n\n    const patchesPosition = layer.parallaxX !== 1 || layer.parallaxY !== 1;\n    const patchesScale = layer.parallaxScale !== 1;\n\n    if (patchesPosition || patchesScale) {\n      const camCenter = builder.view.center;\n      const prevX = this.x;\n      const prevY = this.y;\n      const prevScaleX = this.scale.x;\n      const prevScaleY = this.scale.y;\n\n      if (patchesPosition) {\n        this.x = this._baseOffsetX + camCenter.x * (1 - layer.parallaxX);\n        this.y = this._baseOffsetY + camCenter.y * (1 - layer.parallaxY);\n      }\n\n      if (patchesScale) {\n        this.setScale(prevScaleX * layer.parallaxScale, prevScaleY * layer.parallaxScale);\n      }\n\n      try {\n        this._updateRepeatCoverage(builder, layer.parallaxScale);\n        super._collectContent(builder);\n      } finally {\n        if (patchesPosition) {\n          this.setPosition(prevX, prevY);\n        }\n\n        if (patchesScale) {\n          this.setScale(prevScaleX, prevScaleY);\n        }\n      }\n    } else {\n      this._updateRepeatCoverage(builder);\n      super._collectContent(builder);\n    }\n  }\n\n  public override destroy(): void {\n    const sprite = this._sprite;\n\n    super.destroy();\n\n    sprite?.destroy();\n  }\n\n  /**\n   * Grow the wrapped sprite along each repeating axis so it covers the visible\n   * view, with a period-aligned local origin so the pattern offset stays zero\n   * (seamless tiling). Non-repeating axes keep the natural image size at local\n   * `0`. Reads `this.x`/`this.y` after the parallax patch, so the pattern anchor\n   * follows the parallax-shifted origin. Skips the rebuild when neither the view\n   * span nor the patched origin changed since the last frame.\n   */\n  private _updateRepeatCoverage(builder: RenderPlanBuilder, parallaxScale = 1): void {\n    const layer = this._layer;\n    const sprite = this._sprite;\n\n    if (sprite === null || (!layer.repeatX && !layer.repeatY)) {\n      return;\n    }\n\n    const bounds = builder.view.getBounds();\n    const originX = this.x;\n    const originY = this.y;\n\n    if (\n      bounds.x === this._covViewX &&\n      bounds.y === this._covViewY &&\n      bounds.width === this._covViewWidth &&\n      bounds.height === this._covViewHeight &&\n      originX === this._covOriginX &&\n      originY === this._covOriginY\n    ) {\n      return;\n    }\n\n    this._covViewX = bounds.x;\n    this._covViewY = bounds.y;\n    this._covViewWidth = bounds.width;\n    this._covViewHeight = bounds.height;\n    this._covOriginX = originX;\n    this._covOriginY = originY;\n\n    let childX = 0;\n    let childY = 0;\n    let childWidth = this._imageWidth;\n    let childHeight = this._imageHeight;\n\n    if (layer.repeatX) {\n      const imgW = this._imageWidth;\n      const localViewMin = (bounds.x - originX) / parallaxScale;\n      const localViewWidth = bounds.width / parallaxScale;\n      const startLocal = Math.floor(localViewMin / imgW) * imgW;\n      const periods = Math.ceil((localViewMin + localViewWidth - startLocal) / imgW);\n\n      childX = startLocal;\n      childWidth = periods * imgW;\n    }\n\n    if (layer.repeatY) {\n      const imgH = this._imageHeight;\n      const localViewMin = (bounds.y - originY) / parallaxScale;\n      const localViewHeight = bounds.height / parallaxScale;\n      const startLocal = Math.floor(localViewMin / imgH) * imgH;\n      const periods = Math.ceil((localViewMin + localViewHeight - startLocal) / imgH);\n\n      childY = startLocal;\n      childHeight = periods * imgH;\n    }\n\n    sprite.setPosition(childX, childY);\n    sprite.setSize(childWidth, childHeight);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAa,iBAAb,cAAoC,UAAU;CAC5C,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAQ,iBAAgC,cAAc;CAItD,AAAQ,YAAY;CACpB,AAAQ,YAAY;CACpB,AAAQ,gBAAgB;CACxB,AAAQ,iBAAiB;CACzB,AAAQ,cAAc;CACtB,AAAQ,cAAc;CAEtB,AAAO,YAAY,OAAmB;EACpC,MAAM;EAEN,KAAK,SAAS;EACd,KAAK,eAAe,MAAM;EAC1B,KAAK,eAAe,MAAM;EAE1B,KAAK,YAAY,MAAM,SAAS,MAAM,OAAO;EAC7C,KAAK,UAAU,MAAM;EAErB,MAAM,UAAU,MAAM;EAEtB,IAAI,YAAY,MAAM;GACpB,KAAK,UAAU;GACf,KAAK,cAAc;GACnB,KAAK,eAAe;GAEpB;EACF;EAEA,KAAK,cAAc,QAAQ;EAC3B,KAAK,eAAe,QAAQ;EAK5B,MAAM,SAAS,IAAI,gBAAgB,SAAS;GAC1C,OAAO,MAAM,UAAU,WAAW;GAClC,OAAO,MAAM,UAAU,WAAW;GAClC,OAAO,QAAQ;GACf,QAAQ,QAAQ;EAClB,CAAC;EAED,MAAM,YAAY,MAAM;EACxB,MAAM,IAAI,cAAc,OAAO,MAAO,aAAa,KAAM;EACzD,MAAM,IAAI,cAAc,OAAO,MAAO,aAAa,IAAK;EACxD,MAAM,IAAI,cAAc,OAAO,MAAM,YAAY;EAEjD,OAAO,KAAK,IAAI,GAAG,GAAG,GAAG,MAAM,OAAO;EAEtC,KAAK,UAAU;EACf,KAAK,SAAS,MAAM;EAEpB,IAAI,MAAM,WAAW,MAAM,WAAW,MAAM,cAAc,KAAK,MAAM,cAAc,KAAK,MAAM,kBAAkB,GAC9G,KAAK,WAAW;CAEpB;;CAGA,IAAW,QAAoB;EAC7B,OAAO,KAAK;CACd;;;;;;;;;;;;;;;CAgBA,IAAW,gBAA+B;EACxC,OAAO,KAAK;CACd;CAEA,IAAW,cAAc,MAAqB;EAC5C,IAAI,SAAS,KAAK,gBAChB;EAGF,oBAAoB,IAAI;EACxB,KAAK,iBAAiB;EAEtB,IAAI,KAAK,YAAY,MACnB,KAAK,QAAQ,gBAAgB;CAEjC;;CAGA,AAAmB,gBAAgB,SAAkC;EACnE,IAAI,KAAK,YAAY,MAAM;GACzB,MAAM,gBAAgB,OAAO;GAE7B;EACF;EAEA,MAAM,QAAQ,KAAK;EAEnB,MAAM,kBAAkB,MAAM,cAAc,KAAK,MAAM,cAAc;EACrE,MAAM,eAAe,MAAM,kBAAkB;EAE7C,IAAI,mBAAmB,cAAc;GACnC,MAAM,YAAY,QAAQ,KAAK;GAC/B,MAAM,QAAQ,KAAK;GACnB,MAAM,QAAQ,KAAK;GACnB,MAAM,aAAa,KAAK,MAAM;GAC9B,MAAM,aAAa,KAAK,MAAM;GAE9B,IAAI,iBAAiB;IACnB,KAAK,IAAI,KAAK,eAAe,UAAU,KAAK,IAAI,MAAM;IACtD,KAAK,IAAI,KAAK,eAAe,UAAU,KAAK,IAAI,MAAM;GACxD;GAEA,IAAI,cACF,KAAK,SAAS,aAAa,MAAM,eAAe,aAAa,MAAM,aAAa;GAGlF,IAAI;IACF,KAAK,sBAAsB,SAAS,MAAM,aAAa;IACvD,MAAM,gBAAgB,OAAO;GAC/B,UAAU;IACR,IAAI,iBACF,KAAK,YAAY,OAAO,KAAK;IAG/B,IAAI,cACF,KAAK,SAAS,YAAY,UAAU;GAExC;EACF,OAAO;GACL,KAAK,sBAAsB,OAAO;GAClC,MAAM,gBAAgB,OAAO;EAC/B;CACF;CAEA,AAAgB,UAAgB;EAC9B,MAAM,SAAS,KAAK;EAEpB,MAAM,QAAQ;EAEd,QAAQ,QAAQ;CAClB;;;;;;;;;CAUA,AAAQ,sBAAsB,SAA4B,gBAAgB,GAAS;EACjF,MAAM,QAAQ,KAAK;EACnB,MAAM,SAAS,KAAK;EAEpB,IAAI,WAAW,QAAS,CAAC,MAAM,WAAW,CAAC,MAAM,SAC/C;EAGF,MAAM,SAAS,QAAQ,KAAK,UAAU;EACtC,MAAM,UAAU,KAAK;EACrB,MAAM,UAAU,KAAK;EAErB,IACE,OAAO,MAAM,KAAK,aAClB,OAAO,MAAM,KAAK,aAClB,OAAO,UAAU,KAAK,iBACtB,OAAO,WAAW,KAAK,kBACvB,YAAY,KAAK,eACjB,YAAY,KAAK,aAEjB;EAGF,KAAK,YAAY,OAAO;EACxB,KAAK,YAAY,OAAO;EACxB,KAAK,gBAAgB,OAAO;EAC5B,KAAK,iBAAiB,OAAO;EAC7B,KAAK,cAAc;EACnB,KAAK,cAAc;EAEnB,IAAI,SAAS;EACb,IAAI,SAAS;EACb,IAAI,aAAa,KAAK;EACtB,IAAI,cAAc,KAAK;EAEvB,IAAI,MAAM,SAAS;GACjB,MAAM,OAAO,KAAK;GAClB,MAAM,gBAAgB,OAAO,IAAI,WAAW;GAC5C,MAAM,iBAAiB,OAAO,QAAQ;GACtC,MAAM,aAAa,KAAK,MAAM,eAAe,IAAI,IAAI;GACrD,MAAM,UAAU,KAAK,MAAM,eAAe,iBAAiB,cAAc,IAAI;GAE7E,SAAS;GACT,aAAa,UAAU;EACzB;EAEA,IAAI,MAAM,SAAS;GACjB,MAAM,OAAO,KAAK;GAClB,MAAM,gBAAgB,OAAO,IAAI,WAAW;GAC5C,MAAM,kBAAkB,OAAO,SAAS;GACxC,MAAM,aAAa,KAAK,MAAM,eAAe,IAAI,IAAI;GACrD,MAAM,UAAU,KAAK,MAAM,eAAe,kBAAkB,cAAc,IAAI;GAE9E,SAAS;GACT,cAAc,UAAU;EAC1B;EAEA,OAAO,YAAY,QAAQ,MAAM;EACjC,OAAO,QAAQ,YAAY,WAAW;CACxC;AACF"}

package/dist/esm/MapObject.d.ts

@@ -0,0 +1,70 @@
+import type { ObjectLayer, TileMapObject } from './ObjectLayer';
+import type { TileMap } from './TileMap';
+import type { TileProperties } from './types';
+/**
+ * A format-neutral view of one map object, as handed to a
+ * {@link import('./MapObjectSpawner').MapObjectFactory}.
+ *
+ * The descriptor is what game code writes against: it resolves the two things
+ * that differ between authoring formats - stable identity and the dispatch
+ * key - and pairs the object with the layer it came from. The parsed object
+ * itself stays reachable through {@link object}, and the untouched source
+ * record through {@link TileMapObject.source}.
+ */
+export interface MapObjectDescriptor {
+    /**
+     * Stable identity for this object.
+     *
+     * Uniqueness domain is **one {@link TileMap}**: Tiled object ids are unique
+     * within a map, and LDtk entity iids are unique globally, so an LDtk-sourced
+     * id keeps that stronger guarantee. Combine with the owning level's id if a
+     * world-wide key is needed.
+     *
+     * Derived from {@link TileMapObject.sourceId} when the format supplies one,
+     * otherwise from the numeric {@link TileMapObject.id}.
+     */
+    readonly id: string;
+    /**
+     * Canonical dispatch key - the object's class/type string, or `null` when the
+     * source declares none.
+     *
+     * LDtk fills it with the entity definition identifier, Tiled with the
+     * object's class. A {@link import('./MapObjectSpawner').MapObjectSpawner}
+     * uses it to pick a factory unless an `identify` strategy overrides that.
+     */
+    readonly kind: string | null;
+    /** Object name; may be empty and is not unique. */
+    readonly name: string;
+    /** X of the object origin in object-layer pixel space. */
+    readonly x: number;
+    /** Y of the object origin in object-layer pixel space. */
+    readonly y: number;
+    /** Bounding width in px (0 for points). */
+    readonly width: number;
+    /** Bounding height in px (0 for points). */
+    readonly height: number;
+    /** Rotation in degrees, clockwise. See {@link TileMapObject} for the pivot. */
+    readonly rotation: number;
+    /** The object's immutable custom properties. */
+    readonly properties: TileProperties;
+    /** The object layer this object was authored on, with its placement metadata. */
+    readonly layer: ObjectLayer;
+    /** The parsed object itself - narrow on `object.kind` to read geometry. */
+    readonly object: TileMapObject;
+}
+/**
+ * Build the {@link MapObjectDescriptor} for one object of `layer`.
+ *
+ * Exposed for code that spawns from a hand-picked object rather than from a
+ * whole map; {@link mapObjectDescriptors} covers the common case.
+ */
+export declare const mapObjectDescriptor: (object: TileMapObject, layer: ObjectLayer) => MapObjectDescriptor;
+/**
+ * Every object of `map`, in a defined order: object-layer order first, then
+ * object order within each layer.
+ *
+ * This is the order a {@link import('./MapObjectSpawner').MapObjectSpawner}
+ * spawns in, so the same map always produces the same sequence.
+ */
+export declare const mapObjectDescriptors: (map: TileMap) => Generator<MapObjectDescriptor>;
+//# sourceMappingURL=MapObject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MapObject.d.ts","sourceRoot":"","sources":["../../src/MapObject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,aAAa,EAAE,OAAO,WAAW,KAAG,mBAY9E,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAc,KAAK,OAAO,KAAG,SAAS,CAAC,mBAAmB,CAM1F,CAAC"}

package/dist/esm/MapObject.js

@@ -0,0 +1,34 @@
+//#region src/MapObject.ts
+/**
+* Build the {@link MapObjectDescriptor} for one object of `layer`.
+*
+* Exposed for code that spawns from a hand-picked object rather than from a
+* whole map; {@link mapObjectDescriptors} covers the common case.
+*/
+const mapObjectDescriptor = (object, layer) => ({
+	id: object.sourceId ?? String(object.id),
+	kind: object.type === "" ? null : object.type,
+	name: object.name,
+	x: object.x,
+	y: object.y,
+	width: object.width,
+	height: object.height,
+	rotation: object.rotation,
+	properties: object.properties,
+	layer,
+	object
+});
+/**
+* Every object of `map`, in a defined order: object-layer order first, then
+* object order within each layer.
+*
+* This is the order a {@link import('./MapObjectSpawner').MapObjectSpawner}
+* spawns in, so the same map always produces the same sequence.
+*/
+const mapObjectDescriptors = function* (map) {
+	for (const layer of map.objectLayers) for (const object of layer.objects) yield mapObjectDescriptor(object, layer);
+};
+
+//#endregion
+export { mapObjectDescriptor, mapObjectDescriptors };
+//# sourceMappingURL=MapObject.js.map

package/dist/esm/MapObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapObject.js","names":[],"sources":["../../src/MapObject.ts"],"sourcesContent":["import type { ObjectLayer, TileMapObject } from './ObjectLayer';\nimport type { TileMap } from './TileMap';\nimport type { TileProperties } from './types';\n\n/**\n * A format-neutral view of one map object, as handed to a\n * {@link import('./MapObjectSpawner').MapObjectFactory}.\n *\n * The descriptor is what game code writes against: it resolves the two things\n * that differ between authoring formats - stable identity and the dispatch\n * key - and pairs the object with the layer it came from. The parsed object\n * itself stays reachable through {@link object}, and the untouched source\n * record through {@link TileMapObject.source}.\n */\nexport interface MapObjectDescriptor {\n  /**\n   * Stable identity for this object.\n   *\n   * Uniqueness domain is **one {@link TileMap}**: Tiled object ids are unique\n   * within a map, and LDtk entity iids are unique globally, so an LDtk-sourced\n   * id keeps that stronger guarantee. Combine with the owning level's id if a\n   * world-wide key is needed.\n   *\n   * Derived from {@link TileMapObject.sourceId} when the format supplies one,\n   * otherwise from the numeric {@link TileMapObject.id}.\n   */\n  readonly id: string;\n  /**\n   * Canonical dispatch key - the object's class/type string, or `null` when the\n   * source declares none.\n   *\n   * LDtk fills it with the entity definition identifier, Tiled with the\n   * object's class. A {@link import('./MapObjectSpawner').MapObjectSpawner}\n   * uses it to pick a factory unless an `identify` strategy overrides that.\n   */\n  readonly kind: string | null;\n  /** Object name; may be empty and is not unique. */\n  readonly name: string;\n  /** X of the object origin in object-layer pixel space. */\n  readonly x: number;\n  /** Y of the object origin in object-layer pixel space. */\n  readonly y: number;\n  /** Bounding width in px (0 for points). */\n  readonly width: number;\n  /** Bounding height in px (0 for points). */\n  readonly height: number;\n  /** Rotation in degrees, clockwise. See {@link TileMapObject} for the pivot. */\n  readonly rotation: number;\n  /** The object's immutable custom properties. */\n  readonly properties: TileProperties;\n  /** The object layer this object was authored on, with its placement metadata. */\n  readonly layer: ObjectLayer;\n  /** The parsed object itself - narrow on `object.kind` to read geometry. */\n  readonly object: TileMapObject;\n}\n\n/**\n * Build the {@link MapObjectDescriptor} for one object of `layer`.\n *\n * Exposed for code that spawns from a hand-picked object rather than from a\n * whole map; {@link mapObjectDescriptors} covers the common case.\n */\nexport const mapObjectDescriptor = (object: TileMapObject, layer: ObjectLayer): MapObjectDescriptor => ({\n  id: object.sourceId ?? String(object.id),\n  kind: object.type === '' ? null : object.type,\n  name: object.name,\n  x: object.x,\n  y: object.y,\n  width: object.width,\n  height: object.height,\n  rotation: object.rotation,\n  properties: object.properties,\n  layer,\n  object,\n});\n\n/**\n * Every object of `map`, in a defined order: object-layer order first, then\n * object order within each layer.\n *\n * This is the order a {@link import('./MapObjectSpawner').MapObjectSpawner}\n * spawns in, so the same map always produces the same sequence.\n */\nexport const mapObjectDescriptors = function* (map: TileMap): Generator<MapObjectDescriptor> {\n  for (const layer of map.objectLayers) {\n    for (const object of layer.objects) {\n      yield mapObjectDescriptor(object, layer);\n    }\n  }\n};\n"],"mappings":";;;;;;;AA8DA,MAAa,uBAAuB,QAAuB,WAA6C;CACtG,IAAI,OAAO,YAAY,OAAO,OAAO,EAAE;CACvC,MAAM,OAAO,SAAS,KAAK,OAAO,OAAO;CACzC,MAAM,OAAO;CACb,GAAG,OAAO;CACV,GAAG,OAAO;CACV,OAAO,OAAO;CACd,QAAQ,OAAO;CACf,UAAU,OAAO;CACjB,YAAY,OAAO;CACnB;CACA;AACF;;;;;;;;AASA,MAAa,uBAAuB,WAAW,KAA8C;CAC3F,KAAK,MAAM,SAAS,IAAI,cACtB,KAAK,MAAM,UAAU,MAAM,SACzB,MAAM,oBAAoB,QAAQ,KAAK;AAG7C"}