sm.physics
Contains functions regarding the physics engine.
Constants:
Functions:
sm.physics.filter table
Collision filter types
| dynamicBody |
| staticBody |
| character |
| areaTrigger |
| joints |
| terrainSurface |
| terrainAsset |
| harvestable |
| areaTrigger |
| static |
| default |
| all |
sm.physics.types table
Physics types are used to define an object's characteristics is in the physics world. Upon a raycast or collision detection, these types are used to find out what object was intersected.
| "invalid" | No object. |
| "terrainSurface" | The ground. |
| "terrainAsset" | Trees and boulders. |
| "lift" | A Lift. |
| "body" | A Body. |
| "character" | A Character. |
| "joint" | A Joint. |
| "harvestable" | A Harvestable. |
| "vision" | A collision area used by sensors. |
sm.physics.applyImpulse(target, impulse, worldSpace=false, offset=nil)
Applies an impulse to a Shape, changing its velocity immediately. The impulse is applied to the shape's centerpoint with an optional offset.
Parameters:
| Type | Name | Description |
|---|---|---|
| Shape | target | The object on which the impulse is exerted on. |
| Vec3 | impulse | The direction and strength of the impulse. |
| boolean | worldSpace=false | Whether the impulse is applied in world space coordinates. (Defaults to local rotation) |
| Vec3 | offset=nil | The offset from the center point. (Defaults to no offset) |
sm.physics.applyImpulse(target, impulse, worldSpace=false, offset=nil)
Applies an impulse to a Body, changing its velocity immediately. The impulse is applied to the body's center of mass with an optional offset.
Parameters:
| Type | Name | Description |
|---|---|---|
| Body | target | The object on which the impulse is exerted on. |
| Vec3 | impulse | The direction and strength of the impulse. |
| boolean | worldSpace=false | Whether the impulse is applied in world space coordinates. (Defaults to local rotation) |
| Vec3 | offset=nil | The offset from the center point. (Defaults to no offset) |
sm.physics.applyImpulse(target, impulse)
Applies an impulse to a Character, changing its velocity immediately. The impulse is applied to the character's centerpoint.
Parameters:
| Type | Name | Description |
|---|---|---|
| Character | target | The character on which the impulse is exerted on. |
| Vec3 | impulse | The direction and strength of the impulse. |
sm.physics.applyTorque(target, torque, worldSpace=false)
Applies a torque impulse to a Body, changing its angular velocity immediately. The torque is applied along the body's center of mass, making it rotate.
Parameters:
| Type | Name | Description |
|---|---|---|
| Body | target | The object on which the torque is exerted on. |
| Vec3 | torque | The direction and strength of the torque. |
| boolean | worldSpace=false | Whether the torque is applied in world space coordinates. (Defaults to local rotation) |
sm.physics.distanceRaycast(start, direction)
Performs a distance ray cast from a position with a given direction.
Note:
sm.physics.distanceRaycast is generally cheaper to use than sm.physics.raycast as it performs collision checks in a simplified world. If the raycast is only used for checking collision, it is advised to use this method instead.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | start | The start position. |
| Vec3 | direction | The ray's direction and length. |
Returns:
| Type | Description |
|---|---|
| boolean, number | 2 values: whether raycast was successful; the fraction (0–1) of the distance reached until collision divided by the ray's length. |
sm.physics.explode(position, level, destructionRadius, impulseRadius, magnitude, effectName=nil, ignoreShape=nil, parameters=nil)
Server only
Creates an explosion at given position. The explosion creates a shockwave that is capable of destroying blocks and pushing characters and creations away.
Shapes that are within the explosion's destruction radius may receive the event server_onExplosionHit.
Note:
The destruction level is the damage effect on blocks and parts, determining how likely it is that they are destroyed. This is related to the `qualityLevel` found in parts json-files.
Any quality level equal to or less than the destruction level may be destroyed. The effect fades one level every half travelled of the remaining destruction radius.
A quality level of 0 means a block or part is indestructible.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | position | The center point of the explosion. |
| integer | level | The destruction level affecting nearby objects. |
| number | destructionRadius | The destruction radius. Objects inside this sphere may be destroyed. |
| number | impulseRadius | The impulse radius. Objects inside this sphere are affected by an impulse. |
| number | magnitude | The impulse strength of the explosion. The strength diminishes with distance. |
| string | effectName=nil | The name of the effect to be played upon explosion. (Optional) |
| Shape | ignoreShape=nil | The shape to be ignored. (Optional) |
| table | parameters=nil | The table containing the parameters for the effect. (Optional) |
sm.physics.getGravity()
Server only
Returns the gravitational acceleration affecting shapes and bodies.
Returns:
| Type | Description |
|---|---|
| number | The gravitational value. |
sm.physics.getGroundMaterial(worldPosition)
Returns the material at the given position in the terrain.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | worldPosition | The world position to check the material at. |
Returns:
| Type | Description |
|---|---|
| string | The material name. |
sm.physics.getSphereContacts(pos, radius)
Server only
Returns a table of the game objects that are found inside the given sphere
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | pos | The world position of the sphere. |
| number | radius | The radius of the sphere. |
Returns:
| Type | Description |
|---|---|
| table | The table with tables of objects found inside the sphere. { bodies={Body, ..}, characters={Character, ..}, harvestables={Harvestable, ..}, lifts={Lift, ..} } |
sm.physics.multicast(casts)
Performs multiple sphere and/or raycasts given a table of parameters.
Type can be "sphere" or "ray". Radius is ignored for rays.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | casts | Table of casts. { type=string, startPoint=Vec3, endPoint=Vec3, radius=number, mask=sm.physics.filter } |
Returns:
| Type | Description |
|---|---|
| table | Array of pairs of boolean and RaycastResult. {{boolean, RaycastResult}, ..} |
sm.physics.raycast(start, end, body=nil, mask=nil)
Performs a ray cast between two positions.
The returned RaycastResult contains information about any object intersected by the ray.
If the ray cast is called from within a shape (e.g. a Sensor), a Body may be provided which the ray will not intersect.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | start | The start position. |
| Vec3 | end | The end position. |
| Body | body=nil | The body to be ignored. (Optional) |
| integer | mask=nil | The collision mask. Defaults to sm.physics.filter.default (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |
sm.physics.raycastTarget(start, end, body)
Performs a ray cast between two positions to find a specific target.
a Body must be provided as a target.
The returned RaycastResult contains information about any object intersected by the ray.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | start | The start position. |
| Vec3 | end | The end position. |
| Body | body | The body to be exclusively checked. |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |
sm.physics.setGravity(gravity)
Server only
Sets the gravitational acceleration affecting shapes and bodies.
Parameters:
| Type | Name | Description |
|---|---|---|
| number | gravity | The gravitational value. |
sm.physics.sphereContactCount(worldPosition, radius, includeTerrain=false, countWater=false)
Returns the number of collision objects that are found inside the given sphere
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | worldPosition | The world position of the sphere. |
| number | radius | The radius of the sphere. |
| boolean | includeTerrain=false | True if terrain should be included in the test |
| boolean | countWater=false | True if water should be included |
Returns:
| Type | Description |
|---|---|
| integer | The number of objects. |
sm.physics.spherecast(start, end, radius, body=nil, mask=nil)
Performs a spherical ray cast between two positions.
The returned RaycastResult contains information about any object intersected by the ray.
If the ray cast is called from within a shape (e.g. a Sensor), a Body may be provided which the ray will not intersect.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | start | The start position. |
| Vec3 | end | The end position. |
| number | radius | The radius of the sphere. |
| Body | body=nil | The body to be ignored. (Optional) |
| integer | mask=nil | The collision mask. Defaults to sm.physics.filter.default (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |