tecs.physics

Bodytype#

type Body = BodyValue

The value a Body column holds.

BodyOptionstype#

type BodyOptions = {
    kind: string?,
    halfWidth: number?,
    halfHeight: number?,
    radius: number?,
    capsuleLength: number?,
    segment: {number}?,
    offsetX: number?,
    offsetY: number?,
    density: number?,
    friction: number?,
    restitution: number?,
    categoryBits: integer?,
    maskBits: integer?,
    isSensor: boolean?,
    fixedRotation: boolean?,
    isBullet: boolean?,
    sleepEnabled: boolean?,
    gravityScale: number?,
    linearDamping: number?,
    angularDamping: number?
}

The initial body and collider settings attach reads. segment = {x1, y1, x2, y2} selects a line collider in local pixels, useful for static map boundaries. It takes precedence over box or radius settings. Segment coordinates may be negative; endpoints must differ.

Collidertype#

type Collider = ColliderValue

The value a Collider column holds.

ContactBeginrecord#

record ContactBegin
    entityA: integer
    entityB: integer
end

Fields

entityA: integer

entityB: integer

ContactEndrecord#

record ContactEnd
    entityA: integer
    entityB: integer
end

Fields

entityA: integer

entityB: integer

Jointtype#

type Joint = JointValue

The value a Joint column holds.

JointOptionstype#

type JointOptions = {
    kind: string?,
    anchorAX: number?,
    anchorAY: number?,
    anchorBX: number?,
    anchorBY: number?,
    axisX: number?,
    axisY: number?,
    limitMin: number?,
    limitMax: number?,
    motorTargetVelocity: number?,
    motorMaxForce: number?,
    contactsEnabled: boolean?
}

The joint settings attachJoint reads.

Motiontype#

type Motion = MotionValue

The value a Motion column holds.

Optionstype#

type Options = {
    gravity: {number}?,
    subStepCount: integer?,
    workerCount: integer?,
    simulation: contract.Simulation?
}

The settings install reads before it creates a simulation.

QueryOptionstype#

type QueryOptions = {
    categoryBits: integer?,
    maskBits: integer?
}

The collision filters a raycast reads.

RaycastHitrecord#

record RaycastHit
    entity: integer
    x: number
    y: number
    normalX: number
    normalY: number
    fraction: number
end

Reports where a ray first met a collider.

Fields

entity: integer

x: number

y: number

normalX: number

normalY: number

fraction: number

SensorBeginrecord#

record SensorBegin
    sensor: integer
    visitor: integer
end

Fields

sensor: integer

visitor: integer

SensorEndrecord#

record SensorEnd
    sensor: integer
    visitor: integer
end

Fields

sensor: integer

visitor: integer

SolverHandlestruct#

struct SolverHandle
    index1: integer
    world0: integer
    generation: uint32
end

Identifies one live slot in a simulation.

Engine-owned and transient. RigidBody, ColliderShape and JointLink all use this shape so debug tools can read an attachment without knowing which arena it names. Ordinary game code should use Body, Motion and the functions on this module.

Fields

index1: integer

world0: integer

generation: uint32

angularVelocityfunction#

function angularVelocity(borrows world: ecs.World, entity: integer): number

Reads angular velocity in radians per second.

Radians need no conversion, so this is the number the solver holds, unlike the linear velocity beside it.

Arguments

Returns

applyForcefunction#

function applyForce(borrows world: ecs.World, entity: integer, x: number, y: number): nil

Applies a continuous force at the body's center.

The solver clears forces at the end of every step, so holding a body up against gravity means calling this every fixed step rather than once.

Arguments

Returns

applyForceAtfunction#

function applyForceAt(borrows world: ecs.World, entity: integer, x: number, y: number, pointX: number, pointY: number): nil

Applies a continuous force at a world-space point.

Cleared at the end of every step, like applyForce.

Arguments

Returns

applyImpulsefunction#

function applyImpulse(borrows world: ecs.World, entity: integer, x: number, y: number): nil

Pushes a body once, at its center of mass.

An impulse rather than a force, so the effect does not depend on how long the step happened to be. The solver applies it at the start of the next fixed step and wakes the body, because a resting island would otherwise ignore it.

Arguments

Returns

applyImpulseAtfunction#

function applyImpulseAt(borrows world: ecs.World, entity: integer, x: number, y: number, pointX: number, pointY: number): nil

Pushes a body once at a world-space point, which spins it as well.

Arguments

Returns

applyTorquefunction#

function applyTorque(borrows world: ecs.World, entity: integer, torque: number): nil

Applies torque, cleared at the end of every step like the two forces.

Arguments

Returns

attachfunction#

function attach(exclusive world: ecs.World, entity: integer, options: BodyOptions?): nil

Declares a body on an entity.

Physics creates the body during the next fixed update, at which point the entity gains its RigidBody row.

Arguments

Returns

Raises

• when the world has no simulation, the body kind is unknown, or a capsule has no positive radius

attachColliderfunction#

function attachCollider(exclusive world: ecs.World, entity: integer, body: integer, options: BodyOptions?): nil

Adds another collider to a declared body.

The collider is its own entity, which makes each shape independently inspectable and mutable. Physics creates the shape at the first fixed step after its body is live, and an owner that never gains a Body leaves the shape declared and unrealized.

Arguments

Returns

Raises

• when a capsule is requested without a positive radius

attachJointfunction#

function attachJoint(exclusive world: ecs.World, entity: integer, bodyA: integer, bodyB: integer, options: JointOptions?): nil

Declares a joint between two bodies.

Physics creates the joint at the first fixed step after both bodies are live, so declaring the joint in the same frame as the bodies it constrains costs no extra frame. A target that never gains a Body leaves the joint declared and unrealized, which is deliberate: a spawn staged this frame is not published yet, so reading the target here would reject correct code. Destroying either body destroys the joint entity with it.

Arguments

Returns

Raises

• when the joint kind is unknown

detachfunction#

function detach(exclusive world: ecs.World, entity: integer): nil

Removes a body's declaration.

Physics destroys the body during the next fixed update. The entity's other physics components remain.

Arguments

Returns

hasBodyfunction#

function hasBody(borrows world: ecs.World, entity: integer): boolean

Reports whether the solver is still simulating a body for an entity.

False for an entity whose RigidBody row came out of a snapshot into a simulation that never issued it, which is how a game tells "was simulating and is not any more" from "never had a body".

Arguments

Returns

installfunction#

function install(exclusive world: ecs.World, options: Options?): contract.Simulation

Installs a simulation and its fixed-step systems in a world.

Every system this registers runs in the fixed phases, so a simulation advances by whole steps of the world's own timestep and replays the same way on every machine.

Arguments

Returns

Raises

• when the world already has a simulation

isAwakefunction#

function isAwake(borrows world: ecs.World, entity: integer): boolean

Reports whether the solver currently considers a body awake.

Arguments

Returns

offunction#

function of(borrows world: ecs.World): contract.Simulation?

Returns the simulation installed in a world.

Arguments

Returns

raycastfunction#

function raycast(borrows world: ecs.World, x1: number, y1: number, x2: number, y2: number, options: QueryOptions?): RaycastHit?

Casts a segment and returns its nearest collider, in pixels.

The cast tests one segment and ignores everything beyond its end, so a miss may mean the segment was too short.

Arguments

Returns

setAngularVelocityfunction#

function setAngularVelocity(borrows world: ecs.World, entity: integer, omega: number): nil

Sets angular velocity in radians per second and wakes the body.

Arguments

Returns

setAwakefunction#

function setAwake(borrows world: ecs.World, entity: integer, awake: boolean): nil

Wakes or sleeps a body at the next fixed step.

Arguments

Returns

setVelocityfunction#

function setVelocity(borrows world: ecs.World, entity: integer, vx: number, vy: number): nil

Sets a body's velocity, in pixels per second, and wakes it.

Does nothing for an entity with no live body, which matches the zero velocity returns for one.

Arguments

Returns

teleportfunction#

function teleport(exclusive world: ecs.World, entity: integer, x: number, y: number, angle: number?): nil

Teleports a body and immediately updates its Transform2D.

A move rather than a push: velocity is left exactly as it was, so a falling body carries on falling from wherever it lands. The solver receives the move at the next fixed step, while the transform changes now so the frame that requested the teleport already draws it there.

Arguments

Returns

velocityfunction#

function velocity(borrows world: ecs.World, entity: integer): number, number

Reads a body's velocity after the last completed fixed step, in pixels per second.

Pixels match every other linear number this module accepts and returns. A caller that wants meters divides by pixelsPerMeter.

This reports what the solver last computed. Motion stores velocity only at a pause or a save, and does not mirror live motion.

Arguments

Returns

Bodyvariable#

const Body: ecs.ComponentDefinition<BodyValue>

Collidervariable#

const Collider: ecs.ComponentDefinition<ColliderValue>

ColliderOfvariable#

const ColliderOf: ecs.Relationship

ColliderShapevariable#

const ColliderShape: ecs.ComponentDefinition<SolverHandle>

Jointvariable#

const Joint: ecs.ComponentDefinition<JointValue>

JointBodyAvariable#

const JointBodyA: ecs.Relationship

JointBodyBvariable#

const JointBodyB: ecs.Relationship

JointLinkvariable#

const JointLink: ecs.ComponentDefinition<SolverHandle>

Motionvariable#

const Motion: ecs.ComponentDefinition<MotionValue>

PhysicsDisabledvariable#

const PhysicsDisabled: ecs.Component

PhysicsHeldvariable#

const PhysicsHeld: ecs.Component

pixelsPerMetervariable#

const pixelsPerMeter: number

Reports the fixed conversion between public pixels and solver meters.

The conversion keeps game coordinates in pixels and solver coordinates in meter-sized values.

RigidBodyvariable#

const RigidBody: ecs.ComponentDefinition<SolverHandle>