namespacePhysics7 functions, 1 propertyUI apps only
Unified 2D/3D physics. A DrawPrimitive's body simulates in the app's 2D world, a SceneNode's or Voxel's in its 3D world. Each app simulates in its own worlds: bodies, joints, queries, and gravity never interact with other apps.
The examples on this page start from:
local vec2 = datumhue.math.vec2
local vec3 = datumhue.math.vec3
local canvas =
datumhue.draw.new({ background = datumhue.color("#2d353b") })
canvas:mount({ width = 400, height = 300 })
local floor =
canvas:rect({ pos = vec2(-200, -150), width = 400, height = 20 })
floor:add_body({ type = "static" })| Field | Type | Access | Description |
|---|---|---|---|
gravity | Vec3 | read/write | This app's gravity vector (Y-up; default {0, -9.81, 0}). 2D bodies feel its X/Y components. Assign a vec2/vec3. |
| |||
datumhue.physics.world() -> PhysicsWorldCreate an additional isolated physics world. Bodies join it via add_body{world = ...}; it has its own gravity and query methods. Bodies in different worlds never interact.
In the guide: Bodies, joints and collisions
datumhue.physics.on_step(callback: (fun(dt: number))?)Register this app's physics step handler, called once per completed simulation step with dt the fixed timestep in seconds -- the constant interval every step advances by, independent of frame rate. Steps finish before the frame's Lua callbacks run, so the handler reads post-step state; within a frame it runs after the same steps' collision callbacks and before on_update, and a frame that ran several catch-up steps calls it once per step. At most one handler is active per app -- calling again replaces the previous one. Pass nil to clear it.
datumhue.physics.add_joint(body1: DrawPrimitive | SceneNode | Voxel, body2: DrawPrimitive | SceneNode | Voxel, options: physics.JointOptions) -> JointCreate a physics joint (fixed, revolute, prismatic, distance, or spherical) between two bodies of the same dimension and world. The joint rests in the pose the bodies are in when it is made: a fixed joint keeps their turn, a hinge's zero angle is that pose. The anchors and axis follow each body's handle as it scales, and the joint survives add_body replacing a body in the same world (moving a jointed body to another world raises). Raises for a body joined to itself, bodies of different worlds or dimensions, and an option its kind does not take.
local hub = canvas:circle({ radius = 6 })
local arm = canvas:rect({ pos = vec2(0, -4), width = 80, height = 8 })
hub:add_body({ type = "static" })
arm:add_body({ mass = 1 })
-- A hinge at the hub's center. Anchors are in each body's own
-- frame, so the arm's is its left end. The motor turns it.
datumhue.physics.add_joint(hub, arm, {
type = "revolute",
anchor2 = vec3(-40, 0, 0),
motor_speed = math.pi,
motor_force = 100000,
})options physics.JointOptions options 14 keys
| Key | Type | Default | Description |
|---|---|---|---|
| type | "fixed" | "revolute" | "prismatic" | "distance" | "spherical" | "fixed" | Joint kind. An option the kind does not take raises. |
| anchor1 | Vec3 | datumhue.math.vec3(0, 0, 0) | Attachment point on the first body, in its handle's own frame and units: it stays on the drawing as the handle moves and scales. |
| anchor2 | Vec3 | datumhue.math.vec3(0, 0, 0) | Attachment point on the second body, in its handle's own frame and units. |
| axis | Vec3 | +z for a revolute joint, +x for a prismatic or spherical one | Hinge axis (revolute), slide axis (prismatic), or twist axis (spherical): a non-zero direction in the first body's handle frame; the second body takes the same line as it is drawn. A 2D revolute turns about +z and takes no other axis. |
| angle_limits | number[] | the hinge turns freely | Revolute-only {min, max} angle range in radians from the pose the joint was made in, positive counter-clockwise about the axis as it points from the first body. |
| limits | number[] | the body slides freely along the axis | Prismatic-only {min, max} travel along the axis, in world units. |
| distance_limits | number[] | a distance joint raises | Distance-only, {0, max}: the anchors stay at most max world units apart (at most 1000000), like a rope; nothing holds them apart. |
| swing_limits | number[] | the swing is free | Spherical-only {min, max} angle in radians between the two bodies' twist axes, min 0 or more: a cone around the axis. |
| twist_limits | number[] | the twist is free | Spherical-only {min, max} twist about the axis, in radians from the pose the joint was made in. |
| motor_speed | number | no velocity motor | Target motor velocity (radians/s revolute, world units/s prismatic). |
| motor_force | number | the motor's torque or force is unlimited | Maximum motor torque (revolute) or force (prismatic), 0 or more. |
| motor_target | number | no position motor | Motor target position (radians revolute, world units prismatic). |
| motor_stiffness | number | 1000 with a motor_target, else 0 | Spring gain toward motor_target, 0 or more. |
| motor_damping | number | 100 with a motor_speed, 30 with only a motor_target, else 0 | Damper gain toward motor_speed, 0 or more. |
In the guide: Bodies, joints and collisions Troubleshooting
datumhue.physics.raycast(ray: Ray, options?: physics.RaycastOptions) -> physics.RayHit?Cast a ray and return the nearest body hit, or nil. An options value that is not a table is ignored.
-- New bodies are found once the simulation has stepped.
datumhue.time.sleep(0.1)
-- A 2D ray runs in the canvas plane, at z = 0.
local down = datumhue.math.ray(vec3(0, 100, 0), vec3(0, -1, 0))
local hit = datumhue.physics.raycast(down, { max_distance = 500 })
-- The floor's top is at y = -130.
print(hit.body == floor, hit.distance) --> true 230.0
print(hit.point) --> vec3(0.0, -130.0, 0.0)
print(hit.normal) --> vec3(0.0, 1.0, 0.0)options physics.RaycastOptions options 4 keys
| Key | Type | Default | Description |
|---|---|---|---|
| max_distance | number | 1000000 | Maximum ray length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
| solid | boolean | true | Count a ray starting inside a collider as a hit at distance 0. |
returns physics.RayHit record 4 keys
| Key | Type | Description |
|---|---|---|
| body | DrawPrimitive | SceneNode | Voxel | The body that was hit. |
| point | Vec3 | World-space contact point. |
| normal | Vec3 | World-space surface normal at the hit. |
| distance | number | Distance from the origin to the hit. |
In the guide: Bodies, joints and collisions
datumhue.physics.raycast_all(ray: Ray, options?: physics.RaycastAllOptions) -> physics.RayHit[]Cast a ray and return every body along it, nearest first. An options value that is not a table is ignored.
local box = canvas:rect({ pos = vec2(-20, 0), width = 40, height = 40 })
box:add_body({ type = "static" })
-- New bodies are found once the simulation has stepped.
datumhue.time.sleep(0.1)
local down = datumhue.math.ray(vec3(0, 100, 0), vec3(0, -1, 0))
local hits = datumhue.physics.raycast_all(down, { max_hits = 8 })
-- Nearest first.
print(#hits, hits[1].body == box, hits[2].body == floor) --> 2 true trueoptions physics.RaycastAllOptions options 5 keys, 4 inherited
| Key | Type | Default | Description |
|---|---|---|---|
| max_hits | integer | 64 | Maximum hits to return, 0 or more. |
| From physics.RaycastOptions | |||
| max_distance | number | 1000000 | Maximum ray length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
| solid | boolean | true | Count a ray starting inside a collider as a hit at distance 0. |
returns physics.RayHit record 4 keys
| Key | Type | Description |
|---|---|---|
| body | DrawPrimitive | SceneNode | Voxel | The body that was hit. |
| point | Vec3 | World-space contact point. |
| normal | Vec3 | World-space surface normal at the hit. |
| distance | number | Distance from the origin to the hit. |
datumhue.physics.point_query(point: Vec2 | Vec3, options?: physics.PointQueryOptions) -> (DrawPrimitive | SceneNode | Voxel)[]Return every body whose collider overlaps the given world-space point. An options value that is not a table is ignored.
-- New bodies are found once the simulation has stepped.
datumhue.time.sleep(0.1)
local under = datumhue.physics.point_query(vec2(0, -140))
print(#under, under[1] == floor) --> 1 true
local others = datumhue.physics.point_query(vec2(0, -140), {
exclude = floor,
})
print(#others) --> 0options physics.PointQueryOptions options 2 keys
| Key | Type | Default | Description |
|---|---|---|---|
| layers | integer[] | every layer | Only include bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
In the guide: Bodies, joints and collisions
datumhue.physics.shapecast(ray: Ray, options: physics.ShapecastOptions) -> physics.RayHit?Sweep a 3D collider shape along the ray and return the nearest body hit, or nil.
-- It sweeps a 3D shape, so it finds bodies in a 3D scene.
local scene = datumhue.scene.new({ width = 320, height = 240 })
local ground = scene:cube({ scale = vec3(10, 1, 10) })
ground:add_body({ type = "static" })
-- New bodies are found once the simulation has stepped.
datumhue.time.sleep(0.1)
local down = datumhue.math.ray(vec3(0, 5, 0), vec3(0, -1, 0))
local box = { shape = "cube", width = 2, height = 1, depth = 2 }
local hit = datumhue.physics.shapecast(down, box)
-- The box's bottom, 0.5 below the ray, meets the top at y = 0.5.
print(hit.body == ground, hit.distance) --> true 4.0options physics.ShapecastOptions options 9 keys
| Key | Type | Default | Description |
|---|---|---|---|
| shape | physics.Shape | "cube" | 3D collider shape to cast. |
| width | number | 1 | Box width. |
| height | number | 1 | Box height / capsule length. |
| depth | number | 1 | Box depth. |
| radius | number | 0.5 | Sphere / capsule / cylinder / cone radius. |
| rotation | Quat | datumhue.math.quat.identity() | Shape orientation. |
| max_distance | number | 1000000 | Maximum cast length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
returns physics.RayHit record 4 keys
| Key | Type | Description |
|---|---|---|
| body | DrawPrimitive | SceneNode | Voxel | The body that was hit. |
| point | Vec3 | World-space contact point. |
| normal | Vec3 | World-space surface normal at the hit. |
| distance | number | Distance from the origin to the hit. |
options 3 keys
| Key | Type | Default | Description |
|---|---|---|---|
| max_height | number | physics.RelativeLength | {relative = 0.25} | Max step height the character climbs. |
| min_width | number | physics.RelativeLength | {relative = 0.5} | Minimum free width that must remain on the step. |
| include_dynamic_bodies | boolean | true | Whether dynamic bodies can act as steps. |
Used by: CharacterController.autostep
Nested in: physics.CharacterControllerOptions
| Value | Description |
|---|---|
"x" | |
"y" | |
"z" |
Nested in: physics.BodyOptions, physics.LockedAxesOptions
options 18 keys
| Key | Type | Default | Description |
|---|---|---|---|
| type | "dynamic" | "static" | "kinematic" | "dynamic" | Body dynamics. |
| shape | physics.Shape | the collider fits what the handle draws | Collider shape. |
| width | number | taken from what the handle draws, or 1 | Box width, in the handle's own units. |
| height | number | taken from what the handle draws, or 1 | Box, cylinder, or cone height, or a capsule's straight length between its caps, in the handle's own units. |
| depth | number | taken from what the handle draws, or 1 | Box depth in the handle's own units, 3D only. |
| radius | number | taken from what the handle draws, or 0.5 | Circle, sphere, capsule, cylinder, or cone radius, in the handle's own units. |
| restitution | number | 0.3 | Bounciness, 0 or more: 0 absorbs an impact, 1 keeps all its energy. |
| friction | number | 0.5 | Surface friction, 0 or more. |
| mass | number | derived from the collider's size | Mass override, more than 0. |
| sensor | boolean | false | Make the body a non-colliding trigger volume that reports the bodies overlapping it: dynamic and kinematic ones, and static ones unless the sensor is static itself. |
| points | Vec3[] | a convex_hull, polyline or trimesh shape is a box | Vertices for convex_hull / polyline / trimesh in the handle's own frame and units (vec3; vec2 accepted, z = 0). |
| indices | integer[][] | a trimesh shape is a box | Triangles for the trimesh shape: each three 1-based positions in points. |
| layers | integer[] | every layer | Collision membership: layer bit indices 0..=31 the body belongs to. |
| collides_with | integer[] | every layer | Collision filter: layer bit indices 0..=31 the body collides with; an empty list collides with nothing. |
| lock_translation | "x" | "y" | "z"[] | no axis beyond those constraints | Axes to lock translation on, on top of a 2D body's in-plane constraints. |
| lock_rotation | "x" | "y" | "z"[] | no axis beyond those constraints | Axes to lock rotation on, on top of a 2D body's in-plane constraints. |
| ccd | boolean | false | Sweep this body against moving (kinematic and dynamic) bodies too when it moves fast; fast bodies always sweep static geometry so they never tunnel through it. |
| world | PhysicsWorld | the app's default world | Simulate in this world, made by datumhue.physics.world(), instead of the app's default one. |
Used by: SceneNode:add_body, DrawPrimitive:add_body
Extended by: draw.BodyOptions
| Value | Description |
|---|---|
"dynamic" | |
"static" | |
"kinematic" |
Nested in: physics.BodyOptions
record 4 keys
| Key | Type | Description |
|---|---|---|
| body | DrawPrimitive | SceneNode | Voxel | The body that was hit. |
| point | Vec3 | World-space witness point of the hit. |
| normal | Vec3 | World-space surface normal at the hit (use it for wall-jump or facing). |
| distance | number | Distance along the attempted movement when the hit occurred. |
Nested in: physics.CharacterMove
options 8 keys
| Key | Type | Default | Description |
|---|---|---|---|
| up | Vec2 | Vec3 | datumhue.math.vec3(0, 1, 0) | Floor-defining up direction; selects which contacts count as ground. 2D uses the XY components. |
| offset | number | physics.RelativeLength | {relative = 0.01} | Small gap kept between the character and surroundings for stability; must be > 0. |
| slide | boolean | true | Slide along blocking walls instead of stopping dead. |
| max_slope_climb_angle | number | math.pi / 4 | Steepest slope, in radians, the character will climb; steeper surfaces act as walls. |
| min_slope_slide_angle | number | math.pi / 4 | Slope angle, in radians, at/above which the character auto-slides down. |
| snap_to_ground | number | physics.RelativeLength | boolean | {relative = 0.2} | Distance to snap down onto ground after a move, keeping the character glued over dips; false disables. |
| autostep | physics.AutostepConfig | boolean | false | Step-climbing config, or false to disable; stepping is expensive. Needs a flat-bottomed body (cube or cylinder); a capsule's rounded bottom slides back off the ledge. The body also needs head room of its own height plus max_height above where it stands, so a low ceiling stops it stepping. |
| normal_nudge_factor | number | 0.0001 | Tiny anti-stick push along contact normals while sliding, 0 to 1. |
Used by: SceneNode:character_controller, DrawPrimitive:
options 2 keys
| Key | Type | Default | Description |
|---|---|---|---|
| layers | integer[] | every layer | Membership layer bit indices 0..=31. |
| collides_with | integer[] | every layer | Filter layer bit indices 0..=31; an empty list collides with nothing. |
Used by: SceneNode:set_collision_layers, DrawPrimitive:
record 3 keys
| Key | Type | Description |
|---|---|---|
| point | Vec3 | World-space contact point, where the bodies overlap deepest. |
| normal | Vec3 | World-space contact normal, pointing out of this body toward the other. |
| penetration | number | Penetration depth in world units (positive when overlapping). |
Used by: SceneNode:on_collision_start, DrawPrimitive:on_collision_start
| Value | Description |
|---|---|
"fixed" | |
"revolute" | |
"prismatic" | |
"distance" | |
"spherical" |
Nested in: physics.JointOptions
options 2 keys
| Key | Type | Default | Description |
|---|---|---|---|
| lock_translation | "x" | "y" | "z"[] | translation is unlocked | Axes to lock translation on; the 2D in-plane locks always remain. |
| lock_rotation | "x" | "y" | "z"[] | rotation is unlocked | Axes to lock rotation on; the 2D in-plane locks always remain. |
Used by: SceneNode:set_locked_axes, DrawPrimitive:set_locked_axes
options 2 keys
| Key | Type | Default | Description |
|---|---|---|---|
| layers | integer[] | every layer | Only include bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
Used by: datumhue.physics.point_query, PhysicsWorld:point_query
options 5 keys, 4 inherited
| Key | Type | Default | Description |
|---|---|---|---|
| max_hits | integer | 64 | Maximum hits to return, 0 or more. |
| From physics.RaycastOptions | |||
| max_distance | number | 1000000 | Maximum ray length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
| solid | boolean | true | Count a ray starting inside a collider as a hit at distance 0. |
Used by: datumhue.physics.raycast_all, PhysicsWorld:raycast_all
options 4 keys
| Key | Type | Default | Description |
|---|---|---|---|
| max_distance | number | 1000000 | Maximum ray length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |
| solid | boolean | true | Count a ray starting inside a collider as a hit at distance 0. |
Used by: datumhue.physics.raycast, PhysicsWorld:raycast
Extended by: physics.RaycastAllOptions
record 4 keys
| Key | Type | Description |
|---|---|---|
| body | DrawPrimitive | SceneNode | Voxel | The body that was hit. |
| point | Vec3 | World-space contact point. |
| normal | Vec3 | World-space surface normal at the hit. |
| distance | number | Distance from the origin to the hit. |
Used by: datumhue.physics.raycast, datumhue.physics.raycast_all, datumhue.physics.shapecast, PhysicsWorld:raycast, PhysicsWorld:raycast_all, PhysicsWorld:shapecast
options 1 key
| Key | Type | Default | Description |
|---|---|---|---|
| relative required | number | no default | Fraction of the character shape's relevant extent. The table's other keys are ignored. |
Used by: CharacterController.offset, CharacterController.
Nested in: physics.AutostepConfig, physics.CharacterControllerOptions
| Value | Description |
|---|---|
"rect" | |
"circle" | |
"capsule" | |
"convex_hull" | |
"polyline" | |
"cube" | |
"sphere" | |
"cylinder" | |
"cone" | |
"trimesh" |
Nested in: physics.BodyOptions, physics.ShapecastOptions
options 9 keys
| Key | Type | Default | Description |
|---|---|---|---|
| shape | physics.Shape | "cube" | 3D collider shape to cast. |
| width | number | 1 | Box width. |
| height | number | 1 | Box height / capsule length. |
| depth | number | 1 | Box depth. |
| radius | number | 0.5 | Sphere / capsule / cylinder / cone radius. |
| rotation | Quat | datumhue.math.quat.identity() | Shape orientation. |
| max_distance | number | 1000000 | Maximum cast length in world units, 0 or more; math.huge casts without a limit. |
| layers | integer[] | every layer | Only hit bodies in these layer bit indices 0..=31. |
| exclude | DrawPrimitive | SceneNode | Voxel | no body is ignored | A body to ignore. |