@iwsdk/core 0.5.3 → 1.0.0-rc.0

package/dist/physics/physics-system.d.ts

@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Entity, Types } from '.././index.js';
-import { Vector3, Quaternion } from '../runtime/three.js';
+import { Quaternion, Vector3 } from '../runtime/three.js';
+export { getCapsuleAxisEndpoints } from './physics-worker-protocol.js';
 type Vector3Input = Vector3 | readonly [number, number, number];
 type QuaternionInput = Quaternion | readonly [number, number, number, number];
 /** Pose passed to {@link PhysicsSystem.setBodyTransform}. */
@@ -22,12 +23,23 @@ export interface PhysicsBodyTransformOptions {
      */
     resetVelocity?: boolean;
 }
-export declare function getCapsuleAxisEndpoints(radius: number, totalHeight: number): [[number, number, number], [number, number, number]] | null;
 declare const PhysicsSystem_base: import("elics").SystemConstructor<{
     gravity: {
         type: Types.Vec3;
         default: [number, number, number];
     };
+    useWorker: {
+        type: Types.Boolean;
+        default: true;
+    };
+    updateFrequency: {
+        type: Types.Float32;
+        default: number;
+    };
+    interpolation: {
+        type: Types.Boolean;
+        default: true;
+    };
 }, {
     physicsEntities: {
         required: (import("elics").Component<{
@@ -472,6 +484,18 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
         type: Types.Vec3;
         default: [number, number, number];
     };
+    useWorker: {
+        type: Types.Boolean;
+        default: true;
+    };
+    updateFrequency: {
+        type: Types.Float32;
+        default: number;
+    };
+    interpolation: {
+        type: Types.Boolean;
+        default: true;
+    };
 }, {
     physicsEntities: {
         required: (import("elics").Component<{
@@ -913,127 +937,79 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
     };
 }>>;
 /**
- * Manages physics simulation using the Havok physics engine.
+ * Manages a Havok simulation on either a dedicated worker or the main thread.
  *
- * @remarks
- * - Initializes Havok physics engine and creates a physics world with gravity.
- * - Supports automatic physics shapes creation based on entity geometry when {@link PhysicsShapeType.Auto} is used.
- * - Supports multiple collision shapes: Sphere, Box, Cylinder, ConvexHull, and TriMesh.
- * - Synchronizes physics body transforms with Three.js Object3D positions and rotations using {@link PhysicsBody}.
- * - Handles physics manipulations like applying forces and setting velocities in {@link PhysicsManipulation}.
- * - Automatically cleans up physics resources when entities are removed.
- *
- * @example Basic physics setup
- * ```ts
- * // Add to your world to enable physics
- * world.addSystem(PhysicsSystem)
+ * Per-frame commands and poses travel through a pair of transferable
+ * ArrayBuffers.
+ * Both execution modes use the same binary protocol and shared Havok runtime.
+ * Worker mode alternates ownership of transferable ArrayBuffers, avoiding both
+ * structured-clone copies and SharedArrayBuffer's cross-origin-isolation
+ * requirement. Shape creation/removal uses infrequent control messages.
  *
- * // Create a dynamic box that falls due to gravity
- * const box = world.createTransformEntity(boxMesh)
- * box.addComponent(PhysicsShape, {
- *   shape: PhysicsShapeType.Box,
- *   dimensions: [1, 1, 1]
- * })
- * box.addComponent(PhysicsBody, { state: PhysicsState.Dynamic })
- * ```
+ * @remarks
+ * - Supports Sphere, Box, Cylinder, Capsule, ConvexHull, TriMesh, and Auto shapes.
+ * - Synchronizes dynamic body poses and velocities back to ECS entities.
+ * - Sends grab targets, impulses, velocity edits, damping, and gravity changes through one transport contract.
+ * - Automatically releases bodies and shapes when entities are removed.
  *
  * @category Physics
- * @see {@link PhysicsBody}
- * @see {@link PhysicsShape}
- * @see {@link PhysicsManipulation}
  */
 export declare class PhysicsSystem extends PhysicsSystem_base {
-    private havok?;
-    private havokWorld?;
-    private bodyBuffer?;
-    private scaleBuffer;
-    private matrixBuffer;
+    private transport?;
+    private transportReady;
+    private nextBodyHandle;
+    private nextSequence;
+    private bodyEntities;
+    private bodySnapshots;
+    private bodyResultSequenceFloors;
+    private failedBodyEntities;
+    private pendingCommands;
+    private commandPool;
+    private freeExchangeBuffers;
+    private completedExchanges;
+    private inFlightExchangeCount;
+    private stepAccumulator;
+    private pendingDebugStepDelta?;
+    private debugFlushWaiters;
+    init(): void;
     /**
-     * Cached Float32Array view over the entire Havok heap, reused across frames
-     * and bodies. Recreated only when the underlying ArrayBuffer changes (the
-     * WASM heap can grow and detach the old buffer), so per-body transform reads
-     * don't allocate a fresh typed-array view every frame.
-     */
-    private heapFloatView?;
-    /** Float32 view over the current Havok heap buffer (see {@link heapFloatView}). */
-    private getHeapFloatView;
-    init(): Promise<void>;
-    /**
-     * Teleport an existing Havok body to `pose`.
-     *
-     * @remarks
-     * No-ops until the entity has a live {@link PhysicsBody}. The pose is pushed
-     * directly to Havok and mirrored onto `entity.object3D` immediately so callers
-     * do not need to wait for the next physics tick before reading the reset
-     * transform. Linear and angular velocity are cleared by default, which is the
-     * expected behavior for reset/home-position flows.
-     *
-     * @example Reset a fallen prop to its home pose
-     * ```ts
-     * const physics = world.getSystem(PhysicsSystem);
-     * physics.setBodyTransform(prop, {
-     *   position: homePosition,
-     *   quaternion: homeQuaternion,
-     * });
-     * ```
+     * Teleport an existing physics body and mirror the pose immediately on its
+     * Object3D. The runtime consumes the command on the next available exchange.
      */
     setBodyTransform(entity: Entity, pose: PhysicsBodyTransformPose, options?: PhysicsBodyTransformOptions): void;
-    /**
-     * Reset a body's gravityFactor / linearDamping / angularDamping to the engine
-     * default when its field returns to the default value. The entity then drops
-     * out of the override set, so {@link syncReactiveOverrides} no longer visits
-     * it — this is the one place that restores the default. The `hasComponent`
-     * guard distinguishes the value-returned-to-default case from the other
-     * disqualify cause (PhysicsBody/PhysicsShape removal), where the body is being
-     * released and must not be written to.
-     */
-    private subscribeReactiveOverrides;
     update(delta: number): void;
-    private createBody;
+    /** Prepare one exact-delta physics tick for an ECS debugger step. */
+    prepareDebugFrame(delta: number): void;
     /**
-     * Push post-creation gravityFactor / linearDamping / angularDamping edits to
-     * Havok. Only overridden bodies are visited (see the value-predicate queries
-     * in the system definition); each sync diffs the component value against the
-     * last-pushed shadow, so a body whose field is unchanged this frame costs only
-     * a typed-array compare.
+     * Wait until all submitted physics work is reflected in ECS transforms.
+     * Used by debugger pause/step so worker and inline execution expose the same
+     * settled state at command boundaries.
      */
+    flushDebugFrame(): Promise<void>;
+    private handleTransportMessage;
+    private handleTransportFailure;
+    private waitForDebugWork;
+    private resolveDebugFlushWaiters;
+    private applyCompletedExchange;
+    private applyExchangeBuffer;
+    private renderInterpolatedTransforms;
+    private syncSnapshotToObject;
+    private getStepInterval;
+    private sendExchange;
+    private trySendPendingDebugStep;
+    private writeCommand;
+    private getPendingCommand;
+    private releasePendingCommands;
+    private discardPendingCommand;
+    private ensureBody;
+    private serializeShape;
+    private removeBody;
+    private setEngineHandles;
+    private subscribeReactiveOverrides;
     private syncReactiveOverrides;
-    /**
-     * Sync the entity's current {@link PhysicsBody.gravityFactor} onto its Havok
-     * body. Diffs the component value against `_engineGravityFactor` (the last
-     * value pushed) rather than reading back from Havok, so an unchanged body
-     * costs only a typed-array compare — no WASM call and no allocation. The Havok
-     * write and shadow update happen only on an actual change. No-op until the body
-     * exists. See {@link gravityOverrides}.
-     */
     private syncGravityFactor;
-    /**
-     * Sync the entity's current {@link PhysicsBody.linearDamping} onto its Havok
-     * body. Diffs against `_engineLinearDamping` (the last value pushed) rather
-     * than reading back from Havok, so an unchanged body costs only a typed-array
-     * compare — no WASM call and no allocation. The Havok write and shadow update
-     * happen only on an actual change. No-op until the body exists.
-     * See {@link linearDampingOverrides}.
-     */
     private syncLinearDamping;
-    /**
-     * Sync the entity's current {@link PhysicsBody.angularDamping} onto its Havok
-     * body. Diffs against `_engineAngularDamping` (the last value pushed) rather
-     * than reading back from Havok, so an unchanged body costs only a typed-array
-     * compare — no WASM call and no allocation. The Havok write and shadow update
-     * happen only on an actual change. No-op until the body exists.
-     * See {@link angularDampingOverrides}.
-     */
     private syncAngularDamping;
-    private createHavokShapes;
-    private createBallShape;
-    private createBoxShape;
-    private createCylinderShape;
-    private createCapsuleShape;
-    private createConvexHullShape;
-    private createTriMeshShape;
-    private getVertices;
-    private getIndices;
+    private queueManipulations;
 }
-export {};
 //# sourceMappingURL=physics-system.d.ts.map

package/dist/physics/physics-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"physics-system.d.ts","sourceRoot":"","sources":["../../src/physics/physics-system.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"physics-system.d.ts","sourceRoot":"","sources":["../../src/physics/physics-system.ts"],"names":[],"mappings":"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"}