physics.space.intersect_shape

Queries the physics world for all colliders overlapping a given shape at a position — useful for explosion radius or area-of-effect checks

Syntax

local results = physics.space.intersect_shape(
    shape,
    position,
    options = {}
)

Parameters

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

Returns

Type	Name	Description
`table`	results	Array of tables, each with a `collider` field

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 an empty table
`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
`int`	max_results	`32`	Shared	Maximum number of colliders returned
`number`	margin	`0.04`	Shared	Extra collision margin applied to the shape
`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

Query colliders in a radius

local nearby = physics.space.intersect_shape(
    { type = "sphere", radius = 5 },
    explosion_position
)

for i, hit in ipairs(nearby) do
    core.engine.print("info", hit.collider)
end