physics
Convenience wrapper around the `__physics` FFI namespace. Covers raycasting, force / impulse / torque application, velocity reads and writes, body-property mutators (mass, damping, body type, locks), collision groups, joints, constraints, colliders, wheel-collider helpers, and th…
physics
Convenience wrapper around the __physics FFI namespace. Covers
raycasting, force / impulse / torque application, velocity reads and
writes, body-property mutators (mass, damping, body type, locks),
collision groups, joints, constraints, colliders, wheel-collider
helpers, and the observation reads that report what the solver holds
for a body and why it is not moving it, in one consistent surface.
Exposed as the Physics global via --!global Physics.
Exports
Queries:
Physics.raycast(origin, direction, maxDistance?, exclude?) -> table?Physics.raycastAll(origin, direction, maxDistance?, maxHits?) -> tablePhysics.overlapSphere(center, radius) -> tablePhysics.sphereCast(origin, radius, direction, maxDistance?, exclude?) -> table?Physics.capsuleCast(origin, radius, halfHeight, direction, maxDistance?, exclude?) -> table?Physics.boxCast(origin, halfExtents, direction, maxDistance?, exclude?) -> table?Physics.getGravity() -> vec3/Physics.setGravity(g)Physics.getVelocity(entityId?) -> vec3?/Physics.getAngularVelocity(entityId?) -> vec3?
Forces / impulses (each accepts either (vec3) for the script-context entity or (entityId, vec3); a vec3 may be an {x, y, z} table or three loose numbers):
Physics.applyForce/Physics.applyForceAtPoint/Physics.applyTorque: from code that runs inside a step (Physics.onBeforeStep/onAfterStep, a contact listener,fixedUpdate) they act on the next step alone (call once per step); from anywhere else they act over the next frame's simulated time (call once per frame). A continuous force integrates to force times time at any frame rate and tick ratePhysics.applyImpulse— one-shot velocity changePhysics.setVelocity/Physics.addVelocity/Physics.setAngularVelocity
Step hooks (at the physics tick rate, however many steps a frame runs):
Physics.onBeforeStep(fn) -> off:fn(dt, step)at the start of every step, after its force reset; a force written there acts on that step, and a read sees the state it starts from (springs, fields, thrusters, controllers)Physics.onAfterStep(fn) -> off:fn(dt, step)once the step has run, after its contact events and beforefixedUpdate; a read sees what that step left- One engine call runs every hook of a side, and a hook ends with
off()or with the component that registered it
Body properties:
Physics.setGravityScale,Physics.setMass,Physics.setLinearDamping,Physics.setAngularDamping,Physics.setCcdEnabledPhysics.setBodyType(entityId, "dynamic" | "kinematic" | "static")Physics.setRotationLocks(entityId, x, y, z)/Physics.setTranslationLocks(entityId, x, y, z)
Surfaces (what colliders are made of):
Physics.defineSurface(name, { friction?, restitution?, rollingResistance?, spinningResistance?, tags? })/Physics.removeSurface(name)/Physics.getSurface(name) -> PhysicsSurface?/Physics.surfaces(): a named material a collider takes by naming it in itssurfacefield, and a heightfield per sample throughsurfaceLayers/surfaceMap(a terrain's painted layers each collide as their own surface)rollingResistancec: a body rolling on the surface slows at c times gravity on level ground, stopping after v^2 / (2 c g), whatever its mass and shape;spinningResistancedoes the same for a body spinning about the contact normal. Both act through contacts only, so a ball in flight keeps its spin- Per contact friction and restitution combine as they always have (the average), and the two sides' rolling and spinning resistances add, so a ball of none on a floor of c rolls against c
- Ray and shape cast hits carry
surface; contacts, contact points, contact events andPhysics.contactPeakcarrysurfaceandotherSurface;Physics.groundContact(entityId, maxSlope?) -> PhysicsGroundContact?names what a body stands on and the surface under it
Surfaces that act on what touches them (collider fields, read by the physics step itself, no script per contact):
oneWay = { x, y, z }: the direction, in the collider's own frame, bodies pass through it along; a body meeting it from that side stands on it (a jump-through platform is{ 0, 1, 0 }).Physics.passThrough(entityId, throughId?)drops a standing rigid body throughsurfaceVelocity = { x, y, z }: the velocity, m/s in the collider's own frame, its surface moves at along itself while the collider stays put; friction carries what rests on it (conveyor belts, treadmills, escalators). Write the field at runtime to change itcontactTag = "name"withPhysics.setContactFilter(tagA, tagB, "ignore" | "sensor" | "solid")/Physics.contactFilters(): a pair of tags passes through each other ("ignore"), reports contacts and pushes nothing ("sensor"), or collides ("solid", every pair the filter does not name)
Collision groups & filtering:
Physics.setCollisionGroups(entityId, membership, filter)Physics.ignoreCollision(entityIdA, entityIdB, ignore?)
Joints / constraints / colliders:
Physics.addJoint(a, b, opts?)/Physics.removeJoint(id)/Physics.setJointMotor(id, vel, maxForce): joints with limits (limitMin/limitMax,swingLimit/twistLimit,axisLimits), motors (motorMode"velocity" / "position", capped bymotorMaxForce), joint frames (axis,remoteAxis),collideConnected, and a 6-DOFkind = "generic"withlockedAxesPhysics.jointState(id): a joint's angle / travel / swing and twist, velocity, whether it is at a limit, and the force its limit and motor appliedPhysics.jointReaction(id): the load (the stress) a joint carries as signed vectors, read along the member it holds (axialtension positive, compression negative,shear,bending,torsion, a rope'stension) and asload, the share of the break thresholds it is measured againstPhysics.jointReactions(targets?, opts?)/Physics.listenJointLoads(targets, listen?): many joints' loads in one call as arrays, and the peak each carried between two readsPhysics.addConstraint(id, opts?)/Physics.removeConstraint(id, index?)Physics.addCollider(id, config)/Physics.removeCollider(id)Physics.addWheelCollider(id, config?)/Physics.removeWheelCollider(id)/Physics.getWheelState(id)/Physics.vehicleState(chassisId): the wheels under one rigid body make up that body's ray-cast vehicle; theWheelCollidercomponent README covers the fieldsPhysics.detachWheel(id)/Physics.attachWheel(id): a wheel comes off its vehicle as a dynamic body of its own (rolling and bouncing with its spin, the vehicle driving on the wheels it has left) and goes back on its mount; abreakLoadtakes it off by itself, asolidwheel is a volume other bodies strike, andvehicleStatelists the wheels that came off underdetachedWheels
Observation (read off the solver, not off the Physics component):
Physics.observe(entityId?, opts?) -> PhysicsObservation?— one read of the world, or of one body;bodiesis an array whose entries each name their own entityPhysics.worldState() -> PhysicsWorldState— bodies by type, awake / asleep, colliders, soft bodies, joints, contact pairs and points, gravity, timestep, and the last step's costPhysics.softBodyState(entityId, opts?) -> PhysicsSoftBodyState?— a soft body's particle and cell counts, volume against rest, frame, bounds, sleep state and contacts, the solver simulating it (solver:"constraints"or"fem"), its particles' positions with{ positions = true }, the cage ashape = "mesh"body was filled with (cage: cell size, whether it came from the cache, build time, parts filled and left out), and where the body stands:statusis"built","pending"(the component stands and the body is built at the start of the next frame, so a read in the call that added it answers this;waitingFornames what the build waits on),"refused"(refusalsays why the component was not built) or"none"Physics.debugLines(opts?) -> PhysicsDebugLines?: what the physics world simulates beyond collider surfaces, as world-space lines with the data behind them: a soft body's elements coloured by load (cage), its free, pinned and attached particles (particles), soft-soft contacts (contacts), and eachWheelColliderwheel's suspension ray, travel, tyre and ground contact (wheels).capture { pass = "physics" }and the edit-mode collider overlay draw these lines;Physics.softBodyState(id).diagnosticsreads a soft body's inverted cells, self-crossings, element loads (maxLoad,loadedElements), pinned and attached particles as numbersPhysics.drawnPose(entityId) -> PhysicsDrawnPose?: where an entity is drawn this frame (position,rotation) beside the pose its transform holds (simulatedPosition,simulatedRotation, whatentity.positionreports). A dynamic body withPhysics.interpolationon is drawn blended between its last two physics ticks, and so is everything parented under it:interpolated,interpolatedBy(the body whose blend places it) andalpha(how far into the current tick the frame sits) say so. A camera or anything else that has to stay with a moving body on screen reads thisPhysics.bodyState(entityId) -> PhysicsBodyState?— the mass, inertia, gravity scale, damping, locks, CCD, collision groups, sleep timers, velocities, queued force and torque, colliders, contacts, joints and transform constraints the solver holdsPhysics.whyStill(entityId) -> (string?, string?)— the one reason the solver is not advancing a body, and the detail behind itPhysics.stillnessReasons() -> {string}— every reasonwhyStillcan answer withPhysics.contacts(entityId) -> {PhysicsContact}/Physics.touching(a, b) -> (boolean, number, {PhysicsContactPoint})Physics.catchUp() -> PhysicsCatchUp: how the frame clock kept up with real time: the frames it ran, those that dropped simulated time, owing more than a frame may catch up (boundSeconds, frommaxCatchUpSeconds) or with steps pastmaxSubstepsthat fell behind the time they cover (framesBehind), and the simulated seconds they dropped, counted since the engine startedPhysics.stepCost() -> PhysicsStepCost?: the last step's per-stage cost, with the share attributed to soft bodies (softBodyMs) and each soft body's part of it (softBodies: entity, ms, particles, cells, elements, contacts, substeps, costliest first); a soft body's own read carries its part aslastStepMsPhysics.softBodySettings(changes?) -> PhysicsSoftBodySettings: the settings every soft body runs under, each trading quality for cost (maxExtraSubstepRate,contactStiffening,resweepStrain,tangleDetection,overlapConstraints,recoveryPace, and the FEM solver'sfemTolerance,femMaxIterations,femMaxDenseDofs, read by the bodies whoseSoftBody.solveris"fem"); with a table, changes the fields it names, saved asphysics.soft_body_*world settings and applied from the next tick, and refuses an unknown field or a value out of range by namePhysics.solverSettings(changes?) -> PhysicsSolverSettings: the settings the constraint solver runs every step under (tickRate,maxCatchUpSeconds,maxSubsteps,solverIterations,pgsIterations,stabilizationIterations,warmStartCoefficient,warmStartJoints,lengthUnit,contactFrequency,contactDampingRatio,staticContactFrequency,staticContactDampingRatio,allowedLinearError,maxCorrectiveVelocity,predictionDistance,ccdSubsteps,frictionModel,frictionInBiasPass); with a table, changes the fields it names, saved asphysics.*world settings and run by the solver from the next step, and refuses an unknown field or a value out of range by name
High-level helpers:
Physics.raycastBetween(fromId, toId, maxDistance?) -> table?(ids or proxies)Physics.hasLineOfSight(fromId, toId) -> boolean(ids or proxies)
Usage
-- `Physics` is auto-injected by the prelude — no require in user code.
local hit = Physics.raycast({x=0,y=2,z=0}, {x=0,y=-1,z=0})
Physics.applyImpulse(entityId, {x=0, y=5, z=0})
Physics.addJoint(a, b, { kind = "fixed" })
Notes
- Most apply/set helpers are polymorphic on the first argument: they accept either an explicit
entityId(with the value as a second arg) or a value directly (using the script-context entity). addJointaccepts both vec3-style anchor tables (localAnchor = {x,y,z}) and pre-split scalar keys (localAnchorX/Y/Z); both forms forward as split keys to the Joint component.setCollisionGroupsadds theCollisionGroupcomponent if missing.getWheelStatereturnsnilwhen the entity has noWheelCollidercomponent, andvehicleStatereturnsnilwhen noWheelCollidersits under the chassis.- The sweeps (
sphereCast,capsuleCast,boxCast) reportdistanceas how far the shape's centre travels before its surface meets the geometry, andnormalas the outward normal of the surface it met — the same normal a ray hit carries. - A ray's or a sweep's
directionmay have any length: the engine normalises it, somaxDistanceand the reporteddistanceare world units whatever the direction's length, and a direction of zero length hits nothing. excludeis applied while searching: the first hitraycastreports, and every hitraycastAllcounts towardmaxHits, is on an entity outside the list, however many excluded colliders lie in front of it.- Every hit table carries
startedInside, and it says which surfacenormaldescribes.false— the query travelled to the collider and crossed its surface, sodistanceis how far it went,pointis where it met the surface, andnormalis that surface's outward normal.true— the query's own start already lay inside that collider, sodistanceis 0,pointis the start itself, andnormalis the collider's outward surface normal at the surface point nearest the start: the shortest way out of it.normalis a unit vector either way, and every collider shape answers an inside start the same way, so a slope read likemath.acos(hit.normal.y)is meaningful without knowing which shape was hit. raycastBetweenandhasLineOfSightcast from the source's world position toward the target's world position, wherever each sits in the hierarchy. Each end takes either an entity id or a proxy, and an end naming no entity raises an error naming the argument (fromIdortoId) and the id.- Each end's own colliders hold nothing up: those of the body it rides (its own
PhysicsorSoftBody, else the body of its nearest ancestor carrying one) and of every entity riding that body, a child collider composed onto it included.raycastBetweenpasses over the source's; with nothing between the pair, its first hit is the target's collider. raycastBetweenreturnsnilif the two entities are coincident (< 0.001 units apart).hasLineOfSightreturnstrueeven when nothing is hit: line-of-sight only fails if a collider belonging to neither end sits between the pair.- The observation reads answer in edit mode as well as play mode.
bodyStatereportsexists = falsewithstillness = "noBody"for an entity that carries no rigid body, andnilonly when nothing in the scene answers to that id. observe(nil, { bodies = false })builds the world accounting alone;{ contactPoints = false }keeps each contact pair's normal, depth, impulse and point count while leaving out the individual points.stepCostfigures cover the one step that ran, so they are already per-step costs; it isnilon a frame where the pipeline did not step.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2global Physics global physics
raycast(origin: vec3, direction: vec3, maxDistance: number?, exclude: (string | {string}) →
Cast a ray and return the first hit. Answers from COLLIDERS ALONE: a mesh that renders but carries no collider is not in the physics world, so a ray fired through it reports the same `nil` a ray through open air does. `renderer.raycast` answers the same ray against the geometry the renderer DRAWS, which is what reads the surface of a terrain, a procedurally generated mesh, or any plain `Model`. A trigger (`isTrigger`) holds nothing up, so the ray passes through it. `maxDistance` and `distance` are world units. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is. A `nil` says the ray met no COLLIDER, which `Physics.colliderCount()` separates from a world that holds none for it to meet.
| arg | type | description |
|---|---|---|
| origin | vec3 | Ray origin in world space. |
| direction | vec3 | Ray direction, of any length: the engine normalises it, so |
| maxDistance | number? | Maximum distance along the ray (defaults to 1000). |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local hit = Physics.raycast({x=0,y=2,z=0}, {x=0,y=-1,z=0})local hit = Physics.raycast(origin, dir, 50, { selfId, carriedId })local hit = Physics.raycast(muzzle, aim, 100); if hit and hit.softBody then Physics.applyImpulseAtPoint(hit.entityId, {x=0, y=0, z=-20}, hit.point, { radius = 0.3 }) endif Physics.colliderCount() == 0 then hit = renderer.raycast(eye, down, 200) end
colliderCount( ) →
How many colliders the physics world holds. Zero means no ray, cast or overlap fired into this world can hit anything, so it is what separates a query that MISSED from a query fired into a world that holds nothing to hit. Read off the collider set itself, so it costs the same whatever the world holds.
examples
if Physics.colliderCount() == 0 then print("nothing here is solid") endraycastAll(origin: vec3, direction: vec3, maxDistance: number?, maxHits: number?, exclude: (string | {string}) →
Cast a ray and return every hit up to `maxHits`. Answers from COLLIDERS ALONE, so a rendered mesh with no collider is absent from the result; `renderer.raycastAll` answers the same ray against the geometry the renderer draws. A trigger (`isTrigger`) holds nothing up, so the ray passes through it. `maxDistance` and `distance` are world units. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is.
| arg | type | description |
|---|---|---|
| origin | vec3 | Ray origin in world space. |
| direction | vec3 | Ray direction, of any length: the engine normalises it, so |
| maxDistance | number? | Optional distance limit along the ray. |
| maxHits | number? | Optional cap on the number of hits returned. |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local hits = Physics.raycastAll(origin, dir, 50, 4)
raycastScreen(sx: number, sy: number, maxDistance: number?, exclude: (string | {string}) →
Cast a ray from a screen pixel into the scene and return the first hit. Unprojects the pixel with `screenToRay`, then casts with `raycast`. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is.
| arg | type | description |
|---|---|---|
| sx | number | Screen X in viewport-local pixels (the space of `input.mouse_position` and `screenToRay`). |
| sy | number | Screen Y in viewport-local pixels. |
| maxDistance | number? | Maximum distance along the ray (defaults to 1000, matching `raycast`). |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local Zin = require("@builtin::modules.zinput")local x, y = Zin.state.mousePosition(); local hit = Physics.raycastScreen(x, y)
overlapSphere(center: vec3, radius: number) →
Find every entity id whose colliders overlap a sphere. A trigger (`isTrigger`) holds nothing up, so it is left out.
| arg | type | description |
|---|---|---|
| center | vec3 | Sphere center in world space. |
| radius | number | Sphere radius. |
examples
local ids = Physics.overlapSphere({x=0,y=0,z=0}, 5)sphereCast(origin: vec3, radius: number, direction: vec3, maxDistance: number?, exclude: (string | {string}) →
Cast a sphere along a direction and return the first hit. A trigger (`isTrigger`) holds nothing up, so the sweep passes through it. `maxDistance` and `distance` are world units. Applied while sweeping rather than to the answer, so a cast that starts inside an excluded collider reports what is behind it. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is.
| arg | type | description |
|---|---|---|
| origin | vec3 | Sphere center at the start of the cast. |
| radius | number | Sphere radius. |
| direction | vec3 | Cast direction, of any length: the engine normalises it, so |
| maxDistance | number? | Optional distance limit. |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local hit = Physics.sphereCast(o, 0.5, dir, 10)
local hit = Physics.sphereCast(o, 0.5, dir, 10, selfId)
capsuleCast(origin: vec3, radius: number, halfHeight: number, direction: vec3, maxDistance: number?, exclude: (string | {string}) →
Cast an upright capsule along a direction and return the first hit. This is the sweep that answers whether a body of that shape fits through a passage: a capsule of radius `r` reports a hit on anything that leaves it less than `2 * r` of clearance. A trigger (`isTrigger`) holds nothing up, so the sweep passes through it. stands `halfHeight + radius` tall in each direction. `maxDistance` and `distance` are world units. Applied while sweeping rather than to the answer, so a cast that starts inside an excluded collider reports what is behind it. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is.
| arg | type | description |
|---|---|---|
| origin | vec3 | Capsule centre at the start of the cast. |
| radius | number | Capsule radius. |
| halfHeight | number | Distance from the centre to either cap centre. The capsule |
| direction | vec3 | Cast direction, of any length: the engine normalises it, so |
| maxDistance | number? | Optional distance limit. |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local hit = Physics.capsuleCast(o, 0.3, 0.6, dir, 0.5)
local hit = Physics.capsuleCast(o, 0.3, 0.6, dir, 0.5, selfId)
boxCast(origin: vec3, halfExtents: vec3, direction: vec3, maxDistance: number?, exclude: (string | {string}) →
Cast a box along a direction and return the first hit. A trigger (`isTrigger`) holds nothing up, so the sweep passes through it. `maxDistance` and `distance` are world units. Applied while sweeping rather than to the answer, so a cast that starts inside an excluded collider reports what is behind it. `startedInside` is `false` for a surface the query crossed on its way there, and `true` when the query's own start already lay inside that collider — where `distance` is 0, `point` is the start itself, and `normal` is the shortest way out of the collider. `normal` is a unit vector either way. `surface` names the surface the collider is made of where the query met it (`Physics.defineSurface`; on a heightfield whose samples name layers, the layer of the sample nearest the point), and is absent for a collider naming none. `softBody` is set when what was hit is a soft body, whose surface the query meets as it is deformed now: a `PhysicsSoftHit` naming the surface triangle, the particles carrying it with the hit's weight on each, the particle nearest the hit, and `region`, the hit as a soft region to hand to `Physics.applyImpulse`, `Physics.pinSoftRegion` or `Physics.softParticles`. `Physics.applyImpulseAtPoint` takes the hit's `point` as it is.
| arg | type | description |
|---|---|---|
| origin | vec3 | Box center at the start of the cast. |
| halfExtents | vec3 | Half the size of the box on each axis. |
| direction | vec3 | Cast direction, of any length: the engine normalises it, so |
| maxDistance | number? | Optional distance limit. |
| exclude | (string | {string} | Optional entity id, or array of entity ids, to exclude from hits. |
examples
local hit = Physics.boxCast(o, {x=0.5,y=0.5,z=0.5}, dir, 10)local hit = Physics.boxCast(o, {x=0.5,y=0.5,z=0.5}, dir, 10, { selfId, carriedId })colliderShapes(entityId: string | entityRef) →
Read an entity's resolved physics collider shape(s) as the physics engine sees them, including auto-sized colliders. `shapeType` is one of `box`, `sphere`, `capsule`, `convex`, `mesh`, `heightfield`, `compound`, `wire` (a soft body's elements, colliding at its particle radius), `other`: the shape the simulation is running, so a mesh collider reads `mesh`. `params` carries half-extents for a box, radius for a sphere, radius and half-height for a capsule, and the collider's bounding half-extents for the shapes that have no parametric description. A convex collider reports its outline in `linePoints` instead.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
examples
local shapes = Physics.colliderShapes(id)
colliderManifest( ) →
List every physics collider in the world with what it is and what it takes part in — no geometry, so it is the cheap read to make before deciding what to do with each one. `role` is one of `static`, `dynamic`, `kinematic`, `sensor`. A sensor is a collider the simulation holds as one, reported ahead of the body type behind it, and a collider with no rigid body is static. `exact` says whether `colliderGeometry` would return this collider's true surface or its bounding box. Every collider of one entity shares its `entity`, so this is what to key per-object decisions on. The order is stable across calls over an unchanged world, which is what makes `colliderGeometry`'s positional colours usable.
examples
for _, c in ipairs(Physics.colliderManifest()) do print(c.entity, c.role) end
colliderGeometry(options: table?) →
Read the physics world as drawable triangles: every collider triangulated in world space into one indexed mesh, in GPU buffers ready to draw. Box, sphere, capsule, cylinder, cone, convex, triangle-mesh and heightfield colliders return their real surface, and a compound returns its children folded together; a shape with no triangulation returns its bounding box and reports `exact = false`. `options.colors` is POSITIONAL over `colliderManifest()` — entry `i` colours collider `i` — so you can colour by role, shape, entity or anything else you read there. A position you leave out takes `options.defaultColor`. The returned buffers are yours: destroy them when you replace them. entry of `colliders` is `{ entity, colliderName?, shapeType, role, exact, firstIndex, indexCount }`.
| arg | type | description |
|---|---|---|
| options | table? | `{ tessellation = "low"|"medium"|"high", colors = { {r,g,b,a}, ... }, defaultColor = {r,g,b,a} }`. |
examples
local geo = Physics.colliderGeometry({ tessellation = "high" })getGravity( ) →
Read the current world gravity vector.
examples
local g = Physics.getGravity()
setGravity(gravity: vec3) → void
Replace the world gravity vector.
| arg | type | description |
|---|---|---|
| gravity | vec3 | New gravity vector in m/s². |
examples
Physics.setGravity({x=0, y=-9.81, z=0})getVelocity(entityId: (string | entityRef) →
Read the linear velocity of an entity's rigid body, or of its soft body as a whole (its particles' velocities averaged by mass).
| arg | type | description |
|---|---|---|
| entityId | (string | entityRef | Target entity id or proxy; resolves from script context when omitted. |
examples
local v = Physics.getVelocity(id)
getAngularVelocity(entityId: (string | entityRef) →
Read the angular velocity of an entity's rigid body.
| arg | type | description |
|---|---|---|
| entityId | (string | entityRef | Target entity id or proxy; resolves from script context when omitted. |
examples
local w = Physics.getAngularVelocity(id)
isSleeping(entityId: (string | entityRef) →
Whether an entity's rigid or soft body is currently asleep (at rest and not simulating). A body sleeps once it stops moving, to save simulation cost.
| arg | type | description |
|---|---|---|
| entityId | (string | entityRef | Target entity id or proxy; resolves from script context when omitted. |
examples
if Physics.isSleeping(id) then Physics.wakeUp(id) end
wakeUp(entityId: (string | entityRef) → void
Wake an entity's sleeping rigid or soft body so it resumes simulating. The motion setters (`applyImpulse`, `setVelocity`, `setAngularVelocity`) wake the body for you; call this to wake one explicitly.
| arg | type | description |
|---|---|---|
| entityId | (string | entityRef | Target entity id or proxy; resolves from script context when omitted. |
examples
Physics.wakeUp(id)
idOf(ref: (string | entityRef) → void
Internal: the stable id of an entity id or proxy.
| arg | type | description |
|---|---|---|
| ref | (string | entityRef |
jointOwnerOf(carrierId: string) → void
The entity whose Joint the constraint carried by `carrierId` is, and that Joint's name (nil for the unnamed Joint): a named Joint's constraint is carried by an entity of its own directly under the Joint's entity.
| arg | type | description |
|---|---|---|
| carrierId | string |
jointCarrier(target: any, name: string?, fname: string) → string
The entity carrying the constraint of the joint `target` names: a `Joint` component (as `component.get("Joint", name)` returns it), or an entity with the Joint named `name` on it (its unnamed Joint when `name` is nil).
| arg | type | description |
|---|---|---|
| target | any | |
| name | string? | |
| fname | string |
observe(entityId: (string | entityRef, opts: ?) →
Read the solver's own state — the world's accounting, and what it holds for each body plus why it is not moving one. Every value comes off the simulation rather than the `Physics` component, so a write the solver refused or clamped reads back as what it kept. Answers in edit mode as well as play mode. builds the world accounting alone, and `contactPoints = false` keeps each contact pair's normal, depth, impulse and point count while leaving out the individual points. Both default to true. scene. `bodies` is an array, not a table keyed by entity id — each entry names its own entity in `entity`.
| arg | type | description |
|---|---|---|
| entityId | (string | entityRef | Report on this one entity. Omit for every body in the world. |
| opts | ? | `{ bodies: boolean?, contactPoints: boolean? }` — `bodies = false` |
examples
local o = Physics.observe(); for _, b in o.bodies do print(b.entity, b.stillness) end
local o = Physics.observe(id); print(o.bodies[1].stillness, o.bodies[1].stillnessDetail)
worldState( ) →
How many bodies, colliders, joints and contacts the simulation holds right now, with world gravity, the timestep, whether the pipeline is stepping at all, what the last step cost, and how many step hooks run around every step (`stepHooks`). Counted off the solver, so a body that failed to build is absent here while its `Physics` component still exists.
examples
local w = Physics.worldState(); print(w.bodies.awake .. "/" .. w.bodies.total .. " awake")
print(Physics.worldState().contacts.touchingPairs .. " pairs touching")
bodyState(entityId: string | entityRef) →
Everything the solver holds for one body — its type, mass, centre of mass, inertia, gravity scale, damping, lock flags, CCD, collision groups, sleep state, velocities, the force and torque queued for the next step, its colliders, contacts, joints and transform constraints, and why it is not moving. carries no rigid body, and `waitingFor` naming what its collider needs while that collider cannot be built), or `nil` when nothing in the scene answers to that id.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. |
examples
local b = Physics.bodyState(id); print(b.bodyType, b.mass, b.stillness)
local b = Physics.bodyState(id); if not b.exists then print(b.waitingFor or "no body was built") end
planeHold(entityId: string | entityRef) →
Which plane holds a body, and where the hold comes from: the `PlaneHold` covering the body (on its entity or an ancestor, a group hold over its collision groups, or a world hold), as the physics world applied it. A rigid or a soft body answers alike. when no hold holds the body (or nothing in the scene answers to that id).
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy of a body. |
examples
local h = Physics.planeHold(crate); if h then print(h.holder, h.covers, h.normal.z) end
forces(entityId: string | entityRef) →
Which forces act on a body from step to step, and their sum: every `Force` component driving it (on its entity or an entity under it, each named by its `source` entity and instance `name`), each evaluated at the pose the body stands at now, in the world frame, as the next step applies it. `applied` reads whether this engine's step applies them: an enabled dynamic body takes them, a static or kinematic one carries them unmoved. Forces written for one step (`applyForce`) are the body state's `queuedForce`. empty `forces` and zero sums for a body carrying none, or nil when nothing in the scene answers to that id with a rigid body.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy of a body. |
examples
local f = Physics.forces(rocket); print(f.force.y, #f.forces)
drawnPose(entityId: string | entityRef) →
Where an entity is drawn this frame, and where its transform puts it. The simulation advances in fixed ticks (`physics.tick_rate`, 30 a second by default) while frames are drawn at the display's rate, so a body with `Physics.interpolation` on is drawn blended between its last two ticks, and everything parented under it is drawn moved with it. `entity.position` reports the simulated pose, which moves only when a tick runs; this read reports the drawn one as well. Read it from a component's `update` to place anything that has to stay with a moving body on screen: a camera following it, a label over it, a measurement of how smoothly it moves. does not blend is drawn at its simulated pose. that id.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. Any entity answers; one the simulation |
examples
local d = Physics.drawnPose(car); print(d.position.z, d.simulatedPosition.z, d.interpolated)
local d = Physics.drawnPose(tyre); print(d.interpolated, d.interpolatedBy)
whyStill(entityId: string | entityRef) →
Why the solver is not moving a body. Returns `nil` when it IS moving it, and otherwise one of `noBody`, `simulationNotStepping`, `disabled`, `static`, `kinematic`, `infiniteMass`, `translationLocked`, `gravityDisabled`, `asleep`, `outsideIsland`, `resting`, `aboutToMove` — the nearest cause, so the answer names the thing to change. A second return carries the detail: which collider it rests on and how deeply, what its effective gravity works out to, and so on.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. |
examples
local why, detail = Physics.whyStill(id); if why then print(why, detail) end
stillnessReasons( ) →
Every reason `whyStill` can answer with, in the order the engine considers them. Read from the engine, so the list is the one the answers come from.
examples
for _, reason in Physics.stillnessReasons() do print(reason) end
contacts(entityId: string | entityRef, otherId: (string | entityRef) →
Every contact one body's colliders are in right now, with the other entity, the normal, how deeply the two interpenetrate, the normal and friction impulse the last step applied, how fast the two were closing as that step began, the step, and each contact point: the read behind "is it touching", "is it grounded" and "how hard did that hit land". It describes the last physics step; to detect every collision, hit and impact as an event on the step it happens, use `Physics.onContact`, `Physics.onImpact` or `Physics.contactPeak`. A pair is listed while its surfaces touch: a pair kept apart (`Physics.ignoreCollision`, collision groups) or no longer touching is not. For a soft body these are the contacts of its surface with every other collider, another soft body's surface included. A contact with a soft body on either side names the particles of it that are touching (`particles` for this side, `otherParticles` for the other), so a hit can be answered where it landed. Name `otherId` to read only the contacts with that one entity: a body resting on the ground holds a contact point per surface element that touches it, and a read of one pair costs that pair alone. or when the entity carries neither a rigid body nor a soft body.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. |
| otherId | (string | entityRef | Optional entity id or proxy: report only the contacts with it. |
examples
for _, c in Physics.contacts(id) do print(c.other, c.deepestPenetration) end
for _, c in Physics.contacts(truck, pole) do if c.totalImpulse > 5 then print("dented at", #c.particles, "particles") end enddefineSurface(name: string, surface: PhysicsSurfaceDefinition?) → void
Define a surface: a named material of contact coefficients that a collider takes by naming it in its `surface` field (every collider component carries one), and that a heightfield takes per sample through `surfaceLayers` / `surfaceMap` (how each painted layer of a terrain is its own ground). A surface holds `friction`, `restitution`, `rollingResistance` (a body rolling on it loses speed at this many times gravity on level ground, so a ball rolled at v stops after v^2 / (2 * rollingResistance * 9.81)), `spinningResistance` (the same for a body spinning on it about the contact normal) and free `tags` (what a footstep, a skid mark or an impact sound reads it by). Per contact the two sides' friction and restitution average and their resistances add (a ball of none on a floor of c rolls against c). Contacts, contact events and ray and shape cast hits name the surface each side is made of at the point, and `Physics.groundContact` names what a body stands on. Defining a name again replaces it, and every collider naming it takes the new values from the next physics step; a collider naming a surface no one defined keeps its own coefficients and still reports the name. unstated coefficients take friction 0.5 and 0 for the rest.
| arg | type | description |
|---|---|---|
| name | string | The surface's name, 1 to 64 bytes. |
| surface | PhysicsSurfaceDefinition? | `{ friction?, restitution?, rollingResistance?, spinningResistance?, tags? }`; |
examples
Physics.defineSurface("gravel", { friction = 0.6, rollingResistance = 0.04, tags = { "loose", "crunchy" } })Physics.defineSurface("ice", { friction = 0.05, rollingResistance = 0.002 })entity("road").component.add("BoxCollider", { half = { 50, 0.5, 4 }, surface = "gravel" })removeSurface(name: string) → void
Remove a surface `Physics.defineSurface` defined. Colliders naming it keep the name and collide with their own coefficients from the next step.
| arg | type | description |
|---|---|---|
| name | string | The surface's name. |
examples
Physics.removeSurface("ice")getSurface(name: string) →
The surface `name` names, as `Physics.defineSurface` defined it.
| arg | type | description |
|---|---|---|
| name | string | The surface's name. |
examples
local s = Physics.getSurface(hit.surface); if s and table.find(s.tags, "loose") then sprayGravel(hit.point) end
surfaces( ) →
Every surface `Physics.defineSurface` defined, by name.
examples
for name, s in Physics.surfaces() do print(name, s.friction, s.rollingResistance) end
groundContact(entityId: string | entityRef, maxSlope: number?) →
What a body stands on now: of its contacts whose normal leans less than `maxSlope` degrees from straight up against gravity, the one the last step pushed hardest, with the surface it is made of under the body. The read a footstep sound, a tyre without a `WheelCollider`, a skid mark or dust takes to know what is underfoot, on a painted terrain as well.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy carrying a rigid body. |
| maxSlope | number? | Optional steepest ground counted, in degrees from level (default 60). |
examples
local g = Physics.groundContact(player); if g and g.surface == "gravel" then playStep("gravel") endtouching(entityId: string | entityRef, otherId: string | entityRef) →
Whether two entities are touching, and how deeply. in metres and `0` for surfaces that meet without overlapping.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. |
| otherId | string | entityRef | The other entity id or proxy. |
examples
local hit, depth = Physics.touching(a, b); print(hit, depth)
softBodyState(entityId: string | entityRef, opts: table?) →
What the solver holds for one soft body (an entity with a `SoftBody` component): its particle, cell and edge counts, the volume it encloses against its rest volume, its centre of mass and frame, the box around its particles, how fast they move, whether it sleeps, and what it touches, and in `render` how the entity's model is drawn carried by the body. `plastic` is how deep the deformation that stayed is, in metres (a dent past the component's `plasticYield`; `plasticMean` the mean over the particles), 0 for a body that only deformed elastically. `diverged` is true while a step has carried the body into a state no material reaches (its particles spread, or its volume grown, past ten times the shape it is held at, or a particle carried to a value that is not a number), and `divergence` says what was measured; the engine log names the body the step it diverges. `tearStrain` and `tearForce` are the thresholds it tears past (0 tears never), and `piece` names the torn piece a body split off another continues (nil for a body built from its fields). `attachments` lists the regions held to rigid bodies (`attachSoftRegion`) with the force each pulls with, `attachedParticles` counts the particles tied, and `clusters` counts the body's frame plus one per joint end anchored on a region of it. `pins` lists the regions pinned (`pinSoftRegion`) with how many particles each holds, its target and where its particles' centre stands, and `pinnedParticles` counts the particles held kinematic. `diagnostics` is what the physics debug views picture of the body as numbers: inverted cells, self-crossings, element loads (`maxLoad`, `loadedElements`), pinned and attached particles (see `PhysicsSoftBodyDiagnostics`; `Physics.debugLines` draws them). `replication`, on a synced entity in a multiplayer session, says which peer simulates the body (`authority` `"local"` or `"remote"`, `owner`) and what it costs on the wire here (`lastSync` in seconds, `bytesPerSecond`). `stability` compares the body's stiffest elements with the rate the solver runs them at, from the moment it is built, before it steps (see `PhysicsSoftBodyStability`): `holds` is false and `cannotHold` names each part, with its frequency and the substep rate, when the default solver holds it softer than it is stated. `status` says where the body stands: `"built"`, `"pending"` (the component stands and the body is not built yet, `waitingFor` naming what the build waits on), `"refused"` (`refusal` says why the component was not built) or `"none"` (no SoftBody component). A body is built at the start of the frame after its component is added, so a read in the call that added it answers `"pending"`; wait on `status` rather than reading `exists = false` as a refusal. Answers in edit mode as well as play mode. `positions = true` adds every particle's world position; `contactPoints = true` adds each contact's individual points (each contact names its count, normal, depth, impulse and particles either way); `contactsWith` reports only the contacts with that one entity, so a read about one pair costs that pair alone. answers to that id.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Entity id or proxy. |
| opts | table? | `{ positions: boolean?, contactPoints: boolean?, contactsWith: (string | entityRef)? }`: |
examples
local s = Physics.softBodyState(jelly); print(s.particleCount, s.volumeRatio, s.sleeping)
print(Physics.softBodyState(shell).plastic) -- metres of dent the shell kept
local s = Physics.softBodyState(shell); if s.diverged then print(s.divergence) end
for _, p in Physics.softBodyState(jelly, { positions = true }).positions do print(p.y) endlocal r = Physics.softBodyState(jelly).render; print(r.drawn, r.vertexCount, r.uploadedThisFrame)
local s = Physics.softBodyState(jelly); if s.status == "pending" then print("waiting for", s.waitingFor) endlocal st = Physics.softBodyState(beam).stability; if not st.holds then print(st.cannotHold[1]) end
debugLines(opts: table?) →
Draw what the physics world simulates beyond collider surfaces as world-space lines, with what each object's lines picture as data. This is the read the physics debug views draw from: `capture { pass = "physics" }` and the edit-mode collider overlay (debugViz category `colliders`) both show these lines. Layers: `cage` draws a soft body's elements coloured by load: slack blue, yellow half way, red at the load it tears (see `PhysicsSoftBodyDiagnostics` for how a load is read); `particles` draws its particles: free ones as small grey crosses, pinned ones as green octahedra, ones held to a rigid body as magenta octahedra; `contacts` draws the contacts soft surfaces hold against soft surfaces (their own included): the segment joining the two witness points in orange, the normal in cyan; `wheels` draws each `WheelCollider` wheel: its suspension ray as far as it reaches, its whole travel and the tyre's radius below the mount (green on ground, red in the air, as the wheel's `isGrounded` reads), the travel from its mount to the tyre's centre coloured by how much of it is taken up on the same ramp, its tyre circle in white across its steered axle, and its ground point (yellow) and normal (cyan). Answers in edit mode as well as play mode; in edit mode a vehicle stands at rest with its wheels where they are authored. `layers` names the layers to draw (every layer when omitted; an unknown name is an error naming the layers), `entities` keeps to those entities' objects (a wheel is kept by its own entity or its chassis'). no physics world (a worker).
| arg | type | description |
|---|---|---|
| opts | table? | `{ layers: {string}?, entities: {(string | entityRef)}? }`: |
examples
local d = Physics.debugLines(); print(d.lineCount, #d.objects)
for _, o in Physics.debugLines({ layers = { "particles" } }).objects do print(o.entity, o.pinned, o.attached) endlocal w = Physics.debugLines({ layers = { "wheels" }, entities = { truck } }); for _, o in w.objects do print(o.index, o.grounded, o.compression) endstepCost( ) →
What the last physics step cost, stage by stage — the same figures `worldState().step` carries, for a caller that wants only these. Each covers that one step rather than a window of them, and consecutive steps over the same resting scene vary by tens of percent, so several samples averaged is the honest read of what a step costs. `softBodyMs` is the soft body part of the step and `softBodies` each soft body's part of it. A frame can run several steps; `recent` lists the last 64 with their ordinals (`step`), so a loop reading once a frame counts every step. step — a paused simulation, or a world still bootstrapping.
examples
local c = Physics.stepCost(); if c then print(c.stepMs, c.narrowPhaseMs) end
local c = Physics.stepCost(); if c then for _, b in c.softBodies do print(b.entity, b.ms, b.particles) end end
local seen, total = 0, 0
-- once a frame: every step since the last read, however many a frame ran
local c = Physics.stepCost(); if c then for _, s in c.recent do if s.step > seen then total += s.softBodyMs; seen = s.step end end end
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
fits(n: ?) → void
| arg | type | description |
|---|---|---|
| n | ? |
softBodySettingNames( ) → string
softBodySettings(changes: table?) →
The settings every soft body of the world is simulated under, and the way to change them: how many extra substeps a hard hit may run, how stiff soft contacts are, which tangle and overlap recovery runs, and how far the FEM solver (`SoftBody.solver = "fem"`) solves each step. Each one trades simulation quality for cost; `Physics.stepCost().softBodies` shows what each body costs under them. They are world settings (`physics.soft_body_*` in `.world_settings`) saved with the world: a change reads back at once and the solver runs under it from the next physics tick. Written during play, they land on the play shadow like any other `/source` write: the solver runs under them at once, and they are gone when the play edits are discarded. Write them in edit mode (or keep them with `vfs.promotePlayShadow("/zero/source/.world_settings")`) for the world to keep them. left out keep their values. A field the settings do not have, or a value of the wrong type or out of range, is refused by name.
| arg | type | description |
|---|---|---|
| changes | table? | Optional `PhysicsSoftBodySettings` fields to change; the fields |
examples
print(Physics.softBodySettings().maxExtraSubsteps)
Physics.softBodySettings({ maxExtraSubsteps = 2 }) -- cheaper hard hitsPhysics.softBodySettings({ tangleDetection = false, overlapConstraints = false })Physics.softBodySettings({ femMaxIterations = 60 }) -- FEM bodies converge further each substepsoftBodyComponentOf(softId: string, verb: string, level: number) → any
Forces / impulses The SoftBody component of `softId`, refusing an id that names nothing, a rigid body and an entity with no body, each by name. `level` is the stack level the error is raised at, the caller of the verb.
| arg | type | description |
|---|---|---|
| softId | string | |
| verb | string | |
| level | number |
pushedBody(ref: any, verb: string) → string
The id of a body a push is aimed at, refusing an id that names nothing and an entity that carries no body to push.
| arg | type | description |
|---|---|---|
| ref | any | |
| verb | string |
pushRadius(opts: any, verb: string) → number
The radius a push's options state, checked.
| arg | type | description |
|---|---|---|
| opts | any | |
| verb | string |
softPush(ref: any, verb: string, vector: any, what: string, region: any) → void
A push on a region of a soft body: the soft body's id, its region in the engine form, refusing a rigid body by name and a push that states no vector (`what` names it: "force" or "impulse").
| arg | type | description |
|---|---|---|
| ref | any | |
| verb | string | |
| vector | any | |
| what | string | |
| region | any |
applyForce(entityIdOrForce: string | entityRef | vec3, force: vec3?, region: PhysicsSoftRegion?) → void
Apply a force to an entity's rigid or soft body, in newtons, for a span of simulated time, whatever the frame rate and the physics tick rate are. Called from code that runs inside a physics step (`Physics.onBeforeStep` / `onAfterStep`, a contact listener, `fixedUpdate`) it acts on the next physics step alone: call it once per step for a continuous force. Called anywhere else (`update`, a task, a tool call) it acts over the simulated time the next frame advances, shared across however many steps that frame runs: call it once per frame for a continuous force. Either way a continuous force integrates to force times elapsed time, so a body pushed up with its own weight floats. A force that depends on where the body is or how fast it moves (a spring, a field, a controller) belongs in `Physics.onBeforeStep`, which reads the state the step starts from; a pull that drives an orbit or an oscillation keeps its energy given there as the momentum it makes over the step, `Physics.applyImpulse(id, force * dt)`. With one argument the script-context entity is targeted; with two args the explicit entity id wins. A soft body takes the force spread over its particles by mass, so it accelerates as a whole the way a rigid body of its mass would; `region` puts it on part of the body instead (`{ box = { min, max } }` or `{ nearest = point }`, as `Physics.softRegion` takes it), which accelerates that part alike and leaves the rest to follow.
| arg | type | description |
|---|---|---|
| entityIdOrForce | string | entityRef | vec3 | Entity id (when paired with `force`) OR a force vector for the script-context entity. |
| force | vec3? | Optional force vector when targeting an explicit entity. |
| region | PhysicsSoftRegion? | Part of a soft body to push, as `Physics.softRegion` takes it; omit for the whole body. |
examples
Physics.applyForce({x=0, y=10, z=0})Physics.applyForce(entityId, {x=0, y=10, z=0})Physics.applyForce(cloth, {x=0, y=0, z=4}, { box = { min = {-0.5, -1, 0.4}, max = {0.5, 1, 0.5} } })applyForceAtPoint(entityId: string | entityRef, force: vec3, point: vec3, opts: PhysicsPushOptions?) → void
Apply a force at a specific world-space point, over the span `Physics.applyForce` states: from `Physics.onBeforeStep` (or `fixedUpdate`) on the next step alone, from anywhere else over the next frame's simulated time. On a rigid body it generates the matching torque from the lever arm. On a soft body it pushes the particles around the point, weighted from the whole at the point to nothing at `opts.radius` (by default twice the spacing of the body's particles), so the body gives way there first. It always reaches at least the four particles nearest the point, the smallest patch a body can dent, so a radius finer than the particles are spaced spreads over that patch.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| force | vec3 | Force vector, in newtons. |
| point | vec3 | World-space application point. |
| opts | PhysicsPushOptions? | `{ radius: number? }`: how far into a soft body the force reaches, in metres. |
examples
Physics.applyForceAtPoint(id, {x=0,y=10,z=0}, {x=1,y=0,z=0})Physics.applyForceAtPoint(jelly, {x=0,y=-40,z=0}, {x=0,y=1.5,z=0}, { radius = 0.3 })applyImpulseAtPoint(entityId: string | entityRef, impulse: vec3, point: vec3, opts: PhysicsPushOptions?) → void
Apply an instantaneous impulse at a world-space point: a hit, a kick, a crash. On a rigid body it changes the body's velocity and spin as an impulse at that point of it would. On a soft body it pushes the particles around the point, weighted from the whole at the point to nothing at `opts.radius` (by default twice the spacing of the body's particles), so the body dents there and the rest of it is carried along through its elastic elements. It always reaches at least the four particles nearest the point, the smallest patch a body can dent, so a radius finer than the particles are spaced spreads over that patch; a finer dent takes a finer body (a higher `resolution`). The impulse is the momentum the body gains, in newton-seconds, wherever it lands.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The body's entity id or proxy. |
| impulse | vec3 | The impulse, in newton-seconds. |
| point | vec3 | Where it lands, in world space: a contact point. |
| opts | PhysicsPushOptions? | `{ radius: number? }`: how far into a soft body the impulse reaches, in metres. |
examples
Physics.applyImpulseAtPoint(crate, {x=0, y=0, z=-30}, hit.point)local contact = Physics.contacts(shell)[1]; if contact then Physics.applyImpulseAtPoint(shell, {x=-60, y=0, z=0}, contact.points[1].point, { radius = 0.4 }) endapplyRadialImpulse(entityId: string | entityRef, center: vec3, magnitude: number, opts: PhysicsPushOptions?) → void
Push a body straight away from a world point, like a blast: the push is `magnitude` newton-seconds at the centre, weighted to nothing at `opts.radius` (omitted, it reaches any distance at full strength). A rigid body is pushed by the distance to its centre of mass; a soft body particle by particle, each away from the centre by its own distance, so a blast beside a balloon pushes it off and one inside a body spreads it out. Each moves off at the speed `magnitude` gives a body of its mass.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The body's entity id or proxy. |
| center | vec3 | The blast's world position. |
| magnitude | number | The impulse at the centre, in newton-seconds. |
| opts | PhysicsPushOptions? | `{ radius: number? }`: how far the push reaches, in metres. |
examples
Physics.applyRadialImpulse(balloon, {x=0, y=1, z=-1}, 8, { radius = 3 })for _, id in pile do Physics.applyRadialImpulse(id, blast, 20, { radius = 4 }) endapplyImpulse(entityIdOrImpulse: string | entityRef | vec3, impulse: vec3?, region: PhysicsSoftRegion?) → void
Apply an instantaneous impulse (one-shot velocity change). With one argument the script-context entity is targeted; with two args the explicit entity id wins. A soft body takes the impulse spread over its particles by mass, so it moves off as a whole the way a rigid body of its mass would; `region` puts it on part of the body instead (as `Physics.softRegion` takes it), which sets that part moving and leaves the rest to follow. `applyImpulseAtPoint` aims one at a point.
| arg | type | description |
|---|---|---|
| entityIdOrImpulse | string | entityRef | vec3 | Entity id (with `impulse`) OR an impulse vector for the script-context entity. |
| impulse | vec3? | Optional impulse vector when targeting an explicit entity. |
| region | PhysicsSoftRegion? | Part of a soft body to push, as `Physics.softRegion` takes it; omit for the whole body. |
examples
Physics.applyImpulse({x=0, y=5, z=0})Physics.applyImpulse(entityId, {x=0, y=5, z=0})Physics.applyImpulse(jelly, {x=0, y=-2, z=0}, { box = { min = {-0.5, 0.4, -0.5}, max = {0.5, 0.5, 0.5} } })applyTorque(entityIdOrTorque: string | entityRef | vec3, torque: vec3?) → void
Apply a torque to an entity's rigid body, over the span `Physics.applyForce` states: from `Physics.onBeforeStep` (or `fixedUpdate`) on the next step alone, from anywhere else over the next frame's simulated time. With one argument the script-context entity is targeted; with two args the explicit entity id wins.
| arg | type | description |
|---|---|---|
| entityIdOrTorque | string | entityRef | vec3 | Entity id (with `torque`) OR a torque vector for the script-context entity. |
| torque | vec3? | Optional torque vector when targeting an explicit entity. |
examples
Physics.applyTorque({x=0, y=1, z=0})Physics.applyTorque(entityId, {x=0, y=1, z=0})setVelocity(a: string | entityRef | number | vec3, b: (number | vec3, c: ?, d: ?) → void
Set the linear velocity of an entity. Accepts `(x, y, z)` or a `{x, y, z}` vector for the script-context entity, or the same prefixed with an explicit `entityId`.
| arg | type | description |
|---|---|---|
| a | string | entityRef | number | vec3 | x-component, a `{x, y, z}` vector, or an entity id (explicit target). |
| b | (number | vec3 | y-component, x-component, or the vector depending on call form. |
| c | ? | z-component or y-component depending on call form. |
| d | ? | Optional z-component when targeting an explicit entity. |
examples
Physics.setVelocity(0, 10, 0)
Physics.setVelocity(entityId, 0, 10, 0)
Physics.setVelocity(entityId, {x=0, y=10, z=0})addVelocity(a: string | entityRef | number | vec3, b: (number | vec3, c: ?, d: ?) → void
Add to the linear velocity of an entity. Same call shapes as `setVelocity`.
| arg | type | description |
|---|---|---|
| a | string | entityRef | number | vec3 | dx, a `{x, y, z}` delta vector, or an entity id (explicit target). |
| b | (number | vec3 | dy, dx, or the delta vector depending on call form. |
| c | ? | dz or dy depending on call form. |
| d | ? | Optional dz when targeting an explicit entity. |
examples
Physics.addVelocity(0, 5, 0)
Physics.addVelocity(entityId, 0, 5, 0)
Physics.addVelocity(entityId, {x=0, y=5, z=0})setAngularVelocity(a: string | entityRef | number | vec3, b: (number | vec3, c: ?, d: ?) → void
Set the angular velocity of an entity (radians/sec). Same call shapes as `setVelocity`.
| arg | type | description |
|---|---|---|
| a | string | entityRef | number | vec3 | x-component, a `{x, y, z}` vector, or an entity id (explicit target). |
| b | (number | vec3 | y-component, x-component, or the vector depending on call form. |
| c | ? | z-component or y-component depending on call form. |
| d | ? | Optional z-component when targeting an explicit entity. |
examples
Physics.setAngularVelocity(0, 0, 1)
Physics.setAngularVelocity(entityId, 0, 0, 1)
Physics.setAngularVelocity(entityId, {x=0, y=0, z=1})setGravityScale(entityIdOrScale: string | entityRef | number, scale: number?) → void
Set the per-entity gravity scale (1.0 = normal, 0.0 = no gravity). One-arg form targets the script-context entity.
| arg | type | description |
|---|---|---|
| entityIdOrScale | string | entityRef | number | Entity id (with `scale`) OR scale value (script-context entity). |
| scale | number? | Optional explicit scale when targeting another entity. |
examples
Physics.setGravityScale(0.5)
Physics.setGravityScale(entityId, 0.5)
setMass(entityIdOrMass: string | entityRef | number, mass: number?) → void
Set the mass of an entity's rigid body (kg). One-arg form targets the script-context entity.
| arg | type | description |
|---|---|---|
| entityIdOrMass | string | entityRef | number | Entity id (with `mass`) OR mass value (script-context entity). |
| mass | number? | Optional explicit mass when targeting another entity. |
examples
Physics.setMass(10)
Physics.setMass(entityId, 10)
setLinearDamping(entityIdOrDamping: string | entityRef | number, damping: number?) → void
Set linear damping on an entity's rigid body (0 = no damping). One-arg form targets the script-context entity.
| arg | type | description |
|---|---|---|
| entityIdOrDamping | string | entityRef | number | Entity id (with `damping`) OR damping value (script-context entity). |
| damping | number? | Optional explicit damping when targeting another entity. |
examples
Physics.setLinearDamping(0.05)
Physics.setLinearDamping(entityId, 0.05)
setAngularDamping(entityIdOrDamping: string | entityRef | number, damping: number?) → void
Set angular damping on an entity's rigid body. One-arg form targets the script-context entity.
| arg | type | description |
|---|---|---|
| entityIdOrDamping | string | entityRef | number | Entity id (with `damping`) OR damping value (script-context entity). |
| damping | number? | Optional explicit damping when targeting another entity. |
examples
Physics.setAngularDamping(0.1)
Physics.setAngularDamping(entityId, 0.1)
setCcdEnabled(entityIdOrEnabled: string | entityRef | boolean, enabled: boolean?) → void
Enable or disable continuous collision detection on an entity's rigid body. One-arg form targets the script-context entity.
| arg | type | description |
|---|---|---|
| entityIdOrEnabled | string | entityRef | boolean | Entity id (with `enabled`) OR boolean (script-context entity). |
| enabled | boolean? | Optional explicit boolean when targeting another entity. |
examples
Physics.setCcdEnabled(true)
Physics.setCcdEnabled(entityId, true)
setBodyType(entityId: string | entityRef, bodyType: string) → void
Change a rigid body's type at runtime. Mass, colliders, and joints are preserved — only the body's response to forces and position writes changes.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| bodyType | string | One of `"dynamic"`, `"kinematic"`, `"static"`. |
examples
Physics.setBodyType(entityId, "kinematic")
setRotationLocks(entityId: string | entityRef, x: boolean, y: boolean, z: boolean) → void
Lock or unlock rotation on specific axes.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| x | boolean | Lock rotation about the world X axis. |
| y | boolean | Lock rotation about the world Y axis. |
| z | boolean | Lock rotation about the world Z axis. |
examples
Physics.setRotationLocks(id, false, true, false)
setTranslationLocks(entityId: string | entityRef, x: boolean, y: boolean, z: boolean) → void
Lock or unlock translation on specific axes.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| x | boolean | Lock translation along the world X axis. |
| y | boolean | Lock translation along the world Y axis. |
| z | boolean | Lock translation along the world Z axis. |
examples
Physics.setTranslationLocks(id, false, false, true)
setCollisionGroups(entityId: string | entityRef, membership: number, filter: number) → void
Set the collision-group membership and filter bitmasks on an entity's colliders. Adds a `CollisionGroup` component if missing; the component holds the groups, so they apply to the colliders of the entity's rigid body or standalone collider by the next physics step, and a body built or rebuilt later takes them as it is built, in edit mode as well as play. A soft body's groups are its `SoftBody` component's `collisionMemberships` and `collisionFilter`.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| membership | number | Bitmask: which groups this collider belongs to. |
| filter | number | Bitmask: which groups this collider can collide with. |
examples
Physics.setCollisionGroups(id, 0x0001, 0xFFFF)
ignoreCollision(entityIdA: string | entityRef, entityIdB: string | entityRef, ignore: boolean?) → void
Keep two entities from colliding, or let them collide again. Covers every collider each one owns (its rigid body with the shapes composed onto it, its standalone collider, its ragdoll's bones, its soft body's surface), so it keeps a soft shell off the chassis it is held to as well as two rigid bodies apart. An ignored pair holds no contact: the solver pushes neither one and `Physics.contacts` lists neither to the other. It applies from the next physics step, to bodies already touching as well, and lasts until it is turned off, either entity is despawned, or the mode changes: entering or leaving play starts without it, so make the call where the bodies are set up for play (a component's `onLoad`). It stands beside collision groups: a pair either one excludes does not collide.
| arg | type | description |
|---|---|---|
| entityIdA | string | entityRef | First entity id. |
| entityIdB | string | entityRef | Second entity id. |
| ignore | boolean? | When `true` (default) the pair is kept apart; `false` lets it collide again. |
examples
Physics.ignoreCollision(a, b, true)
addJoint(entityIdA: string | entityRef, entityIdB: string | entityRef, opts: table?) → any
Add a Joint component connecting two entities. Accepts either vec3-style anchor inputs (`localAnchor = {x,y,z}`) or pre-split scalar keys (`localAnchorX/Y/Z`); every other key is a `Joint` field. A body takes any number of joints: on an entity that already carries a Joint the new one is added under `name` (or, without one, the first of `joint2`, `joint3`, ... free on it), and each is its own solver joint. An end entity that is no body itself joins the nearest body above it at its own position and orientation, so a marker under a beam's end pins the beam there: a truss is beams joined through end markers. Either end may be a soft body (an entity with a `SoftBody` component): `region` anchors this end on a region of entity A's soft body and `remoteRegion` the other end on a region of B's, each as `Physics.softRegion` takes it (`{ box = { min, max } }` or `{ nearest = point }`); an end with no region is anchored on the soft body as a whole. The anchor of a region end is measured from the centre of its particles. and `Physics.removeJoint` take.
| arg | type | description |
|---|---|---|
| entityIdA | string | entityRef | Entity that hosts the Joint component. |
| entityIdB | string | entityRef | Connected entity. |
| opts | table? | Optional joint description: `kind` (fixed, hinge, ball, prismatic, spring, rope, generic), `localAnchor`, `remoteAnchor`, `axis`, `remoteAxis`, `collideConnected`, the limits (`limitMin` / `limitMax` for a hinge in degrees or a prismatic in metres, `swingLimit` / `twistLimit` for a ball joint in degrees, `axisLimits` on any axis), the motor (`motorMode` "velocity" | "position", `motorVelocity`, `motorTarget`, `motorStiffness`, `motorDamping`, `motorMaxForce`, `motorModel`, `axisMotors` on any axis), `lockedAxes` for a generic joint, `stiffness`, `damping`, `restLength`, `maxDistance`, `breakForce`, `breakTorque`, `region`, `remoteRegion`. |
examples
Physics.addJoint(a, b, { kind = "fixed" })Physics.addJoint(a, b, { kind = "hinge", axis = {x=0,y=1,z=0} })Physics.addJoint(door, frame, { kind = "hinge", axis = {0,1,0}, limitMin = 0, limitMax = 110 })Physics.addJoint(arm, base, { kind = "hinge", axis = {0,0,1}, motorMode = "position", motorTarget = 90, motorMaxForce = 500 })Physics.addJoint(forearm, upperArm, { kind = "ball", swingLimit = 45, twistLimit = 20, collideConnected = false })Physics.addJoint(piston, cylinder, { kind = "prismatic", axis = {0,1,0}, limitMin = 0, limitMax = 0.5 })Physics.addJoint(seat, rail, { kind = "generic", lockedAxes = {"linY", "linZ", "angX", "angY", "angZ"}, axisLimits = { linX = {-0.2, 0.2} } })Physics.addJoint(a, b, { kind = "rope", maxDistance = 8 })Physics.addJoint(a, b, { kind = "fixed", breakForce = 1200, breakTorque = 800 })Physics.addJoint(bag, hook, { kind = "ball", region = { nearest = {0, 0.5, 0} } })Physics.addJoint(jellyA, jellyB, { kind = "fixed", region = { box = { min = {0.4, -0.5, -0.5}, max = {0.5, 0.5, 0.5} } }, remoteRegion = { box = { min = {-0.5, -0.5, -0.5}, max = {-0.4, 0.5, 0.5} } } })local grab = Physics.addJoint(hand, crate, { kind = "fixed", breakForce = 2000 }); Physics.removeJoint(grab)split(prefix: string) → void
A vec3 given as a table becomes the three split keys; a vector given neither way keeps the Joint's own default.
| arg | type | description |
|---|---|---|
| prefix | string |
removeJoint(entityId: string | entityRef | table, name: string?) → void
Remove one joint, leaving every other joint on its bodies standing: the `Joint` an entity carries (its unnamed one, or the one `name` names), or the `Joint` component given itself, as `Physics.addJoint` returns it.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | table | Target entity id, or a `Joint` component. |
| name | string? | The Joint's name on that entity; omit for its unnamed Joint. |
examples
Physics.removeJoint(id)
Physics.removeJoint(beam, "right")
local grab = Physics.addJoint(hand, crate); Physics.removeJoint(grab)
jointCarrierOf(id: string) → string
The entity carrying the joint `id` is the connected end of, or nil when no joint connects to it.
| arg | type | description |
|---|---|---|
| id | string |
setJointMotor(entityId: string | entityRef | table, targetVelocity: number, maxForce: number, name: string?) → void
Drive an entity's joint motor at `targetVelocity` with at most `maxForce`. The joint is the one `entityId` carries, or, when it carries none, the joint it is the connected end of. Writes the joint's own motor fields (`motorMode = "velocity"`, `motorVelocity`, `motorMaxForce`), so the motor is component data that syncs and reads back. A hinge turns at radians per second under newton-metres, a prismatic slides at metres per second under newtons, a ball joint drives each of its angles (velocity 0 holds it still: joint friction up to `maxForce`), a generic joint every free axis. For a target angle or travel set `motorMode = "position"` and `motorTarget` on the Joint; for single axes, its `axisMotors`.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | table | Entity carrying the Joint component, or the body it connects to, or a `Joint` component. |
| targetVelocity | number | Velocity the motor holds: rad/s for an angle, m/s for a travel. |
| maxForce | number | The most force or torque the motor applies; 0 leaves it uncapped. |
| name | string? | The Joint's name on that entity, for one of several joints; omit for its unnamed Joint. |
examples
Physics.setJointMotor(wheel, 10, 50)
Physics.setJointMotor(piston, 0.5, 2000)
Physics.setJointMotor(arm, 2, 300, "elbow")
softVec(v: any, what: string) → void
Soft bodies held to rigid bodies, pinned, and soft body joint ends
| arg | type | description |
|---|---|---|
| v | any | |
| what | string |
softRegion(region: PhysicsSoftRegion?) →
The engine form of a soft body region: the record the `SoftBody` component's attachments and a `Joint`'s soft body ends carry. A region names part of a soft body by where its particles stand: `{ box = { min, max } }` is every particle between the two corners, `{ nearest = point }` the one particle nearest the point, and `nil` (or `{}`) the whole body. Coordinates are in the soft body entity's local space, the unit box it is built in (-0.5 to 0.5 on each axis, before its scale; for a `custom` body, the space its particles are listed in), so a region stays the same part of the body wherever the body is; `space = "world"` reads them in world space instead. A box counts a particle whose contact skin reaches into it: a generated body's outer particles stand that skin inside the unit box, so a box flat on one of its faces (`min = {-0.5, -1, -1}, max = {-0.5, 1, 1}`) holds that face's particles. Errors naming the key that is wrong.
| arg | type | description |
|---|---|---|
| region | PhysicsSoftRegion? | `{ box = { min = v, max = v } | { v, v }, nearest = v, space = "local" | "world" }`, or nil for the whole body. |
examples
Physics.softRegion({ box = { min = {-0.5, 0.45, -0.5}, max = {0.5, 0.5, 0.5} } })Physics.softRegion({ nearest = {0, 0.5, 0} })softBodyComponent(softId: string, verb: string) → any
| arg | type | description |
|---|---|---|
| softId | string | |
| verb | string |
attachSoftRegion(softId: string | entityRef, targetId: string | entityRef, region: PhysicsSoftRegion?) →
Hold a region of a soft body to a rigid body, two-way: the region follows the rigid body wherever it goes, and the rigid body carries the region's weight and pull. Each particle in the region is tied to the point of the rigid body it stands at when the attachment is made. The attachment is an entry of the soft body's `SoftBody` component (`attachments`), so it is saved with the scene, reaches every peer, and is made again on a rebuilt body; it is released when either side is removed. Its load reads back from `Physics.softBodyState(softId).attachments`. A cloth's edge on a flagpole, a soft panel on a car's chassis, a jelly glued to a moving platform. Where the rigid body's colliders touch the soft body (a shell resting on its chassis), the contact and the hold push on each other: keep them clear, or `Physics.ignoreCollision(softId, targetId)`.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity (it carries a `SoftBody` component). |
| targetId | string | entityRef | The rigid body's entity (it carries `Physics`), by id, name or proxy. |
| region | PhysicsSoftRegion? | Which particles to hold, as `Physics.softRegion` takes it: `{ box = { min, max } }`, `{ nearest = point }`, with `space = "world"` for world coordinates; nil holds the whole body. |
examples
Physics.attachSoftRegion(flag, pole, { box = { min = {-0.5, -1, -1}, max = {-0.45, 1, 1} } })Physics.attachSoftRegion(shell, chassis, { box = { min = {-0.5, -0.5, -0.5}, max = {0.5, -0.4, 0.5} } })repairSoftBody(softId: string | entityRef) → number
Restore the shape a soft body was built in: every permanent dent, crumple and crease it took past its `plasticYield` is undone, and the body is put back in that shape where it stands, keeping its motion as a whole. The repair is the `SoftBody` component's `repairs` count raised by one, so it reaches every peer. `Physics.softBodyState(softId).plastic` reads 0 once it is applied (at the start of the next frame), and a `Physics.setSoftParticles` made before then is put back in the built shape with the rest of the body.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity (it carries a `SoftBody` component). |
examples
Physics.repairSoftBody(shell)
detachSoftRegion(softId: string | entityRef, targetId: (string | entityRef) →
Release regions of a soft body held with `attachSoftRegion` (or authored in its `SoftBody` component's `attachments`).
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| targetId | (string | entityRef | Release only the regions held to this rigid body; omit to release every one. |
examples
Physics.detachSoftRegion(flag, pole)
Physics.detachSoftRegion(shell)
pinSoftRegion(softId: string | entityRef, region: PhysicsSoftRegion?, opts: { name: string?, target: vec3? }?) →
Pin a region of a soft body: its particles are held kinematic, where they stand now, and the rest of the body hangs from them, rests on them or swings about them through its elastic elements. A cloth pinned by two corners hangs; a jelly pinned along its base stays put while its top wobbles. Give the pin a `target` (or set one later with `Physics.setPinTarget`) and the pinned particles move together so their centre stands there, dragging the body after them: a hand grabbing a corner, a press driven down into a block. The pin is an entry of the soft body's `SoftBody` component (`pins`), so it is saved with the scene, reaches every peer and is made again on a rebuilt body; it reads back from `Physics.softBodyState(softId).pins`.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity (it carries a `SoftBody` component). |
| region | PhysicsSoftRegion? | Which particles to pin, as `Physics.softRegion` takes it: `{ box = { min, max } }` or `{ nearest = point }` in the entity's unit box (-0.5 to 0.5 on each axis), `space = "world"` for world coordinates; nil pins the whole body. |
| opts | { name: string?, target: vec3? }? | `{ name: string?, target: vec3? }`: the name the pin is addressed by (by default `pin1`, `pin2`, ...), and a world position to move the pinned particles' centre to. |
examples
local corner = Physics.pinSoftRegion(cloth, { nearest = {-0.5, 0, 0.5} })Physics.pinSoftRegion(cloth, { box = { min = {-0.5, -1, 0.45}, max = {0.5, 1, 0.5} } }, { name = "top" })local grab = Physics.pinSoftRegion(jelly, { nearest = hit.point, space = "world" }, { target = hit.point })setPinTarget(softId: string | entityRef, name: string, position: vec3?) → void
Drive a pin of a soft body to a world position: its particles move together over the next step so the centre they had when the pin was made stands at `position`, with the velocity that carries them there, and the rest of the body follows. Set it every frame to drag the region along a path. `nil` stops driving it and holds it where it stands. The target is the pin's entry in the `SoftBody` component's `pins`, so it reaches every peer.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| name | string | The pin's name, as `pinSoftRegion` returned it. |
| position | vec3? | The world position for the pinned particles' centre; nil holds them where they stand. |
examples
Physics.setPinTarget(cloth, corner, {x=2, y=3, z=0})releasePin(softId: string | entityRef, name: string?) →
Release a pin of a soft body, or every pin: its particles take their mass back, keep the velocity they had, and move with the body again.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| name | string? | The pin to release; omit to release every one. |
examples
Physics.releasePin(cloth, corner)
Physics.releasePin(cloth)
softParticles(softId: string | entityRef, region: PhysicsSoftRegion?) →
Read the particles of a soft body that a region selects: where each stands, how fast it moves, where it stands in the body's rest shape and whether it is pinned, with the selection's centre of mass and mean velocity. `Physics.setSoftParticles` writes a read back as it is. The way to see a dent where a hit landed, how far a pinned corner was dragged, or how a region moves. `indices` name the particles for comparing two reads of the same body. The region is resolved at each call against where the particles stand then (a local-space region in the body's frame as it stands now), so a read after the body moved can select other particles than an earlier read of the same region; a pin's own particles read back through `Physics.softBodyState(softId).pins` (`center`) and the `pinned` flags.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| region | PhysicsSoftRegion? | Which particles to read, as `Physics.softRegion` takes it; nil reads the whole body. |
examples
local top = Physics.softParticles(jelly, { box = { min = {-0.5, 0.4, -0.5}, max = {0.5, 0.5, 0.5} } }); print(top.count, top.center.y)local near = Physics.softParticles(shell, { box = { min = {1.6, 0, -0.3}, max = {2.2, 1, 0.3} }, space = "world" })setSoftParticles(softId: string | entityRef, particles: PhysicsSoftParticlesWrite) →
Write a soft body's particles: where each stands, how fast it moves, and where it stands in the body's rest shape, the shape it springs back to. The body simulates on from the written state, so a shape read once can be put back: a replay or a rewind, a saved game holding a damaged object, a level that starts with something already bent, a correction from the network, a repair that pushes one dent out. The write is applied at once on the peer that simulates the body: a read straight after sees it, and the next physics step starts from it. Written from `Physics.onBeforeStep`, it is the state that step starts from, ahead of the step's drives, tears and solve. `positions` and `velocities` move the particles and leave the rest shape as it was, so the body springs back from a written shape toward its rest shape (a dent past its `plasticYield` can then set); `restPositions` changes the rest shape itself, the permanent part of the shape, which stays once the body settles, the way a dent past the yield stays (`Physics.softBodyState(id) .plastic` reads it, and `Physics.repairSoftBody` undoes it). A read's `restPositions` are where each particle rests, which a crumple's elements pull the body away from, so to keep the shape a body stands in after a crash, write its `positions` as `restPositions`. Positions are written first and the body's frame fitted to them, then the rest places are measured through that frame, and each element of the body takes the rest shape its particles' places give it, which can differ from the one a crumple's elements flowed to: a body whose flow left its elements pulling against one another (a deep crumple) keeps the written dent and settles a little way from the written shape, into it or out of it. Rest places that state the shape the body was built in (a read taken before its first dent) put that shape back exactly, the way `Physics.repairSoftBody` does, so a rewind to a moment before a crash replays it the same way each time. A write that places every particle (a whole read written back) is the whole state the body steps on from, so two rewinds to one read fall the same way, and the frame after a write draws the body where it was written, paused or not. A rewind starts from the read alone, while the run the read came from carried on with what the solver had built up, so the two can part by rounding where a hit amplifies it; writing the read back the moment it is taken (from `Physics.onBeforeStep`) makes that run a replay of it too. A read's rest places say where each particle rests, while each element of a crumple keeps a flow of its own: written back over the body while it still holds the read's dent, a read leaves those elements as they are, and written over any other state it gives each element the rest its particles' places give, so a body read with a deep crumple steps on from the two a little apart (about 1.5 cm over 20 steps where a 3 m slab's crumple pulls hardest). A repair (`Physics.repairSoftBody`) applies at the start of the next frame and puts the body back in its built shape over a write made before it; a written `restPositions` in the built shape is the same repair, at once. A pinned particle stands where it is written and its pin holds it there, whatever velocity is written to it (a read before the next step reads that velocity; the step keeps the particle in place). A `Physics.softParticles` read is a write of this shape, so `Physics.setSoftParticles(id, read)` puts back the particles it read, their rest places included.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity (it carries a `SoftBody` component). |
| particles | PhysicsSoftParticlesWrite | `PhysicsSoftParticlesWrite`: `indices` (zero-based, as `Physics.softParticles` reads them; omit to write every particle in order) and any of `positions`, `velocities` and `restPositions`, one value per named particle, in world space. |
examples
local saved = Physics.softParticles(shell); if saved then Physics.setSoftParticles(shell, saved) end -- later: put the shell back as it was
local bent = Physics.softParticles(bar); if bent then Physics.setSoftParticles(bar, { restPositions = bent.positions }) end -- the shape it stands in becomes its rest shapePhysics.setSoftParticles(jelly, { indices = { 0, 7 }, velocities = { {x=0, y=3, z=0}, {x=0, y=3, z=0} } })softElements(softId: string | entityRef) →
Read every element of a soft body in one call: the force each carries (newtons, positive pulling, negative pushing), its strain, length, rest length, permanent set, its load against its break limit, whether it broke, and where its two ends stand in world space (`endA`, `endB`; a broken element's are where its particles went), as arrays indexed by element. A `custom` body's authored `elements` read by their number in the component's list, wherever a tear left them, the same read from the body's entity and from each piece's; any other body's edges read in its own order with `a` / `b` naming their particles. The way to colour a structure by stress, draw its members, find its most loaded member or watch a span carry a load, at the cost of one call per frame.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
examples
local s = Physics.softElements(bridge); for i = 1, s.count do if s.load[i] > 0.8 then print("member", i, "near breaking", s.force[i]) end endlocal s = Physics.softElements(bridge); for i = 1, s.count do if not s.broken[i] then print("member", i, "from", s.endA[i], "to", s.endB[i]) end endsoftBodyEnergy(softId: string | entityRef, opts: { mark: boolean? }?) →
Read a soft body's energy ledger, to tune a deformable by numbers: the kinetic and elastic energy it holds now, and since the mark the work gravity did on it, the work plastic flow absorbed, the energy tears and cuts took out of it, what pieces split off carried away and what it lost otherwise (damping, friction, contacts, less what whatever holds or pushes it gave it), each by region too, with the peak acceleration of its centre of mass. `opts.mark = true` sets the mark first and starts the ledger again; a body never marked reads its kinetic and elastic energy only (`accounted` is false), and costs nothing per step. A marked body is accounted after every step that moves it, so a crash read straight after it reads the whole crash: mark before, read after.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| opts | { mark: boolean? }? | `{ mark: boolean? }`. |
examples
Physics.softBodyEnergy(shell, { mark = true }) -- before the crashlocal e = Physics.softBodyEnergy(shell); print(e.absorbed, e.elastic, e.dissipated) -- after it: joules
for _, r in Physics.softBodyEnergy(shell).regions do print(r.name, r.absorbed) end
measureSoftBody(softId: string | entityRef, test: { [string]: any }) →
Measure how a soft body responds to a stated load, without building a rig: a copy of it, built from its component as authored, is pressed between two plates, sent at a speed into a post or a wall, or dropped onto a floor, in a world of its own at the tick and solver iterations the world's settings state (in edit mode as in play), and every step is sampled: force against displacement, its energy and what it absorbed. The live body is untouched. A press answers its initial `stiffness` (N/m), `peakForce`, the `work` under the loading curve and the `permanentSet`; an impact the `crush`, `peakForce`, `peakDeceleration`, `rebound` and the share of its energy it absorbed (`absorbedShare`); a drop the same against the height. Tune a material toward "takes X kJ over Y m" with it, then build the body.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| test | { [string]: any } | One load: `{ press = { depth, axis?, speed?, hold?, settle?, friction? } }` (axis "x", "y" or "z" in the body's own frame, default "y"; speed default depth / 2 s; frictionless plates unless `friction` says otherwise), `{ impact = { speed, direction?, radius?, offset?, carried?, duration?, friction? } }` (direction default "-z", a post of `radius` metres or a wall when it is left out, `carried` kilograms on a rigid block held to its trailing face) or `{ drop = { height, duration?, friction? } }`. |
examples
local m = Physics.measureSoftBody(block, { press = { depth = 0.05 } }); print(m.stiffness, m.work, m.absorbed)local m = Physics.measureSoftBody(nose, { impact = { speed = 15, radius = 0.1, carried = 700 } }); print(m.crush, m.rebound, m.absorbedShare, m.peakDeceleration / 9.81)local m = Physics.measureSoftBody(crate, { drop = { height = 2 } }); print(m.absorbed, m.elastic, m.dissipated, m.gravityWork)driveSoftElements(softId: string | entityRef, targets: { [number]: number }, opts: { speed: number? }?) → void
Drive the length of authored elements of a `custom` soft body: each named element's rest length moves toward its target at `opts.speed` (metres per second; 0 or omitted sets it at once), pushing and pulling with no more than the element's own `maxForce`, so a blocked ram stalls instead of tearing the body. A hydraulic ram, a muscle, a crane's luffing cylinder. The drive holds until the element's fields are written again (an element of kind "actuator" is driven to its `targetLength` from its fields). Takes effect from the next physics step, on the peer that simulates the body.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| targets | { [number]: number } | Element number (as listed in the component's `elements`) to the length in metres it is driven to. |
| opts | { speed: number? }? | `{ speed: number? }`: how fast the lengths move, in metres per second. |
examples
Physics.driveSoftElements(crane, { [7] = 2.5, [8] = 2.5 }, { speed = 0.4 })entitiesForPieces(record: any) → void
Make the entity of every piece a tear record names: a copy of the entity the piece came from, without its children, that is play state (left out of every save), stands at the root of the scene, so it flies free of whatever the torn entity hangs from, and whose SoftBody adopts the piece's body.
| arg | type | description |
|---|---|---|
| record | any |
pumpSoftBodyTears( ) → void
pumpSoftBodyTears( ) → void
Give every piece the soft bodies tore off since the last call its entity, and deliver each tear to the `onSoftBodyTear` listeners. Every `SoftBody` component calls this each frame, so tears are handled on their own; the work is done once per frame however many call it.
examples
Physics.pumpSoftBodyTears()
onSoftBodyTear(fn: (PhysicsSoftBodyTear) →
Call `fn` for every tear of a soft body from now on: a body loaded past its `tearStrain` or `tearForce` (fields of its `SoftBody` component), cut by `Physics.cutSoftBody` or torn by `Physics.tearSoftBody`. The torn entity keeps the largest piece; every piece split off is an entity of its own by the time `fn` runs, standing at the root of the scene and carrying a `SoftBody` with the torn body's fields, its share of the model and the material, the velocity, dents and pins that fell on its side. Its body joins it on the next frame, and an impulse applied to it in `fn` reaches the body then. A piece is play state: it is left out of every save, and leaving play takes it away and gives the torn entity back its whole body.
| arg | type | description |
|---|---|---|
| fn | (PhysicsSoftBodyTear | Receives one `PhysicsSoftBodyTear` per tear: `{ entity, pieces, position, kind, particles }`. |
examples
local off = Physics.onSoftBodyTear(function(e) print(e.entity, #e.pieces, e.position) end)
Physics.onSoftBodyTear(function(e) for _, id in e.pieces do Physics.applyImpulse(id, { x = 0, y = 2, z = 0 }) end end)softBodyTears( ) →
Every soft body tear since the last call to this function, oldest first, with the entities of the pieces each split off: the same records `onSoftBodyTear` delivers. The 256 most recent are kept.
examples
for _, t in Physics.softBodyTears() do print(t.kind, t.entity, #t.pieces) end
refuseBreakInEdit(verb: string) → void
Refuse a cut or a tear asked in edit mode: nothing simulates there, so it would wait for a physics step that only play mode takes, on a body play mode builds anew.
| arg | type | description |
|---|---|---|
| verb | string |
cutSoftBody(softId: string | entityRef, blade: { vec3 } | { point: vec3, normal: vec3 }) → void
Cut a soft body along a blade, every element of the body the blade meets opening along it: `{ point = p, normal = n }` cuts along the whole plane through `p` facing `n`, splitting the body in two wherever it lies on both sides; `{ a, b, c }` cuts along that world-space triangle, which cuts only as far as the triangle reaches. Applied straight after the next physics step; a piece the cut separates becomes an entity of its own (see `onSoftBodyTear`), and the cut reports as a tear of kind "cut". A plane is measured against the body where that step leaves it, so it cuts a moving body wherever it has gone; a cut that opens nothing is reported in the log. Raises when the entity carries no `SoftBody`, and in edit mode, where nothing simulates.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| blade | { vec3 } | { point: vec3, normal: vec3 } | `{ point = vec3, normal = vec3 }` for a plane, or the triangle's three world-space corners `{ a, b, c }`. |
examples
Physics.cutSoftBody(jelly, { point = vector.create(0, 1, 0), normal = vector.create(1, 0, 0) }) -- in two along x = 0Physics.cutSoftBody(jelly, { vector.create(0, -5, -5), vector.create(0, 5, -5), vector.create(0, 0, 10) })-- slice off the part of a body 0.2 m above its centre
local c = Physics.softBodyState(jelly).centerOfMass
Physics.cutSoftBody(jelly, { point = vector.create(c.x, c.y + 0.2, c.z), normal = vector.create(0, 1, 0) })tearSoftBody(softId: string | entityRef, region: PhysicsSoftRegion) → void
Tear a soft body at a region: every edge and cell holding a particle of the region comes apart there, opening a hole or, when the region runs across the body, splitting it. Applied straight after the next physics step; a piece the tear separates becomes an entity of its own (see `onSoftBodyTear`), and it reports as a tear of kind "tear". Raises when the entity carries no `SoftBody`, for a region naming no box and no point (the whole body), and in edit mode, where nothing simulates.
| arg | type | description |
|---|---|---|
| softId | string | entityRef | The soft body's entity. |
| region | PhysicsSoftRegion | Which particles to tear through, as `Physics.softRegion` takes it: `{ box = { min, max } }` or `{ nearest = point }` in the entity's unit box (-0.5 to 0.5 on each axis), `space = "world"` for world coordinates. |
examples
Physics.tearSoftBody(cloth, { nearest = hit.point, space = "world" })Physics.tearSoftBody(sheet, { box = { min = {-0.02, -1, -0.5}, max = {0.02, 1, 0.5} } })pumpJointBreaks( ) → void
The engine hands each break over exactly once, so every record this reads is the only copy there will ever be: buffer the whole batch before any listener runs, and run each listener under pcall, so one handler that raises costs its own delivery and nothing else's.
pumpJointBreaks( ) → void
Deliver every joint break the simulation has recorded to the registered listeners. The engine calls this after every physics step that broke a joint, before that step's `fixedUpdate`, so listeners hear each break at the physics rate whichever way the joint was made.
examples
Physics.pumpJointBreaks()
jointReaction(entityId: string | entityRef | table, name: string?) →
The load (the stress) an entity's joint is carrying right now, as the constraint solver resolved it on the last physics step: the force and the moment it applies to the body carrying it, as vectors and read along the member it holds, so tension tells from compression, axial load from shear and bending from twist. This is the same quantity a break threshold is measured against, and `load` is the share of `breakForce` / `breakTorque` it stands at. A joint with a soft body at either end reads the same way. `Physics.jointReactions` reads many joints in one call. its constraint is not built yet. `axial` is the force along the member at this body's end, positive pulling it outward (tension) and negative pushing it inward (compression): a member hanging 10 kg reads +98.1, one propping it -98.1. `direction` is that line, from the body's centre of mass out to its anchor; `connectedAxial` reads the connected body as a member the same way. `tension` is the pull along the line between the two anchors (a rope's or a spring's), 0 while they stand together. `shear` is the force across the member, `bending` the moment across it, `torsion` the moment about it. `worldForce` / `worldTorque` are the force and the moment about the anchor the joint applies to this body (N, N·m), `localForce` / `localTorque` the same along the joint frame's axes, and `force` / `torque` their sizes. `load` is the larger of force / breakForce and torque / breakTorque, 1 breaking the joint, 0 with no threshold. A joint `Physics.listenJointLoads` listens to carries `peak`, the largest load any step put on it since the last read, which reading takes.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | table | Entity carrying the Joint component, or a `Joint` component. |
| name | string? | The Joint's name on that entity, for one of several joints; omit for its unnamed Joint. |
examples
local r = Physics.jointReaction(id); print(r and r.axial)
local r = Physics.jointReaction(beam, "right"); if r and r.axial < 0 then print("compressed", -r.axial) endjointCarriers(targets: any, fname: string) → void
The entities carrying the constraints of the joints `targets` names: a `Joint` component, an entity (every joint its body is in), or an array of Joint components and entities (each entity's unnamed Joint).
| arg | type | description |
|---|---|---|
| targets | any | |
| fname | string |
jointReactions(targets: any?, opts: { vectors: boolean?, fields: { string }? }?) →
The load (the stress) of many joints in one call, as arrays of one value per joint, each read the way `Physics.jointReaction` reads one: a whole bridge or machine coloured by load in one read a frame. `targets` is an array of `Joint` components and entities (each entity's unnamed Joint), in the order the arrays answer; one entity, for every joint its body is in; or nil for every joint in the world. Each joint is named by `entityId` (whose Joint), `joint` (its name, empty for the unnamed one), `jointEntityId` and `connectedEntityId`, and by `bodyEntityId` and `connectedBodyEntityId`, the entities of the two bodies it holds: the members to sum a structure's loads on. A joint `Physics.listenJointLoads` listens to gives the peak it carried since its last read in `peakLoad`, `peakMaxAxial` and `peakMinAxial`, which reading takes; every other joint gives its current reading there. (any listed in the return, the vectors and names included), the cheapest read of a large structure; `{ vectors = true }` adds the arrays `worldForce`, `worldTorque`, `localForce`, `localTorque`, `direction` and `position` of {x, y, z}. Reading the same joints every frame, pass their `joint:jointEntityId()` ids, taken once, in place of the Joints. while a joint's constraint is not built, its values 0), `axial`, `connectedAxial`, `tension`, `shear`, `bending`, `torsion`, `force`, `torque`, `impulse`, `load`, `listened`, `peakLoad`, `peakMaxAxial`, `peakMinAxial`.
| arg | type | description |
|---|---|---|
| targets | any? | An array of Joints and entities, one entity, or nil for every joint. |
| opts | { vectors: boolean?, fields: { string }? }? | `{ fields = { "axial", "load" } }` builds only the arrays it names |
examples
local r = Physics.jointReactions(); for i = 1, r.count do print(r.entityId[i], r.axial[i], r.load[i]) end
local r = Physics.jointReactions(members); for i = 1, r.count do if r.load[i] > 0.8 then print(i, "near breaking") end end
local r = Physics.jointReactions(ids, { fields = { "axial", "load" } }); print(r.axial[1], r.load[1])listenJointLoads(targets: any, listen: boolean?) → void
Keep the peak load of joints between reads: from the next physics step on, every step offers its load to each joint's peak, and `Physics.jointReaction(..).peak` and the `peak*` arrays of `Physics.jointReactions` take it, so a load that crossed a threshold for one step and fell back is still read however many steps ran between two reads. Only listened joints (and breakable ones) are measured every step. Listening ends when `listen` is false or the joint's entity is gone.
| arg | type | description |
|---|---|---|
| targets | any | A `Joint`, an entity (every joint its body is in), or an array of Joints and entities. |
| listen | boolean? | True (the default) to keep the peak, false to stop. |
examples
Physics.listenJointLoads(bridgeJoints)
local r = Physics.jointReaction(cable); if r and r.peak and r.peak.load > 1 then print("overloaded at step", r.peak.step) endjointState(entityId: string | entityRef | table, name: string?) →
Where an entity's joint stands as of the last physics step: the angle of a hinge, the travel of a prismatic, the swing and twist of a ball joint, whether it is at a limit, and the force its limit and motor applied. `axes` holds the same for each axis of the joint's frame (the frame's X along the joint's `axis`). Angles are degrees, angular velocities radians per second, travels metres.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | table | Entity carrying the Joint component, or a `Joint` component. |
| name | string? | The Joint's name on that entity, for one of several joints; omit for its unnamed Joint. |
examples
local s = Physics.jointState(door); print(s.angle, s.atLimit)
if Physics.jointState(elbow).atLimit then playSound("creak") endjointBreaks( ) →
Every joint that has broken since the last call to this function. A joint breaks when the reaction it carries exceeds the `breakForce` (newtons of force on the body carrying it) or `breakTorque` (newton-metres of moment about its anchor) its joint was given; each joint reports once and its constraint is already released when the record arrives. The 256 most recent are kept: a structure that comes apart while nothing reads them drops the oldest beyond that, as the engine's own queue does beyond 1024.
examples
for _, e in ipairs(Physics.jointBreaks()) do print(e.entityId, e.force) end
onJointBreak(fn: (table) →
Call `fn` for every joint that breaks from now on, with the same record `jointBreaks` returns.
| arg | type | description |
|---|---|---|
| fn | (table | Receives one break record per broken joint. |
examples
local off = Physics.onJointBreak(function(e) print(e.kind, e.force, e.position) end)
contactEventFrom(record: any, flipped: boolean) → PhysicsContactEvent
A record as `entity` sees it: the record unchanged when `entity` is its first side, else its two sides exchanged and its normals reversed.
| arg | type | description |
|---|---|---|
| record | any | |
| flipped | boolean |
contactSideOf(record: any, target: string) → boolean
How a record reaches a target: as is when the target is its first side, reversed when it is the second, nil when it is neither. The empty target (every contact) takes every record as is.
| arg | type | description |
|---|---|---|
| record | any | |
| target | string |
contactWanted(listener: any, event: PhysicsContactEvent) → boolean
Whether a listener wants an event. An impact is the listener's when the impulse rose past its own `minImpulse` on that step, whichever threshold of another listener's the engine recorded it for.
| arg | type | description |
|---|---|---|
| listener | any | |
| event | PhysicsContactEvent |
pumpContactEvents( ) → void
Take what the engine recorded and hand each record to every listener and buffer whose target it concerns.
view(flipped: boolean) → PhysicsContactEvent
| arg | type | description |
|---|---|---|
| flipped | boolean |
syncContactInterest(target: string) → void
Tell the engine what to record for `target`: the union of what its listeners and buffers ask, or nothing once none is left.
| arg | type | description |
|---|---|---|
| target | string |
ask(entry: any) → void
| arg | type | description |
|---|---|---|
| entry | any |
contactAsk(fname: string, opts: PhysicsContactOptions?, defaults: { string }) → any
What a listener or buffer asks for, from its options, raising on a kind the engine does not record.
| arg | type | description |
|---|---|---|
| fname | string | |
| opts | PhysicsContactOptions? | |
| defaults | { string } |
contactTarget(fname: string, target: (string | entityRef) → void
| arg | type | description |
|---|---|---|
| fname | string | |
| target | (string | entityRef |
addContactListener(fname: string, target: (string | entityRef) → void
| arg | type | description |
|---|---|---|
| fname | string | |
| target | (string | entityRef |
_onDisconnect( ) → void
The connection ends when `off` runs, or when the component that made it is removed or its entity destroyed; either way the listener goes and the engine stops recording what nobody hears any more.
onContact(target: (string | entityRef, fn: ?, opts: ?) →
Call `fn` for each collision and contact event of an entity's colliders from now on: on collision begin, while the two stay in contact, on collision end, on an impact (a hit, by how hard it lands), and on a trigger's enter and exit. Events are recorded by the physics step itself and `fn` runs once per step, before that step's `fixedUpdate`, so an impact that lasts one step is heard even when a frame runs several steps. The listener ends when the returned function is called, or when the component that registered it is removed or its entity destroyed. Only the colliders somebody listens to cost the step anything. Use it to detect a hit, a landing, two things touching or parting, or a body in a zone. built from), a collider's own entity, a trigger, a soft body. `nil` hears every contact in the world. `{ kind, step, entity, other, collider, otherCollider, trigger, normal, closingSpeed, impulse, tangentImpulse, peakImpulse, totalImpulse, steps, pointCount, points }`. `kinds` defaults to begin, end, enter and exit, plus impact when `minImpulse` is given; add "persist" for an event on every step of a contact.
| arg | type | description |
|---|---|---|
| target | (string | entityRef | The entity whose contacts to hear: a body (every collider it is |
| fn | ? | Receives one `PhysicsContactEvent` per event, seen from `target`: |
| opts | ? | `PhysicsContactOptions`: `{ kinds?, minImpulse?, minSpeed? }`. |
examples
local off = Physics.onContact(ball, function(e) if e.kind == "begin" then print("hit", e.other, e.closingSpeed) end end)Physics.onContact(nil, function(e) print(e.kind, e.entity, e.other) end, { kinds = { "begin", "end" } })Physics.onContact(public.entityId, function(e) log.info(`{e.kind} with {e.other}`) end)onImpact(target: (string | entityRef, fn: ?, opts: ?) →
Call `fn` for every impact (a collision hit) on an entity from now on: the physics step on which the normal impulse between it and something it touches rises past `minImpulse` newton-seconds. Each impact is heard once, on the step it lands, with the impulse of that step (`impulse`, N s; a rigid stop of mass m from speed v is m * v), how fast the two were closing as they met (`closingSpeed`, m/s) and where (`points`); the impulse divided by the step's time is the mean impact force over it. Use it to detect a hit and answer it: damage, impact sounds, fall damage, scoring, breaking things. Runs once per physics step, before that step's `fixedUpdate`. (default 0, the step a pair first takes any load) and the closing speed it must reach.
| arg | type | description |
|---|---|---|
| target | (string | entityRef | The entity to hear impacts on, or `nil` for every impact in the world. |
| fn | ? | Receives one `PhysicsContactEvent` (kind "impact") per impact. |
| opts | ? | `{ minImpulse?, minSpeed? }`: the impulse an impact must reach |
examples
Physics.onImpact(box, function(e) print("hit by", e.other, e.impulse, "N s at", e.closingSpeed, "m/s") end, { minImpulse = 50 })Physics.onImpact(player, function(e) if e.closingSpeed > 12 then takeFallDamage(e.closingSpeed) end end)
onTrigger(target: (string | entityRef, fn: ?) →
Call `fn` when a body enters or leaves a trigger from now on (on trigger enter, on trigger exit). A trigger is a collider with `isTrigger` set: it holds nothing up and reports what overlaps it, whether it stands alone or rides a body, and it detects dynamic and kinematic bodies alike. A fixed trigger leaves out the fixed geometry it stands in, such as the floor under a zone. hear; `nil` hears every trigger in the world. ("exit"), seen from `target`, with `other` the entity that entered or left.
| arg | type | description |
|---|---|---|
| target | (string | entityRef | The trigger's entity, or the entity whose trigger overlaps to |
| fn | ? | Receives one `PhysicsContactEvent` per enter ("enter") and exit |
examples
Physics.onTrigger(zone, function(e) if e.kind == "enter" then print(e.other, "entered") end end)
listenContacts(target: (string | entityRef, opts: ?) →
Start keeping an entity's collision and contact events for polling: from now on every event of the kinds `opts` names is kept for `Physics.contactEvents(target)` to read, and the hardest hit it takes for `Physics.contactPeak(target)`, however many physics steps run between two reads. Keeps the most recent 1024 events per target. Calling it again for the same target replaces the options. The events stop being kept when the returned function runs, or when the component that called it is removed or its entity destroyed.
| arg | type | description |
|---|---|---|
| target | (string | entityRef | The entity whose events to keep, or `nil` for every contact in the world. |
| opts | ? | `PhysicsContactOptions`, as `onContact` takes it. |
examples
local stop = Physics.listenContacts(body, { minImpulse = 100 })for _, e in Physics.contactEvents(body) do if e.kind == "impact" then print(e.other, e.impulse) end end
_onDisconnect( ) → void
contactEvents(target: (string | entityRef) →
Every collision and contact event kept for `target` since the last call for it, oldest first, each from its own physics step: begin, persist, end, impact, trigger enter and exit, as `Physics.listenContacts` started keeping them. Reading empties the list. nothing is kept for `target`.
| arg | type | description |
|---|---|---|
| target | (string | entityRef | The entity `listenContacts` named, or `nil` for every contact. |
examples
for _, e in Physics.contactEvents(ball) do print(e.kind, e.other, e.step) end
contactPeak(target: string | entityRef) →
The hardest hit `target` took since the last call for it: the largest normal impulse one physics step put between it and anything it touched, with who, on which step, how fast the two were closing as that step began, and the surfaces each side is made of where the hit landed. Every step counts, so an impact that began and ended between two reads is still the peak it was. The engine keeps it while anything listens to `target` (`Physics.listenContacts`, `onContact`, `onImpact`, `onTrigger`). Reading starts the next peak afresh. or nil when nothing pushed on it since the last read.
| arg | type | description |
|---|---|---|
| target | string | entityRef | A listened entity. |
examples
Physics.listenContacts(body); local peak = Physics.contactPeak(body); if peak then print(peak.impulse, peak.closingSpeed) end
pumpContactEvents( ) → void
Deliver every collision and contact event the physics steps recorded since the last delivery to the `onContact`, `onImpact` and `onTrigger` listeners and the lists `listenContacts` keeps. The engine calls this after every physics step that recorded any, before that step's `fixedUpdate`, so listeners hear each step's events at the physics rate.
examples
Physics.pumpContactEvents()
contactEventsDropped( ) →
How many contact events the engine let go before anything read them: its queue keeps 4096 between two deliveries, and each target `listenContacts` keeps 1024. Zero when nothing was lost. lists `listenContacts` keeps, since the world started.
examples
local lost = Physics.contactEventsDropped(); if lost.engine > 0 then log.warn("contact events dropped") endvectorOf(v: any) → vector
| arg | type | description |
|---|---|---|
| v | any |
motionSampleFrom(record: any) → PhysicsMotionSample
| arg | type | description |
|---|---|---|
| record | any |
motionKey(id: string, name: string) → string
| arg | type | description |
|---|---|---|
| id | string | |
| name | string |
motionTarget(fname: string, target: string | entityRef, name: string?) → void
| arg | type | description |
|---|---|---|
| fname | string | |
| target | string | entityRef | |
| name | string? |
trimMotion(probe: any) → void
Keep the probe's `capacity` newest samples, counting the ones let go.
| arg | type | description |
|---|---|---|
| probe | any |
pullMotion(probe: any) → void
Take what the engine recorded for one probe into the probe's own list, which keeps its `capacity` newest samples.
| arg | type | description |
|---|---|---|
| probe | any |
probeMotion(target: string | entityRef, opts: PhysicsMotionProbeOptions?) →
Place a motion probe: a measuring point on a body (an accelerometer, a g-force sensor) whose velocity, acceleration, angular velocity and angular acceleration the physics step samples, for `Physics.motionSamples` and `Physics.motionPeak` to read. On a rigid body it measures a point of the body, the rotation terms (centripetal and tangential acceleration) included, at every solver substep: the rate the solver actually steps the body, which rises when the body's island runs extra substeps. A step the solver does not move the body in (asleep, settled) takes one sample. On a soft body it measures a region's particles, their velocity averaged by mass, at the same rate: a hit soft body's extra substeps are each sampled. Each sample also reads the proper acceleration, what a rider or sensor at the point feels (0 g in free fall, 1 g at rest), and its size in g. Use it for g-force readouts, impact severity, crash and hit strength, controller haptics, flight and roller-coaster feel, and telemetry. A body with no probe costs nothing. The probe follows the entity id across a mode switch or a respawn, and each new body it measures (play starting, a respawn) starts its record afresh: the samples, the peak and the clock. It ends when the returned function runs or the component that placed it is removed or its entity destroyed. Placing it again with the same `name` replaces its options and keeps what it recorded. `opts.region` a soft body.
| arg | type | description |
|---|---|---|
| target | string | entityRef | The entity whose body to measure: a rigid body, or with |
| opts | PhysicsMotionProbeOptions? | `PhysicsMotionProbeOptions`: `{ point?, region?, name?, capacity?, substeps? }`. |
examples
local stop = Physics.probeMotion(car, { point = {0, 0.6, -0.3}, name = "seat" })Physics.probeMotion(ball)
Physics.probeMotion(dummy, { region = { nearest = {0, 0.4, 0} }, name = "head" })_onDisconnect( ) → void
motionSamples(target: string | entityRef, name: string?) →
Every sample a motion probe took since the last call for it, oldest first, each from the solver substep (or physics step) it was taken in, however many steps ran between two calls: read it once a frame, or from `fixedUpdate`, and nothing is missed. A sample carries the point's velocity, acceleration, proper acceleration (what is felt), g-force, angular velocity and angular acceleration, and its step, time and length. Reading empties the list. `Physics.motionProbe` states the rate the samples are taken at and how many were let go. since the last read or no probe has that target and name.
| arg | type | description |
|---|---|---|
| target | string | entityRef | The probed entity. |
| name | string? | The probe's name, when `Physics.probeMotion` gave it one. |
examples
for _, s in Physics.motionSamples(car, "seat") do if s.g > 4 then print("hard hit", s.g, s.step) end endlocal samples = Physics.motionSamples(ball); local last = samples[#samples]; if last then print(last.acceleration, last.g) end
motionPeak(target: string | entityRef, name: string?) →
The sample with the largest g-force (proper acceleration) a motion probe took since the last call for it: the hardest moment of a crash, a hit or a turn. Every sample counts, whether or not `Physics.motionSamples` read it. Reading starts the next peak afresh. last read or no probe has that target and name.
| arg | type | description |
|---|---|---|
| target | string | entityRef | The probed entity. |
| name | string? | The probe's name, when `Physics.probeMotion` gave it one. |
examples
local peak = Physics.motionPeak(car, "seat"); if peak and peak.g > 20 then print("severe impact", peak.g) endmotionProbe(target: string | entityRef, name: string?) →
What a motion probe is doing: the rate it samples at (samples per second), the length of its latest sample, how many samples the latest physics step took, how many it keeps and how many wait to be read, how many it let go since it was placed, and whether it is bound to a body (with the reason when it is not: no entity carries the id, or the entity holds no body the probe can measure).
| arg | type | description |
|---|---|---|
| target | string | entityRef | The probed entity. |
| name | string? | The probe's name, when `Physics.probeMotion` gave it one. |
examples
local info = Physics.motionProbe(car, "seat"); print(info.rate, "samples/s", info.dropped, "dropped")
syncStepListening( ) → void
Step hooks: code that runs with every physics step Tell the engine which sides of the step have a hook to run.
addStepHook(fname: string, signal: any, fn: (number, number) → void
| arg | type | description |
|---|---|---|
| fname | string | |
| signal | any | |
| fn | (number, number |
_onDisconnect( ) → void
The hook ends when `off` runs, or when the component that made it is removed or its entity destroyed (a hot reload of the component ends it before the reloaded copy starts).
onBeforeStep(fn: (number, number) →
Call `fn` at the start of every physics step from now on, at the physics tick rate (`physics.tick_rate`), however many steps a frame runs. It runs after the step's force reset and before the step integrates, so a force, torque, impulse or velocity written here acts on this very step, and a read here (a position, a velocity, a raycast) sees the state the step starts from. This is the place for a force that depends on where a body is or how fast it moves: gravity toward a planet, a spring, a thruster holding altitude, buoyancy, a PID controller, an active ragdoll's balance. `applyForce` holds a force over the whole step the way gravity is held; a pull that stands in for gravity (an orbit) or drives an oscillation keeps its energy when it is given as the momentum it makes over the step instead: `Physics.applyImpulse(id, force * dt)`. One engine call runs every hook, so one hook looping over many bodies costs about what the loop costs. Runs while the gameplay clock runs, on every engine that steps the world: under multiplayer push only the bodies this peer simulates. The hook ends when the returned function is called, or when the component that registered it is removed, its entity destroyed or its code reloaded. A hook must not wait (`task.wait`); spawn a task from it for work that does. The engine runs the hooks of the engine thread's VM, so a worker job's call (a `jobs.dispatch` entry) raises, naming the refusal. the `step` the contact events of this step carry.
| arg | type | description |
|---|---|---|
| fn | (number, number | Receives `(dt, step)`: the step's length in seconds and its number, |
examples
local off = Physics.onBeforeStep(function(dt) Physics.applyForce(ship, { 0, 9.81 * 500, 0 }) end)Physics.onBeforeStep(function(dt) local p = entity(moon).position; local r = math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z); local k = -GM * mass * dt / (r * r * r); Physics.applyImpulse(moon, { p.x * k, p.y * k, p.z * k }) end)onAfterStep(fn: (number, number) →
Call `fn` at the end of every physics step from now on, at the physics tick rate, however many steps a frame runs. It runs once the step has integrated, after that step's collision events reached their listeners (`Physics.onContact`, `onImpact`, `onTrigger`) and before `fixedUpdate`, so a read here sees what this step left: positions, velocities, `Physics.jointReaction`, `Physics.contactPeak`. Use it to sample a trajectory step by step, measure energy, record a replay, or react to a step's result. A force written here acts on the next step. One engine call runs every hook. The hook ends the way an `onBeforeStep` hook ends, and must not wait either.
| arg | type | description |
|---|---|---|
| fn | (number, number | Receives `(dt, step)`: the step's length in seconds and its number. |
examples
local samples = {}; local off = Physics.onAfterStep(function(dt, step) table.insert(samples, entity(ball).position.y) end)runStepHooks(phase: string, dt: number, step: number) → void
Run the step hooks registered for one side of a physics step. The engine calls this with `"before"` at the start of every step and with `"after"` at its end while `Physics.onBeforeStep` or `Physics.onAfterStep` hooks are registered.
| arg | type | description |
|---|---|---|
| phase | string | `"before"` or `"after"`. |
| dt | number | The step's length in seconds. |
| step | number | The step's number. |
examples
Physics.runStepHooks("before", 1 / 30, 1)addConstraint(entityId: string | entityRef, opts: table?) → void
Add a transform constraint to an entity.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| opts | table? | Optional constraint description (targetEntityId, position, rotation, scale, lookAt, targetPosition, axes, weight). |
examples
Physics.addConstraint(id, { targetEntityId = parent, position = true })removeConstraint(entityId: string | entityRef, index: number?) → void
Remove transform constraints from an entity (if any are present).
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| index | number? | Optional constraint index (currently ignored — the whole component is removed). |
examples
Physics.removeConstraint(id)
colliderOn(entityId: string | entityRef) → string
Which collider component an entity carries, or nil when it carries none.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
examples
local which = Physics.colliderOn(id)
addCollider(entityId: string | entityRef, component: string, config: table?) → void
Add a collider component to an entity, naming the shape you want.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| component | string | One of `Physics.COLLIDER_COMPONENTS`. |
| config | table? | The component's own fields, e.g. `{ radius = 0.5 }` for a sphere. |
examples
Physics.addCollider(id, "SphereCollider", { radius = 0.5 })removeCollider(entityId: string | entityRef) → string
Remove whichever collider component an entity carries.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
examples
Physics.removeCollider(id)
addWheelCollider(entityId: string | entityRef, config: table?) → void
Add a WheelCollider to an entity. The entity must be a child (or descendant) of a rigid body — the system walks up the hierarchy to find the Physics component. Every wheel under one body is a wheel of that body's ray-cast vehicle.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
| config | table? | Optional wheel configuration (`radius?`, `suspensionDistance?`, `springRate?`, `damperRate?`, `targetPosition?`, `maxSuspensionForce?`, `bumpStopRecovery?`, `bumpStopSpeed?`, `groundAngle?`, `motorTorque?`, `brakeTorque?`, `steerAngle?`, `forwardFriction?`, `sidewaysFriction?`, `frictionSlip?`, `sideFrictionStiffness?`, `corneringStiffness?`, `forwardFrictionStiffness?`, `slideGrip?`, `slideSlip?`, `loadSensitivity?`, `referenceLoad?`, `inertia?`, `rollingResistance?`, `width?`, `is2D?`, `visual?`, `solid?`, `mass?`, `breakLoad?`, `attached?`). A `solid` wheel is a volume other bodies strike; a `breakLoad` above 0 lets it come off as a body of its own (`Physics.detachWheel` takes it off on command). An `inertia` above 0 makes the wheel spin on its own (wheelspin, lock-up, drift); the tyre grip curve fields shape its grip over slip and load (`Physics.tyreCurve` measures it, `@builtin::modules.tyres` holds presets). |
examples
Physics.addWheelCollider(id, { radius = 0.35, motorTorque = 500 })removeWheelCollider(entityId: string | entityRef) → void
Remove the WheelCollider component from an entity (if present).
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id. |
examples
Physics.removeWheelCollider(id)
setWheelAttached(entityId: string | entityRef, attached: boolean) → boolean
Write a wheel's `attached`, through its WheelCollider component when it has one, so the change reaches every peer.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | |
| attached | boolean |
detachWheel(entityId: string | entityRef) → boolean
Take a wheel off its vehicle: it leaves as a dynamic body of its own from where it stands, moving as it moved and spinning as it spun, with its volume (`solid`) as its collider and its `mass`, and the vehicle drives on the wheels it has left. The wheel entity stays under the chassis in the hierarchy; `Physics.getVelocity`, `applyImpulse` and the contact listeners reach it as any body. A wheel also comes off by itself when its `reaction` passes its `breakLoad`. On a shared world the peer that may write the wheel takes it off for every peer.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The wheel entity (it carries the WheelCollider). |
examples
Physics.detachWheel(wheel.id); print(Physics.getWheelState(wheel.id).detachReason) -- "command"
attachWheel(entityId: string | entityRef) → boolean
Put a wheel that came off back on its vehicle, at its mount: its own body goes, and the vehicle drives on it again from the next physics tick.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The wheel entity (it carries the WheelCollider). |
examples
Physics.attachWheel(wheel.id)
vec3Of(v: any) → vec3
| arg | type | description |
|---|---|---|
| v | any |
wheelStateOf(v: any) → table
| arg | type | description |
|---|---|---|
| v | any |
getWheelState(entityId: string | entityRef) →
Read a wheel collider's runtime state. Reads the native component the wheel system writes after each physics step.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | Target entity id (must carry a WheelCollider component). |
examples
local state = Physics.getWheelState(id)
tyreCurve(entityId: string | entityRef, opts: table?) →
Measure a wheel's tyre grip curve: the force its tyre pushes with at a steady slip, swept over slip ratio (along the road), slip angle (across it) and load, as the wheel's WheelCollider fields state its grip and as its solve settles on at that slip. Tune a tyre by numbers: its peak, where it peaks, how far it falls past the peak, and how its grip per newton falls with load.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The wheel entity (it carries the WheelCollider). |
| opts | table? | Optional `{ loads = { N... }?, slipRatios = { ... }?, slipAngles = { degrees... }?, at = { { slipRatio, slipAngle }... }? }`: the loads to sweep (default the load the wheel carries now, or its `referenceLoad`), the slip ratios (default 0 to 1 by 0.025), the slip angles (default 0 to 30 degrees by 1), and pairs of slips to answer together. |
examples
local curve = Physics.tyreCurve(wheel.id); print(curve.loads[1].side.peak.slipAngle, curve.loads[1].side.peak.perLoad)
vehicleState(chassisId: string | entityRef) →
Read a vehicle: the chassis body's forward speed and the state of every wheel under it (the wheels whose nearest rigid-body ancestor is this chassis), and the wheels that came off it.
| arg | type | description |
|---|---|---|
| chassisId | string | entityRef | The chassis entity (the rigid body the wheels sit under). |
examples
local car = Physics.vehicleState(carId); print(car.speed, car.groundedWheels)
walk(e: any) → void
| arg | type | description |
|---|---|---|
| e | any |
shaftNetworkState(entityId: string | entityRef) →
Read a ShaftNetwork (a drivetrain, gearbox, differential, clutch, gear train, winch or other network of rotating parts on shafts) as of the last physics tick: every part's speed and torques and every link's torque, slip and lock, by name. The same reading as the component's `state()`.
| arg | type | description |
|---|---|---|
| entityId | string | entityRef | The entity carrying the ShaftNetwork. |
examples
local s = Physics.shaftNetworkState(car.id); print(s.parts.engine.rpm, s.links.clutch.slipping)
raycastBetween(fromId: string, toId: string, maxDistance: number?) →
Cast a ray from one entity toward another and return the first hit.
| arg | type | description |
|---|---|---|
| fromId | string | Origin entity id. |
| toId | string | Target entity id. |
| maxDistance | number? | Optional distance cap (default 1000). |
examples
local hit = Physics.raycastBetween(a, b)
hasLineOfSight(fromId: string, toId: string) →
Check whether two entities have line-of-sight between their origins.
| arg | type | description |
|---|---|---|
| fromId | string | Viewer entity id. |
| toId | string | Target entity id. |
examples
if Physics.hasLineOfSight(a, b) then ... end
PhysicsLocks = {PhysicsSleepState = {PhysicsColliderState = {PhysicsContactPoint = {PhysicsContact = {PhysicsJointMotor = {PhysicsJointState = {PhysicsJointLoadPeak = {PhysicsJointReaction = {PhysicsJointReactions = {PhysicsTransformConstraintState = {PhysicsPlaneHold = {PhysicsHeldForce = {PhysicsBodyForces = {PhysicsBodyState = {PhysicsMovingThreshold = {PhysicsStepCost = {PhysicsStepSummary = {PhysicsSoftBodyCost = {PhysicsSoftBodySettings = {PhysicsWorldState = {PhysicsSoftBodyState = {PhysicsSoftBodyStability = {PhysicsSoftStabilityPart = {PhysicsSoftBodyEnergy = {PhysicsSoftMeasureSamples = {PhysicsSoftMeasurement = {PhysicsSoftRegionState = {PhysicsSoftElements = {PhysicsSoftBodyReplication = {PhysicsSoftBodyDiagnostics = {PhysicsDebugObject = {PhysicsDebugLines = {PhysicsSoftPin = {PhysicsSoftParticles = {PhysicsSoftParticlesWrite = {PhysicsPushOptions = {PhysicsSoftAttachment = {PhysicsSoftHit = {PhysicsSoftRegion = {PhysicsSoftBodyCage = {PhysicsSoftBodyRender = {PhysicsDrawnPose = {PhysicsObservation = {PhysicsSurface = {PhysicsSurfaceDefinition = {PhysicsGroundContact = {PhysicsSoftBodyTear = {PhysicsSoftElementBreak = {PhysicsContactEventPoint = {PhysicsContactEvent = {PhysicsContactOptions = {PhysicsContactPeak = {PhysicsMotionSample = {PhysicsMotionProbeOptions = {PhysicsMotionProbeInfo = {Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
These counts cover only the parts this page shows. Problems on the parts it leaves out are not counted here.
Inside
3 problems across 1 itemagent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.