ecspresso 0.10.2 → 0.12.0

package/dist/plugins/renderers/renderer2D.d.ts

@@ -0,0 +1,262 @@
+/**
+ * 2D Renderer Plugin for ECSpresso
+ *
+ * An opt-in PixiJS-based 2D rendering plugin that automates scene graph wiring.
+ * Import from 'ecspresso/plugins/renderers/renderer2D'
+ *
+ * This plugin includes transform propagation automatically.
+ */
+import type { Application, ApplicationOptions, Container, Sprite, Graphics } from 'pixi.js';
+import { type Plugin } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../../type-utils';
+import { type LocalTransform, type WorldTransform, type TransformComponentTypes, type TransformPluginOptions } from 'ecspresso/plugins/transform';
+import { type BoundsRect } from 'ecspresso/plugins/bounds';
+import type { CameraResourceTypes } from 'ecspresso/plugins/camera';
+export type { LocalTransform, WorldTransform, TransformComponentTypes };
+export type { BoundsRect };
+export { createTransform, createLocalTransform, createWorldTransform, DEFAULT_LOCAL_TRANSFORM, DEFAULT_WORLD_TRANSFORM } from 'ecspresso/plugins/transform';
+/**
+ * Visibility and alpha component
+ */
+export interface Visible {
+    visible: boolean;
+    alpha?: number;
+}
+/**
+ * Aggregate component types for the 2D renderer plugin.
+ * Included automatically via `.withPlugin(createRenderer2DPlugin({ ... }))`.
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createRenderer2DPlugin({ ... }))
+ *   .withComponentTypes<{ velocity: { x: number; y: number }; player: true }>()
+ *   .build();
+ * ```
+ */
+export interface Renderer2DComponentTypes extends TransformComponentTypes {
+    sprite: Sprite;
+    graphics: Graphics;
+    container: Container;
+    visible: Visible;
+    /** Assigns the entity to a named render layer for z-ordering */
+    renderLayer: string;
+}
+/**
+ * Events emitted by the 2D renderer plugin
+ */
+export interface Renderer2DEventTypes {
+    hierarchyChanged: {
+        entityId: number;
+        oldParent: number | null;
+        newParent: number | null;
+    };
+}
+/**
+ * Resources provided by the 2D renderer plugin
+ */
+export interface Renderer2DResourceTypes {
+    pixiApp: Application;
+    rootContainer: Container;
+    /** Screen bounds derived from PixiJS screen dimensions, updated on resize */
+    bounds: BoundsRect;
+}
+export type ScaleMode = 'fit' | 'cover' | 'stretch';
+export interface ScreenScaleOptions {
+    readonly width: number;
+    readonly height: number;
+    readonly mode?: ScaleMode;
+}
+export interface ViewportScale {
+    scaleX: number;
+    scaleY: number;
+    offsetX: number;
+    offsetY: number;
+    physicalWidth: number;
+    physicalHeight: number;
+    readonly designWidth: number;
+    readonly designHeight: number;
+}
+export interface ViewportScaleResourceTypes {
+    viewportScale: ViewportScale;
+}
+/**
+ * Common options shared between both initialization modes
+ */
+interface Renderer2DPluginCommonOptions<G extends string = 'renderer2d'> {
+    /** Optional custom root container (defaults to app.stage) */
+    rootContainer?: Container;
+    /** System group name (default: 'renderer2d') */
+    systemGroup?: G;
+    /** Priority for render sync system (default: 500) */
+    renderSyncPriority?: number;
+    /** Options for the included transform plugin */
+    transform?: TransformPluginOptions;
+    /** When true, wires up pixiApp.ticker to drive ecs.update() automatically (default: true) */
+    startLoop?: boolean;
+    /** Ordered render layer names (back-to-front). Entities with a renderLayer component are placed in the corresponding container. */
+    renderLayers?: string[];
+    /** Automatically apply cameraState resource to rootContainer each frame.
+     *  Requires the camera plugin to be installed. (default: false) */
+    camera?: boolean;
+    /** Enforce a logical design resolution with automatic aspect-ratio-aware scaling.
+     *  When set, systems work in design-resolution coordinate space. */
+    screenScale?: ScreenScaleOptions;
+}
+/**
+ * Options when providing a pre-initialized PixiJS Application
+ */
+export interface Renderer2DPluginAppOptions<G extends string = 'renderer2d'> extends Renderer2DPluginCommonOptions<G> {
+    /** The PixiJS Application instance (already initialized) */
+    app: Application;
+    init?: never;
+    container?: never;
+}
+/**
+ * Options when letting the plugin create and manage the PixiJS Application
+ */
+export interface Renderer2DPluginManagedOptions<G extends string = 'renderer2d'> extends Renderer2DPluginCommonOptions<G> {
+    app?: never;
+    /** PixiJS ApplicationOptions - plugin will create and initialize the Application */
+    init: Partial<ApplicationOptions>;
+    /** Container element to append the canvas to, or CSS selector string */
+    container?: HTMLElement | string;
+}
+/**
+ * Configuration options for the 2D renderer plugin.
+ *
+ * Supports two modes:
+ * 1. **Pre-initialized**: Pass an already-initialized Application via `app`
+ * 2. **Managed**: Pass `init` options and the plugin creates the Application during `ecs.initialize()`
+ *
+ * This plugin includes transform propagation automatically - no need to add createTransformPlugin() separately.
+ *
+ * @example Pre-initialized mode (full control)
+ * ```typescript
+ * const app = new Application();
+ * await app.init({ resizeTo: window });
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createRenderer2DPlugin({ app }))
+ *   .withComponentTypes<{ player: true }>()
+ *   .build();
+ * ```
+ *
+ * @example Managed mode (convenience)
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createRenderer2DPlugin({
+ *     init: { background: '#1099bb', resizeTo: window },
+ *     container: document.body,
+ *   }))
+ *   .withComponentTypes<{ player: true }>()
+ *   .build();
+ * await ecs.initialize(); // Application created here
+ * ```
+ */
+export type Renderer2DPluginOptions<G extends string = 'renderer2d'> = Renderer2DPluginAppOptions<G> | Renderer2DPluginManagedOptions<G>;
+interface PositionOption {
+    x?: number;
+    y?: number;
+}
+interface TransformOptions {
+    rotation?: number;
+    scale?: number | {
+        x: number;
+        y: number;
+    };
+    visible?: boolean;
+    alpha?: number;
+}
+/**
+ * Create components for a sprite entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const player = ecs.spawn({
+ *   ...createSpriteComponents(new Sprite(texture), { x: 100, y: 100 }),
+ *   velocity: { x: 0, y: 0 },
+ * });
+ * ```
+ */
+export declare function createSpriteComponents(sprite: Sprite, position?: PositionOption, options?: TransformOptions & {
+    anchor?: {
+        x: number;
+        y: number;
+    };
+}): Pick<Renderer2DComponentTypes, 'sprite' | 'localTransform' | 'worldTransform' | 'visible'>;
+/**
+ * Create components for a graphics entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const rect = ecs.spawn({
+ *   ...createGraphicsComponents(graphics, { x: 50, y: 50 }),
+ * });
+ * ```
+ */
+export declare function createGraphicsComponents(graphics: Graphics, position?: PositionOption, options?: TransformOptions): Pick<Renderer2DComponentTypes, 'graphics' | 'localTransform' | 'worldTransform' | 'visible'>;
+/**
+ * Create components for a container entity.
+ * Returns an object suitable for spreading into spawn().
+ *
+ * @example
+ * ```typescript
+ * const group = ecs.spawn({
+ *   ...createContainerComponents(new Container(), { x: 0, y: 0 }),
+ * });
+ * ```
+ */
+export declare function createContainerComponents(container: Container, position?: PositionOption, options?: TransformOptions): Pick<Renderer2DComponentTypes, 'container' | 'localTransform' | 'worldTransform' | 'visible'>;
+export declare function computeViewportScale(physicalW: number, physicalH: number, designW: number, designH: number, mode: ScaleMode): ViewportScale;
+/**
+ * Convert physical canvas pixel coordinates to design-resolution (logical) coordinates.
+ * Compose with camera `screenToWorld()` for full physical→world conversion.
+ */
+export declare function physicalToLogical(physicalX: number, physicalY: number, viewport: ViewportScale): {
+    x: number;
+    y: number;
+};
+/**
+ * Create a 2D rendering plugin for ECSpresso.
+ *
+ * This plugin provides:
+ * - Transform propagation (localTransform -> worldTransform)
+ * - Render sync system (updates PixiJS objects from ECS components)
+ * - Scene graph management (mirrors ECS hierarchy in PixiJS scene graph)
+ *
+ * @example Pre-initialized mode
+ * ```typescript
+ * const app = new Application();
+ * await app.init({ resizeTo: window });
+ *
+ * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ *   .withPlugin(createRenderer2DPlugin({ app }))
+ *   .build();
+ * ```
+ *
+ * @example Managed mode
+ * ```typescript
+ * const ecs = ECSpresso.create<GameComponents, {}, {}>()
+ *   .withPlugin(createRenderer2DPlugin({
+ *     init: { background: '#1099bb', resizeTo: window },
+ *     container: document.body,
+ *   }))
+ *   .build();
+ * await ecs.initialize();
+ * ```
+ */
+type Renderer2DLabels = 'renderer2d-sync' | 'renderer2d-scene-graph' | 'renderer2d-camera-sync' | 'transform-propagation';
+type Renderer2DReactiveQueryNames = 'renderer2d-sprites' | 'renderer2d-graphics' | 'renderer2d-containers';
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
+    screenScale: ScreenScaleOptions;
+    camera: true;
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes & CameraResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
+    screenScale: ScreenScaleOptions;
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & ViewportScaleResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G> & {
+    camera: true;
+}): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes & CameraResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;
+export declare function createRenderer2DPlugin<G extends string = 'renderer2d'>(options: Renderer2DPluginOptions<G>): Plugin<WorldConfigFrom<Renderer2DComponentTypes, Renderer2DEventTypes, Renderer2DResourceTypes>, EmptyConfig, Renderer2DLabels, G, never, Renderer2DReactiveQueryNames>;

package/dist/plugins/spatial-index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Spatial Index Plugin for ECSpresso
+ *
+ * Provides a uniform-grid spatial hash for broadphase collision detection
+ * and proximity queries. Replaces O(n²) brute-force with O(n·d) where
+ * d = local density.
+ *
+ * Standalone usage: queryRect / queryRadius for proximity queries.
+ * Automatic acceleration: collision and physics2D plugins detect the
+ * spatialIndex resource at runtime and use it for broadphase when present.
+ */
+import { type Plugin } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+import type { TransformComponentTypes } from './transform';
+import type { CollisionComponentTypes } from './collision';
+import { type SpatialIndex } from '../utils/spatial-hash';
+export interface SpatialIndexResourceTypes {
+    spatialIndex: SpatialIndex;
+}
+type SpatialIndexComponentTypes = TransformComponentTypes & Pick<CollisionComponentTypes<string>, 'aabbCollider' | 'circleCollider'>;
+export type SpatialIndexPhase = 'fixedUpdate' | 'postUpdate';
+type SpatialIndexLabel = `spatial-index-rebuild-${SpatialIndexPhase}`;
+export interface SpatialIndexPluginOptions<G extends string = 'spatialIndex'> {
+    /** Cell size for the spatial hash grid (default: 64) */
+    cellSize?: number;
+    /** System group name (default: 'spatialIndex') */
+    systemGroup?: G;
+    /** Priority for rebuild systems (default: 2000, before collision) */
+    priority?: number;
+    /** Phases to register rebuild systems in (default: ['fixedUpdate', 'postUpdate']) */
+    phases?: ReadonlyArray<SpatialIndexPhase>;
+}
+/**
+ * Create a spatial index plugin for ECSpresso.
+ *
+ * Provides a uniform-grid spatial hash that accelerates collision detection.
+ * When installed alongside the collision or physics2D plugins, they
+ * automatically use the spatial index for broadphase instead of O(n²)
+ * brute-force.
+ *
+ * Also provides proximity query methods for game logic (e.g. "find all
+ * enemies within 200 units").
+ *
+ * @example
+ * ```typescript
+ * const ecs = ECSpresso.create()
+ *   .withPlugin(createTransformPlugin())
+ *   .withPlugin(createCollisionPlugin({ layers }))
+ *   .withPlugin(createSpatialIndexPlugin({ cellSize: 128 }))
+ *   .build();
+ *
+ * // Proximity query in a system:
+ * const si = ecs.getResource('spatialIndex');
+ * const nearby = si.queryRadius(playerX, playerY, 200);
+ * ```
+ */
+export declare function createSpatialIndexPlugin<G extends string = 'spatialIndex'>(options?: SpatialIndexPluginOptions<G>): Plugin<WorldConfigFrom<SpatialIndexComponentTypes, {}, SpatialIndexResourceTypes>, EmptyConfig, SpatialIndexLabel, G>;
+export {};

package/dist/plugins/sprite-animation.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Sprite Animation Plugin for ECSpresso
+ *
+ * ECS-native frame-based sprite animation. Advances through spritesheet frames,
+ * handles loop modes (once, loop, pingPong), publishes completion events, and
+ * syncs the current frame's texture to the PixiJS Sprite via structural access.
+ *
+ * Renderer2D is a required dependency — the `sprite` component comes from that plugin.
+ * This plugin declares only `spriteAnimation` as its component type.
+ */
+import { type Plugin, type BasePluginOptions } from 'ecspresso';
+import type { BaseWorld } from 'ecspresso';
+import type { WorldConfigFrom, EmptyConfig } from '../type-utils';
+/** BaseWorld narrowed to sprite-animation components for typed access in helpers. */
+type SpriteAnimationWorld = BaseWorld<SpriteAnimationComponentTypes>;
+export type AnimationLoopMode = 'once' | 'loop' | 'pingPong';
+/**
+ * A single animation clip: an ordered sequence of texture frames with timing.
+ * Immutable and shared across entities.
+ */
+export interface SpriteAnimationClip {
+    readonly frames: readonly unknown[];
+    readonly frameDuration: number;
+    readonly frameDurations: readonly number[] | null;
+    readonly loop: AnimationLoopMode;
+}
+/**
+ * Input format for defining a clip. Accepts either uniform or per-frame timing.
+ */
+export interface SpriteAnimationClipInput {
+    /** Array of PixiJS Texture objects */
+    frames: readonly unknown[];
+    /** Uniform seconds-per-frame (used when frameDurations is not provided) */
+    frameDuration?: number;
+    /** Per-frame durations in seconds (overrides frameDuration) */
+    frameDurations?: readonly number[];
+    /** Loop mode (default: 'loop') */
+    loop?: AnimationLoopMode;
+}
+/**
+ * A named collection of animation clips. Immutable and shared across entities.
+ * Parameterized by A (animation name union) for compile-time validation.
+ */
+export interface SpriteAnimationSet<A extends string = string> {
+    readonly id: string;
+    readonly clips: {
+        readonly [K in A]: SpriteAnimationClip;
+    };
+    readonly defaultClip: A;
+}
+/**
+ * Per-entity runtime animation state.
+ */
+export interface SpriteAnimation<A extends string = string> {
+    readonly set: SpriteAnimationSet<A>;
+    current: A;
+    currentFrame: number;
+    elapsed: number;
+    playing: boolean;
+    speed: number;
+    direction: 1 | -1;
+    totalLoops: number;
+    completedLoops: number;
+    justFinished: boolean;
+    onComplete?: (data: SpriteAnimationEventData) => void;
+}
+/**
+ * Component types provided by the sprite animation plugin.
+ */
+export interface SpriteAnimationComponentTypes<A extends string = string> {
+    spriteAnimation: SpriteAnimation<A>;
+}
+/**
+ * Data published when an animation completes.
+ */
+export interface SpriteAnimationEventData {
+    entityId: number;
+    animation: string;
+}
+export interface SpriteAnimationPluginOptions<G extends string = 'spriteAnimation'> extends BasePluginOptions<G> {
+}
+/**
+ * Define a single-clip animation set named 'default'.
+ * For simple use cases like spinning coins, pulsing effects, etc.
+ *
+ * @param id Unique identifier for this animation set
+ * @param clip Clip definition
+ * @returns A frozen SpriteAnimationSet with one clip named 'default'
+ */
+export declare function defineSpriteAnimation(id: string, clip: SpriteAnimationClipInput): SpriteAnimationSet<'default'>;
+/**
+ * Define a multi-clip animation set with named animations.
+ * Animation names are inferred from the keys of the clips object.
+ *
+ * @param id Unique identifier for this animation set
+ * @param clips Object mapping animation names to clip definitions
+ * @param options Optional configuration (defaultClip)
+ * @returns A frozen SpriteAnimationSet with inferred animation name union
+ */
+export declare function defineSpriteAnimations<A extends string>(id: string, clips: Record<A, SpriteAnimationClipInput>, options?: {
+    defaultClip?: NoInfer<A>;
+}): SpriteAnimationSet<A>;
+/**
+ * Create a spriteAnimation component from an animation set.
+ *
+ * @param set The animation set to use
+ * @param options Optional configuration (initial clip, speed, onComplete event)
+ * @returns Component object suitable for spreading into spawn()
+ */
+export declare function createSpriteAnimation<A extends string>(set: SpriteAnimationSet<A>, options?: {
+    initial?: A;
+    speed?: number;
+    totalLoops?: number;
+    onComplete?: (data: SpriteAnimationEventData) => void;
+}): Pick<SpriteAnimationComponentTypes<A>, 'spriteAnimation'>;
+/**
+ * Switch an entity's current animation at runtime.
+ * Resets state if switching to a different animation (or restart=true).
+ *
+ * @returns false if entity has no spriteAnimation or animation name doesn't exist
+ */
+export declare function playAnimation(ecs: SpriteAnimationWorld, entityId: number, animation: string, options?: {
+    restart?: boolean;
+    speed?: number;
+}): boolean;
+/**
+ * Pause an entity's animation.
+ *
+ * @returns false if entity has no spriteAnimation
+ */
+export declare function stopAnimation(ecs: SpriteAnimationWorld, entityId: number): boolean;
+/**
+ * Resume a paused animation.
+ *
+ * @returns false if entity has no spriteAnimation
+ */
+export declare function resumeAnimation(ecs: SpriteAnimationWorld, entityId: number): boolean;
+/**
+ * Create a sprite animation plugin for ECSpresso.
+ *
+ * Provides:
+ * - Frame-based animation system processing spriteAnimation components
+ * - Loop modes: once, loop, pingPong
+ * - justFinished one-frame flag for completion detection
+ * - onComplete event publishing
+ * - Sprite texture sync via structural cross-plugin access
+ * - Change detection via markChanged
+ */
+export declare function createSpriteAnimationPlugin<G extends string = 'spriteAnimation'>(options?: SpriteAnimationPluginOptions<G>): Plugin<WorldConfigFrom<SpriteAnimationComponentTypes>, EmptyConfig, 'sprite-animation-update', G>;
+export {};