@zylem/game-lib 0.6.4 → 0.8.0

package/dist/{entity-vj-HTjzU.d.ts → entity-BdSI8CL3.d.ts}

@@ -1,147 +1,10 @@
-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 { c as BehaviorDescriptor, d as BehaviorHandle, e as BehaviorRef } from './behavior-descriptor-BXnVR8Ki.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;
-        SecondaryHorizontal: AnalogState;
-        SecondaryVertical: AnalogState;
-    };
-    /** Screen-space cursor position (normalized 0..1). Only populated by MouseProvider. */
-    pointer?: {
-        x: number;
-        y: number;
-    };
-}
-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;
-}
+import { BufferGeometry, Material, Mesh, Group, Vector3, Color, ShaderMaterial } from 'three';
+import { SimulationColliderDefinition, TransformState, SimulationBodyDefinition, MoveableEntity, BehaviorRuntime, Vector, BehaviorDescriptor, BehaviorHandle, BehaviorRef } from '@zylem/behaviors/core';
+import { c as Vec3, e as Vec3Input, b as Vec2Input, l as SimulationBody } from './vector-CiSHbivc.js';
+import { M as MaterialBuilder, e as MaterialOptions } from './material-9vJ6SZaI.js';
+import { C as CollisionBuilder, a as CollisionOptions } from './collision-builder-jF-toPIl.js';
+import { a as SetupContext, U as UpdateContext, D as DestroyContext, h as SetupFunction, i as LoadedFunction, g as UpdateFunction, j as DestroyFunction, C as CleanupFunction, k as LoadedContext, l as CleanupContext } from './base-node-life-cycle-D2NuN1VB.js';
+import { EventEmitterDelegate, EntityEvents } from './events.js';
 
 interface NodeInterface {
     uuid: string;
@@ -170,7 +33,6 @@ 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;
@@ -237,484 +99,49 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     private recordLifecycleRegistration;
 }
 
-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;
-    /** Opacity from 0 (fully transparent) to 1 (fully opaque). */
-    opacity?: number;
-    /**
-     * 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>;
-    /**
-     * Clear the static batch material cache.
-     * Should be called during game disposal to prevent stale material references
-     * from persisting across demo/stage switches.
-     */
-    static clearBatchCache(): void;
-    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, opacity?: number): this;
-    withShader(shader: ZylemShaderObject, opacity?: number): this;
-    withTSLShader(shader: ZylemTSLShader, opacity?: number): this;
-    private applyOpacity;
-    /**
-     * Set texture - loads in background (deferred).
-     * Material is created immediately with null map, texture applies when loaded.
-     */
-    setTexture(texturePath?: TexturePath, repeat?: Vector2, useTSL?: boolean, opacity?: number): void;
-    /**
-     * Set normal map for the current material
-     */
-    setNormalMap(normalMapPath: string, repeat?: Vector2): void;
-    setColor(color: Color, useTSL?: boolean, opacity?: number): void;
-    /**
-     * Set GLSL shader (WebGL only)
-     */
-    setShader(customShader: ZylemShaderObject, opacity?: number): void;
-    /**
-     * Set TSL shader (WebGPU compatible)
-     */
-    setTSLShader(tslShader: ZylemTSLShader, opacity?: number): 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'>>;
+type MeshBuilderOptions = Partial<Pick<GameEntityOptions, 'material'>>;
 declare class MeshBuilder {
-    _build(meshOptions: MeshBuilderOptions, geometry: BufferGeometry, materials: Material[]): Mesh;
+    _build(_meshOptions: MeshBuilderOptions, geometry: BufferGeometry, materials: Material[]): Mesh;
     _postBuild(): void;
 }
 
 declare abstract class EntityCollisionBuilder extends CollisionBuilder {
-    abstract collider(options: GameEntityOptions): ColliderDesc;
+    abstract collider(options: GameEntityOptions): SimulationColliderDefinition;
 }
 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;
+declare abstract class EntityBuilder<T extends GameEntity<U> & P, U extends GameEntityOptions, P = any> {
+    protected meshBuilder: EntityMeshBuilder | null;
+    protected collisionBuilder: EntityCollisionBuilder | null;
+    protected materialBuilder: MaterialBuilder | null;
+    protected options: Partial<U>;
+    protected entity: T;
+    constructor(options: Partial<U>, entity: T, meshBuilder: EntityMeshBuilder | null, collisionBuilder: EntityCollisionBuilder | null);
+    withPosition(setupPosition: Vec3): this;
+    withMaterial(options: Partial<MaterialOptions>, entityType: symbol): this;
+    applyMaterialToGroup(group: Group, materials: Material[]): void;
+    build(): T;
+    protected abstract createEntity(options: Partial<U>): T;
 }
 
-/**
- * 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>;
-
-type VelocityIntentMode = 'replace' | 'add';
-interface VelocityIntent {
-    x?: number;
-    y?: number;
-    z?: number;
-    mode: VelocityIntentMode;
-    priority?: number;
-}
-/**
- * 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: {
+/** Structural slice of the physics body used by rotation helpers. */
+interface RotatableBodyLike {
+    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;
-    };
-    /** Per-source velocity intents composed once per frame */
-    velocityChannels: Record<string, VelocityIntent>;
-    /** Dirty flags to track what needs to be applied */
-    dirty: {
-        position: boolean;
-        rotation: boolean;
-        /** @deprecated Use per-axis velocityX/Y/Z flags for new code */
-        velocity: boolean;
-        velocityX: boolean;
-        velocityY: boolean;
-        velocityZ: boolean;
-        velocityChannels: 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;
+    body: RotatableBodyLike | null;
     group: any;
     transformStore?: TransformState;
 }
@@ -800,14 +227,14 @@ interface RotatableEntityAPI extends RotatableEntity {
 }
 
 /**
- * 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().
+ * A built collision component containing plain body and collider definitions
+ * for the behaviors `Simulation`. Returned by collision factory functions
+ * (boxCollision, sphereCollision, etc.) and consumed by GameEntity.add().
  */
 interface CollisionComponent {
     __kind: 'collision';
-    bodyDesc: RigidBodyDesc;
-    colliderDesc: ColliderDesc;
+    bodyDesc: SimulationBodyDefinition;
+    colliderDesc: SimulationColliderDefinition;
     cloneComponent: () => CollisionComponent;
 }
 interface BaseCollisionOptions {
@@ -815,8 +242,12 @@ interface BaseCollisionOptions {
     static?: boolean;
     /** Whether this collider is a sensor */
     sensor?: boolean;
+    /** Allow the body to sleep when at rest (recommended for bulk dynamic scenes) */
+    canSleep?: boolean;
+    /** Continuous collision detection (expensive at scale; disable for small boxes) */
+    ccdEnabled?: boolean;
     /** Position offset relative to the entity origin */
-    offset?: Vec3;
+    offset?: Vec3Input;
     /** Collision type string for group filtering */
     collisionType?: string;
     /** Allowed collision types for filtering */
@@ -824,7 +255,7 @@ interface BaseCollisionOptions {
 }
 interface BoxCollisionOptions extends BaseCollisionOptions {
     /** Box dimensions (default: 1x1x1) */
-    size?: Vec3;
+    size?: Vec3Input;
 }
 /**
  * Create a box (cuboid) collision component.
@@ -882,10 +313,7 @@ interface PillCollisionOptions extends BaseCollisionOptions {
 declare function pillCollision(opts?: PillCollisionOptions): CollisionComponent;
 interface PlaneCollisionOptions extends BaseCollisionOptions {
     /** Tile dimensions (default: 10x10) */
-    tile?: {
-        x: number;
-        y: number;
-    };
+    tile?: Vec2Input;
     /** Number of subdivisions per axis (default: 10) */
     subdivisions?: number;
     /** Pre-computed height data for the heightfield */
@@ -898,7 +326,7 @@ interface PlaneCollisionOptions extends BaseCollisionOptions {
 declare function planeCollision(opts?: PlaneCollisionOptions): CollisionComponent;
 interface ZoneCollisionOptions extends BaseCollisionOptions {
     /** Zone dimensions (default: 1x1x1) */
-    size?: Vec3;
+    size?: Vec3Input;
 }
 /**
  * Create a zone (sensor cuboid) collision component.
@@ -958,12 +386,25 @@ type IBuilder<BuilderOptions = any> = {
     build: (options: BuilderOptions) => BuilderOptions;
     postBuild: (options: BuilderOptions) => BuilderOptions;
 };
+type GameEntitySimulationMode = 'ts' | 'runtime';
+/** Scene-direct, WebGPU bundle (static), or instanced pack. Default `none`. */
+type RenderCategory = 'none' | 'environment' | 'pack';
+type RuntimeEntityBodyMode = 'dynamic' | 'static' | 'none';
+type RuntimeEntityColorMode = 'base' | 'heatTint';
+interface RuntimeEntityOptions {
+    simulation?: GameEntitySimulationMode;
+    packKeyOverride?: string;
+    body?: RuntimeEntityBodyMode;
+    colorMode?: RuntimeEntityColorMode;
+}
 type GameEntityOptions = {
     name?: string;
     color?: Color;
-    size?: Vec3;
-    position?: Vec3;
-    batched?: boolean;
+    size?: Vec3Input;
+    position?: Vec3Input;
+    /** Render path: `environment` (bundle), `pack` (instanced), or `none` (default). */
+    category?: RenderCategory;
+    runtime?: RuntimeEntityOptions;
     collision?: Partial<CollisionOptions>;
     material?: Partial<MaterialOptions>;
     custom?: {
@@ -987,32 +428,54 @@ 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;
+    bodyDesc: SimulationBodyDefinition | null;
+    body: SimulationBody | null;
     physicsAttached: boolean;
-    colliderDesc: ColliderDesc | undefined;
-    collider: Collider | undefined;
+    /**
+     * The physics world that currently owns this entity's body/colliders.
+     * Tagged on registration and checked on teardown so a stale world never
+     * frees handles another world now owns (which would poison the wasm
+     * simulation). Untyped to avoid a circular import.
+     */
+    physicsWorldRef: unknown;
+    colliderDesc: SimulationColliderDefinition | 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[];
+    colliderDescs: SimulationColliderDefinition[];
     /** 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 */
+    /** Pack key for instanced rendering (null if not instanced) */
+    packKey: string | null;
+    /** Bundle key for WebGPU bundle rendering (null if not bundled) */
+    bundleKey: string | null;
+    /** Index within the instanced mesh pack */
     instanceId: number;
     /** Whether this entity uses instanced rendering */
     isInstanced: boolean;
+    /** Whether this entity is drawn via a WebGPU render bundle */
+    isBundled: boolean;
+    /**
+     * Raw wasm slot index for this entity in the stage's `Simulation`; -1 when
+     * not attached. Behavior systems address the runtime's slot-indexed buffers by
+     * this slot.
+     */
+    runtimeHandle: number;
+    /** True once the entity has been spawned into the wasm simulation. */
+    runtimeAttached: boolean;
+    /**
+     * The stage simulation's low-level runtime adapter. Set by
+     * `ZylemWorld.addEntity()` so {@link GameEntity.getPose} /
+     * {@link GameEntity.setPose} and behavior descriptors can route through
+     * the runtime without threading the handle around.
+     */
+    wasmStageRef: BehaviorRuntime | null;
     protected eventDelegate: EventEmitterDelegate<EntityEvents>;
     private behaviorRefs;
     private cloneFactory;
@@ -1051,6 +514,34 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     setRotation: (x: number, y: number, z: number) => void;
     getRotation: () => any;
     constructor();
+    /**
+     * Read the entity's pose from the wasm simulation. Returns `null` when
+     * the entity has not been spawned into the runtime yet.
+     */
+    getPose(): {
+        position: Vec3;
+        rotation: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        };
+    } | null;
+    /**
+     * Write the entity's pose into the wasm simulation.
+     *
+     * Either or both of `position` and `rotation` may be omitted to leave
+     * that component unchanged.
+     */
+    setPose(input: {
+        position?: Vec3Input;
+        rotation?: {
+            x: number;
+            y: number;
+            z: number;
+            w: number;
+        };
+    }): boolean;
     /**
      * Add meshes, collision components, or child entities to this entity.
      * Supports fluent chaining: `entity.add(boxMesh()).add(boxCollision())`.
@@ -1076,6 +567,8 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
      * @example `const press = entity.action(onPress())`
      */
     action<A extends Action>(action: A): A;
+    /** Remove all registered actions (fire-and-forget and persistent). */
+    clearActions(): void;
     /**
      * Tick all registered actions. Called automatically before user onUpdate callbacks.
      *
@@ -1166,4 +659,4 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
  */
 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, type LoadingEvent as N, BaseNode 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 };
+export { type Action as A, BaseNode as B, type CollisionComponent as C, EntityMeshBuilder as D, EntityBuilder as E, EntityCollisionBuilder as F, GameEntity as G, type NodeInterface as N, type GameEntityOptions as a, boxCollision as b, create as c, coneCollision as d, cylinderCollision as e, pillCollision as f, planeCollision as g, rotateYEuler as h, rotateEuler as i, rotateX as j, rotateY as k, rotateZ as l, setRotationY as m, setRotationX as n, setRotationZ as o, pyramidCollision as p, setRotationDegrees as q, rotateInDirection as r, sphereCollision as s, setRotationDegreesY as t, setRotationDegreesX as u, setRotationDegreesZ as v, setRotation as w, getRotation as x, GameEntityLifeCycle as y, zoneCollision as z };