ecspresso
Version:
A minimal Entity-Component-System library for typescript and javascript.
149 lines (148 loc) • 4.77 kB
TypeScript
/**
* 3D Transform Plugin for ECSpresso
*
* Provides hierarchical 3D transform propagation following Bevy's Transform/GlobalTransform pattern.
* LocalTransform3D is modified by user code; WorldTransform3D is computed automatically.
*
* Rotation is stored as Euler angles (radians, XYZ intrinsic order matching Three.js defaults).
* Hierarchical composition converts to quaternions internally for correct rotation composition,
* then converts back to Euler for storage.
*/
import { type BasePluginOptions } from 'ecspresso';
import type { ComponentsConfig } from '../../type-utils';
/**
* 3D local transform relative to parent (or world if no parent).
* This is the transform you modify directly.
*
* Rotation is in radians, using XYZ intrinsic Euler order (Three.js default).
*/
export interface LocalTransform3D {
x: number;
y: number;
z: number;
rx: number;
ry: number;
rz: number;
sx: number;
sy: number;
sz: number;
}
/**
* Computed 3D world transform (accumulated from parent chain).
* Read-only — managed by the transform propagation system.
*/
export interface WorldTransform3D {
x: number;
y: number;
z: number;
rx: number;
ry: number;
rz: number;
sx: number;
sy: number;
sz: number;
}
/**
* Component types provided by the 3D transform plugin.
* Included automatically via `.withPlugin(createTransform3DPlugin())`.
*/
export interface Transform3DComponentTypes {
localTransform3D: LocalTransform3D;
worldTransform3D: WorldTransform3D;
}
/**
* WorldConfig representing the 3D transform plugin's provided components.
* Used as the `Requires` type parameter by plugins that depend on transform3D.
*/
export type Transform3DWorldConfig = ComponentsConfig<Transform3DComponentTypes>;
/**
* Configuration options for the 3D transform plugin.
*/
export interface Transform3DPluginOptions<G extends string = 'transform3d'> extends BasePluginOptions<G> {
}
/**
* Default local 3D transform values.
*/
export declare const DEFAULT_LOCAL_TRANSFORM_3D: Readonly<LocalTransform3D>;
/**
* Default world 3D transform values.
*/
export declare const DEFAULT_WORLD_TRANSFORM_3D: Readonly<WorldTransform3D>;
/**
* Create a local 3D transform component with position only.
* Uses default rotation (0, 0, 0) and scale (1, 1, 1).
*
* @example
* ```typescript
* ecs.spawn({
* ...createLocalTransform3D(10, 5, -20),
* mesh: myMesh,
* });
* ```
*/
export declare function createLocalTransform3D(x: number, y: number, z: number): Pick<Transform3DComponentTypes, 'localTransform3D'>;
/**
* Create a world 3D transform component with position only.
* Typically used alongside createLocalTransform3D for initial state.
*/
export declare function createWorldTransform3D(x: number, y: number, z: number): Pick<Transform3DComponentTypes, 'worldTransform3D'>;
/**
* Options for creating a full 3D transform.
*/
export interface Transform3DOptions {
rotation?: {
x?: number;
y?: number;
z?: number;
};
scaleX?: number;
scaleY?: number;
scaleZ?: number;
/** Uniform scale (overrides scaleX/scaleY/scaleZ if provided) */
scale?: number;
}
/**
* Create both local and world 3D transform components.
* World transform is initialized to match local transform.
*
* @example
* ```typescript
* ecs.spawn({
* ...createTransform3D(10, 5, -20),
* mesh: myMesh,
* });
*
* // With rotation and scale
* ecs.spawn({
* ...createTransform3D(10, 5, -20, {
* rotation: { y: Math.PI / 4 },
* scale: 2,
* }),
* mesh: myMesh,
* });
* ```
*/
export declare function createTransform3D(x: number, y: number, z: number, options?: Transform3DOptions): Transform3DComponentTypes;
/**
* Create a 3D transform plugin for ECSpresso.
*
* This plugin provides:
* - 3D transform propagation system that computes world transforms from local transforms
* - Parent-first traversal ensures parents are processed before children
* - Supports full 3D transform hierarchy (position, rotation, scale)
* - Rotation composed via quaternions internally for correctness
*
* @example
* ```typescript
* const ecs = ECSpresso.create()
* .withPlugin(createTransform3DPlugin())
* .withComponentTypes<{ velocity: { x: number; y: number; z: number } }>()
* .build();
*
* ecs.spawn({
* ...createTransform3D(10, 5, -20),
* velocity: { x: 1, y: 0, z: 0 },
* });
* ```
*/
export declare function createTransform3DPlugin<G extends string = 'transform3d'>(options?: Transform3DPluginOptions<G>): import("ecspresso").Plugin<import("ecspresso").WithComponents<import("ecspresso").EmptyConfig, Transform3DComponentTypes>, import("ecspresso").EmptyConfig, "transform3d-propagation", G, never, never>;