@yagejs/tilemap 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,333 @@
+import { Plugin, EngineContext, SystemScheduler, Component, System, Phase, AssetHandle } from '@yagejs/core';
+import { Container, ExtensionType, LoaderParser } from 'pixi.js';
+import { ColliderConfig } from '@yagejs/physics';
+import { CompositeTilemap } from '@pixi/tilemap';
+
+/** Plugin that adds Tiled map loading and rendering to YAGE. */
+declare class TilemapPlugin implements Plugin {
+    readonly name = "tilemap";
+    readonly version = "2.0.0";
+    readonly dependencies: readonly ["renderer"];
+    install(context: EngineContext): void;
+    registerSystems(scheduler: SystemScheduler): void;
+}
+
+interface TiledMapData {
+    width: number;
+    height: number;
+    tilewidth: number;
+    tileheight: number;
+    layers: (TileLayer | ObjectGroup)[];
+    tilesets: TilesetRef[];
+    orientation?: string;
+    renderorder?: string;
+    infinite?: boolean;
+    nextlayerid?: number;
+    nextobjectid?: number;
+    tiledversion?: string;
+    type?: string;
+    version?: string | number;
+}
+interface TileLayer {
+    type: "tilelayer";
+    data: number[];
+    width: number;
+    height: number;
+    id: number;
+    name: string;
+    opacity: number;
+    visible: boolean;
+    x: number;
+    y: number;
+}
+interface ObjectGroup {
+    type: "objectgroup";
+    id: number;
+    name: string;
+    objects: TileObject[];
+    opacity: number;
+    visible: boolean;
+    x: number;
+    y: number;
+    draworder?: string;
+}
+interface RectangleObject {
+    id: number;
+    name: string;
+    class?: string;
+    type?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    visible: boolean;
+    point?: undefined | false;
+    polygon?: undefined;
+    properties?: TileObjectProperty[];
+}
+interface PolygonObject {
+    id: number;
+    name: string;
+    class?: string;
+    type?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    visible: boolean;
+    point?: undefined | false;
+    polygon: {
+        x: number;
+        y: number;
+    }[];
+    properties?: TileObjectProperty[];
+}
+interface PointObject {
+    id: number;
+    name: string;
+    class?: string;
+    type?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    visible: boolean;
+    point: true;
+    polygon?: undefined;
+    properties?: TileObjectProperty[];
+}
+type TileObject = RectangleObject | PointObject | PolygonObject;
+interface TileObjectProperty {
+    name: string;
+    type: string;
+    value: unknown;
+}
+interface TilesetRef {
+    firstgid: number;
+    source?: string;
+    /** Resolved tileset data — populated by the loader. */
+    data?: TilesetData;
+}
+interface TilesetData {
+    name: string;
+    tilewidth: number;
+    tileheight: number;
+    tilecount: number;
+    columns: number;
+    margin?: number;
+    spacing?: number;
+    /** Single-image tileset: path to the spritesheet image. */
+    image?: string;
+    imagewidth?: number;
+    imageheight?: number;
+    /** Collection-of-images tileset: individual tile metadata. */
+    tiles?: TileData[];
+    tiledversion?: string;
+    type?: string;
+    version?: string | number;
+}
+interface TileData {
+    id: number;
+    image?: string;
+    imagewidth?: number;
+    imageheight?: number;
+}
+
+interface TilemapData {
+    width: number;
+    height: number;
+    tileWidth: number;
+    tileHeight: number;
+    tileLayers: TileLayerData[];
+    objectLayers: ObjectLayerData[];
+}
+interface TileLayerData {
+    name: string;
+    data: number[];
+    width: number;
+    height: number;
+    visible: boolean;
+}
+interface ObjectLayerData {
+    name: string;
+    objects: MapObject[];
+    visible: boolean;
+}
+interface MapObject {
+    id: number;
+    name: string;
+    class?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    visible: boolean;
+    point?: boolean;
+    polygon?: {
+        x: number;
+        y: number;
+    }[];
+    properties?: MapObjectProperty[];
+}
+interface MapObjectProperty {
+    name: string;
+    type: string;
+    value: unknown;
+}
+/** Interface for anything that has a `properties` array (MapObject, etc.). */
+interface HasProperties {
+    properties?: MapObjectProperty[];
+}
+interface RectColliderConfig {
+    type: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface PolygonColliderConfig {
+    type: "polygon";
+    x: number;
+    y: number;
+    vertices: {
+        x: number;
+        y: number;
+    }[];
+}
+type TilemapColliderConfig = RectColliderConfig | PolygonColliderConfig;
+
+/** Options for creating a TilemapComponent. */
+interface TilemapComponentOptions {
+    /** Parsed Tiled map data (not serializable). */
+    map?: TiledMapData;
+    /** Asset path to the Tiled JSON (serializable, resolved via Assets.get). */
+    mapKey?: string;
+    /** Which tile layers to render. Omit to render all. */
+    layers?: string[];
+    /** Render layer name. Default: "default". */
+    layer?: string;
+}
+/** Serializable snapshot of a TilemapComponent. */
+interface TilemapComponentData {
+    mapKey: string;
+    layers?: string[];
+    layer: string;
+}
+/** Component that renders a Tiled map using @pixi/tilemap. */
+declare class TilemapComponent extends Component {
+    readonly container: Container;
+    readonly data: TilemapData;
+    private readonly _tiledMap;
+    private readonly _mapKey;
+    private readonly layerNames;
+    private readonly renderLayerName;
+    constructor(options: TilemapComponentOptions);
+    onAdd(): void;
+    onDestroy(): void;
+    serialize(): TilemapComponentData | null;
+    static fromSnapshot(data: TilemapComponentData): TilemapComponent;
+    /** Map width in pixels. */
+    get widthPx(): number;
+    /** Map height in pixels. */
+    get heightPx(): number;
+    /** Tile width in pixels. */
+    get tileWidth(): number;
+    /** Tile height in pixels. */
+    get tileHeight(): number;
+    /**
+     * Returns the tile GID at a world position, accounting for entity Transform offset.
+     * Returns null if the position is outside the map or the tile is empty.
+     */
+    getTileAt(worldX: number, worldY: number, layerName?: string): number | null;
+    /** Extract physics-agnostic collision shapes from object layers. */
+    getCollisionShapes(objectLayerName?: string): TilemapColliderConfig[];
+    /** Extract objects from object layers grouped by class/name. */
+    getObjects(objectLayerName?: string): Record<string, MapObject[]>;
+}
+
+/** Syncs Transform to TilemapComponent display containers. */
+declare class TilemapRenderSystem extends System {
+    readonly phase = Phase.Render;
+    readonly priority = -1;
+    private query;
+    onRegister(context: EngineContext): void;
+    update(): void;
+}
+
+/** Create a typed asset handle for a Tiled map JSON. */
+declare function tiledMap(path: string): AssetHandle<TiledMapData>;
+
+/**
+ * Extract physics-agnostic collision shapes from object layers.
+ *
+ * - Rectangle objects -> RectColliderConfig
+ * - Polygon objects -> PolygonColliderConfig
+ * - Point objects -> skipped (not collision shapes)
+ *
+ * @param map - Generic TilemapData.
+ * @param objectLayerName - Optional: only extract from this layer.
+ */
+declare function extractCollisionShapes(map: TilemapData, objectLayerName?: string): TilemapColliderConfig[];
+
+/**
+ * Convert tilemap TilemapColliderConfig[] (top-left origin rects/polygons) into
+ * physics-package ColliderConfig[] (center-origin shape + offset).
+ */
+declare function toPhysicsColliders(shapes: TilemapColliderConfig[]): ColliderConfig[];
+
+/**
+ * Get a single property value by name.
+ * Returns `undefined` if the property is not found.
+ */
+declare function getProperty<T = unknown>(obj: HasProperties, name: string): T | undefined;
+/**
+ * Get a pseudo-array of property values.
+ *
+ * Tiled doesn't support array properties natively, so a common convention
+ * is to use indexed names like `spawns[0]`, `spawns[1]`, etc.
+ * This function collects them into a proper array, preserving index order.
+ */
+declare function getPropertyArray<T = unknown>(obj: HasProperties, name: string): T[];
+/**
+ * Resolve a property of `type: "object"` (an ID reference) to the actual MapObject.
+ * Returns `undefined` if the property doesn't exist or the referenced object isn't found.
+ */
+declare function resolveObjectRef(obj: HasProperties, propName: string, allObjects: MapObject[]): MapObject | undefined;
+/**
+ * Resolve a pseudo-array of object ID references to actual MapObjects.
+ * Uses the `name[0]`, `name[1]` convention.
+ */
+declare function resolveObjectRefArray(obj: HasProperties, propName: string, allObjects: MapObject[]): MapObject[];
+
+/** PixiJS asset extension bundle for Tiled map JSON files. */
+declare const tiledMapAssetExtension: {
+    extension: ExtensionType;
+    loader: LoaderParser<TiledMapData, any, Record<string, any>>;
+};
+
+/**
+ * Convert Tiled JSON data to the generic TilemapData format.
+ */
+declare function toTilemapData(map: TiledMapData): TilemapData;
+/**
+ * Build CompositeTilemap display objects from a parsed Tiled map.
+ *
+ * @param map - Parsed TiledMapData (with resolved tilesets).
+ * @param layerNames - Optional filter: only process these tile layer names.
+ * @returns Array of CompositeTilemap, one per tile layer.
+ */
+declare function createTilemapLayers(map: TiledMapData, layerNames?: string[]): CompositeTilemap[];
+/**
+ * Extract objects from Tiled object layers, grouped by class/type/name.
+ *
+ * @param map - Parsed TiledMapData.
+ * @param objectLayerName - Optional: only extract from this layer.
+ * @returns Record mapping class/type/name to arrays of TileObject.
+ */
+declare function extractObjects(map: TiledMapData, objectLayerName?: string): Record<string, TileObject[]>;
+
+export { type HasProperties, type MapObject, type MapObjectProperty, type ObjectGroup, type ObjectLayerData, type PointObject, type PolygonColliderConfig, type PolygonObject, type RectColliderConfig, type RectangleObject, type TileData, type TileLayer, type TileLayerData, type TileObject, type TileObjectProperty, type TiledMapData, type TilemapColliderConfig, TilemapComponent, type TilemapComponentData, type TilemapComponentOptions, type TilemapData, TilemapPlugin, TilemapRenderSystem, type TilesetData, type TilesetRef, createTilemapLayers, extractCollisionShapes, extractObjects, getProperty, getPropertyArray, resolveObjectRef, resolveObjectRefArray, tiledMap, tiledMapAssetExtension, toPhysicsColliders, toTilemapData };