Byte Engine Docs

Physics

Look up the body kinds and properties, the collider shapes, constraints, the contact and sleep rules, ray queries, how a step runs, and the units and limits of the simulation.

Physics simulates rigid bodies that an application creates on the world scope and places with transforms. Dynabit is the built-in implementation. This page specifies the bodies, shapes, constraints, and queries it accepts, the observable rules of contact and sleep, and how a step runs. The message model it builds on is in World and messages.

Bodies

KindBehavior
StaticIgnores forces and collision resolution. Never moves and publishes no transform.
KinematicTakes the same path as static today: no mass, no gravity, never moved by the solver.
DynamicResponds to forces and collisions. Its mass must be finite and positive.
PropertyDefaultUnitNotes
ShapeRequiredMeters, collider spaceSee Shapes.
VelocityZerom/s, world spaceThe initial linear velocity.
Mass1kgUsed by dynamic bodies only.
Center of massThe capsule's center, the hull's center of mass, or the origin for a sphere or boxCollider spaceSpin is about it.
Elasticity0.1A pair's restitution is the product of both elasticities.
Friction0.5A pair's friction is the product of both frictions.
RotatesTrueWhen off, the body never turns and its shape collides upright, for characters.
Angular velocityZerorad/sNot settable at creation.
InertiaFrom the shape's principal inertia scaled by massA hull uses the diagonal of its inertia tensor.
DampingNone

A transform's scale is carried and republished with the body but never applied to its collision shape.

Shapes

ShapeParameters
SphereRadius, centered on the local origin.
BoxHalf extents on each axis.
CapsuleRadius, height from the bottom of the lower cap to the top of the upper cap, and center. The axis is local Y. A height below twice the radius is a sphere.
Convex hullA hull built from a point cloud, shareable between bodies. Corners and edges are rounded by a margin of 0.02 m, capped at a quarter of the distance from the center of mass to the nearest side.

Building a hull needs at least four finite points that aren't coplanar, collinear, or coincident. Coordinates snap to a grid of 2^26 steps.

Placing and removing bodies

RuleBehavior
CreatePublish the body through the world scope's factory. Publishing again under the same handle replaces the body and forgets its kept impulses.
PlaceSend a transformation update for the handle. Until one arrives, the body sits at the origin with identity orientation.
ResultsEach step publishes a transformation update for every awake dynamic body on the same route.
Authored moveAn update equal to the current pose moves nothing. A different one re-places the body, wakes it, and wakes sleepers near the old and new bounds.
ImpulseA world-space linear impulse wakes the body. An unknown handle is ignored.
DeleteDelete the handle. The next flush removes the body and any constraint created under that handle, and wakes its island and neighbors.

Create the physics system before the bodies it simulates, step it after everything that posts transforms for the step, and flush deletions where readers are done, for example at the start of the next step.

Constraints

A constraint joins two bodies. Its anchors default to both origins, and angles count counterclockwise for someone the axis points at.

KindParametersRule
DistanceA length in meters, finite and zero or moreA rod along its line. A zero length doesn't pin.
HingeAn axis in the first body's frame and an optional limit within plus or minus piTurns about the axis only. The limit counts from the pose of the first step both bodies exist.
Constant velocityAn axis and an optional lean limit from 0 to piLeans any way, never twists about the axis.
BallAn axis, an optional lean limit, and an optional twist rangeSet a lean when setting a twist.
RuleBehavior
ResistanceAn optional function of the angle returning a braking torque in newton-meters, evaluated once per step.
LifecycleCreate in any order relative to the bodies; delete the handle to release; publishing again under a handle replaces.
ActivityActs only in steps where both bodies exist. A constraint naming one body twice is ignored.
Rest poseCaptured in the first step both bodies are present and awake.
CollisionsHeld bodies still collide with each other.
SleepBodies joined by constraints, transitively, sleep and wake as one island.
Correction5 percent of the positional error per step, with a slack of 5 mm for anchors and 5 mrad for turns.

Contacts

RuleValue
Contacts per pairUp to four, at the corners of the touching patch when bodies meet along an edge or face. Corners within 0.02 m count.
NormalPoints from the body created earlier toward the later one.
Continuous collisionA body that moves more than half its thinnest reach in one step gets swept bounds and time-of-impact contacts, so it can't pass through a thin wall.
RestitutionThe product of both elasticities, applied only when the closing speed exceeds 1 m/s.
FrictionThe product of both frictions, limited by the normal push.
OverlapResolved by a position shift of 20 percent of the depth beyond 5 mm, at most 5 cm per step, split by inverse mass, with no velocity change.
Angular speedCapped at 30 rad/s by contacts.
OrderConstraints are solved before each contact pass, so contacts have the last word.
Warm startingEach contact's impulses carry into the next step. A body that takes over a slot doesn't inherit them.
RecyclingA searched pair reuses its contacts while neither body moved more than 0.02 m relative to the other or turned more than 0.05 rad.

Sleep

Sleep is per body, not per pile.

RuleValue
Rest timeA body sleeps after staying put for 0.5 s.
Staying putWithin 0.025 m and 0.05 rad of where the watch found it. Nothing sleeps in the air.
Wake by a neighborA body moving faster than 0.5 m/s, or that strayed, wakes sleepers within 0.05 m of its bounds.
Other wakesAn impulse, an authored transform that moves it or a neighbor, a body created or removed nearby, a constraint taking hold or letting go, or turning sleep off.
AsleepVelocities are zeroed and the solver treats the body as fixed.
AwakeA new or woken body stays awake for at least one full rest time.
IslandsConstrained bodies sleep and wake together.
Massless bodiesNever sleep and never move.

Ray queries

A ray query names a ray and a maximum distance, or a segment. It's created on the world scope and answered after the next step, in creation order, against the bodies where that step left them, sleeping bodies included. The answer is a response naming the query and the first hit, if any, with the body, the distance, the world-space point, and the outward normal.

RuleValue
Start inside a bodyHits at distance 0 with the normal pointing back along the ray.
ShapeCast against the shape as contacts place it, after a bounds prefilter.
PrecisionThe distance can fall short by about 0.0001.
Other queriesThere is no shape cast, overlap, or sweep query.

Stepping

RuleValue
Step lengthThe tick's delta. There are no internal substeps. The stepped application loop runs fixed steps of the simulation rate, 60 per second by default, at most 8 per frame; see Time and ticks.
Gravity16 m/s² downward along -Y, applied as an impulse at the start of the step. Not configurable.
IntegrationVelocities are solved first, then positions and orientations advance at the new velocities.
Lanesphysics.step-lanes sets lanes per body count; the lanes used never exceed the alley's parallelism.
Empty stepA step with no awake massive body returns at once.

A step adopts new bodies, constraints, and authored transforms and wakes disturbed sleepers; applies gravity and computes swept bounds; finds contacts; solves constraints and contacts in four passes; moves dynamic bodies and publishes their transforms; advances the sleep watch; and finally answers ray queries.

Contacts are found and solved in the same order whatever the lane count, so the resulting poses don't depend on it. The order in which transforms are published does.

Units and conventions

QuantityUnit
Length, time, massMeters, seconds, kilograms
AnglesRadians
Torque, impulseNewton-meters, newton-seconds
Up+Y
Collider spaceShapes, anchors, and axes
World spacePositions, velocities, contacts, ray hits

Limits

LimitValue
Contacts per body pair4
Hull inputAt least 4 points
Lanes by defaultAt most 4
Constraint rowsAt most 7 per constraint
BodiesNo fixed limit below 2^31 slots

Rust API

On this page