Library

physics

table

Raycasts and physics-world queries against the live simulation: line-of-sight tests, volume checks, and distance queries.

Functions

#physics.are_parts_updated() → boolean

since 1.2.0-alpha

Returns whether the local physics simulation is currently active and tracking parts.

Aliasesarepartsupdated

#physics.raycast(origin: Vector3, direction: Vector3, distance: number, filterList: { BasePart }) → RaycastResult | nil

since 0.5.1-alpha

Casts a ray from origin in direction (normalized internally) up to distance studs. filterList is an array of Instances to exclude from the cast. Returns a result table with fields hit_successful (boolean), distance (number), position (Vector3), and instance (BasePart | nil), or nil if no physics simulation is active.

Parameters

origin	Vector3	Ray origin.
direction	Vector3	Ray direction.
distance	number	Maximum distance in studs.
filterList	{ BasePart }	Instances to exclude.

Errors

LuaError physics unavailable -- Raycast service is not initialised.
LuaError zero direction -- Direction vector collapsed to a zero vector.

#physics.is_part_tracked(part: BasePart) → boolean

since 0.7.0b-alpha

Returns whether part has an active physics object being tracked in the local simulation.

Aliasesisparttracked

Parameters

part

BasePart

The part to check.

#physics.can_part_be_tracked(part: BasePart) → boolean

since 0.7.0b-alpha

Returns whether part is eligible to be tracked in the physics simulation (i.e. has physics simulation enabled).

Aliasescanpartbetracked

Parameters

part

BasePart

The part to check.

#physics.get_part_pool(part: BasePart) → number

since 0.7.0b-alpha

Returns the physics pool ID of part's tracked physics object. Compare against PhysicsPool.Dynamic, PhysicsPool.Mixed, or PhysicsPool.Static. Errors if the part is not tracked.

Aliasesgetpartpool

Parameters

part

BasePart

The tracked part.

#physics.get_tracked_size(part: BasePart) → Vector3

since 0.7.0b-alpha

Returns the size of part as recorded in the local physics simulation. Errors if the part is not tracked.

Aliasesgettrackedsize

Parameters

part

BasePart

The tracked part.

#physics.get_tracked_cframe(part: BasePart) → CFrame

since 0.7.0b-alpha

Returns the CFrame of part as recorded in the local physics simulation. Errors if the part is not tracked.

Aliasesgettrackedcframe

Parameters

part

BasePart

The tracked part.

#physics.is_point_in_sphere_volume(point: Vector3, center: Vector3, radius: number) → boolean

since 1.2.0-alpha

Returns whether point lies within a sphere centered at center with the given radius.

Aliasesispointinspherevolume

Parameters

point	Vector3	Point to test.
center	Vector3	Sphere center.
radius	number	Sphere radius.

Errors

LuaError internal error -- Internal VM error during volume check.

#physics.is_point_in_box_volume(point: Vector3, cframe: CFrame, size: Vector3) → boolean

since 1.2.0-alpha

Returns whether point lies within an axis-aligned box defined by a cframe (center and orientation) and size (full extents as a Vector3).

Aliasesispointinboxvolume

Parameters

point	Vector3	Point to test.
cframe	CFrame	Box center and orientation.
size	Vector3	Full extents of the box.

#physics.is_point_in_part(point: Vector3, part: BasePart) → boolean

since 1.2.0-alpha

Returns whether point lies within the bounding box of part, using physics simulation data. Errors if the part data cannot be retrieved.

Aliasesispointinpart

Parameters

point	Vector3	Point to test.
part	BasePart	The part to test against.