ecspresso
Version:
A minimal Entity-Component-System library for typescript and javascript.
151 lines (150 loc) • 4.72 kB
TypeScript
/**
* Transform Plugin for ECSpresso
*
* Provides hierarchical transform propagation following Bevy's Transform/GlobalTransform pattern.
* LocalTransform is modified by user code; WorldTransform is computed automatically.
*
* @see https://docs.rs/bevy/latest/bevy/transform/components/struct.GlobalTransform.html
*/
import { type BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig } from '../../type-utils';
/**
* Local transform relative to parent (or world if no parent).
* This is the transform you modify directly.
*/
export interface LocalTransform {
x: number;
y: number;
rotation: number;
scaleX: number;
scaleY: number;
}
/**
* Computed world transform (accumulated from parent chain).
* Read-only - managed by the transform propagation system.
*/
export interface WorldTransform {
x: number;
y: number;
rotation: number;
scaleX: number;
scaleY: number;
}
/**
* Component types provided by the transform plugin.
* Included automatically via `.withPlugin(createTransformPlugin())`.
*
* @example
* ```typescript
* const ecs = ECSpresso.create()
* .withPlugin(createTransformPlugin())
* .withComponentTypes<{ sprite: Sprite; velocity: { x: number; y: number } }>()
* .build();
* ```
*/
export interface TransformComponentTypes {
localTransform: LocalTransform;
worldTransform: WorldTransform;
}
/**
* WorldConfig representing the transform plugin's provided components.
* Used as the `Requires` type parameter by plugins that depend on transform.
*/
export type TransformWorldConfig = ComponentsConfig<TransformComponentTypes>;
/**
* Configuration options for the transform plugin.
*/
export interface TransformPluginOptions<G extends string = 'transform'> extends BasePluginOptions<G> {
}
/**
* Default local transform values.
*/
export declare const DEFAULT_LOCAL_TRANSFORM: Readonly<LocalTransform>;
/**
* Default world transform values.
*/
export declare const DEFAULT_WORLD_TRANSFORM: Readonly<WorldTransform>;
/**
* Create a local transform component with position only.
* Uses default rotation (0) and scale (1, 1).
*
* @param x The x coordinate
* @param y The y coordinate
* @returns Component object suitable for spreading into spawn()
*
* @example
* ```typescript
* ecs.spawn({
* ...createLocalTransform(100, 200),
* sprite,
* });
* ```
*/
export declare function createLocalTransform(x: number, y: number): Pick<TransformComponentTypes, 'localTransform'>;
/**
* Create a world transform component with position only.
* Typically used alongside createLocalTransform for initial state.
*
* @param x The x coordinate
* @param y The y coordinate
* @returns Component object suitable for spreading into spawn()
*/
export declare function createWorldTransform(x: number, y: number): Pick<TransformComponentTypes, 'worldTransform'>;
/**
* Options for creating a full transform.
*/
export interface TransformOptions {
rotation?: number;
scaleX?: number;
scaleY?: number;
/** Uniform scale (overrides scaleX/scaleY if provided) */
scale?: number;
}
/**
* Create both local and world transform components.
* World transform is initialized to match local transform.
*
* @param x The x coordinate
* @param y The y coordinate
* @param options Optional rotation and scale
* @returns Component object suitable for spreading into spawn()
*
* @example
* ```typescript
* ecs.spawn({
* ...createTransform(100, 200),
* sprite,
* });
*
* // With rotation and scale
* ecs.spawn({
* ...createTransform(100, 200, { rotation: Math.PI / 4, scale: 2 }),
* sprite,
* });
* ```
*/
export declare function createTransform(x: number, y: number, options?: TransformOptions): TransformComponentTypes;
/**
* Create a transform plugin for ECSpresso.
*
* This plugin provides:
* - Transform propagation system that computes world transforms from local transforms
* - Parent-first traversal ensures parents are processed before children
* - Supports full transform hierarchy (position, rotation, scale)
*
* @example
* ```typescript
* const ecs = ECSpresso
* .create<Components, Events, Resources>()
* .withPlugin(createTransformPlugin())
* .withPlugin(createPhysics2DPlugin())
* .build();
*
* // Spawn entity with transform
* ecs.spawn({
* ...createTransform(100, 200),
* velocity: { x: 50, y: 0 },
* });
* ```
*/
export declare function createTransformPlugin<G extends string = 'transform'>(options?: TransformPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, TransformComponentTypes>, import("ecspresso").EmptyConfig, "transform-propagation", G, never, never>;