Class: PhysicsSystem

Defined in: packages/core/src/physics/physics-system.ts:160

Manages a Havok simulation on either a dedicated worker or the main thread.

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.

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.

Extends

• System<{ gravity: { default: [number, number, number]; type: Vec3; }; interpolation: { default: true; type: Boolean; }; updateFrequency: { default: number; type: Float32; }; useWorker: { default: true; type: Boolean; }; }, { angularDampingOverrides: { required: (Component<{ _angularVelocity: { default: [number, number, number]; type: Vec3; }; _engineAngularDamping: { default: number; type: Float32; }; _engineBody: { default: number; type: Float64; }; _engineGravityFactor: { default: number; type: Float32; }; _engineLinearDamping: { default: number; type: Float32; }; _engineOffset: { default: number; type: Float64; }; _linearVelocity: { default: [number, number, number]; type: Vec3; }; angularDamping: { default: number; type: Float32; }; centerOfMass: { default: [number, number, number]; type: Vec3; }; gravityFactor: { default: number; type: Float32; }; linearDamping: { default: number; type: Float32; }; state: { default: "DYNAMIC"; enum: { Dynamic: "DYNAMIC"; Kinematic: "KINEMATIC"; Static: "STATIC"; }; type: Enum; }; }> | Component<{ _engineShape: { default: number; type: Float64; }; density: { default: number; type: Float32; }; dimensions: { default: [number, number, number]; type: Vec3; }; friction: { default: number; type: Float32; }; restitution: { default: number; type: Float32; }; shape: { default: "Auto"; enum: { Auto: "Auto"; Box: "Box"; Capsules: "Capsules"; ConvexHull: "ConvexHull"; Cylinder: "Cylinder"; Sphere: "Sphere"; TriMesh: "TriMesh"; }; type: Enum; }; }>)[]; where: ValuePredicate[]; }; gravityOverrides: { required: (Component<{ _angularVelocity: { default: [number, number, number]; type: Vec3; }; _engineAngularDamping: { default: number; type: Float32; }; _engineBody: { default: number; type: Float64; }; _engineGravityFactor: { default: number; type: Float32; }; _engineLinearDamping: { default: number; type: Float32; }; _engineOffset: { default: number; type: Float64; }; _linearVelocity: { default: [number, number, number]; type: Vec3; }; angularDamping: { default: number; type: Float32; }; centerOfMass: { default: [number, number, number]; type: Vec3; }; gravityFactor: { default: number; type: Float32; }; linearDamping: { default: number; type: Float32; }; state: { default: "DYNAMIC"; enum: { Dynamic: "DYNAMIC"; Kinematic: "KINEMATIC"; Static: "STATIC"; }; type: Enum; }; }> | Component<{ _engineShape: { default: number; type: Float64; }; density: { default: number; type: Float32; }; dimensions: { default: [number, number, number]; type: Vec3; }; friction: { default: number; type: Float32; }; restitution: { default: number; type: Float32; }; shape: { default: "Auto"; enum: { Auto: "Auto"; Box: "Box"; Capsules: "Capsules"; ConvexHull: "ConvexHull"; Cylinder: "Cylinder"; Sphere: "Sphere"; TriMesh: "TriMesh"; }; type: Enum; }; }>)[]; where: ValuePredicate[]; }; linearDampingOverrides: { required: (Component<{ _angularVelocity: { default: [number, number, number]; type: Vec3; }; _engineAngularDamping: { default: number; type: Float32; }; _engineBody: { default: number; type: Float64; }; _engineGravityFactor: { default: number; type: Float32; }; _engineLinearDamping: { default: number; type: Float32; }; _engineOffset: { default: number; type: Float64; }; _linearVelocity: { default: [number, number, number]; type: Vec3; }; angularDamping: { default: number; type: Float32; }; centerOfMass: { default: [number, number, number]; type: Vec3; }; gravityFactor: { default: number; type: Float32; }; linearDamping: { default: number; type: Float32; }; state: { default: "DYNAMIC"; enum: { Dynamic: "DYNAMIC"; Kinematic: "KINEMATIC"; Static: "STATIC"; }; type: Enum; }; }> | Component<{ _engineShape: { default: number; type: Float64; }; density: { default: number; type: Float32; }; dimensions: { default: [number, number, number]; type: Vec3; }; friction: { default: number; type: Float32; }; restitution: { default: number; type: Float32; }; shape: { default: "Auto"; enum: { Auto: "Auto"; Box: "Box"; Capsules: "Capsules"; ConvexHull: "ConvexHull"; Cylinder: "Cylinder"; Sphere: "Sphere"; TriMesh: "TriMesh"; }; type: Enum; }; }>)[]; where: ValuePredicate[]; }; manipluatedEntities: { required: (Component<{ _angularVelocity: { default: [number, number, number]; type: Vec3; }; _engineAngularDamping: { default: number; type: Float32; }; _engineBody: { default: number; type: Float64; }; _engineGravityFactor: { default: number; type: Float32; }; _engineLinearDamping: { default: number; type: Float32; }; _engineOffset: { default: number; type: Float64; }; _linearVelocity: { default: [number, number, number]; type: Vec3; }; angularDamping: { default: number; type: Float32; }; centerOfMass: { default: [number, number, number]; type: Vec3; }; gravityFactor: { default: number; type: Float32; }; linearDamping: { default: number; type: Float32; }; state: { default: "DYNAMIC"; enum: { Dynamic: "DYNAMIC"; Kinematic: "KINEMATIC"; Static: "STATIC"; }; type: Enum; }; }> | Component<{ angularVelocity: { default: [number, number, number]; type: Vec3; }; force: { default: [number, number, number]; type: Vec3; }; linearVelocity: { default: [number, number, number]; type: Vec3; }; }>)[]; where: ValuePredicate[]; }; physicsEntities: { required: (Component<{ _angularVelocity: { default: [number, number, number]; type: Vec3; }; _engineAngularDamping: { default: number; type: Float32; }; _engineBody: { default: number; type: Float64; }; _engineGravityFactor: { default: number; type: Float32; }; _engineLinearDamping: { default: number; type: Float32; }; _engineOffset: { default: number; type: Float64; }; _linearVelocity: { default: [number, number, number]; type: Vec3; }; angularDamping: { default: number; type: Float32; }; centerOfMass: { default: [number, number, number]; type: Vec3; }; gravityFactor: { default: number; type: Float32; }; linearDamping: { default: number; type: Float32; }; state: { default: "DYNAMIC"; enum: { Dynamic: "DYNAMIC"; Kinematic: "KINEMATIC"; Static: "STATIC"; }; type: Enum; }; }> | Component<{ _engineShape: { default: number; type: Float64; }; density: { default: number; type: Float32; }; dimensions: { default: [number, number, number]; type: Vec3; }; friction: { default: number; type: Float32; }; restitution: { default: number; type: Float32; }; shape: { default: "Auto"; enum: { Auto: "Auto"; Box: "Box"; Capsules: "Capsules"; ConvexHull: "ConvexHull"; Cylinder: "Cylinder"; Sphere: "Sphere"; TriMesh: "TriMesh"; }; type: Enum; }; }>)[]; }; }, this>

Constructors

Constructor

new PhysicsSystem(_w, _qm, _p): PhysicsSystem

Defined in: node_modules/.pnpm/elics@3.4.2/node_modules/elics/lib/system.d.ts:76

Parameters

_w

World

_qm

QueryManager

_p

number

Returns

PhysicsSystem

Inherited from

createSystem( { physicsEntities: { required: [PhysicsBody, PhysicsShape], }, manipluatedEntities: { required: [PhysicsBody, PhysicsManipulation], where: [ne(PhysicsBody, '_engineBody', 0)], }, gravityOverrides: { required: [PhysicsBody, PhysicsShape], where: [ne(PhysicsBody, 'gravityFactor', DEFAULT_GRAVITY_FACTOR)], }, linearDampingOverrides: { required: [PhysicsBody, PhysicsShape], where: [ne(PhysicsBody, 'linearDamping', DEFAULT_LINEAR_DAMPING)], }, angularDampingOverrides: { required: [PhysicsBody, PhysicsShape], where: [ne(PhysicsBody, 'angularDamping', DEFAULT_ANGULAR_DAMPING)], }, }, { gravity: { type: Types.Vec3, default: [0, -9.81, 0] }, useWorker: { type: Types.Boolean, default: true }, updateFrequency: { type: Types.Float32, default: DEFAULT_UPDATE_FREQUENCY }, interpolation: { type: Types.Boolean, default: true }, }, ).constructor

Properties

camera

readonly camera: PerspectiveCamera

Defined in: packages/core/src/ecs/system.ts:63

Inherited from

System.camera

---

cleanupFuncs

readonly cleanupFuncs: () => void[]

Defined in: packages/core/src/ecs/system.ts:66

Returns

void

Inherited from

System.cleanupFuncs

---

config

config: SystemConfigSignals<S>

Defined in: packages/core/src/ecs/system.ts:49

Inherited from

System.config

---

createEntity()

createEntity: () => Entity

Defined in: packages/core/src/ecs/system.ts:81

Returns

Entity

Inherited from

System.createEntity

---

globals

globals: Record<string, any>

Defined in: packages/core/src/ecs/system.ts:54

Inherited from

System.globals

---

input

readonly input: InputManager

Defined in: packages/core/src/ecs/system.ts:61

Inherited from

System.input

---

isPaused

isPaused: boolean

Defined in: packages/core/src/ecs/system.ts:48

Inherited from

System.isPaused

---

player

readonly player: XROrigin

Defined in: packages/core/src/ecs/system.ts:58

Inherited from

System.player

---

playerEntity

readonly playerEntity: Entity

Defined in: packages/core/src/ecs/system.ts:59

Inherited from

System.playerEntity

---

playerHeadEntity

readonly playerHeadEntity: Entity

Defined in: packages/core/src/ecs/system.ts:60

Inherited from

System.playerHeadEntity

---

priority

priority: number

Defined in: packages/core/src/ecs/system.ts:53

Inherited from

System.priority

---

queries

queries: Record<keyof Q, Query>

Defined in: packages/core/src/ecs/system.ts:50

Inherited from

System.queries

---

queryManager

queryManager: QueryManager

Defined in: packages/core/src/ecs/system.ts:52

Inherited from

System.queryManager

---

renderer

readonly renderer: WebGLRenderer

Defined in: packages/core/src/ecs/system.ts:64

Inherited from

System.renderer

---

scene

readonly scene: Scene

Defined in: packages/core/src/ecs/system.ts:62

Inherited from

System.scene

---

visibilityState

readonly visibilityState: Signal<VisibilityState>

Defined in: packages/core/src/ecs/system.ts:65

Inherited from

System.visibilityState

---

world

world: World

Defined in: packages/core/src/ecs/system.ts:51

Inherited from

System.world

---

xrFrame

xrFrame: XRFrame

Defined in: packages/core/src/ecs/system.ts:56

Inherited from

System.xrFrame

---

xrManager

xrManager: WebXRManager

Defined in: packages/core/src/ecs/system.ts:55

Inherited from

System.xrManager

Methods

flushDebugFrame()

flushDebugFrame(): Promise<void>

Defined in: packages/core/src/physics/physics-system.ts:408

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.

Returns

Promise<void>

---

init()

init(): void

Defined in: packages/core/src/physics/physics-system.ts:207

Returns

void

Overrides

System.init

---

play()

play(): void

Defined in: packages/core/src/ecs/system.ts:79

Returns

void

Inherited from

System.play

---

prepareDebugFrame()

prepareDebugFrame(delta): void

Defined in: packages/core/src/physics/physics-system.ts:397

Prepare one exact-delta physics tick for an ECS debugger step.

Parameters

delta

number

Returns

void

---

setBodyTransform()

setBodyTransform(entity, pose, options): void

Defined in: packages/core/src/physics/physics-system.ts:285

Teleport an existing physics body and mirror the pose immediately on its Object3D. The runtime consumes the command on the next available exchange.

Parameters

entity

Entity

pose

PhysicsBodyTransformPose

options

PhysicsBodyTransformOptions = {}

Returns

void

---

stop()

stop(): void

Defined in: packages/core/src/ecs/system.ts:80

Returns

void

Inherited from

System.stop

---

update()

update(delta): void

Defined in: packages/core/src/physics/physics-system.ts:332

Per-frame tick. Both arguments are in seconds (Three.js Clock convention), not milliseconds.

Parameters

delta

number

Seconds since the previous frame.

Returns

void

Overrides

System.update