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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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, raycastType, filterLayers)

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

  • raycastType (RaycastType) – type of raycast

  • filterLayers (list[str] or nil) – Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns:

Returns a promise of the raycast result. The raycast result is a table of raycast results if raycast type is Physics.RaycastType.AllHits. If nothing was hit, the result has the hit field set to false or is an empty table, depending on the raycast type.

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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,
    {"Terrain"}
):next(function(hits)
    Console.log(Tools.dump(hits))

    -- Example output for raycastType Physics.RaycastType.Closest: {
    --    ["hit"] = true,
    --    ["point"] = { ["x"] = 0, ["y"] = 3, ["z"] = 0 },
    --    ["normal"] = { ["x"] = 0, ["y"] = 1, ["z"] = 0 },
    --    ["object"] = 218deb9bc439
    -- }

    -- Example output for non-hit of Physics.RaycastType.Closest: {
    --    ["hit"] = false,
    -- }

    -- Example output for raycastType Physics.RaycastType.AllHits: {
    --    [1] = {
    --        ["hit"] = true,
    --        ["point"] = { ["x"] = 0, ["y"] = 3, ["z"] = 0 },
    --        ["normal"] = { ["x"] = 0, ["y"] = 1, ["z"] = 0 },
    --        ["object"] = 218deb9bc439
    --    },
    -- }

    -- Example output for non-hit of Physics.RaycastType.AllHits: {}
end)
physics.raycastMany(startVectors, endVectors, raycastType, filterLayers)

Do many raycasts to test for any objects along a ray. The usage is similar to a single raycast, but the vectors are now arrays. The size of the vectors has to match

Parameters:

  • startVectors (list[Vector3]) – An array of start vectors

  • endVectors (list[Vector3]) – An array of end vectors

  • raycastType (RaycastType) – type of raycast

  • filterLayers (list[str] or nil) – Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns:

Returns a promise of a table of raycast results. If the raycast type is Physics.RaycastType.AllHits, the result is a table of tables of raycast results. A raycast result for a ray that didnt hit, is an object with the hit field set to false or is an empty table, depending on the raycast type.

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
local Physics = require 'engine/physics'
local Console = require 'engine/console'
local Tools = require 'engine/tools'
Physics.raycastMany(
    {
        Vector3.new(0, 0, 0),
        Vector3.new(1, 0, 0)
    },
    {
        Vector3.new(0, 3, 0),
        Vector3.new(1, 3, 0)
    },
    Physics.RaycastType.Closest,
    {"Terrain"}
):next(function(hits)
    Console.log(Tools.dump(hits))

    -- Example output for raycastType Physics.RaycastType.Closest:
    -- {
    --    [1] = {
    --        ["hit"] = true,
    --        ["point"] = { ["x"] = 0, ["y"] = 3, ["z"] = 0 },
    --        ["normal"] = { ["x"] = 0, ["y"] = 1, ["z"] = 0 },
    --        ["object"] = 218deb9bc439
    --    } ,
    --    [2] = {
    --        ["hit"] = false,
    --    },
    -- }

    -- Example output for raycastType Physics.RaycastType.AllHits:
    -- {
    --     [1] = {
    --         [1] = {
    --             ["hit"] = true,
    --             ["point"] = { ["x"] = 0, ["y"] = 3, ["z"] = 0 },
    --             ["normal"] = { ["x"] = 0, ["y"] = 1, ["z"] = 0 },
    --             ["object"] = 218deb9bc439
    --         }
    --     },
    --     [2] = {}
    -- }
end)
physics.convexSweepTest(startVector, endVector, shape, filterLayers)

Do a convex sweep test to check if anything intersects the trajectory of a shape.

Parameters:

  • startVector (Vector3) – a start vector to start the test from

  • endVector (Vector3) – an end vector for the test

  • shape (table) – shape for the test. Use one of the shape functions in this module to create a shape

  • filterLayers (list[str] or nil) – Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns:

Returns a promise of the sweep test result. If nothing was hit, the result is nil.

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
local Physics = require 'engine/physics'
local Console = require 'engine/console'
local Tools = require 'engine/tools'
Physics.convexSweepTest(
    Vector3.new(0, 0, 0),
    Vector3.new(1, 0, 0),
    Physics.sphereShape(1.0),
    {"Terrain"}
):next(function(hit)
    Console.log(Tools.dump(hit))

    -- Example output:
    -- {
    --     ["point"] = { ["x"] = 0.5, ["y"] = 0, ["z"] = 0 },
    --     ["normal"] = { ["x"] = 1, ["y"] = 0, ["z"] = 0 },
    --     ["object"] = 218deb9bc439
    -- }
end)
physics.convexSweepTestMany(startVectors, endVectors, shape, filterLayers)

Do many convex sweep tests to check if anything intersects the trajectory of a shape. The usage is similar to a single sweep, but the vectors are now arrays.

Parameters:

  • startVectors (list[Vector3]) – An array of start vectors

  • endVectors (list[Vector3]) – An array of end vectors

  • shape (table) – shape for the test. Use one of the shape functions in this module to create a shape

  • filterLayers (list[str] or nil) – Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns:

Returns a promise of a table of sweep test results. If a ray didnt hit, the result for that table entry is nil.

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
local Physics = require 'engine/physics'
local Console = require 'engine/console'
local Tools = require 'engine/tools'
Physics.convexSweepTestMany(
    {
        { startVec = Vector3.new(0, 0, 0), endVec = Vector3.new(1, 0, 0) },
        { startVec = Vector3.new(1, 0, 0), endVec = Vector3.new(2, 0, 0) }
    },
    Physics.sphereShape(1.0),
    {"Terrain"}
):next(function(hits)
    Console.log(Tools.dump(hits))

    -- Example output for a convex sweep test result:
    -- {
    --     [1] = {
    --         ["point"] = { ["x"] = 0.5, ["y"] = 0, ["z"] = 0 },
    --         ["normal"] = { ["x"] = 1, ["y"] = 0, ["z"] = 0 },
    --         ["object"] = 218deb9bc439
    --     },
    --     [2] = {
    --         ["point"] = { ["x"] = 1.5, ["y"] = 0, ["z"] = 0 },
    --         ["normal"] = { ["x"] = 1, ["y"] = 0, ["z"] = 0 },
    --         ["object"] = 218deb9bc440
    --     }
    -- }
end)
physics.sphereShape(radius)

Create a sphere shape object for the convex sweep test

Parameters:

radius (number) – Radius of the sphere. Default is 1

physics.pause()

Pause physics engine. No further simulation happens after calling this

physics.resume()

Resume physics engine again

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

Examples