Physics¶

The Physics Lua package is a module designed to manipulate physical interactions in a given environment, providing an intuitive API for handling these operations. It enables developers to simulate real-world physics in applications created with the Lua programming language. This package provides functionalities for controlling physical entities, their properties, and their interactions.

The Physics package allows manipulation of the environment’s global gravity vector, adds or removes rigid bodies, manages their physical properties, applies forces, impulses, and torques, and more. Additionally, it allows the definition of constraints between bodies, such as hinge, slider, and cone twist constraints, providing a rich toolset for physics simulation in 3D applications.

Reference¶

A module to handle physical actions in the environment

physics.addPointToPointConstraint(bodyId1, bodyId2, point1, point2, disableCollisions)¶

Adds a point-to-point constraint between two bodies

Parameters:¶

bodyId1 (number) – The id of the first body
bodyId2 (number) – The id of the second body
point1 (Vector3) – The point of the first body where the constraint is attached
point2 (Vector3) – The point of the second body where the constraint is attached
disableCollisions (boolean) – Whether to disable collisions between the two bodies

Returns:¶

The id of the constraint added

Return type:¶

number

Usage:

local physics = require 'engine/physics'
-- This example creates a chain of boxes linked by a pointTopoint constraint
local box1ID = addBody("Box1", 1) -- Ensure "Box1" is created
local box2ID = addBody("Box2", 1)  -- Ensure "Box2" is created
local box3ID = addBody("Box3", 1)  -- Ensure "Box3" is created
local box4ID = addBody("Box4", 1)  -- Ensure "Box4" is created
local box5ID = addBody("Box5", 1)  -- Ensure "Box5" is created
local pivot1 = Vector3.new(0, -0.5, 0)  -- For Box1 (bottom box)
local pivot2 = Vector3.new(0, 0.5, 0)  -- For Box2 (top box)
-- P2P Constraint
physics.addPointToPointConstraint(box1ID, box2ID, pivot1, pivot2, true)
physics.addPointToPointConstraint(box2ID, box3ID, pivot1, pivot2, true)
physics.addPointToPointConstraint(box3ID, box4ID, pivot1, pivot2, true)
physics.addPointToPointConstraint(box4ID, box5ID, pivot1, pivot2, true)

physics.addHingeConstraint(bodyId1, bodyId2, point1, point2, axis1, axis2, useReferenceFrameA, disableCollisions)¶

Adds a hinge constraint between two bodies

Parameters:¶

bodyId1 (number) – The id of the first body
bodyId2 (number) – The id of the second body
point1 (Vector3) – The point of the first body where the constraint is attached
point2 (Vector3) – The point of the second body where the constraint is attached
axis1 (Vector3) – The hinge axis of the first body
axis2 (Vector3) – The hinge axis of the second body
useReferenceFrameA (boolean) – Whether to use the reference frame of the first body
disableCollisions (boolean) – Whether to disable collisions between the two bodies

Returns:¶

The id of the constraint added

Return type:¶

number

physics.addSliderConstraint(bodyId1, bodyId2, frame1, frame2, useLinearReferenceFrameA, disableCollisions)¶

Adds a slider constraint between two bodies

Parameters:¶

bodyId1 (number) – Identifier of the first body to be constrained
bodyId2 (number) – Identifier of the second body to be constrained
frame1 (Transform) – Location and orientation on the first body where the constraint is attached
frame2 (Transform) – Location and orientation on the second body where the constraint is attached
useLinearReferenceFrameA (boolean) – Defines linear part of the constraint in the frame of first body if true
disableCollisions (boolean) – Allows the bodies to pass through each other if set to true

Returns:¶

The id of the newly added constraint

Return type:¶

number

physics.addConeTwistConstraint(bodyId1, bodyId2, frame1, frame2, disableCollisions)¶

Adds a cone twist constraint between two bodies

Parameters:¶

bodyId1 (number) – The id of the first body
bodyId2 (number) – The id of the second body
frame1 (Transform) – Location and orientation on the first body where the constraint is attached
frame2 (Transform) – Location and orientation on the second body where the constraint is attached
disableCollisions (boolean) – Whether to disable collisions between the two bodies

Returns:¶

The id of the constraint added

Return type:¶

number

physics.removeConstraint(id)¶

Removes a constraint from the physics simulation.

Parameters:¶: id (number) – The id of the constraint to be removed

physics.raycast(startVector, endVector, type, returnObjects)¶

Do a raycast to test for any objects along a ray

Parameters:¶

startVector (Vector3) – a start vector to start the ray from
endVector (Vector3) – an end vector for the ray
type (str) – type of raycast. See RaycastType enum
returnObjects (boolean) – return the hit objects, otherwise only point and normal is returned

Returns:¶

raycast result containing an array of hit points or a single hit point depending on type

Return type:¶

Promise

Usage:

local Physics = require 'engine/physics'
local Console = require 'engine/console'
local Tools = require 'engine/tools'
Physics.raycast(Vector3.new(0, 0, 0), Vector3.new(1, 0, 0), Physics.RaycastType.Closest, true):next(function(hits)
    Console.log(Tools.dump(hits))
end)

physics.raycastMany(startVectors, endVectors, type, returnObjects)¶

Do many raycasts to test for any objects along a ray. The usage is similar to a single raycast, but

the single parameter takes an array of raycast options

Parameters:¶

startVectors (array) – An array of start vectors
endVectors (array) – An array of end vectors
type (str) – type of raycast. See RaycastType enum
returnObjects (boolean) – return the hit objects, otherwise only point and normal is returned

Returns:¶

array An array of raycast results

Return type:¶

Promise

Usage:

local Physics = require 'engine/physics'
local Console = require 'engine/console'
local Tools = require 'engine/tools'
Physics.raycastMany({{ startVec=Vector3.new(0, 0, 0), endVec=Vector3.new(1, 0, 0) }}, Physics.RaycastType.Closest, true):next(function(hits)
    Console.log(Tools.dump(hits))
end)

class physics.RaycastType¶

Enumeration of all raycast types

Name	Description
Closest	Only the closest hit is returned
AllHits	All hits along the ray are returned

Physics¶

Reference¶

Examples¶