@zylem/game-lib 0.7.0 → 0.8.2

package/dist/{entity-DNkYKfdp.d.ts → entity-BGEq1yfC.d.ts}

@@ -1,9 +1,10 @@
 import { BufferGeometry, Material, Mesh, Group, Vector3, Color, ShaderMaterial } from 'three';
-import { RigidBodyDesc, ColliderDesc, RigidBody, Collider, Vector } from '@dimforge/rapier3d-compat';
-import { a as Vec3Input, c as Vec3, s as MaterialBuilder, M as MaterialOptions, b as Vec2Input } from './material-Wz83vTTp.js';
-import { S as SetupContext, f as UpdateContext, D as DestroyContext, h as SetupFunction, i as LoadedFunction, U as UpdateFunction, j as DestroyFunction, k as CleanupFunction, L as LoadedContext, C as CleanupContext } from './base-node-life-cycle-CnJ-7zX-.js';
+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-DN6zlPoE.js';
+import { M as MaterialBuilder, e as MaterialOptions } from './material-DbSuZBbP.js';
+import { C as CollisionBuilder, L as LockAxesInput, a as CollisionOptions } from './collision-builder-B_tm8OVy.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-BK9xebT9.js';
 import { EventEmitterDelegate, EntityEvents } from './events.js';
-import { TransformState, MoveableEntity, BehaviorDescriptor, BehaviorHandle, BehaviorRef } from '@zylem/behaviors/core';
 
 interface NodeInterface {
     uuid: string;
@@ -98,417 +99,19 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     private recordLifecycleRegistration;
 }
 
-/**
- * `WasmStageRuntime` — owns one wasm `WebAssembly.Instance` of `@zylem/runtime`
- * and exposes the unified-Stage FFI as a set of typed TypeScript methods.
- * Replaces the legacy {@link ZylemRuntimeStageAdapter} + {@link ZylemWorld}
- * pair; every `ZylemStage` instantiates exactly one `WasmStageRuntime`.
- *
- * The runtime is the single source of truth for per-frame physics state.
- * TS-side behaviors and visual layers (destructible-3d, particle-emitter,
- * screen-visibility) read transforms from the render buffer; sim-only
- * behaviors push their attach/query payload through the per-behavior
- * helpers exposed here.
- */
-/** Sentinel handle for "no entity / failed allocation". Mirrors `INVALID_SLOT` in Rust. */
-declare const STAGE_INVALID_SLOT = 4294967295;
-/** Fixed render-buffer stride in floats. Must match `STAGE_RENDER_STRIDE` in Rust. */
-declare const STAGE_RENDER_STRIDE = 12;
-/** Fixed event-buffer stride in floats. Must match `STAGE_EVENT_STRIDE` in Rust. */
-declare const STAGE_EVENT_STRIDE = 6;
-/** Fixed pose-scratch stride in floats. Must match `POSE_SCRATCH_LEN` in Rust. */
-declare const STAGE_POSE_LEN = 7;
-declare const enum StageBodyKind {
-    Dynamic = 0,
-    Static = 1,
-    KinematicPosition = 2,
-    KinematicVelocity = 3
-}
-declare const enum StageBoundaryDim {
-    Two = 2,
-    Three = 3
-}
-declare const enum StageRicochetDim {
-    Two = 2,
-    Three = 3
-}
-declare const enum StageRicochetReflection {
-    Mirror = 0,
-    Angled = 1
-}
-declare const enum StageTopDownPlane {
-    Xy = 0,
-    Xz = 1
-}
-declare const enum StageEventType {
-    CollisionStarted = 1,
-    CollisionStopped = 2,
-    BoundaryHit = 3,
-    Ricochet = 4,
-    RegionEntered = 5,
-    JumpStarted = 6,
-    Landed = 7,
-    Wrapped = 8,
-    CooldownFired = 9
-}
-interface StageEvent {
-    type: StageEventType;
-    primarySlot: number | null;
-    secondarySlot: number | null;
-    payload: [number, number, number];
-}
-interface StagePose {
-    position: [number, number, number];
-    rotation: [number, number, number, number];
-}
-interface StageBodyConfig {
-    kind: StageBodyKind;
-    position: readonly [number, number, number];
-    rotation: readonly [number, number, number, number];
-    linearDamping: number;
-    angularDamping: number;
-    gravityScale: number;
-    canSleep: boolean;
-    ccdEnabled: boolean;
-    lockRotation: readonly [boolean, boolean, boolean];
-    lockTranslation: readonly [boolean, boolean, boolean];
-}
-type StageColliderShape = {
-    type: 'box';
-    halfExtents: readonly [number, number, number];
-} | {
-    type: 'sphere';
-    radius: number;
-} | {
-    type: 'capsule';
-    halfHeight: number;
-    radius: number;
-} | {
-    type: 'cylinder';
-    halfHeight: number;
-    radius: number;
-} | {
-    type: 'convexHull';
-    vertices: Float32Array;
-} | {
-    type: 'trimesh';
-    vertices: Float32Array;
-    indices: Uint32Array;
-} | {
-    type: 'heightfield';
-    rows: number;
-    cols: number;
-    scale: readonly [number, number, number];
-    heights: Float32Array;
-};
-interface StageColliderConfig {
-    shape: StageColliderShape;
-    offset: readonly [number, number, number];
-    friction: number;
-    restitution: number;
-    sensor: boolean;
-    /** Packed Rapier interaction-groups: high 16 bits = membership, low 16 bits = filter. */
-    collisionGroups: number;
-}
-/** Minimal exports surface used by `WasmStageRuntime`. Mirrors `stage_ffi.rs`. */
-interface StageWasmExports {
-    readonly memory: WebAssembly.Memory;
-    zylem_stage_create(initialCapacity: number): number;
-    zylem_stage_destroy(): void;
-    zylem_stage_set_gravity(x: number, y: number, z: number): void;
-    zylem_stage_step(dt: number): number;
-    zylem_stage_active_count(): number;
-    zylem_stage_capacity(): number;
-    zylem_stage_tick_count(): number;
-    zylem_stage_create_entity(): number;
-    zylem_stage_destroy_entity(slot: number): number;
-    zylem_stage_attach_body(slot: number, kind: number, px: number, py: number, pz: number, rx: number, ry: number, rz: number, rw: number, linearDamping: number, angularDamping: number, gravityScale: number, canSleep: number, ccdEnabled: number, lockRotX: number, lockRotY: number, lockRotZ: number, lockTransX: number, lockTransY: number, lockTransZ: number): number;
-    zylem_stage_add_collider_box(slot: number, hx: number, hy: number, hz: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_sphere(slot: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_capsule(slot: number, halfHeight: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_cylinder(slot: number, halfHeight: number, radius: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_convex_hull(slot: number, vertexOffset: number, vertexCount: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_trimesh(slot: number, vertexOffset: number, vertexCount: number, indexOffset: number, indexCount: number, ox: number, oy: number, oz: number, friction: number, restitution: number, sensor: number, collisionGroups: number): number;
-    zylem_stage_add_collider_heightfield(slot: number, rows: number, cols: number, sx: number, sy: number, sz: number, heightOffset: number, px: number, py: number, pz: number, friction: number, restitution: number, collisionGroups: number): number;
-    zylem_stage_get_pose(slot: number): number;
-    zylem_stage_pose_ptr(): number;
-    zylem_stage_pose_len(): number;
-    zylem_stage_set_position(slot: number, x: number, y: number, z: number): number;
-    zylem_stage_set_rotation(slot: number, x: number, y: number, z: number, w: number): number;
-    zylem_stage_set_linvel(slot: number, x: number, y: number, z: number): number;
-    zylem_stage_get_linvel(slot: number): number;
-    zylem_stage_set_angvel(slot: number, x: number, y: number, z: number): number;
-    zylem_stage_apply_impulse(slot: number, x: number, y: number, z: number): number;
-    zylem_stage_vec3_ptr(): number;
-    zylem_stage_render_ptr(): number;
-    zylem_stage_render_len(): number;
-    zylem_stage_render_stride(): number;
-    zylem_stage_event_ptr(): number;
-    zylem_stage_event_len(): number;
-    zylem_stage_event_count(): number;
-    zylem_stage_event_stride(): number;
-    zylem_stage_query_ptr(): number;
-    zylem_stage_query_len(): number;
-    zylem_stage_scratch_ptr(): number;
-    zylem_stage_scratch_capacity(): number;
-    zylem_stage_attach_cooldown(slot: number): number;
-    zylem_stage_cooldown_register(slot: number, id: number, duration: number, immediate: number): number;
-    zylem_stage_cooldown_fire(slot: number, id: number): number;
-    zylem_stage_cooldown_reset(slot: number, id: number): number;
-    zylem_stage_cooldown_remaining(slot: number, id: number): number;
-    zylem_stage_attach_world_boundary(slot: number, dim: number, top: number, bottom: number, left: number, right: number, front: number, back: number, padding: number): number;
-    zylem_stage_query_world_boundary(slot: number): number;
-    zylem_stage_attach_screen_wrap(slot: number, width: number, height: number, centerX: number, centerY: number, edgeThreshold: number): number;
-    zylem_stage_query_screen_wrap(slot: number): number;
-    zylem_stage_attach_ricochet(slot: number, dim: number, minSpeed: number, maxSpeed: number, speedMultiplier: number, maxAngleDeg: number, reflectionMode: number): number;
-    zylem_stage_query_ricochet(slot: number): number;
-    zylem_stage_attach_thruster(slot: number, maxSpeed: number, acceleration: number, turnRateRadS: number, linearDamping: number): number;
-    zylem_stage_set_thruster_input(slot: number, thrust: number, turn: number): void;
-    zylem_stage_query_thruster(slot: number): number;
-    zylem_stage_attach_top_down(slot: number, plane: number, speed: number, faceMovement: number): number;
-    zylem_stage_set_top_down_input(slot: number, a: number, b: number): void;
-    zylem_stage_attach_jumper_2d(slot: number, jumpForce: number, maxJumps: number, jumpBufferTime: number, coyoteTime: number, gravity: number): number;
-    zylem_stage_set_jumper_2d_input(slot: number, jumpPressed: number): void;
-    zylem_stage_query_jumper_2d(slot: number): number;
-    zylem_stage_attach_jumper_3d(slot: number, jumpForce: number, maxJumps: number, gravity: number): number;
-    zylem_stage_set_jumper_3d_input(slot: number, jump: number): void;
-    zylem_stage_query_jumper_3d(slot: number): number;
-    zylem_stage_attach_shooter_2d(slot: number, fireRateHz: number, muzzleOffsetX: number, muzzleOffsetY: number, muzzleSpeed: number): number;
-    zylem_stage_shooter_2d_fire(slot: number, x: number, y: number, z: number, yaw: number): number;
-    zylem_stage_query_shooter_2d(slot: number): number;
-    zylem_stage_attach_platformer_3d(slot: number, halfHeight: number, radius: number, walkSpeed: number, runSpeed: number, jumpForce: number, maxJumps: number, gravity: number): number;
-    zylem_stage_set_platformer_3d_input_axes(slot: number, moveX: number, moveZ: number): void;
-    zylem_stage_set_platformer_3d_input_buttons(slot: number, jump: number, run: number): void;
-    zylem_stage_query_platformer_3d(slot: number): number;
-    zylem_stage_attach_first_person(slot: number, walkSpeed: number, runSpeed: number, eyeHeight: number, lookSensitivity: number): number;
-    zylem_stage_set_first_person_input(slot: number, moveX: number, moveZ: number, lookYaw: number, lookPitch: number, run: number): void;
-    zylem_stage_query_first_person(slot: number): number;
-    zylem_stage_invalid_slot(): number;
-}
-/** Default options for `createWasmStageRuntime`. */
-interface WasmStageRuntimeOptions {
-    initialCapacity?: number;
-    gravity?: readonly [number, number, number];
-    imports?: WebAssembly.Imports;
-}
-/**
- * Owns the wasm instance plus the live float-views over its render / event /
- * pose / scratch buffers. The instance is per-`ZylemStage`; each stage gets
- * its own `WebAssembly.Instance` so the singleton inside `stage_ffi.rs`
- * stays single-stage scoped (today's `thread_local!` contract).
- */
-declare class WasmStageRuntime {
-    readonly exports: StageWasmExports;
-    private readonly memory;
-    private renderView;
-    private eventView;
-    private poseView;
-    private vec3View;
-    private queryView;
-    private scratchView;
-    constructor(exports: StageWasmExports, options?: WasmStageRuntimeOptions);
-    /** Recreate typed views over wasm memory. Call after step() or whenever memory may have grown. */
-    refreshViews(): void;
-    /** Step the simulation by `dt` seconds. Refreshes views afterwards. */
-    step(dt: number): number;
-    dispose(): void;
-    get tickCount(): number;
-    get activeCount(): number;
-    setGravity(x: number, y: number, z: number): void;
-    createEntity(): number;
-    destroyEntity(slot: number): boolean;
-    attachBody(slot: number, config: StageBodyConfig): boolean;
-    addCollider(slot: number, config: StageColliderConfig): boolean;
-    private stageScratch;
-    private stageScratchIndices;
-    getPose(slot: number, out?: StagePose): StagePose | null;
-    setPosition(slot: number, x: number, y: number, z: number): boolean;
-    setRotation(slot: number, x: number, y: number, z: number, w: number): boolean;
-    setLinearVelocity(slot: number, x: number, y: number, z: number): boolean;
-    getLinearVelocity(slot: number, out?: [number, number, number]): [number, number, number] | null;
-    setAngularVelocity(slot: number, x: number, y: number, z: number): boolean;
-    applyImpulse(slot: number, x: number, y: number, z: number): boolean;
-    /** Read-only view over the render buffer; one slot occupies {@link STAGE_RENDER_STRIDE} floats. */
-    get render(): Float32Array;
-    get renderStride(): number;
-    /** Drain the wasm event buffer into a fresh array of typed events. */
-    drainEvents(): StageEvent[];
-    get queryScratch(): Float32Array;
-    attachCooldown(slot: number): boolean;
-    registerCooldown(slot: number, id: number, durationSeconds: number, immediate?: boolean): boolean;
-    fireCooldown(slot: number, id: number): boolean;
-    resetCooldown(slot: number, id: number): boolean;
-    cooldownRemaining(slot: number, id: number): number;
-    attachWorldBoundary(slot: number, dim: StageBoundaryDim, bounds: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-        front: number;
-        back: number;
-        padding?: number;
-    }): boolean;
-    queryWorldBoundary(slot: number): {
-        hits: number;
-        clamped: [number, number, number];
-    } | null;
-    attachScreenWrap(slot: number, opts: {
-        width: number;
-        height: number;
-        centerX?: number;
-        centerY?: number;
-        edgeThreshold?: number;
-    }): boolean;
-    queryScreenWrap(slot: number): {
-        fsm: number;
-        lastWrappedAxes: number;
-    } | null;
-    attachRicochet(slot: number, dim: StageRicochetDim, opts: {
-        minSpeed: number;
-        maxSpeed: number;
-        speedMultiplier: number;
-        maxAngleDeg: number;
-        reflectionMode: StageRicochetReflection;
-    }): boolean;
-    queryRicochet(slot: number): {
-        bounces: number;
-        lastKind: number;
-    } | null;
-    attachThruster(slot: number, opts: {
-        maxSpeed: number;
-        acceleration: number;
-        turnRateRadPerSec: number;
-        linearDamping: number;
-    }): boolean;
-    setThrusterInput(slot: number, thrust: number, turn: number): void;
-    queryThruster(slot: number): {
-        headingRad: number;
-        speed: number;
-    } | null;
-    attachTopDown(slot: number, opts: {
-        plane: StageTopDownPlane;
-        speed: number;
-        faceMovement?: boolean;
-    }): boolean;
-    setTopDownInput(slot: number, axisA: number, axisB: number): void;
-    attachJumper2D(slot: number, opts: {
-        jumpForce: number;
-        maxJumps: number;
-        jumpBufferTime: number;
-        coyoteTime: number;
-        gravity: number;
-    }): boolean;
-    setJumper2DInput(slot: number, jumpPressed: boolean): void;
-    queryJumper2D(slot: number): {
-        grounded: boolean;
-        jumpCount: number;
-        coyote: number;
-        jumpBuffer: number;
-    } | null;
-    attachJumper3D(slot: number, opts: {
-        jumpForce: number;
-        maxJumps: number;
-        gravity: number;
-    }): boolean;
-    setJumper3DInput(slot: number, jump: boolean): void;
-    queryJumper3D(slot: number): {
-        grounded: boolean;
-        jumpCount: number;
-        verticalVelocity: number;
-    } | null;
-    attachShooter2D(slot: number, opts: {
-        fireRateHz: number;
-        muzzleOffsetX: number;
-        muzzleOffsetY: number;
-        muzzleSpeed: number;
-    }): boolean;
-    fireShooter2D(slot: number, x: number, y: number, z: number, yaw: number): boolean;
-    queryShooter2D(slot: number): {
-        cooldown: number;
-        firedCount: number;
-    } | null;
-    attachPlatformer3D(slot: number, opts: {
-        halfHeight: number;
-        radius: number;
-        walkSpeed: number;
-        runSpeed: number;
-        jumpForce: number;
-        maxJumps: number;
-        gravity: number;
-    }): boolean;
-    setPlatformer3DInputAxes(slot: number, moveX: number, moveZ: number): void;
-    setPlatformer3DInputButtons(slot: number, jump: boolean, run: boolean): void;
-    queryPlatformer3D(slot: number): {
-        grounded: boolean;
-        jumpCount: number;
-        fsmState: number;
-        speed: number;
-    } | null;
-    attachFirstPerson(slot: number, opts: {
-        walkSpeed: number;
-        runSpeed: number;
-        eyeHeight: number;
-        lookSensitivity: number;
-    }): boolean;
-    setFirstPersonInput(slot: number, opts: {
-        moveX: number;
-        moveZ: number;
-        lookYawDelta: number;
-        lookPitchDelta: number;
-        run: boolean;
-    }): void;
-    queryFirstPerson(slot: number): {
-        yaw: number;
-        pitch: number;
-        speed: number;
-        eyeHeight: number;
-    } | null;
-}
-/** Loads + instantiates a wasm module and constructs a `WasmStageRuntime`. */
-declare function createWasmStageRuntime(source: RequestInfo | URL | ArrayBuffer, options?: WasmStageRuntimeOptions): Promise<WasmStageRuntime>;
-
-/**
- * Options for configuring entity collision behavior.
- */
-interface CollisionOptions {
-    static?: boolean;
-    sensor?: boolean;
-    size?: Vec3Input;
-    position?: Vec3Input;
-    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;
@@ -528,8 +131,17 @@ declare abstract class EntityBuilder<T extends GameEntity<U> & P, U extends Game
     protected abstract createEntity(options: Partial<U>): T;
 }
 
+/** Structural slice of the physics body used by rotation helpers. */
+interface RotatableBodyLike {
+    rotation(): {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+}
 interface RotatableEntity {
-    body: RigidBody | null;
+    body: RotatableBodyLike | null;
     group: any;
     transformStore?: TransformState;
 }
@@ -615,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 {
@@ -630,12 +242,22 @@ 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?: Vec3Input;
     /** Collision type string for group filtering */
     collisionType?: string;
     /** Allowed collision types for filtering */
     collisionFilter?: string[];
+    /** Gravity scale applied at body spawn (no live setter FFI; default 1). */
+    gravityScale?: number;
+    /** Lock rotation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockRotations?: LockAxesInput;
+    /** Lock translation axes at body spawn: `true` for all, or per-axis tuple. */
+    lockTranslations?: LockAxesInput;
 }
 interface BoxCollisionOptions extends BaseCollisionOptions {
     /** Box dimensions (default: 1x1x1) */
@@ -771,13 +393,13 @@ type IBuilder<BuilderOptions = any> = {
     postBuild: (options: BuilderOptions) => BuilderOptions;
 };
 type GameEntitySimulationMode = 'ts' | 'runtime';
-type GameEntityRenderMode = 'mesh' | 'instanced';
+/** 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;
-    render?: GameEntityRenderMode;
-    batchKeyOverride?: string;
+    packKeyOverride?: string;
     body?: RuntimeEntityBodyMode;
     colorMode?: RuntimeEntityColorMode;
 }
@@ -786,7 +408,19 @@ type GameEntityOptions = {
     color?: Color;
     size?: Vec3Input;
     position?: Vec3Input;
-    batched?: boolean;
+    /**
+     * Spawn visibility behavior:
+     * - `undefined` (default): hidden while `spawnEntity` runs, revealed once
+     *   the spawn finalizes — even if no position was assigned.
+     * - `true` (strict): stays hidden until the first `setPosition`/`setPose`,
+     *   for spawner patterns that place the entity frames after spawn.
+     * - `false`: never hidden during spawn.
+     */
+    hideUntilPositioned?: boolean;
+    /** Explicit render visibility. When false, entity stays hidden until {@link GameEntity.reveal}. */
+    visible?: boolean;
+    /** Render path: `environment` (bundle), `pack` (instanced), or `none` (default). */
+    category?: RenderCategory;
     runtime?: RuntimeEntityOptions;
     collision?: Partial<CollisionOptions>;
     material?: Partial<MaterialOptions>;
@@ -814,52 +448,65 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     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;
-    /** Runtime slot index when owned by a stage runtime adapter (legacy alias for runtimeHandle). */
-    runtimeSlot: number;
+    /** Whether this entity is drawn via a WebGPU render bundle */
+    isBundled: boolean;
     /**
-     * Stable u32 handle into the wasm `StageSimulation`. Returned by
-     * `WasmStageRuntime.createEntity()`; -1 means the entity is not currently
-     * attached to the runtime. Replaces `runtimeSlot` and the legacy
-     * `entity.body` / `entity.collider` fields once Phase 3 lands.
+     * 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 attached to the wasm `StageSimulation`. */
+    /** True once the entity has been spawned into the wasm simulation. */
     runtimeAttached: boolean;
     /**
-     * Optional reference to the stage's {@link WasmStageRuntime}. Set by
-     * `StageEntityDelegate.spawnEntity()` so {@link GameEntity.getPose} /
-     * {@link GameEntity.setPose} can route through the unified-Stage runtime
-     * without each call site needing to thread the wasm handle around.
+     * 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: WasmStageRuntime | null;
+    wasmStageRef: BehaviorRuntime | null;
     protected eventDelegate: EventEmitterDelegate<EntityEvents>;
     private behaviorRefs;
     private cloneFactory;
     private trackAddedComponents;
     private trackedComponents;
     transformStore: TransformState;
+    /** Hide render target until spawn placement is confirmed. */
+    _spawnPlacementPending: boolean;
+    /** Author passed `position` in create options. */
+    _spawnPositionExplicit: boolean;
+    /** setPosition / setPose assigned a spawn placement during this spawn. */
+    _spawnPlacementReady: boolean;
+    /** True while {@link StageEntityDelegate.spawnEntity} is running for this entity. */
+    _spawnInProgress: boolean;
     moveX: (delta: number) => void;
     moveY: (delta: number) => void;
     moveZ: (delta: number) => void;
@@ -892,11 +539,12 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     setRotation: (x: number, y: number, z: number) => void;
     getRotation: () => any;
     constructor();
+    private wrapSpawnPlacementMutators;
+    /** Make the entity visible, clearing spawn placement pending state. */
+    reveal(): void;
     /**
-     * Read the entity's pose. Prefers the unified-Stage wasm runtime when
-     * the entity has a live `runtimeHandle`; otherwise falls back to the
-     * legacy TS Rapier `RigidBody` translation/rotation. Returns `null` when
-     * neither source is available.
+     * 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;
@@ -908,8 +556,7 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
         };
     } | null;
     /**
-     * Write the entity's pose. Routes through the unified-Stage wasm runtime
-     * when present; otherwise writes to the legacy TS Rapier `RigidBody`.
+     * Write the entity's pose into the wasm simulation.
      *
      * Either or both of `position` and `rotation` may be omitted to leave
      * that component unchanged.
@@ -1040,4 +687,4 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
  */
 declare function create(options?: Partial<GameEntityOptions>): GameEntity<GameEntityOptions>;
 
-export { type Action as A, setRotationDegrees as B, setRotationDegreesY as C, setRotationDegreesX as D, setRotationDegreesZ as E, setRotation as F, GameEntity as G, getRotation as H, type GameEntityOptions as I, EntityBuilder as J, EntityMeshBuilder as K, EntityCollisionBuilder as L, BaseNode as M, create as N, boxCollision as O, sphereCollision as P, coneCollision as Q, pyramidCollision as R, StageBodyKind as S, cylinderCollision as T, pillCollision as U, planeCollision as V, type WasmStageRuntimeOptions as W, zoneCollision as X, type CollisionComponent as Y, type NodeInterface as Z, GameEntityLifeCycle as _, type StageBodyConfig as a, type StageColliderConfig as b, type StageColliderShape as c, type StageEvent as d, type StagePose as e, type StageWasmExports as f, StageBoundaryDim as g, StageEventType as h, StageRicochetDim as i, StageRicochetReflection as j, StageTopDownPlane as k, STAGE_EVENT_STRIDE as l, STAGE_INVALID_SLOT as m, STAGE_POSE_LEN as n, STAGE_RENDER_STRIDE as o, WasmStageRuntime as p, createWasmStageRuntime as q, rotateInDirection as r, rotateYEuler as s, rotateEuler as t, rotateX as u, rotateY as v, rotateZ as w, setRotationY as x, setRotationX as y, setRotationZ 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 };