@codexo/exojs-tilemap 0.13.0 → 0.15.0

package/dist/esm/ImageLayer.d.ts

@@ -0,0 +1,81 @@
+import type { Texture } from '@codexo/exojs';
+import type { TileProperties } from './types';
+/** Construction options for an {@link ImageLayer}. */
+export interface ImageLayerOptions {
+    /** Layer id (unique within the map). */
+    readonly id: number;
+    /** Layer name. */
+    readonly name?: string;
+    /** Layer class string. */
+    readonly class?: string;
+    /** Resolved image URL. */
+    readonly image: string;
+    /** Loaded texture for the image, or `null` if unavailable. */
+    readonly texture?: Texture | null;
+    /** Whether the layer is visible. Default `true`. */
+    readonly visible?: boolean;
+    /** Layer opacity in `[0, 1]`. Default `1`. */
+    readonly opacity?: number;
+    /** Layer pixel offset X. Default `0`. */
+    readonly offsetX?: number;
+    /** Layer pixel offset Y. Default `0`. */
+    readonly offsetY?: number;
+    /** Horizontal parallax factor. Default `1`. */
+    readonly parallaxX?: number;
+    /** Vertical parallax factor. Default `1`. */
+    readonly parallaxY?: number;
+    /** Tint colour as `0xRRGGBB`, or `null`. Default `null`. */
+    readonly tintColor?: number | null;
+    /** Whether the image repeats horizontally. Default `false`. */
+    readonly repeatX?: boolean;
+    /** Whether the image repeats vertically. Default `false`. */
+    readonly repeatY?: boolean;
+    /** Layer properties (copied and frozen). */
+    readonly properties?: TileProperties;
+}
+/**
+ * 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
+ */
+export declare class ImageLayer {
+    /** Layer-kind discriminant. */
+    readonly kind: "image";
+    /** Layer id (unique within the map). */
+    readonly id: number;
+    /** Layer name. */
+    readonly name: string;
+    /** Layer class string. */
+    readonly class: string;
+    /** Resolved URL of the layer image. */
+    readonly image: string;
+    /** Loaded texture for the image, or `null` if unavailable. */
+    readonly texture: Texture | null;
+    /** Whether the layer is visible. */
+    readonly visible: boolean;
+    /** Layer opacity in `[0, 1]`. */
+    readonly opacity: number;
+    /** Layer pixel offset X. */
+    readonly offsetX: number;
+    /** Layer pixel offset Y. */
+    readonly offsetY: number;
+    /** Horizontal parallax factor. */
+    readonly parallaxX: number;
+    /** Vertical parallax factor. */
+    readonly parallaxY: number;
+    /** Tint colour as `0xRRGGBB`, or `null`. */
+    readonly tintColor: number | null;
+    /** Whether the image repeats horizontally. */
+    readonly repeatX: boolean;
+    /** Whether the image repeats vertically. */
+    readonly repeatY: boolean;
+    /** Immutable layer properties. */
+    readonly properties: TileProperties;
+    constructor(options: ImageLayerOptions);
+}

package/dist/esm/ImageLayer.js

@@ -0,0 +1,67 @@
+/**
+ * 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({});
+    }
+}
+
+export { ImageLayer };
+//# sourceMappingURL=ImageLayer.js.map

package/dist/esm/ImageLayer.js.map

@@ -0,0 +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;;;;"}

package/dist/esm/ObjectLayer.d.ts

@@ -0,0 +1,277 @@
+import type { ResolvedTile, TileProperties, TilePropertyValue } from './types';
+/**
+ * Geometry kinds for a {@link TileMapObject}, as an `as const` value object.
+ *
+ * Modelled as a frozen string map (not a TS `enum`) so the values stay
+ * wire-compatible with the Tiled string serialisation, survive
+ * `verbatimModuleSyntax` (no emitted runtime helper), and follow the package
+ * convention for enum-like constants. Use the members for ergonomic, typo-safe
+ * call sites: `layer.byKind(ObjectKind.Polygon)`.
+ * @stable
+ */
+export declare const ObjectKind: {
+    readonly Rectangle: "rectangle";
+    readonly Ellipse: "ellipse";
+    readonly Polygon: "polygon";
+    readonly Polyline: "polyline";
+    readonly Point: "point";
+    readonly Tile: "tile";
+    readonly Text: "text";
+};
+/** Geometry discriminant for a {@link TileMapObject}. */
+export type ObjectKind = (typeof ObjectKind)[keyof typeof ObjectKind];
+/**
+ * Geometry discriminant for a {@link TileMapObject}.
+ * Structural alias of {@link ObjectKind}; retained so existing code keeps
+ * compiling. New code may prefer {@link ObjectKind}.
+ */
+export type TileMapObjectKind = ObjectKind;
+/** A point in object-layer space (pixels, relative to the object). */
+export interface ObjectPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Fields shared by every {@link TileMapObject} kind. */
+interface TileMapObjectBase<P extends TileProperties = TileProperties> {
+    /** Source-unique object id. */
+    readonly id: number;
+    /** Object name (may be empty; not unique). */
+    readonly name: string;
+    /** Object class/type string (Tiled `type`/`class`; may be empty). */
+    readonly type: 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, about the object origin. */
+    readonly rotation: number;
+    /** Whether the object is marked visible. */
+    readonly visible: boolean;
+    /** Immutable custom properties. */
+    readonly properties: P;
+}
+/** An axis-aligned rectangle object spanning `[x, y, width, height]`. */
+export interface RectangleObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Rectangle;
+}
+/** An ellipse inscribed in `[x, y, width, height]`. */
+export interface EllipseObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Ellipse;
+}
+/** A single point at `(x, y)`. */
+export interface PointObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Point;
+}
+/** A closed polygon; `points` are relative to the object origin. */
+export interface PolygonObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Polygon;
+    readonly points: readonly ObjectPoint[];
+}
+/** An open polyline; `points` are relative to the object origin. */
+export interface PolylineObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Polyline;
+    readonly points: readonly ObjectPoint[];
+}
+/** A tile (GID) object carrying a resolved tile reference. */
+export interface TileObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Tile;
+    readonly tile: ResolvedTile;
+}
+/** Text styling options carried by a {@link TextObject}. */
+export interface TextStyle {
+    /** The text content. */
+    readonly text: string;
+    /** Text colour as 0xRRGGBB, or `null` if default. */
+    readonly color?: number | null;
+    /** Font family name. */
+    readonly fontFamily?: string;
+    /** Font size in pixels. */
+    readonly pixelSize?: number;
+    /** Bold text. */
+    readonly bold?: boolean;
+    /** Italic text. */
+    readonly italic?: boolean;
+    /** Underline text. */
+    readonly underline?: boolean;
+    /** Strikeout text. */
+    readonly strikeout?: boolean;
+    /** Wrap text within the object bounds. */
+    readonly wrap?: boolean;
+    /** Horizontal alignment. */
+    readonly halign?: 'left' | 'center' | 'right' | 'justify';
+    /** Vertical alignment. */
+    readonly valign?: 'top' | 'center' | 'bottom';
+}
+/** A text object carrying styled text content within `[x, y, width, height]`. */
+export interface TextObject<P extends TileProperties = TileProperties> extends TileMapObjectBase<P> {
+    readonly kind: typeof ObjectKind.Text;
+    readonly text: TextStyle;
+}
+/**
+ * A format-independent map object. The geometry kind is the discriminant;
+ * narrow on `kind` to read shape-specific fields. Template objects are not
+ * yet represented.
+ *
+ * The optional property-shape parameter `P` lets typed accessors
+ * (see {@link ObjectLayer.byType}) narrow `properties` to a developer-declared
+ * schema. It defaults to the generic {@link TileProperties} bag, so the plain
+ * `TileMapObject` form is unchanged.
+ * @advanced
+ */
+export type TileMapObject<P extends TileProperties = TileProperties> = RectangleObject<P> | EllipseObject<P> | PointObject<P> | PolygonObject<P> | PolylineObject<P> | TileObject<P> | TextObject<P>;
+/**
+ * A developer-declared mapping from object `type`/class strings to the property
+ * shape an object of that type is expected to carry. Supplied as the type
+ * parameter to {@link ObjectLayer} to unlock the typed accessors
+ * ({@link ObjectLayer.byType}, {@link ObjectLayer.where}).
+ *
+ * @remarks
+ * A schema is a **developer promise, not a runtime guarantee.** Tiled data is
+ * untyped at runtime and ExoJS performs no validation against the schema —
+ * the property objects are returned exactly as parsed. The schema only refines
+ * the static type of `properties` for ergonomic, typo-safe field access. If the
+ * source data does not match the declared shape, reads still succeed but the
+ * static type is a fiction. Validate at the boundary if you need certainty.
+ *
+ * @example
+ * ```ts
+ * const EntityType = { Spawn: 'spawn', Pickup: 'pickup' } as const;
+ * interface LevelObjects {
+ *   [EntityType.Spawn]:  { team: 'red' | 'blue' };
+ *   [EntityType.Pickup]: { item: 'coin' | 'gem'; amount: number };
+ * }
+ * const entities = map.getObjectLayer<LevelObjects>('Entities');
+ * entities.byType(EntityType.Spawn)[0].properties.team; // 'red' | 'blue'
+ * ```
+ * @stable
+ */
+export type ObjectSchema = Record<string, TileProperties>;
+/**
+ * A {@link TileMapObject} whose `properties` are narrowed to the schema shape
+ * declared for the object `type` `T` in schema `S`.
+ * @advanced
+ */
+export type TypedObject<S extends ObjectSchema, T extends keyof S & string> = TileMapObject<S[T]>;
+/** Filter for {@link ObjectLayer.query}. Unspecified fields match everything. */
+export interface ObjectQuery {
+    /** Match objects whose `name` equals this. */
+    readonly name?: string;
+    /** Match objects whose `type`/class equals this. */
+    readonly type?: string;
+    /** Match objects of this geometry kind. */
+    readonly kind?: TileMapObjectKind;
+    /** Match objects that carry this property key. */
+    readonly property?: string;
+    /** When combined with `property`, also require the property value to equal this. */
+    readonly value?: TilePropertyValue;
+}
+/** Construction options for an {@link ObjectLayer}. */
+export interface ObjectLayerOptions {
+    /** Layer id (unique within the map). */
+    readonly id: number;
+    /** Layer name. */
+    readonly name?: string;
+    /** Layer class string. */
+    readonly class?: string;
+    /** Whether the layer is visible. Default `true`. */
+    readonly visible?: boolean;
+    /** Layer opacity in `[0, 1]`. Default `1`. */
+    readonly opacity?: number;
+    /** Layer pixel offset X. Default `0`. */
+    readonly offsetX?: number;
+    /** Layer pixel offset Y. Default `0`. */
+    readonly offsetY?: number;
+    /**
+     * Draw order for the objects (Tiled `draworder`): `'topdown'` (sorted by `y`)
+     * or `'index'` (source order). Informational; objects are stored as given.
+     * Default `'topdown'`.
+     */
+    readonly drawOrder?: 'topdown' | 'index';
+    /** The objects in this layer. */
+    readonly objects?: readonly TileMapObject[];
+    /** Layer-level properties (copied and frozen). */
+    readonly properties?: TileProperties;
+}
+/**
+ * A data-only layer of {@link TileMapObject}s — spawn points, trigger zones,
+ * collision regions, markers. Object layers are not rendered by the tile
+ * renderer; they are parsed and exposed for gameplay use (e.g. building physics
+ * colliders, placing entities).
+ *
+ * Query with {@link query} (untyped, fully back-compatible) or, when an
+ * {@link ObjectSchema} type argument `S` is supplied, with the typed accessors
+ * {@link byType}, {@link byKind}, and {@link where} — these narrow `properties`
+ * to the developer-declared shape. The schema is **opt-in**: the default type
+ * parameter reproduces the original untyped behaviour, so
+ * `new ObjectLayer(options)` and `map.getObjectLayer('x')` are unchanged.
+ *
+ * @remarks
+ * A schema is a developer promise, not a runtime guarantee — Tiled data is
+ * untyped at runtime and ExoJS performs no validation. See {@link ObjectSchema}.
+ *
+ * @typeParam S - Optional {@link ObjectSchema} mapping object `type` strings to
+ * their property shapes. Defaults to a generic schema (every type maps to the
+ * loose {@link TileProperties} bag).
+ *
+ * @advanced
+ */
+export declare class ObjectLayer<S extends ObjectSchema = ObjectSchema> {
+    /** Layer-kind discriminant (distinguishes object layers from tile layers). */
+    readonly kind: "object";
+    /** Layer id (unique within the map). */
+    readonly id: number;
+    /** Layer name. */
+    readonly name: string;
+    /** Layer class string. */
+    readonly class: string;
+    /** Whether the layer is visible. */
+    readonly visible: boolean;
+    /** Layer opacity in `[0, 1]`. */
+    readonly opacity: number;
+    /** Layer pixel offset X. */
+    readonly offsetX: number;
+    /** Layer pixel offset Y. */
+    readonly offsetY: number;
+    /** Draw order for the objects (Tiled `draworder`). Informational. */
+    readonly drawOrder: 'topdown' | 'index';
+    /** Immutable layer-level properties. */
+    readonly properties: TileProperties;
+    /** The objects in this layer (insertion order). */
+    readonly objects: readonly TileMapObject[];
+    constructor(options: ObjectLayerOptions);
+    /** Objects matching every specified criterion of `filter`. Returns a fresh array. */
+    query(filter?: ObjectQuery): TileMapObject[];
+    /**
+     * Objects whose `type` equals `type`, with `properties` narrowed to the
+     * schema shape `S[T]`. Returns a fresh array (insertion order).
+     *
+     * The narrowing is a static convenience only — no runtime validation is
+     * performed (see {@link ObjectSchema}). On an unschematised layer this
+     * behaves like `query({ type })` with `TileProperties` properties.
+     */
+    byType<T extends keyof S & string>(type: T): Array<TypedObject<S, T>>;
+    /**
+     * Objects of the given geometry {@link ObjectKind}, narrowed to that
+     * geometry's member type (e.g. `byKind(ObjectKind.Polygon)` yields
+     * {@link PolygonObject}s with their `points`). Returns a fresh array.
+     */
+    byKind<K extends ObjectKind>(kind: K): Array<Extract<TileMapObject, {
+        kind: K;
+    }>>;
+    /**
+     * Objects of `type` (typed as in {@link byType}) that also satisfy
+     * `predicate`. A convenience combination of {@link byType} and `Array.filter`
+     * that keeps the narrowed `properties` type inside the predicate. Returns a
+     * fresh array.
+     */
+    where<T extends keyof S & string>(type: T, predicate: (object: TypedObject<S, T>) => boolean): Array<TypedObject<S, T>>;
+    /** First object with the given id, or undefined. */
+    getObjectById(id: number): TileMapObject | undefined;
+    /** First object with the given name, or undefined. */
+    getObjectByName(name: string): TileMapObject | undefined;
+}
+export {};

package/dist/esm/ObjectLayer.js

@@ -0,0 +1,176 @@
+import { TilePropertyKind } from './types.js';
+
+/**
+ * Geometry kinds for a {@link TileMapObject}, as an `as const` value object.
+ *
+ * Modelled as a frozen string map (not a TS `enum`) so the values stay
+ * wire-compatible with the Tiled string serialisation, survive
+ * `verbatimModuleSyntax` (no emitted runtime helper), and follow the package
+ * convention for enum-like constants. Use the members for ergonomic, typo-safe
+ * call sites: `layer.byKind(ObjectKind.Polygon)`.
+ * @stable
+ */
+const ObjectKind = {
+    Rectangle: 'rectangle',
+    Ellipse: 'ellipse',
+    Polygon: 'polygon',
+    Polyline: 'polyline',
+    Point: 'point',
+    Tile: 'tile',
+    Text: 'text',
+};
+/**
+ * Type guard for the {@link TilePropertyObjectRef} variant of
+ * {@link TilePropertyValue}.
+ * @internal
+ */
+function isTilePropertyObjectRef(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.kind === TilePropertyKind.ObjectRef);
+}
+/**
+ * Equality used by {@link ObjectLayer.query}'s `value` filter.
+ *
+ * Scalars and `null` compare with `===`. `objectRef` values compare by `id`
+ * alone — the one genuinely common "find all objects referencing X" query
+ * need — regardless of differing LDtk navigation fields. Every other
+ * structured shape (`point`, `tileRef`, arrays, nested property bags) has no
+ * obvious value-equality semantics (exact float coordinates? array order?)
+ * and only matches when reference-identical; use `query({ property })`
+ * (presence-only) for those.
+ * @internal
+ */
+function tilePropertyValueEquals(a, b) {
+    if (a === b)
+        return true;
+    if (isTilePropertyObjectRef(a) && isTilePropertyObjectRef(b))
+        return a.id === b.id;
+    return false;
+}
+/**
+ * A data-only layer of {@link TileMapObject}s — spawn points, trigger zones,
+ * collision regions, markers. Object layers are not rendered by the tile
+ * renderer; they are parsed and exposed for gameplay use (e.g. building physics
+ * colliders, placing entities).
+ *
+ * Query with {@link query} (untyped, fully back-compatible) or, when an
+ * {@link ObjectSchema} type argument `S` is supplied, with the typed accessors
+ * {@link byType}, {@link byKind}, and {@link where} — these narrow `properties`
+ * to the developer-declared shape. The schema is **opt-in**: the default type
+ * parameter reproduces the original untyped behaviour, so
+ * `new ObjectLayer(options)` and `map.getObjectLayer('x')` are unchanged.
+ *
+ * @remarks
+ * A schema is a developer promise, not a runtime guarantee — Tiled data is
+ * untyped at runtime and ExoJS performs no validation. See {@link ObjectSchema}.
+ *
+ * @typeParam S - Optional {@link ObjectSchema} mapping object `type` strings to
+ * their property shapes. Defaults to a generic schema (every type maps to the
+ * loose {@link TileProperties} bag).
+ *
+ * @advanced
+ */
+class ObjectLayer {
+    /** Layer-kind discriminant (distinguishes object layers from tile layers). */
+    kind = 'object';
+    /** Layer id (unique within the map). */
+    id;
+    /** Layer name. */
+    name;
+    /** Layer class string. */
+    class;
+    /** Whether the layer is visible. */
+    visible;
+    /** Layer opacity in `[0, 1]`. */
+    opacity;
+    /** Layer pixel offset X. */
+    offsetX;
+    /** Layer pixel offset Y. */
+    offsetY;
+    /** Draw order for the objects (Tiled `draworder`). Informational. */
+    drawOrder;
+    /** Immutable layer-level properties. */
+    properties;
+    /** The objects in this layer (insertion order). */
+    objects;
+    constructor(options) {
+        this.id = options.id;
+        this.name = options.name ?? '';
+        this.class = options.class ?? '';
+        this.visible = options.visible ?? true;
+        this.opacity = options.opacity ?? 1;
+        this.offsetX = options.offsetX ?? 0;
+        this.offsetY = options.offsetY ?? 0;
+        this.drawOrder = options.drawOrder ?? 'topdown';
+        this.properties = options.properties ? Object.freeze({ ...options.properties }) : Object.freeze({});
+        this.objects = options.objects ? Object.freeze([...options.objects]) : Object.freeze([]);
+    }
+    /** Objects matching every specified criterion of `filter`. Returns a fresh array. */
+    query(filter = {}) {
+        return this.objects.filter(object => {
+            if (filter.name !== undefined && object.name !== filter.name) {
+                return false;
+            }
+            if (filter.type !== undefined && object.type !== filter.type) {
+                return false;
+            }
+            if (filter.kind !== undefined && object.kind !== filter.kind) {
+                return false;
+            }
+            if (filter.property !== undefined) {
+                // TilePropertyValue never includes `undefined`, so an `undefined`
+                // read is a reliable "key absent" signal (equivalent to, but avoids
+                // re-indexing after, an `in` check).
+                const value = object.properties[filter.property];
+                if (value === undefined) {
+                    return false;
+                }
+                if (filter.value !== undefined && !tilePropertyValueEquals(value, filter.value)) {
+                    return false;
+                }
+            }
+            return true;
+        });
+    }
+    /**
+     * Objects whose `type` equals `type`, with `properties` narrowed to the
+     * schema shape `S[T]`. Returns a fresh array (insertion order).
+     *
+     * The narrowing is a static convenience only — no runtime validation is
+     * performed (see {@link ObjectSchema}). On an unschematised layer this
+     * behaves like `query({ type })` with `TileProperties` properties.
+     */
+    byType(type) {
+        return this.objects.filter(object => object.type === type);
+    }
+    /**
+     * Objects of the given geometry {@link ObjectKind}, narrowed to that
+     * geometry's member type (e.g. `byKind(ObjectKind.Polygon)` yields
+     * {@link PolygonObject}s with their `points`). Returns a fresh array.
+     */
+    byKind(kind) {
+        return this.objects.filter(object => object.kind === kind);
+    }
+    /**
+     * Objects of `type` (typed as in {@link byType}) that also satisfy
+     * `predicate`. A convenience combination of {@link byType} and `Array.filter`
+     * that keeps the narrowed `properties` type inside the predicate. Returns a
+     * fresh array.
+     */
+    where(type, predicate) {
+        return this.byType(type).filter(object => predicate(object));
+    }
+    /** First object with the given id, or undefined. */
+    getObjectById(id) {
+        return this.objects.find(object => object.id === id);
+    }
+    /** First object with the given name, or undefined. */
+    getObjectByName(name) {
+        return this.objects.find(object => object.name === name);
+    }
+}
+
+export { ObjectKind, ObjectLayer };
+//# sourceMappingURL=ObjectLayer.js.map

package/dist/esm/ObjectLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectLayer.js","sources":["../../../src/ObjectLayer.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAGA;;;;;;;;;AASG;AACI,MAAM,UAAU,GAAG;AACxB,IAAA,SAAS,EAAE,WAAW;AACtB,IAAA,OAAO,EAAE,SAAS;AAClB,IAAA,OAAO,EAAE,SAAS;AAClB,IAAA,QAAQ,EAAE,UAAU;AACpB,IAAA,KAAK,EAAE,OAAO;AACd,IAAA,IAAI,EAAE,MAAM;AACZ,IAAA,IAAI,EAAE,MAAM;;AAiLd;;;;AAIG;AACH,SAAS,uBAAuB,CAAC,KAAwB,EAAA;AACvD,IAAA,QACE,OAAO,KAAK,KAAK,QAAQ;AACzB,QAAA,KAAK,KAAK,IAAI;AACd,QAAA,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;AACpB,QAAA,KAA4B,CAAC,IAAI,KAAK,gBAAgB,CAAC,SAAS;AAErE;AAEA;;;;;;;;;;;AAWG;AACH,SAAS,uBAAuB,CAAC,CAAoB,EAAE,CAAoB,EAAA;IACzE,IAAI,CAAC,KAAK,CAAC;AAAE,QAAA,OAAO,IAAI;IACxB,IAAI,uBAAuB,CAAC,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,CAAC;AAAE,QAAA,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;AAClF,IAAA,OAAO,KAAK;AACd;AA8BA;;;;;;;;;;;;;;;;;;;;;;AAsBG;MACU,WAAW,CAAA;;IAEN,IAAI,GAAG,QAAiB;;AAGxB,IAAA,EAAE;;AAEF,IAAA,IAAI;;AAEJ,IAAA,KAAK;;AAEL,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,OAAO;;AAEP,IAAA,SAAS;;AAET,IAAA,UAAU;;AAEV,IAAA,OAAO;AAEvB,IAAA,WAAA,CAAmB,OAA2B,EAAA;AAC5C,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;QAChC,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,SAAS;AAC/C,QAAA,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;AACnG,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1F;;IAGO,KAAK,CAAC,SAAsB,EAAE,EAAA;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAG;AAClC,YAAA,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE;AAC5D,gBAAA,OAAO,KAAK;YACd;AAEA,YAAA,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE;AAC5D,gBAAA,OAAO,KAAK;YACd;AAEA,YAAA,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE;AAC5D,gBAAA,OAAO,KAAK;YACd;AAEA,YAAA,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE;;;;gBAIjC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC;AAChD,gBAAA,IAAI,KAAK,KAAK,SAAS,EAAE;AACvB,oBAAA,OAAO,KAAK;gBACd;AAEA,gBAAA,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;AAC/E,oBAAA,OAAO,KAAK;gBACd;YACF;AAEA,YAAA,OAAO,IAAI;AACb,QAAA,CAAC,CAAC;IACJ;AAEA;;;;;;;AAOG;AACI,IAAA,MAAM,CAA6B,IAAO,EAAA;AAC/C,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAwC;IACnG;AAEA;;;;AAIG;AACI,IAAA,MAAM,CAAuB,IAAO,EAAA;AACzC,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAA+C;IAC1G;AAEA;;;;;AAKG;IACI,KAAK,CACV,IAAO,EACP,SAAiD,EAAA;AAEjD,QAAA,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9D;;AAGO,IAAA,aAAa,CAAC,EAAU,EAAA;AAC7B,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACtD;;AAGO,IAAA,eAAe,CAAC,IAAY,EAAA;AACjC,QAAA,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC;IAC1D;AACD;;;;"}

package/dist/esm/TileAnimator.d.ts

@@ -0,0 +1,62 @@
+import type { TileLayer } from './TileLayer';
+/**
+ * Drives per-tile animations on one or more {@link TileLayer}s, RPG-Maker style.
+ *
+ * On construction it scans the given layer(s) once and registers every cell
+ * whose tile carries an `animation` (see {@link import('./types').TileDefinition}).
+ * Each {@link update} advances a shared clock and rewrites **only** the
+ * registered animated cells, and **only** when a cell crosses a frame boundary —
+ * static tiles are never touched. Because a tile rewrite goes through
+ * `layer.setTileAt`, only the chunks that actually contain animated cells rebuild
+ * their geometry, and only on the (infrequent) frames where a boundary is
+ * crossed. The large static body of the map never rebuilds.
+ *
+ * Tick it from your update loop, like `TweenSequencer`:
+ *
+ * ```ts
+ * const animator = new TileAnimator(map.layers);
+ * scene.systems.add({ update: (t) => animator.update(t.deltaSeconds) });
+ * ```
+ *
+ * The animator references — but never owns — the layers and their tilesets;
+ * {@link destroy} only drops its own cell registry.
+ *
+ * @advanced
+ */
+export declare class TileAnimator {
+    private readonly _layers;
+    private _cells;
+    private _elapsedMs;
+    /**
+     * @param layers One layer, or an array of layers (e.g. `map.layers`), to scan
+     *               for animated tiles.
+     */
+    constructor(layers: TileLayer | readonly TileLayer[]);
+    /** Number of animated cells currently registered across all layers. */
+    get animatedCellCount(): number;
+    /** Total elapsed animation time in milliseconds since construction/reset. */
+    get elapsedMs(): number;
+    /**
+     * Advance all registered animations by `deltaSeconds` and write the current
+     * frame into any cell that crossed a frame boundary. Cells that did not change
+     * frame are not touched, so their chunks do not rebuild.
+     *
+     * @param deltaSeconds Elapsed wall-clock time since the last call, in seconds.
+     */
+    update(deltaSeconds: number): void;
+    /**
+     * Restore every animated cell to its first frame and reset the clock.
+     * Useful before serialising or pausing.
+     */
+    reset(): void;
+    /**
+     * Re-scan the layers for animated cells. Call after structural edits that add
+     * or remove animated tiles. Resets all currently-tracked cells to frame 0
+     * first so the rescan starts from a clean, deterministic state.
+     */
+    rescan(): void;
+    /** Drop the cell registry. Does not modify the layers or tilesets. */
+    destroy(): void;
+    /** Scan all layers for cells whose tile carries a (multi-frame) animation. */
+    private _scan;
+}