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 |
| allTerrain |
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?, offset?)
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? | Whether the impulse is applied in world space coordinates. (Defaults to local rotation) |
| Vec3 | offset? | The offset from the center point. (Defaults to no offset) |
sm.physics.applyImpulse(target, impulse, worldSpace?, offset?)
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? | Whether the impulse is applied in world space coordinates. (Defaults to local rotation) |
| Vec3 | offset? | 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?)
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? | Whether the torque is applied in world space coordinates. (Defaults to local rotation) |
sm.physics.capsuleContactCount(from, to, radius, mask?)
Returns the number of collision objects that are found inside a given capsule.
The capsule is formed by connecting two spheres.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | from | The world position of the first sphere. |
| Vec3 | to | The world position of the second sphere. |
| number | radius | The radius of the spheres. |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default (Optional) |
Returns:
| Type | Description |
|---|---|
| integer | The number of objects. |
sm.physics.capsuleHasContact(from, to, radius, mask?)
Returns true if any collision object is found inside a given capsule.
Faster than capsuleContactCount when only checking for existence.
The capsule is formed by connecting two spheres.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | from | The world position of the first sphere. |
| Vec3 | to | The world position of the second sphere. |
| number | radius | The radius of the spheres. |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean | True if any contact was found. |
sm.physics.capsulecast(start, end, radius, height, ignore?, mask?, world?, ignoreUuids?)
Performs a capsule ray cast (Z-axis aligned) 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 capsule. |
| number | height | The height of the cylindrical part of the capsule. |
| Body|Shape|Harvestable|Character|AreaTrigger | ignore? | An object to be ignored. (Optional) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default (Optional) |
| World | world? | The world to perform the cast in. (Optional) |
| table | ignoreUuids? | A table of uuids {Uuid, ...} of Shape, Harvestable or Character type to be ignored. (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |
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?, ignoreShape?, parameters?, world?, damage?, source?, type?)
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? | The name of the effect to be played upon explosion. (Optional) |
| Shape | ignoreShape? | The shape to be ignored. (Optional) |
| table | parameters? | The table containing the parameters for the effect. (Optional) |
| World | world? | The world to cause the explosion in. (Optional) |
| integer | damage? | The damage of the explosion. Defaults to 2 * destruction level (Optional) |
| userdata | source? | The source of the explosion. Defaults to none (Optional) |
| Uuid | type? | The explosionType. Defaults to nil uuid (Optional) |
sm.physics.getBoxContacts(pos, rotation, halfExtents, world, mask?)
Returns a table of the game objects that are found inside the given box
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | pos | The world position of the box center. |
| Quat | rotation | The rotation of the box. |
| Vec3 | halfExtents | The half extents of the box. |
| World | world | The world to search in. (optional) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.static and sm.physics.filter.dynamicBody and sm.physics.filter.character (Optional) |
Returns:
| Type | Description |
|---|---|
| table | The table with tables of objects found inside the box. { bodies={Body, ..}, characters={Character, ..}, harvestables={Harvestable, ..}, lifts={Lift, ..} } |
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.getMaterialId(materialName)
Returns the material id from name
Parameters:
| Type | Name | Description |
|---|---|---|
| string | materialName | Material name. |
Returns:
| Type | Description |
|---|---|
| integer | The id of the material. |
sm.physics.getShapeContactsInBox(position, rotation, halfExtents, world)
Returns a table of all shapes colliding with a given box.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | position | The center position of the box. |
| Quat | rotation | The rotation of the box. |
| Vec3 | halfExtents | The halved size of the box. |
| World | world | The world to search in. (optional) |
Returns:
| Type | Description |
|---|---|
| table | The table of found shapes. {{shape=Shape, contactWorldPosition=Vec3 }, ..} |
sm.physics.getShapeContactsInSphere(center, radius, world)
Returns a table of all shapes colliding with a given sphere.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | center | The center position of the sphere. |
| number | radius | The radius of the sphere. |
| World | world | The world to search in. (optional) |
Returns:
| Type | Description |
|---|---|
| table | The table of found shapes. {{shape=Shape, contactWorldPosition=Vec3 }, ..} |
sm.physics.getSphereContacts(pos, radius, world?, mask?)
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. |
| World | world? | The world to search in. Defaults to current world (Optional) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.static and sm.physics.filter.dynamicBody and sm.physics.filter.character (Optional) |
Returns:
| Type | Description |
|---|---|
| table | The table with tables of objects found inside the sphere. { bodies={Body, ..}, characters={Character, ..}, harvestables={Harvestable, ..}, lifts={Lift, ..} } |
sm.physics.isPointInLiquid(position, world?)
Returns whether a point is in a liquid or not.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | position | The world position to check. |
| World | world? | The world to check in. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the point is inside liquid or not |
sm.physics.isSphereHittingLiquid(position, world?, radius)
Returns whether a sphere is hitting a liquid or not.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | position | The world position to check. |
| World | world? | The world to check in. |
| number | radius | The radius of the sphere. |
Returns:
| Type | Description |
|---|---|
| boolean | Whether the sphere is hitting a liquid or not |
sm.physics.multicast(casts, world?)
Performs multiple sphere and/or raycasts given a table of parameters.
Type can be "sphere" or "ray". Radius is ignored for rays.
ignoreUuids option is a table of uuids {Uuid, ...} of Shape, Harvestable or Character type to be ignored.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | casts | Table of casts. { type=string, startPoint=Vec3, endPoint=Vec3, radius=number, mask=sm.physics.filter, ignoreUuids=table } |
| World | world? | The world to perform the cast in. (Optional) |
Returns:
| Type | Description |
|---|---|
| table | Array of pairs of boolean and RaycastResult. {{boolean, RaycastResult}, ..} |
sm.physics.raycast(start, end, body?, mask?, world?, ignoreUuids?)
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? | The body to be ignored. (Optional) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default (Optional) |
| World | world? | The world to perform the raycast in. (Optional) |
| table | ignoreUuids? | A table of uuids {Uuid, ...} of Shape, Harvestable or Character type to be ignored. (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |
sm.physics.raycastTarget(start, end, body, world?, ignoreUuids?)
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. |
| World | world? | The world to perform the raycast in. (Optional) |
| table | ignoreUuids? | A table of uuids {Uuid, ...} of Shape, Harvestable or Character type to be ignored. (Optional) |
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?, countWater?, mask?)
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? | True if terrain should be included in the test (Defaults to false) |
| boolean | countWater? | True if water should be included (Defaults to false) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default. Using this will override "includeTerrain" and "countWater". (Optional) |
Returns:
| Type | Description |
|---|---|
| integer | The number of objects. |
sm.physics.sphereHasContact(worldPosition, radius, includeTerrain?, countWater?, mask?)
Returns true if any collision object is found inside the given sphere.
Faster than sphereContactCount when only checking for existence.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | worldPosition | The world position of the sphere. |
| number | radius | The radius of the sphere. |
| boolean | includeTerrain? | True if terrain should be included in the test (Defaults to false) |
| boolean | countWater? | True if water should be included (Defaults to false) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default. Using this will override "includeTerrain" and "countWater". (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean | True if any contact was found. |
sm.physics.spherecast(start, end, radius, ignore?, mask?, world?, ignoreUuids?)
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|Shape|Harvestable|Character|AreaTrigger | ignore? | An object to be ignored. (Optional) |
| integer | mask? | The collision mask. Defaults to sm.physics.filter.default (Optional) |
| World | world? | The world to perform the cast in. (Optional) |
| table | ignoreUuids? | A table of uuids {Uuid, ...} of Shape, Harvestable or Character type to be ignored. (Optional) |
Returns:
| Type | Description |
|---|---|
| boolean, RaycastResult | True if raycast was successful; The raycast result data. |