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.

It provides common physics functionalities such as configuring global gravity, managing rigid bodies and their properties, applying forces, impulses, and torques, and defining constraints between objects, including hinge, slider, and cone twist constraints. This allows developers to simulate a wide range of physical behaviors in 3D environments.

You can manipulate the environment's global gravity using the function Project.setGravity, which sets the gravity vector for the entire physics engine, affecting all physics-enabled objects.

In addition to global settings, object-specific physics properties can be controlled directly from the SceneObject class. This includes setting an object's position and rotation in the physics world, applying impulses or forces (both central and relative), and querying velocities. These functions give fine-grained control over how individual objects behave within the physics simulation.

Usage

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

local Physics = require 'engine/physics'

Reference

raycast

static 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 (string[]|nil): Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns

• Promise: 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.

Example

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)

raycastMany

static 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 (Vector3[]): An array of start vectors
• endVectors (Vector3[]): An array of end vectors
• raycastType (RaycastType): type of raycast
• filterLayers (string[]|nil): Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns

• Promise: 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.

Example

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)

convexSweepTest

static 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 (string[]|nil): Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns

• Promise: a promise of the sweep test result. If nothing was hit, the result is a table with hit = false.

Example

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)

convexSweepTestMany

static 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 (Vector3[]): An array of start vectors
• endVectors (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 (string[]|nil): Optional table of layer names to filter results. If not provided, no filtering is applied.

Returns

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

Example

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)

sphereShape

static sphereShape(radius)

Create a sphere shape object for the convex sweep test

Parameters

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

pause

static pause()

Pause physics engine. No further simulation happens after calling this

resume

static resume()

Resume physics engine again

Enum: RaycastType

Enumeration of all raycast types

Examples