docs/api/physics

@usbx/physics

Explosions, constraints, collision groups

local physics = require("@usbx/physics")

groupsfunction collidesfunction set_collidesfunction explodefunction constrainfunction

physics.groups

function#

The names of the Collision Groups of the place.

physics.groups() -> { string }

example

for _, group in physics.groups() do print(group) end

Use it forreading the Collision Group names you set up in Studio.

physics.collides

function#

Whether parts of the two Collision Groups collide.

physics.collides(a: string, b: string) -> boolean

example

if physics.collides("Ghosts", "Walls") then print("ghosts are blocked") end

Use it forchecking whether two groups, like ghosts and walls, bump into each other or pass through right now.

aA Collision Group.

bAnother Collision Group.

physics.set_collides

function#

Lets parts of the two Collision Groups collide or not. Players keep their own row of the matrix.

physics.set_collides(a: string, b: string, collide: boolean) -> ()

example

physics.set_collides("Ghosts", "Walls", false)

Use it forletting ghosts pass through walls, or making a wall solid again once a round starts.

aA Collision Group.

bAnother Collision Group.

collideTrue lets their parts collide, false lets them pass through.

physics.explode

function#

Pushes Dynamic Parts and players away from a point, and damages the players. Force, damage and the push fall off to 0 at the radius.

physics.explode(options: { … }) -> ()

example

physics.explode({ position = door.position, radius = 10, force = 500, damage = 30 })

Use it forblowing up a bomb or rocket, which pushes nearby players and loose parts away and can hurt players.

optionsWhere the blast is, how far it reaches and how hard it pushes.

Build a explode callposition · radius · force · damage · players · effect

positionrequired
Where the middle of the blast is in the world.
xyz
radiusrequired
How far the blast reaches in studs, though the explosion players see is at most 80 studs.
forcerequired
How hard the blast pushes things at its middle.
damagedefault 0
How much damage players take at the middle of the blast.
players
Whether the blast pushes and damages players, which it does by default.
effect
Whether players see an explosion, which they do by default.

physics.constrain

function#

Links two parts or models with a Constraint and returns it. Without anchor_b or face_b, anchor B goes where anchor A is now, except for a rope or a spring, which keeps it at the centre of b.

physics.constrain(options: { … }) -> Constraint

example

local hinge = physics.constrain({ type = "hinge", a = door, b = frame, face_a = "left" })

Use it forhanging a door on a hinge, or tying a swing to a beam with a rope.

optionsThe type of joint, the two parts and its settings.

Build a constrain calltype · a · b · name · visible · anchor_a · 15 more

typerequired
What kind of joint the constraint makes between the two parts.
arequired
The first part or model the constraint joins.
brequired
The second part or model the constraint joins, which must not be the same as a.
name
The Script Name to give the constraint.
visible
Whether players can see the constraint, which they can by default.
anchor_a
Where the constraint holds a, given as a point in the space of a.
xyz
anchor_b
Where the constraint holds b, in the space of b, which by default is where anchor A is now, or the centre of b for a rope or spring.
xyz
face_a
The face of a that anchor A is placed on.
face_b
The face of b that anchor B is placed on.
offset_a
How far to move anchor A from the centre of face_a.
xyz
offset_b
How far to move anchor B from the centre of face_b.
xyz
axis
The axis a hinge turns on or a slider moves along, which points straight out of face_a by default.
xyz
limits_enabled
Whether lower_limit and upper_limit are used to hold it in range.
lower_limit
The lowest angle or position allowed, which must not be above upper_limit.
upper_limit
The highest angle or position allowed, which for a ball socket is the angle of its cone.
motor_enabled
Whether a motor drives it, turning a hinge or sliding a slider.
motor_speed
How fast the motor turns or slides it.
motor_max_force
The most force the motor is allowed to use.
length
How long a rope or spring is, which is the distance between the anchors by default.
stiffness
How hard a spring pulls, so a higher number makes it stiffer.
damping
How quickly a spring settles, so a higher number calms it down faster.