physics.space.cast_motion

Predicts how far a shape could travel along a motion vector before colliding, without actually moving anything

Syntax

local motion_result = physics.space.cast_motion(
    shape,
    position,
    motion,
    options = {}
)

Parameters

Type	Name	Description
`table`	shape	Shape descriptor table Refer Shape section
`vector3`	position	World-space starting position of the shape as `{x, y, z}`
`vector3`	motion	Motion vector to test as `{x, y, z}`
`table`	options	Optional query options table Refer Options section

Returns

Type	Name	Description
`table`	motion_result	Table with `safe` and `unsafe` fractions of the motion that can be traveled, or `false` if the query failed

Shape

Shapes are described by a table, only the fields of the chosen type are read.

Type	Key	Shape	Default	Description
`string`	type	All	-	Shape kind to build • `"box"` - uses `size` • `"sphere"` - uses `radius` • `"capsule"` - uses `radius` and `height` • `"cylinder"` - uses `radius` and `height` Required, an unknown type makes the query return `false`
`vector3`	size	`box`	`{1, 1, 1}`	Full extents of the box as `{x, y, z}`
`number`	radius	`sphere`, `capsule`, `cylinder`	• `sphere` - `0.5` • `capsule`, `cylinder` - `0.4`	Radius of the shape
`number`	height	`capsule`, `cylinder`	`1.8`	Total height of the shape

Options

All fields are optional and fall back to their defaults if not specified.

Type	Key	Default	Side	Description
`int`	mask	`4294967295`	Shared	Collision layers to test against, as a bitmask The default matches every layer
`table`	exclude	`{}`	Shared	Array of entities to ignore Only physics bodies and areas are accepted, any other value is skipped
`bool`	collide_bodies	`true`	Shared	• When `true` - physics bodies are tested • When `false` - physics bodies are ignored
`bool`	collide_areas	`false`	Shared	• When `true` - areas are tested • When `false` - areas are ignored
`int`	dimension	`0`	Shared	Dimension whose physics world is queried, from `0` to `65535` • Anything outside this range raises an error • A dimension with nothing in it simply finds nothing

Examples

Predict a capsule's movement

local motion_result = physics.space.cast_motion(
    { type = "capsule", radius = 0.4, height = 1.8 },
    position, {0, 0, -2}
)

core.engine.print("info", motion_result.safe)