ecspresso
Version:
A minimal Entity-Component-System library for typescript and javascript.
103 lines (102 loc) • 4.26 kB
TypeScript
/**
* Isometric Projection Plugin for ECSpresso
*
* Converts Cartesian world-space positions to isometric screen positions
* in the render phase. All ECS-level logic (physics, collision, camera follow)
* continues to operate in Cartesian world space — only PixiJS display object
* positions are projected.
*
* Optionally provides an isometric-aware camera sync system that projects
* the camera position before applying it to the root container.
*/
import type { BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig, ResourcesConfig } from '../../type-utils';
import type { TransformComponentTypes } from '../spatial/transform';
import type { Renderer2DComponentTypes, Renderer2DResourceTypes } from '../rendering/renderer2D';
import type { CameraResourceTypes } from '../spatial/camera';
/**
* Isometric projection configuration.
*/
export interface IsoProjectionState {
readonly tileWidth: number;
readonly tileHeight: number;
readonly originX: number;
readonly originY: number;
}
export interface IsoProjectionResourceTypes {
isoProjection: IsoProjectionState;
}
type IsoProjectionRequires = ComponentsConfig<TransformComponentTypes & Pick<Renderer2DComponentTypes, 'sprite' | 'graphics' | 'container'>> & ResourcesConfig<Renderer2DResourceTypes & CameraResourceTypes>;
export interface IsoProjectionPluginOptions<G extends string = 'isometric'> extends BasePluginOptions<G> {
/** Tile width in pixels (default: 64) */
tileWidth?: number;
/** Tile height in pixels (default: 32) */
tileHeight?: number;
/** Screen-space X origin offset (default: 0) */
originX?: number;
/** Screen-space Y origin offset (default: 0) */
originY?: number;
/** Register an isometric-aware camera sync system (default: false).
* When true, set `camera: false` on createRenderer2DPlugin to avoid conflicts. */
camera?: boolean;
}
/**
* Convert Cartesian world coordinates to isometric screen coordinates.
*
* @param worldX World-space X coordinate
* @param worldY World-space Y coordinate
* @param state Isometric projection state
* @returns New object with projected { x, y }
*/
export declare function worldToIso(worldX: number, worldY: number, state: IsoProjectionState): {
x: number;
y: number;
};
/**
* Convert isometric screen coordinates back to Cartesian world coordinates.
*
* @param isoX Isometric screen-space X coordinate
* @param isoY Isometric screen-space Y coordinate
* @param state Isometric projection state
* @returns New object with world-space { x, y }
*/
export declare function isoToWorld(isoX: number, isoY: number, state: IsoProjectionState): {
x: number;
y: number;
};
/**
* Convert screen coordinates (e.g. clientX/clientY) to isometric world (tile) coordinates,
* accounting for camera position and zoom.
*
* @param screenX Screen-space X coordinate (e.g. clientX from a pointer event)
* @param screenY Screen-space Y coordinate (e.g. clientY from a pointer event)
* @param cameraState Camera state with position and zoom
* @param isoState Isometric projection state
* @param canvas The HTMLCanvasElement used for rendering
* @returns World-space { x, y } in tile coordinates
*/
export declare function screenToIsoWorld(screenX: number, screenY: number, cameraState: {
x: number;
y: number;
zoom: number;
}, isoState: IsoProjectionState, canvas: HTMLCanvasElement): {
x: number;
y: number;
};
/**
* Create an isometric projection plugin.
*
* Adds a render-phase system that overwrites PixiJS display object positions
* with isometric projections of their `worldTransform` coordinates.
*
* @example
* ```typescript
* const ecs = ECSpresso.create()
* .withPlugin(createRenderer2DPlugin({ camera: false, ... }))
* .withPlugin(createCameraPlugin({ ... }))
* .withPlugin(createIsoProjectionPlugin({ tileWidth: 64, tileHeight: 32, camera: true }))
* .build();
* ```
*/
export declare function createIsoProjectionPlugin<G extends string = 'isometric'>(options?: IsoProjectionPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithResources<import("ecspresso").EmptyConfig, IsoProjectionResourceTypes>, IsoProjectionRequires, never, G, never, never>;
export {};