@zylem/game-lib 0.6.0 → 0.6.3

package/dist/entity-BpbZqg19.d.ts

@@ -0,0 +1,1100 @@
+import { Vector3, Vector2, Color, Material, BufferGeometry, Mesh, Group, ShaderMaterial } from 'three';
+import { Vector3 as Vector3$1, RigidBodyDesc, ColliderDesc, RigidBody, Vector, Collider } from '@dimforge/rapier3d-compat';
+import { IComponent } from 'bitecs';
+import * as mitt from 'mitt';
+import { b as BehaviorDescriptor, c as BehaviorHandle, d as BehaviorRef } from './behavior-descriptor-BWNWmIjv.js';
+
+/** Input
+ *
+ * Maximum number of local players is 8.
+ * All input can be mapped to a gamepad or keyboard but shares the common
+ * interface represented as a gamepad.
+ */
+type InputPlayerNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type InputPlayer = `p${InputPlayerNumber}`;
+interface ButtonState {
+    pressed: boolean;
+    released: boolean;
+    held: number;
+}
+interface AnalogState {
+    value: number;
+    held: number;
+}
+interface InputGamepad {
+    playerNumber: InputPlayerNumber;
+    buttons: {
+        A: ButtonState;
+        B: ButtonState;
+        X: ButtonState;
+        Y: ButtonState;
+        Start: ButtonState;
+        Select: ButtonState;
+        L: ButtonState;
+        R: ButtonState;
+    };
+    directions: {
+        Up: ButtonState;
+        Down: ButtonState;
+        Left: ButtonState;
+        Right: ButtonState;
+    };
+    shoulders: {
+        LTrigger: ButtonState;
+        RTrigger: ButtonState;
+    };
+    axes: {
+        Horizontal: AnalogState;
+        Vertical: AnalogState;
+    };
+}
+type Inputs = Record<InputPlayer, InputGamepad>;
+interface InputProvider {
+    getInput(delta: number): Partial<InputGamepad>;
+    isConnected(): boolean;
+    getName(): string;
+    dispose?(): void;
+}
+
+type LoadingEvent = {
+    type: 'start' | 'progress' | 'complete';
+    message?: string;
+    progress?: number;
+    total?: number;
+    current?: number;
+};
+interface IGame<TGlobals extends Record<string, unknown> = any> {
+    start: () => Promise<this>;
+    nextStage: () => void;
+    previousStage: () => void;
+    reset: () => Promise<void>;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    onLoading: (callback: (event: LoadingEvent) => void) => void;
+    loadStageFromId: (stageId: string) => Promise<void>;
+    end: () => Promise<void>;
+    goToStage: () => void;
+}
+interface IStage {
+    onUpdate: (callback: UpdateFunction<IStage>) => void;
+    onSetup: (callback: SetupFunction<IStage>) => void;
+    onDestroy: (callback: DestroyFunction<IStage>) => void;
+}
+interface ICamera {
+    move: (position: Vector3) => void;
+    rotate: (pitch: number, yaw: number, roll: number) => void;
+}
+
+type GlobalRecord = Record<string, unknown>;
+/** Setup */
+interface SetupContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+    inputs?: Inputs;
+    camera?: ICamera;
+    stage?: IStage;
+    game?: IGame<TGlobals>;
+}
+interface SetupFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: SetupContext<T, TGlobals>): void;
+}
+/** Loaded */
+interface LoadedContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface LoadedFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: LoadedContext<T, TGlobals>): void;
+}
+/** Update */
+type UpdateContext<T, TGlobals extends GlobalRecord = any> = {
+    me: T;
+    delta: number;
+    inputs: Inputs;
+    globals: TGlobals;
+    camera: ICamera;
+    stage?: IStage;
+    game?: IGame<TGlobals>;
+};
+interface UpdateFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: UpdateContext<T, TGlobals>): void;
+}
+/** Destroy */
+interface DestroyContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface DestroyFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: DestroyContext<T, TGlobals>): void;
+}
+/** Cleanup */
+interface CleanupContext<T, TGlobals extends GlobalRecord = any> {
+    me: T;
+    globals: TGlobals;
+}
+interface CleanupFunction<T, TGlobals extends GlobalRecord = any> {
+    (context: CleanupContext<T, TGlobals>): void;
+}
+
+interface NodeInterface {
+    uuid: string;
+    name: string;
+    markedForRemoval: boolean;
+    nodeSetup(params: SetupContext<any>): void;
+    nodeUpdate(params: UpdateContext<any>): void;
+    nodeDestroy(params: DestroyContext<any>): void;
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+}
+
+type BaseNodeOptions<T = any> = BaseNode | Partial<T>;
+/**
+ * Lifecycle callback arrays - each lifecycle event can have multiple callbacks
+ * that execute in order.
+ */
+interface LifecycleCallbacks<T> {
+    setup: Array<SetupFunction<T>>;
+    loaded: Array<LoadedFunction<T>>;
+    update: Array<UpdateFunction<T>>;
+    destroy: Array<DestroyFunction<T>>;
+    cleanup: Array<CleanupFunction<T>>;
+}
+declare abstract class BaseNode<Options = any, T = any> implements NodeInterface {
+    protected parent: NodeInterface | null;
+    protected children: NodeInterface[];
+    options: Options;
+    eid: number;
+    uuid: string;
+    name: string;
+    markedForRemoval: boolean;
+    /**
+     * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+     * Uses `any` for the type parameter to avoid invariance issues when subclasses
+     * are assigned to BaseNode references. Type safety is enforced by the public
+     * onSetup/onUpdate/etc. methods which are typed with `this`.
+     */
+    protected lifecycleCallbacks: LifecycleCallbacks<any>;
+    constructor(args?: BaseNodeOptions[]);
+    /**
+     * Add setup callbacks to be executed in order during nodeSetup
+     */
+    onSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Add loaded callbacks to be executed in order during nodeLoaded
+     */
+    onLoaded(...callbacks: Array<LoadedFunction<this>>): this;
+    /**
+     * Add update callbacks to be executed in order during nodeUpdate
+     */
+    onUpdate(...callbacks: Array<UpdateFunction<this>>): this;
+    /**
+     * Add destroy callbacks to be executed in order during nodeDestroy
+     */
+    onDestroy(...callbacks: Array<DestroyFunction<this>>): this;
+    /**
+     * Add cleanup callbacks to be executed in order during nodeCleanup
+     */
+    onCleanup(...callbacks: Array<CleanupFunction<this>>): this;
+    /**
+     * Prepend setup callbacks (run before existing ones)
+     */
+    prependSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Prepend update callbacks (run before existing ones)
+     */
+    prependUpdate(...callbacks: Array<UpdateFunction<this>>): this;
+    setParent(parent: NodeInterface | null): void;
+    getParent(): NodeInterface | null;
+    add(baseNode: NodeInterface): void;
+    remove(baseNode: NodeInterface): void;
+    getChildren(): NodeInterface[];
+    isComposite(): boolean;
+    abstract create(): T;
+    protected abstract _setup(params: SetupContext<this>): void;
+    protected abstract _loaded(params: LoadedContext<this>): Promise<void>;
+    protected abstract _update(params: UpdateContext<this>): void;
+    protected abstract _destroy(params: DestroyContext<this>): void;
+    protected abstract _cleanup(params: CleanupContext<this>): void;
+    nodeSetup(params: SetupContext<this>): void;
+    nodeUpdate(params: UpdateContext<this>): void;
+    nodeDestroy(params: DestroyContext<this>): void;
+    nodeLoaded(params: LoadedContext<this>): Promise<void>;
+    nodeCleanup(params: CleanupContext<this>): void;
+    getOptions(): Options;
+    setOptions(options: Partial<Options>): void;
+}
+
+type Vec3 = Vector3 | Vector3$1;
+
+declare function shortHash(objString: string): string;
+
+/**
+ * GLSL shader object (traditional approach for WebGL)
+ */
+type ZylemShaderObject = {
+    fragment: string;
+    vertex: string;
+};
+/**
+ * TSL shader type (for WebGPU)
+ * colorNode should be a TSL node that returns the fragment color
+ */
+type ZylemTSLShader = {
+    colorNode: any;
+    transparent?: boolean;
+};
+/**
+ * Combined shader type supporting both GLSL and TSL
+ */
+type ZylemShader = ZylemShaderObject | ZylemTSLShader;
+/**
+ * Check if a shader is a TSL shader
+ */
+declare function isTSLShader(shader: ZylemShader): shader is ZylemTSLShader;
+/**
+ * Check if a shader is a GLSL shader
+ */
+declare function isGLSLShader(shader: ZylemShader): shader is ZylemShaderObject;
+interface MaterialOptions {
+    path?: string;
+    normalMap?: string;
+    repeat?: Vector2;
+    shader?: ZylemShader;
+    color?: Color;
+    /**
+     * When true, prefer TSL/NodeMaterial (for WebGPU)
+     * When false, prefer GLSL/ShaderMaterial (for WebGL)
+     */
+    useTSL?: boolean;
+}
+type BatchGeometryMap = Map<symbol, number>;
+interface BatchMaterialMapObject {
+    geometryMap: BatchGeometryMap;
+    material: Material;
+}
+type BatchKey = ReturnType<typeof shortHash>;
+type TexturePath = string | null;
+declare class MaterialBuilder {
+    static batchMaterialMap: Map<BatchKey, BatchMaterialMapObject>;
+    materials: Material[];
+    /** Whether to use TSL/NodeMaterial (for WebGPU compatibility) */
+    private useTSL;
+    constructor(useTSL?: boolean);
+    batchMaterial(options: Partial<MaterialOptions>, entityType: symbol): void;
+    build(options: Partial<MaterialOptions>, entityType: symbol): void;
+    withColor(color: Color, useTSL?: boolean): this;
+    withShader(shader: ZylemShaderObject): this;
+    withTSLShader(shader: ZylemTSLShader): this;
+    /**
+     * Set texture - loads in background (deferred).
+     * Material is created immediately with null map, texture applies when loaded.
+     */
+    setTexture(texturePath?: TexturePath, repeat?: Vector2, useTSL?: boolean): void;
+    /**
+     * Set normal map for the current material
+     */
+    setNormalMap(normalMapPath: string, repeat?: Vector2): void;
+    setColor(color: Color, useTSL?: boolean): void;
+    /**
+     * Set GLSL shader (WebGL only)
+     */
+    setShader(customShader: ZylemShaderObject): void;
+    /**
+     * Set TSL shader (WebGPU compatible)
+     */
+    setTSLShader(tslShader: ZylemTSLShader): void;
+}
+
+/**
+ * Options for configuring entity collision behavior.
+ */
+interface CollisionOptions {
+    static?: boolean;
+    sensor?: boolean;
+    size?: Vector3$1;
+    position?: Vector3$1;
+    collisionType?: string;
+    collisionFilter?: string[];
+}
+declare class CollisionBuilder {
+    static: boolean;
+    sensor: boolean;
+    gravity: Vec3;
+    build(options: Partial<CollisionOptions>): [RigidBodyDesc, ColliderDesc];
+    withCollision(collisionOptions: Partial<CollisionOptions>): this;
+    collider(options: CollisionOptions): ColliderDesc;
+    bodyDesc({ isDynamicBody }: {
+        isDynamicBody?: boolean | undefined;
+    }): RigidBodyDesc;
+}
+
+/**
+ * TODO: allow for multiple materials requires geometry groups
+ * TODO: allow for instanced uniforms
+ * TODO: allow for geometry groups
+ * TODO: allow for batched meshes
+ * import { InstancedUniformsMesh } from 'three-instanced-uniforms-mesh';
+ * may not need geometry groups for shaders though
+ * setGeometry<T extends BufferGeometry>(geometry: T) {
+ *   MeshBuilder.bachedMesh = new BatchedMesh(10, 5000, 10000, material);
+ * }
+ */
+type MeshBuilderOptions = Partial<Pick<GameEntityOptions, 'batched' | 'material'>>;
+declare class MeshBuilder {
+    _build(meshOptions: MeshBuilderOptions, geometry: BufferGeometry, materials: Material[]): Mesh;
+    _postBuild(): void;
+}
+
+declare abstract class EntityCollisionBuilder extends CollisionBuilder {
+    abstract collider(options: GameEntityOptions): ColliderDesc;
+}
+declare abstract class EntityMeshBuilder extends MeshBuilder {
+    build(options: GameEntityOptions): BufferGeometry;
+    postBuild(): void;
+}
+
+interface Behavior {
+    component: IComponent;
+    values: any;
+}
+
+/**
+ * Reusable delegate for event emission and subscription.
+ * Use via composition in Game, Stage, and Entity classes.
+ *
+ * @example
+ * class Game {
+ *   private eventDelegate = new EventEmitterDelegate<GameEvents>();
+ *
+ *   dispatch<K extends keyof GameEvents>(event: K, payload: GameEvents[K]) {
+ *     this.eventDelegate.dispatch(event, payload);
+ *   }
+ * }
+ */
+declare class EventEmitterDelegate<TEvents extends Record<string, unknown>> {
+    private emitter;
+    private unsubscribes;
+    constructor();
+    /**
+     * Dispatch an event to all listeners.
+     */
+    dispatch<K extends keyof TEvents>(event: K, payload: TEvents[K]): void;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    listen<K extends keyof TEvents>(event: K, handler: (payload: TEvents[K]) => void): () => void;
+    /**
+     * Subscribe to all events.
+     */
+    listenAll(handler: (type: keyof TEvents, payload: TEvents[keyof TEvents]) => void): () => void;
+    /**
+     * Clean up all subscriptions.
+     */
+    dispose(): void;
+}
+
+/**
+ * Payload for game loading events with stage context.
+ */
+interface GameLoadingPayload extends LoadingEvent {
+    stageName?: string;
+    stageIndex?: number;
+}
+/** Payload for stage configuration sent to editor. */
+interface StageConfigPayload {
+    id: string;
+    backgroundColor: string;
+    backgroundImage: string | null;
+    gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    inputs: Record<string, string[]>;
+    variables: Record<string, unknown>;
+}
+/** Payload for entity configuration sent to editor. */
+interface EntityConfigPayload {
+    uuid: string;
+    name: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Payload for state dispatch events from game to editor. */
+interface StateDispatchPayload {
+    scope: 'game' | 'stage' | 'entity';
+    path: string;
+    value: unknown;
+    previousValue?: unknown;
+    config?: {
+        id: string;
+        aspectRatio: number;
+        fullscreen: boolean;
+        bodyBackground: string | undefined;
+        internalResolution: {
+            width: number;
+            height: number;
+        } | undefined;
+        debug: boolean;
+    } | null;
+    stageConfig?: StageConfigPayload | null;
+    entities?: EntityConfigPayload[] | null;
+}
+type GameEvents = {
+    'loading:start': GameLoadingPayload;
+    'loading:progress': GameLoadingPayload;
+    'loading:complete': GameLoadingPayload;
+    'paused': {
+        paused: boolean;
+    };
+    'debug': {
+        enabled: boolean;
+    };
+    'state:dispatch': StateDispatchPayload;
+};
+type StageEvents = {
+    'stage:loaded': {
+        stageId: string;
+    };
+    'stage:unloaded': {
+        stageId: string;
+    };
+    'stage:variable:changed': {
+        key: string;
+        value: unknown;
+    };
+};
+type EntityEvents = {
+    'entity:spawned': {
+        entityId: string;
+        name: string;
+    };
+    'entity:destroyed': {
+        entityId: string;
+    };
+    'entity:collision': {
+        entityId: string;
+        otherId: string;
+    };
+    'entity:model:loading': {
+        entityId: string;
+        files: string[];
+    };
+    'entity:model:loaded': {
+        entityId: string;
+        success: boolean;
+        meshCount?: number;
+    };
+    'entity:animation:loaded': {
+        entityId: string;
+        animationCount: number;
+    };
+};
+type ZylemEvents = GameEvents & StageEvents & EntityEvents;
+/**
+ * Global event bus for cross-package communication.
+ *
+ * Usage:
+ * ```ts
+ * import { zylemEventBus } from '@zylem/game-lib';
+ *
+ * // Subscribe
+ * const unsub = zylemEventBus.on('loading:progress', (e) => console.log(e));
+ *
+ * // Emit
+ * zylemEventBus.emit('loading:progress', { type: 'progress', progress: 0.5 });
+ *
+ * // Cleanup
+ * unsub();
+ * ```
+ */
+declare const zylemEventBus: mitt.Emitter<ZylemEvents>;
+
+/**
+ * Transform state managed by Valtio for batched physics updates.
+ *
+ * This store accumulates transformation intents during the frame,
+ * then applies them all at once after onUpdate() callbacks complete.
+ *
+ * Design decisions:
+ * - Position: Accumulated deltas (additive)
+ * - Rotation: Last value wins (replacement)
+ * - Velocity: Accumulated deltas (additive)
+ * - Angular velocity: Accumulated deltas (additive)
+ */
+interface TransformState {
+    /** Position deltas to be applied (accumulated) */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Rotation quaternion (last value wins) */
+    rotation: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    /** Linear velocity (accumulated) */
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Angular velocity (accumulated) */
+    angularVelocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Dirty flags to track what needs to be applied */
+    dirty: {
+        position: boolean;
+        rotation: boolean;
+        velocity: boolean;
+        angularVelocity: boolean;
+    };
+}
+/**
+ * Create a new transform store with optional initial values.
+ * The store is a Valtio proxy, making it reactive for debugging/visualization.
+ *
+ * @param initial Optional initial state values
+ * @returns Reactive transform state
+ */
+declare function createTransformStore(initial?: Partial<TransformState>): TransformState;
+/**
+ * Reset a transform store to its initial clean state.
+ * Called after applying changes to prepare for the next frame.
+ *
+ * @param store The transform store to reset
+ */
+declare function resetTransformStore(store: TransformState): void;
+
+interface EntityWithBody {
+    body: RigidBody | null;
+    transformStore?: TransformState;
+}
+/**
+ * Move an entity along the X axis, preserving other velocities.
+ */
+declare function moveX(entity: EntityWithBody, delta: number): void;
+/**
+ * Move an entity along the Y axis, preserving other velocities.
+ */
+declare function moveY(entity: EntityWithBody, delta: number): void;
+/**
+ * Move an entity along the Z axis, preserving other velocities.
+ */
+declare function moveZ(entity: EntityWithBody, delta: number): void;
+/**
+ * Move an entity along the X and Y axis, preserving Z velocity.
+ */
+declare function moveXY(entity: EntityWithBody, deltaX: number, deltaY: number): void;
+/**
+ * Move an entity along the X and Z axis, preserving Y velocity.
+ */
+declare function moveXZ(entity: EntityWithBody, deltaX: number, deltaZ: number): void;
+/**
+ * Move entity based on a vector, adding to existing velocities.
+ */
+declare function move(entity: EntityWithBody, vector: Vector3): void;
+/**
+ * Reset entity velocity
+ */
+declare function resetVelocity(entity: EntityWithBody): void;
+/**
+ * Move entity forward in 2D space, preserving Z velocity
+ */
+declare function moveForwardXY(entity: EntityWithBody, delta: number, rotation2DAngle: number): void;
+/**
+ * Get entity position
+ */
+declare function getPosition(entity: EntityWithBody): Vector | null;
+/**
+ * Get entity velocity
+ */
+declare function getVelocity(entity: EntityWithBody): Vector | null;
+/**
+ * Set entity position
+ */
+declare function setPosition(entity: EntityWithBody, x: number, y: number, z: number): void;
+/**
+ * Set entity X position
+ */
+declare function setPositionX(entity: EntityWithBody, x: number): void;
+/**
+ * Set entity Y position
+ */
+declare function setPositionY(entity: EntityWithBody, y: number): void;
+/**
+ * Set entity Z position
+ */
+declare function setPositionZ(entity: EntityWithBody, z: number): void;
+/**
+ * Wrap entity around 2D bounds
+ */
+declare function wrapAroundXY(entity: EntityWithBody, boundsX: number, boundsY: number): void;
+/**
+ * Wrap entity around 3D bounds
+ */
+declare function wrapAround3D(entity: EntityWithBody, boundsX: number, boundsY: number, boundsZ: number): void;
+/**
+ * Enhanced moveable entity with bound methods
+ */
+interface MoveableEntity extends EntityWithBody {
+    moveX(delta: number): void;
+    moveY(delta: number): void;
+    moveZ(delta: number): void;
+    moveXY(deltaX: number, deltaY: number): void;
+    moveXZ(deltaX: number, deltaZ: number): void;
+    move(vector: Vector3): void;
+    resetVelocity(): void;
+    moveForwardXY(delta: number, rotation2DAngle: number): void;
+    getPosition(): Vector | null;
+    getVelocity(): Vector | null;
+    setPosition(x: number, y: number, z: number): void;
+    setPositionX(x: number): void;
+    setPositionY(y: number): void;
+    setPositionZ(z: number): void;
+    wrapAroundXY(boundsX: number, boundsY: number): void;
+    wrapAround3D(boundsX: number, boundsY: number, boundsZ: number): void;
+}
+
+interface RotatableEntity {
+    body: RigidBody | null;
+    group: any;
+    transformStore?: TransformState;
+}
+/**
+ * Rotate an entity in the direction of a movement vector
+ */
+declare function rotateInDirection(entity: RotatableEntity, moveVector: Vector3): void;
+/**
+ * Rotate an entity around the Y axis using Euler angles
+ */
+declare function rotateYEuler(entity: RotatableEntity, amount: number): void;
+/**
+ * Rotate an entity using Euler angles
+ */
+declare function rotateEuler(entity: RotatableEntity, rotation: Vector3): void;
+/**
+ * Rotate an entity around the Y axis.
+ */
+declare function rotateY(entity: RotatableEntity, delta: number): void;
+/**
+ * Rotate an entity around the X axis.
+ */
+declare function rotateX(entity: RotatableEntity, delta: number): void;
+/**
+ * Rotate an entity around the Z axis.
+ */
+declare function rotateZ(entity: RotatableEntity, delta: number): void;
+/**
+ * Set rotation around Y axis.
+ */
+declare function setRotationY(entity: RotatableEntity, y: number): void;
+/**
+ * Set rotation around Y axis
+ */
+declare function setRotationDegreesY(entity: RotatableEntity, y: number): void;
+/**
+ * Set rotation around X axis.
+ */
+declare function setRotationX(entity: RotatableEntity, x: number): void;
+/**
+ * Set rotation around X axis
+ */
+declare function setRotationDegreesX(entity: RotatableEntity, x: number): void;
+/**
+ * Set rotation around Z axis.
+ */
+declare function setRotationZ(entity: RotatableEntity, z: number): void;
+/**
+ * Set rotation around Z axis
+ */
+declare function setRotationDegreesZ(entity: RotatableEntity, z: number): void;
+/**
+ * Set rotation for all axes.
+ */
+declare function setRotation(entity: RotatableEntity, x: number, y: number, z: number): void;
+/**
+ * Set rotation for all axes
+ */
+declare function setRotationDegrees(entity: RotatableEntity, x: number, y: number, z: number): void;
+/**
+ * Get current rotation
+ */
+declare function getRotation(entity: RotatableEntity): any;
+/**
+ * Rotatable entity API with bound methods
+ */
+interface RotatableEntityAPI extends RotatableEntity {
+    rotateInDirection(moveVector: Vector3): void;
+    rotateYEuler(amount: number): void;
+    rotateEuler(rotation: Vector3): void;
+    rotateY(delta: number): void;
+    rotateX(delta: number): void;
+    rotateZ(delta: number): void;
+    setRotationY(y: number): void;
+    setRotationX(x: number): void;
+    setRotationZ(z: number): void;
+    setRotationDegrees(x: number, y: number, z: number): void;
+    setRotationDegreesY(y: number): void;
+    setRotationDegreesX(x: number): void;
+    setRotationDegreesZ(z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    getRotation(): any;
+}
+
+/**
+ * A built collision component containing a rigid body description and collider description.
+ * Returned by collision factory functions (boxCollision, sphereCollision, etc.)
+ * and consumed by GameEntity.add().
+ */
+interface CollisionComponent {
+    __kind: 'collision';
+    bodyDesc: RigidBodyDesc;
+    colliderDesc: ColliderDesc;
+}
+interface BaseCollisionOptions {
+    /** Whether the body is static (fixed) or dynamic */
+    static?: boolean;
+    /** Whether this collider is a sensor */
+    sensor?: boolean;
+    /** Position offset relative to the entity origin */
+    offset?: Vec3;
+    /** Collision type string for group filtering */
+    collisionType?: string;
+    /** Allowed collision types for filtering */
+    collisionFilter?: string[];
+}
+interface BoxCollisionOptions extends BaseCollisionOptions {
+    /** Box dimensions (default: 1x1x1) */
+    size?: Vec3;
+}
+/**
+ * Create a box (cuboid) collision component.
+ */
+declare function boxCollision(opts?: BoxCollisionOptions): CollisionComponent;
+interface SphereCollisionOptions extends BaseCollisionOptions {
+    /** Sphere radius (default: 1) */
+    radius?: number;
+}
+/**
+ * Create a sphere (ball) collision component.
+ */
+declare function sphereCollision(opts?: SphereCollisionOptions): CollisionComponent;
+interface ConeCollisionOptions extends BaseCollisionOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a cone collision component.
+ */
+declare function coneCollision(opts?: ConeCollisionOptions): CollisionComponent;
+interface PyramidCollisionOptions extends BaseCollisionOptions {
+    /** Base radius (default: 1) */
+    radius?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a pyramid collision component (approximated as a cone).
+ */
+declare function pyramidCollision(opts?: PyramidCollisionOptions): CollisionComponent;
+interface CylinderCollisionOptions extends BaseCollisionOptions {
+    /** Top radius (default: 1) */
+    radiusTop?: number;
+    /** Bottom radius (default: 1) */
+    radiusBottom?: number;
+    /** Height (default: 2) */
+    height?: number;
+}
+/**
+ * Create a cylinder collision component.
+ */
+declare function cylinderCollision(opts?: CylinderCollisionOptions): CollisionComponent;
+interface PillCollisionOptions extends BaseCollisionOptions {
+    /** Capsule hemisphere radius (default: 0.5) */
+    radius?: number;
+    /** Cylindrical section length (default: 1) */
+    length?: number;
+}
+/**
+ * Create a pill (capsule) collision component.
+ */
+declare function pillCollision(opts?: PillCollisionOptions): CollisionComponent;
+interface PlaneCollisionOptions extends BaseCollisionOptions {
+    /** Tile dimensions (default: 10x10) */
+    tile?: {
+        x: number;
+        y: number;
+    };
+    /** Number of subdivisions per axis (default: 10) */
+    subdivisions?: number;
+    /** Pre-computed height data for the heightfield */
+    heightData?: Float32Array;
+}
+/**
+ * Create a plane (heightfield) collision component.
+ * For flat planes, pass no heightData — a zeroed heightfield is used.
+ */
+declare function planeCollision(opts?: PlaneCollisionOptions): CollisionComponent;
+interface ZoneCollisionOptions extends BaseCollisionOptions {
+    /** Zone dimensions (default: 1x1x1) */
+    size?: Vec3;
+}
+/**
+ * Create a zone (sensor cuboid) collision component.
+ * Always a sensor; static by default.
+ */
+declare function zoneCollision(opts?: ZoneCollisionOptions): CollisionComponent;
+
+/**
+ * Action interface -- the base contract for all actions.
+ *
+ * Actions are entity-scoped, self-contained objects that modify entity state
+ * over time. They are ticked automatically by the entity update loop.
+ */
+interface Action {
+    /** Internal duration in seconds (0 = instant, Infinity = persistent) */
+    readonly duration: number;
+    /** Whether this action has completed */
+    readonly done: boolean;
+    /** Whether this action auto-removes when done (set by entity.action()) */
+    persistent: boolean;
+    /** Advance the action by delta seconds */
+    tick(entity: GameEntity<any>, delta: number): void;
+    /** Reset the action to its initial state */
+    reset(): void;
+}
+
+interface CollisionContext<T, O extends GameEntityOptions, TGlobals extends Record<string, unknown> = any> {
+    entity: T;
+    other: GameEntity<O | any>;
+    globals: TGlobals;
+}
+interface CollisionDelegate<T, O extends GameEntityOptions> {
+    collision?: ((params: CollisionContext<any, any>) => void)[];
+}
+type IBuilder<BuilderOptions = any> = {
+    preBuild: (options: BuilderOptions) => BuilderOptions;
+    build: (options: BuilderOptions) => BuilderOptions;
+    postBuild: (options: BuilderOptions) => BuilderOptions;
+};
+type GameEntityOptions = {
+    name?: string;
+    color?: Color;
+    size?: Vec3;
+    position?: Vec3;
+    batched?: boolean;
+    collision?: Partial<CollisionOptions>;
+    material?: Partial<MaterialOptions>;
+    custom?: {
+        [key: string]: any;
+    };
+    collisionType?: string;
+    collisionGroup?: string;
+    collisionFilter?: string[];
+    _builders?: {
+        meshBuilder?: IBuilder | EntityMeshBuilder | null;
+        collisionBuilder?: IBuilder | EntityCollisionBuilder | null;
+        materialBuilder?: MaterialBuilder | null;
+    };
+};
+declare abstract class GameEntityLifeCycle {
+    abstract _setup(params: SetupContext<this>): void;
+    abstract _update(params: UpdateContext<this>): void;
+    abstract _destroy(params: DestroyContext<this>): void;
+}
+interface EntityDebugInfo {
+    buildInfo: () => Record<string, string>;
+}
+declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implements GameEntityLifeCycle, EntityDebugInfo, MoveableEntity, RotatableEntityAPI {
+    behaviors: Behavior[];
+    group: Group | undefined;
+    mesh: Mesh | undefined;
+    materials: Material[] | undefined;
+    bodyDesc: RigidBodyDesc | null;
+    body: RigidBody | null;
+    colliderDesc: ColliderDesc | undefined;
+    collider: Collider | undefined;
+    custom: Record<string, any>;
+    /** All collider descriptions for this entity (including primary) */
+    colliderDescs: ColliderDesc[];
+    /** All colliders attached to this entity's rigid body */
+    colliders: Collider[];
+    /** Additional meshes for compound visual entities (added via add()) */
+    compoundMeshes: Mesh[];
+    debugInfo: Record<string, any>;
+    debugMaterial: ShaderMaterial | undefined;
+    collisionDelegate: CollisionDelegate<this, O>;
+    collisionType?: string;
+    /** Batch key for instanced rendering (null if not instanced) */
+    batchKey: string | null;
+    /** Index within the instanced mesh batch */
+    instanceId: number;
+    /** Whether this entity uses instanced rendering */
+    isInstanced: boolean;
+    protected eventDelegate: EventEmitterDelegate<EntityEvents>;
+    private behaviorRefs;
+    transformStore: TransformState;
+    moveX: (delta: number) => void;
+    moveY: (delta: number) => void;
+    moveZ: (delta: number) => void;
+    moveXY: (deltaX: number, deltaY: number) => void;
+    moveXZ: (deltaX: number, deltaZ: number) => void;
+    move: (vector: Vector3) => void;
+    resetVelocity: () => void;
+    moveForwardXY: (delta: number, rotation2DAngle: number) => void;
+    getPosition: () => Vector | null;
+    getVelocity: () => Vector | null;
+    setPosition: (x: number, y: number, z: number) => void;
+    setPositionX: (x: number) => void;
+    setPositionY: (y: number) => void;
+    setPositionZ: (z: number) => void;
+    wrapAroundXY: (boundsX: number, boundsY: number) => void;
+    wrapAround3D: (boundsX: number, boundsY: number, boundsZ: number) => void;
+    rotateInDirection: (moveVector: Vector3) => void;
+    rotateYEuler: (amount: number) => void;
+    rotateEuler: (eulerRotation: Vector3) => void;
+    rotateX: (delta: number) => void;
+    rotateY: (delta: number) => void;
+    rotateZ: (delta: number) => void;
+    setRotationY: (y: number) => void;
+    setRotationX: (x: number) => void;
+    setRotationZ: (z: number) => void;
+    setRotationDegrees: (x: number, y: number, z: number) => void;
+    setRotationDegreesY: (y: number) => void;
+    setRotationDegreesX: (x: number) => void;
+    setRotationDegreesZ: (z: number) => void;
+    setRotation: (x: number, y: number, z: number) => void;
+    getRotation: () => any;
+    constructor();
+    /**
+     * Add meshes, collision components, or child entities to this entity.
+     * Supports fluent chaining: `entity.add(boxMesh()).add(boxCollision())`.
+     *
+     * - `Mesh`: First mesh becomes the primary mesh; subsequent meshes are
+     *   compound meshes grouped together.
+     * - `CollisionComponent`: First sets bodyDesc + colliderDesc; subsequent
+     *   add extra colliders to the same rigid body.
+     * - `NodeInterface`: Added as a child entity (delegates to BaseNode.add).
+     */
+    add(...components: Array<NodeInterface | Mesh | CollisionComponent>): this;
+    private addMeshComponent;
+    private addCollisionComponent;
+    private _actions;
+    /**
+     * Run a fire-and-forget action. Auto-removed when done.
+     * @example `me.runAction(moveBy({ x: 10, duration: 0.3 }))`
+     */
+    runAction<A extends Action>(action: A): A;
+    /**
+     * Register a persistent action (throttle, onPress). Not removed when done.
+     * @example `const press = entity.action(onPress())`
+     */
+    action<A extends Action>(action: A): A;
+    /**
+     * Tick all registered actions. Called automatically before user onUpdate callbacks.
+     *
+     * Resets velocity/angularVelocity accumulation before ticking so that
+     * actions can compose via `+=` without cross-frame build-up.
+     * (The existing move helpers like `moveXY` use `=` which doesn't accumulate,
+     * but action composition needs additive writes on a clean slate each frame.)
+     */
+    _tickActions(delta: number): void;
+    create(): this;
+    /**
+     * Add collision callbacks
+     */
+    onCollision(...callbacks: ((params: CollisionContext<this, O>) => void)[]): this;
+    /**
+     * Use a behavior on this entity via typed descriptor.
+     * Behaviors will be auto-registered as systems when the entity is spawned.
+     * @param descriptor The behavior descriptor (import from behaviors module)
+     * @param options Optional overrides for the behavior's default options
+     * @returns BehaviorHandle with behavior-specific methods for lazy FSM access
+     */
+    use<O extends Record<string, any>, H extends Record<string, any> = Record<string, never>>(descriptor: BehaviorDescriptor<O, H>, options?: Partial<O>): BehaviorHandle<O, H>;
+    /**
+     * Get all behavior references attached to this entity.
+     * Used by the stage to auto-register required systems.
+     */
+    getBehaviorRefs(): BehaviorRef[];
+    /**
+     * Entity-specific setup - resets actions for a fresh stage session.
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+     */
+    _setup(params: SetupContext<this>): void;
+    protected _loaded(_params: LoadedContext<this>): Promise<void>;
+    /**
+     * Entity-specific update - updates materials.
+     * Transform changes are applied by the stage after all update callbacks complete.
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+     */
+    _update(params: UpdateContext<this>): void;
+    /**
+     * Entity-specific destroy -- reserved for consumer game logic.
+     * Engine-internal resource disposal runs in _cleanup() instead.
+     */
+    _destroy(params: DestroyContext<this>): void;
+    /**
+     * Engine-internal resource cleanup -- runs automatically after destroy.
+     * Disposes GPU/DOM resources (meshes, materials, debug material).
+     *
+     * Note: actions, collision callbacks, and behavior refs are intentionally
+     * NOT cleared here -- they are registered by consumer code at module level
+     * and must persist across stage reloads. Actions are reset in _setup().
+     */
+    protected _cleanup(_params: CleanupContext<this>): void;
+    _collision(other: GameEntity<O>, globals?: any): void;
+    protected updateMaterials(params: any): void;
+    buildInfo(): Record<string, string>;
+    /**
+     * Dispatch an event from this entity.
+     * Events are emitted both locally and to the global event bus.
+     */
+    dispatch<K extends keyof EntityEvents>(event: K, payload: EntityEvents[K]): void;
+    /**
+     * Listen for events on this entity instance.
+     * @returns Unsubscribe function
+     */
+    listen<K extends keyof EntityEvents>(event: K, handler: (payload: EntityEvents[K]) => void): () => void;
+    /**
+     * Clean up entity event subscriptions.
+     */
+    disposeEvents(): void;
+}
+/**
+ * Create a bare entity with no mesh or collision.
+ * Use `.add(boxMesh(), boxCollision())` to compose its shape.
+ *
+ * @example
+ * ```ts
+ * const box = create({ position: { x: 0, y: 5, z: 0 } })
+ *   .add(boxMesh({ size: { x: 2, y: 2, z: 2 } }))
+ *   .add(boxCollision({ size: { x: 2, y: 2, z: 2 } }));
+ * ```
+ */
+declare function create(options?: Partial<GameEntityOptions>): GameEntity<GameEntityOptions>;
+
+export { sphereCollision as $, type Action as A, setRotationZ as B, setRotationDegrees as C, setRotationDegreesY as D, setRotationDegreesX as E, setRotationDegreesZ as F, setRotation as G, getRotation as H, GameEntity as I, type UpdateFunction as J, type DestroyFunction as K, type SetupContext as L, type DestroyContext as M, BaseNode as N, type LoadingEvent as O, type GameEntityOptions as P, type StageEvents as Q, type MaterialOptions as R, type SetupFunction as S, type TransformState as T, type UpdateContext as U, type Vec3 as V, type MoveableEntity as W, type InputPlayer as X, create as Y, type ZylemShader as Z, boxCollision as _, moveX as a, coneCollision as a0, pyramidCollision as a1, cylinderCollision as a2, pillCollision as a3, planeCollision as a4, zoneCollision as a5, type CollisionComponent as a6, EventEmitterDelegate as a7, zylemEventBus as a8, type ZylemEvents as a9, type GameEvents as aa, type EntityEvents as ab, type GameLoadingPayload as ac, type StateDispatchPayload as ad, type StageConfigPayload as ae, type EntityConfigPayload as af, type ZylemShaderObject as ag, type ZylemTSLShader as ah, isTSLShader as ai, isGLSLShader as aj, type InputPlayerNumber as ak, type InputProvider as al, type Inputs as am, GameEntityLifeCycle as an, type IGame as ao, type LoadedContext as ap, type CleanupContext as aq, type NodeInterface as ar, type TexturePath as as, moveY as b, createTransformStore as c, moveZ as d, moveXY as e, moveXZ as f, resetVelocity as g, moveForwardXY as h, getPosition as i, getVelocity as j, setPositionX as k, setPositionY as l, move as m, setPositionZ as n, wrapAround3D as o, rotateInDirection as p, rotateYEuler as q, resetTransformStore as r, setPosition as s, rotateEuler as t, rotateX as u, rotateY as v, wrapAroundXY as w, rotateZ as x, setRotationY as y, setRotationX as z };