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.

Usage¶

To use this module, add the following require at the top of your script:

local Physics = require 'engine/physics'

Reference¶

A module to handle physical actions in the environment

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:

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:

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:

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:

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