@iwsdk/core 0.4.1 → 0.5.0

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

@@ -4,7 +4,25 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Types } from '.././index.js';
+import { Entity, Types } from '.././index.js';
+import { Vector3, Quaternion } from '../runtime/three.js';
+type Vector3Input = Vector3 | readonly [number, number, number];
+type QuaternionInput = Quaternion | readonly [number, number, number, number];
+/** Pose passed to {@link PhysicsSystem.setBodyTransform}. */
+export interface PhysicsBodyTransformPose {
+    position: Vector3Input;
+    quaternion: QuaternionInput;
+}
+/** Options for {@link PhysicsSystem.setBodyTransform}. */
+export interface PhysicsBodyTransformOptions {
+    /**
+     * Clear linear and angular velocity after teleporting the body.
+     *
+     * @default true
+     */
+    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;
@@ -54,6 +72,18 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
                 type: Types.Float64;
                 default: number;
             };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
         }> | import("elics").Component<{
             shape: {
                 type: Types.Enum;
@@ -133,6 +163,18 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
                 type: Types.Float64;
                 default: number;
             };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
         }> | import("elics").Component<{
             force: {
                 type: Types.Vec3;
@@ -149,13 +191,99 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
         }>)[];
         where: import("elics").ValuePredicate[];
     };
-}, import("../ecs/world.js").World, import("../ecs/system.js").System<{
-    gravity: {
-        type: Types.Vec3;
-        default: [number, number, number];
+    gravityOverrides: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
+        }>)[];
+        where: import("elics").ValuePredicate[];
     };
-}, {
-    physicsEntities: {
+    linearDampingOverrides: {
         required: (import("elics").Component<{
             state: {
                 type: Types.Enum;
@@ -198,6 +326,18 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
                 type: Types.Float64;
                 default: number;
             };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
         }> | import("elics").Component<{
             shape: {
                 type: Types.Enum;
@@ -233,8 +373,9 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
                 default: number;
             };
         }>)[];
+        where: import("elics").ValuePredicate[];
     };
-    manipluatedEntities: {
+    angularDampingOverrides: {
         required: (import("elics").Component<{
             state: {
                 type: Types.Enum;
@@ -277,19 +418,496 @@ declare const PhysicsSystem_base: import("elics").SystemConstructor<{
                 type: Types.Float64;
                 default: number;
             };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
         }> | import("elics").Component<{
-            force: {
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
                 type: Types.Vec3;
                 default: [number, number, number];
             };
-            linearVelocity: {
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
+        }>)[];
+        where: import("elics").ValuePredicate[];
+    };
+}, import("../ecs/world.js").World, import("../ecs/system.js").System<{
+    gravity: {
+        type: Types.Vec3;
+        default: [number, number, number];
+    };
+}, {
+    physicsEntities: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
                 type: Types.Vec3;
                 default: [number, number, number];
             };
-            angularVelocity: {
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
                 type: Types.Vec3;
                 default: [number, number, number];
             };
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
+        }>)[];
+    };
+    manipluatedEntities: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            force: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+        }>)[];
+        where: import("elics").ValuePredicate[];
+    };
+    gravityOverrides: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
+        }>)[];
+        where: import("elics").ValuePredicate[];
+    };
+    linearDampingOverrides: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
+        }>)[];
+        where: import("elics").ValuePredicate[];
+    };
+    angularDampingOverrides: {
+        required: (import("elics").Component<{
+            state: {
+                type: Types.Enum;
+                enum: {
+                    readonly Static: "STATIC";
+                    readonly Dynamic: "DYNAMIC";
+                    readonly Kinematic: "KINEMATIC";
+                };
+                default: "DYNAMIC";
+            };
+            linearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            angularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            gravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            centerOfMass: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _linearVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _angularVelocity: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            _engineBody: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineOffset: {
+                type: Types.Float64;
+                default: number;
+            };
+            _engineGravityFactor: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineLinearDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineAngularDamping: {
+                type: Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            shape: {
+                type: Types.Enum;
+                enum: {
+                    readonly Sphere: "Sphere";
+                    readonly Box: "Box";
+                    readonly Cylinder: "Cylinder";
+                    readonly Capsules: "Capsules";
+                    readonly ConvexHull: "ConvexHull";
+                    readonly TriMesh: "TriMesh";
+                    readonly Auto: "Auto";
+                };
+                default: "Auto";
+            };
+            dimensions: {
+                type: Types.Vec3;
+                default: [number, number, number];
+            };
+            density: {
+                type: Types.Float32;
+                default: number;
+            };
+            restitution: {
+                type: Types.Float32;
+                default: number;
+            };
+            friction: {
+                type: Types.Float32;
+                default: number;
+            };
+            _engineShape: {
+                type: Types.Float64;
+                default: number;
+            };
         }>)[];
         where: import("elics").ValuePredicate[];
     };
@@ -330,13 +948,88 @@ export declare class PhysicsSystem extends PhysicsSystem_base {
     private bodyBuffer?;
     private scaleBuffer;
     private matrixBuffer;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    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;
+    /**
+     * 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.
+     */
+    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;