ecs.Physics

Component spec for ecs.Physics, which maps to the native Physics rigid body. It is the first behavior-bearing ecs component: it declares both stored configuration fields (driven through the generic ecs.insert / ecs.set / ecs.get verbs) and a per-entity behavior factory whose imperative methods the ecs.get handle exposes.

The split follows the behavior tier: stored config goes through the constructor and verbs; per-entity runtime dynamics go through the handle methods below; world queries (raycasts, overlaps) live in the physics capability namespace.

Fields

• bodyType: string?: "Static" | "Dynamic" | "Kinematic" (placed at the pose its transform holds) | "KinematicVelocity" (carried at the velocity it is given).
• gravityScale: number?
• mass: number?
• linearDamping: number?
• angularDamping: number?
• ccd: boolean? — continuous collision detection, off by default. Sweeps the body along its motion so it cannot pass through thin geometry between steps; costly on any body travelling further than its own thickness per step, so turn it on per body (bullets, thrown props, a wrecking ball).
• interpolation: boolean?
• lockRotationX / lockRotationY / lockRotationZ: boolean?
• lockTranslationX / lockTranslationY / lockTranslationZ: boolean?
• dominance: number?: dominance group, -127 to 127: a dynamic body in a higher group pushes one in a lower group and is not pushed back.
• canSleep: boolean?, sleepLinearThreshold: number? (m/s), sleepAngularThreshold: number? (rad/s): whether and below what speeds the solver puts the body to sleep.
• centerOfMass: { number }?: local centre of mass; nil derives it from the colliders.
• inertia: { number }?: principal moments of inertia; nil derives them.
• softCcd: number?: metres of contact prediction ahead of the body; 0 is off.
• extraSolverIterations: number?, extraPgsIterations: number?: 0 to 16 substeps, and passes per substep, added to the world's for the body's island.

The Physics component refuses a value outside these ranges by name. Written through ecs.set directly, a value outside them is brought to the nearest one the solver holds, and Physics.bodyState reads what it holds.

Handle methods

ecs.get(id, ecs.Physics) returns the generic data handle plus these imperative methods, each bound to the entity's id. A vec3 argument accepts {x, y, z} or {a, b, c} array form and raises on malformed input.

• applyForce(force)
• applyImpulse(impulse)
• applyTorque(torque)
• applyForceAtPoint(force, point)
• setVelocity(velocity)
• addVelocity(delta)
• getVelocity() -> { x, y, z }?
• setAngularVelocity(velocity)
• getAngularVelocity() -> { x, y, z }?

Usage

ecs.insert(id, ecs.Physics{ bodyType = "Dynamic", mass = 2, ccd = true })
local body = ecs.get(id, ecs.Physics)
body:applyImpulse({ 0, 10, 0 })