Skip to main content

sm.physics​

Contains functions regarding the physics engine.

Constants

Functions​

applyImpulse​

sm.physics.applyImpulse( target, impulse, worldSpace, offset )

Applies an impulse to an object, changing its velocity immediately.
The impulse is applied to the object's center point with an optional offset.

Arguments:
  • target [ Shape /body/character ]: The target that the impulse is applied to.
  • impulse [ Vec3 ]: The direction and strength of the impulse.
  • worldSpace [ bool ]: Whether the impulse is applied in world space (global) coordinates. Defaults to local.
  • offset [ Vec3 ]: The offset from the center point. Defaults to none.

applyTorque​

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.

Arguments:
  • target [ Body ]: The body that the torque is applied to.
  • torque [ Vec3 ]: The direction and strength of the torque.
  • worldSpace [ bool ]: Whether the torque is applied in world space (global) coordinates. Defaults to local.

distanceRaycast​

sm.physics.distanceRaycast( start, direction )

Performs a distance ray cast from a position in a given direction.

Arguments:
  • start [ Vec3 ]: The start position.
  • direction [ Vec3 ]: The ray's direction and length.
Returns:
  • [ bool ]: Whether the raycast was successful or not.
  • [ number ]: The fraction (0.0 - 1.0) of the distance reached until collision.

explode​

sm.physics.explode( position, level, destructionRadius, impulseRadius, magnitude, effectName, ignoreShape, parameters )
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_onExplosion.

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.

Arguments:
  • position [ Vec3 ]: The center point of the explosion.
  • level [ int ]: The destruction level affecting nearby objects.
  • destructionRadius [ number ]: The destruction radius. Objects inside this sphere may be destroyed.
  • impulseRadius [ number ]: The impulse radius. Objects inside this sphere are affected by an impulse.
  • magnitude [ number ]: The impulse strength of the explosion. The strength diminishes with distance.
  • effectName [ string ]: The name of the effect to be played upon explosion. Optional.
  • ignoreShape [ Shape ]: The shape to be ignored. Optional.
  • parameters [ table ]: A table containing parameters for the effect. Optional.

getGravity​

sm.physics.getGravity()
Server-Only

Returns the gravitational acceleration affecting shapes and bodies.

Returns:
  • [ number ]: The gravitational value.

getGroundMaterial​

sm.physics.getGroundMaterial( position )

Returns the terrain material at the given position.

Arguments:
  • position [ Vec3 ]: The position.
Returns:
  • [ string ]: The terrain material at the position.

getSphereContacts​

sm.physics.getSphereContacts( position, radius )
Server-Only

Returns a table of the objects that were found inside the given sphere.

Arguments:
  • position [ Vec3 ]: The position of the sphere.
  • radius [ number ]: The radius of the sphere.
Returns:
  • [ table ]: A table containing tables of objects found inside the sphere. See structure below.
Table Structure
{
	bodies = {
		Body1,
		Body2,
		...
	},
	characters = {
		Character1,
		Character2,
		...
	},
	harvestables = {
		Harvestable1,
		Harvestable2,
		...
	},
	lifts = {
		Lift1,
		Lift2,
		...
	}
}

multicast​

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.

Arguments:
  • casts [ table ]: The table of casts to perform. See 'casts' table structure below.
Returns:
  • [ table ]: An array of tables containing bool and raycastResult for each cast.
'casts' Table Structure
{
	{
		type = "ray",					--The cast type.
		startPoint = vec3,				--The start point.
		endPoint = vec3,				--The end point.
		mask = sm.physics.filter.all	--The cast filter.
	},
	{
		type = "sphere",				--The cast type.
		startPoint = vec3,				--The start point.
		endPoint = vec3,				--The end point.
		radius = 5,						--The sphere radius.
		mask = sm.physics.filter.all	--The cast filter.
	},
	...									--etc.
}
Returned Table Structure
{
	{
		true,			--Whether the cast is valid or not.
		raycastResult	--The cast result data.
	},
	{
		true,			--Whether the cast is valid or not.
		raycastResult	--The cast result data.
	},
	...					--etc.
}

raycast​

sm.physics.raycast( startPos, endPos, body, mask )

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.

Arguments:
  • startPos [ Vec3 ]: The start position.
  • endPos [ Vec3 ]: The end position.
  • body [ Body ]: The body to ignore. Defaults to none.
  • mask [ int ]: The collision mask. Defaults to sm.physics.filter.default.
Returns:
  • [ bool ]: Whether the raycast is valid or not.
  • [ RaycastResult ]: The raycast result data.

raycastTarget​

sm.physics.raycastTarget( startPos, endPos, body )

Performs a ray cast between two positions to find a specific target.

A target Body must be provided.

The returned RaycastResult contains information about any object intersected by the ray.

Arguments:
  • startPos [ Vec3 ]: The start position.
  • endPos [ Vec3 ]: The end position.
  • body [ Body ]: The body be exclusively checked.
Returns:
  • [ bool ]: Whether the raycast is valid or not.
  • [ RaycastResult ]: The raycast result data.

setGravity​

sm.physics.setGravity( gravity )
Server-Only

Sets the gravitational acceleration affecting shapes and bodies.

Arguments:
  • gravity [ number ]: The gravitational value.

sphereContactCount​

sm.physics.sphereContactCount( worldPosition, radius, includeTerrain, countWater )

Returns the number of collision objects that were found inside the given sphere.

Arguments:
  • worldPosition [ Vec3 ]: The sphere position.
  • radius [ number ]: The sphere radius.
  • includeTerrain [ bool ]: Whether terrain should be included in the test. Defaults to false.
  • countWater [ bool ]: Whether water should be included in the test. Defaults to false.
Returns:
  • [ number ]: The number of objects.

spherecast​

sm.physics.spherecast( startPos, endPos, radius, body, mask )

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.

Arguments:
  • startPos [ Vec3 ]: The start position.
  • endPos [ Vec3 ]: The end position.
  • radius [ number ]: The radius of the sphere.
  • body [ Body ]: The body to ignore. Defaults to none.
  • mask [ int ]: The collision mask. Defaults to sm.physics.filter.default.
Returns:
  • [ bool ]: Whether the raycast is valid or not.
  • [ RaycastResult ]: The raycast result data.