Lua API Reference

• Introduction

Game environment

Classes

• CharacterClass
• GameClass
• HarvestableClass
• PlayerClass
• ScriptableObjectClass
• ShapeClass
• ToolClass
• UnitClass
• WorldClass

Object Types 'userdata'

• AiState
• AreaTrigger
• BlueprintVisualization
• Body
• BuilderGuide
• Character
• Color
• Container
• CullSphereGroup
• Effect
• GuiInterface
• Harvestable
• Interactable
• Joint
• Lift
• LoadCellHandle
• Network
• PathNode
• Player
• Portal
• Quat
• RaycastResult
• ScriptableObject
• Shape
• Storage
• Tool
• Unit
• Uuid
• Vec3
• Widget
• World

Static Function Namespaces

• GLOBAL
• sm
• sm.ai
• sm.areaTrigger
• sm.audio
• sm.body
• sm.builderGuide
• sm.camera
• sm.cell
• sm.challenge
• sm.character
• sm.color
• sm.construction
• sm.container
• sm.creation
• sm.cullSphereGroup
• sm.debris
• sm.debugDraw
• sm.effect
• sm.event
• sm.game
• sm.gui
• sm.gui.widget
• sm.harvestable
• sm.interactable
• sm.item
• sm.joint
• sm.json
• sm.localPlayer
• sm.log
• sm.melee
• sm.menuCreation
• sm.noise
• sm.particle
• sm.pathNode
• sm.pathfinder
• sm.physics
• sm.player
• sm.portal
• sm.projectile
• sm.quat
• sm.render
• sm.scriptableObject
• sm.shape
• sm.storage
• sm.tool
• sm.unit
• sm.util
• sm.uuid
• sm.vec3
• sm.visualization
• sm.world

Terrain environment

Classes

Object Types 'userdata'

• Color
• Harvestable
• Quat
• Uuid
• Vec3
• World

Static Function Namespaces

• GLOBAL
• sm
• sm.color
• sm.debugDraw
• sm.harvestable
• sm.json
• sm.log
• sm.noise
• sm.quat
• sm.terrainData
• sm.terrainGeneration
• sm.terrainTile
• sm.util
• sm.uuid
• sm.vec3

Joint

Associated namespace: sm.joint

A userdata object representing a joint in the game.

Values:

• angle
• angularVelocity
• appliedImpulse
• color
• id
• length
• localPosition
• localRotation
• reversed
• shapeA
• shapeB
• type
• uuid
• worldPosition
• xAxis
• yAxis
• zAxis

Functions:

• createBlock
• createPart
• getAngle
• getAngularVelocity
• getAppliedImpulse
• getBoundingBox
• getColor
• getId
• getLength
• getLocalPosition
• getLocalRotation
• getShapeA
• getShapeB
• getShapeUuid
• getSticky
• getType
• getWorldPosition
• getWorldRotation
• getXAxis
• getYAxis
• getZAxis
• isReversed
• setMotorVelocity
• setTargetAngle
• setTargetLength

Operations:

Operation	Description
Joint == Joint	Checks if two instances of Joint refer to the same Joint.

---

angle number

Get:

Returns the angle of a bearing.

---

angularVelocity number

Get:

Returns the angular velocity of a bearing.

The angular velocity can be set using setMotorVelocity or setTargetAngle.

---

appliedImpulse number

Get:

Returns the applied impulse of a bearing.

The applied impulse can be set using setMotorVelocity or setTargetAngle.

---

color Color

Get:

Returns the color of a joint.

---

id integer

Get:

Returns the id of a joint.

---

length number

Get:

Returns the current length of a piston. The length is measured in blocks.

---

localPosition Vec3

Get:

Returns the local position of a joint.

---

localRotation Quat

Get:

Returns the local rotation of a joint.

---

reversed boolean

Get:

Returns whether a bearing has been reversed using the Connect Tool. A reversed bearing rotates counterclockwise.

---

shapeA Shape

Get:

Returns the Shape a joint is attached to. This shape does always exist.

---

shapeB Shape

Get:

Returns the Shape that is attached to a joint on another Body. This method returns nil if there is no shape attached to the joint.

---

type string

Get:

Returns the joint type of a joint.

---

uuid Uuid

Get:

Returns the uuid string unique to a joint type.

---

worldPosition Vec3

Get:

Returns the world position of a joint.

---

xAxis Vec3

Get:

Returns the local x-axis vector of a joint.

---

yAxis Vec3

Get:

Returns the local y-axis vector of a joint.

---

zAxis Vec3

Get:

Returns the local z-axis vector of a joint.

---

createBlock(joint, uuid, size, position, forceCreate=true)

Server only

Create a block on joint.

Parameters:

Type	Name	Description
Joint	joint	The parent joint.
Uuid	uuid	The uuid of the shape.
Vec3	size	The shape's size.
Vec3	position	The shape's local position.
boolean	forceCreate=true	Set true to force create the shape.

---

createPart(joint, uuid, position, zAxis, xAxis, forceCreate=true)

Server only

Create a part on joint.

Parameters:

Type	Name	Description
Joint	joint	The parent joint.
Uuid	uuid	The uuid of the shape.
Vec3	position	The shape's local position.
Vec3	zAxis	The shape's local z direction.
Vec3	xAxis	The shape's local x direction.
boolean	forceCreate=true	Set true to force create the shape.

---

getAngle(bearing)

Returns the angle of a bearing.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.

Returns:

Type	Description
number	The bearing's angle. The angle ranges between `-math.pi` and `+math.pi`.

---

getAngularVelocity(bearing)

Returns the angular velocity of a bearing.

The angular velocity can be set using setMotorVelocity or setTargetAngle.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.

Returns:

Type	Description
number	The bearing's angular velocity.

---

getAppliedImpulse(bearing)

Returns the applied impulse of a bearing.

The applied impulse can be set using setMotorVelocity or setTargetAngle.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.

Returns:

Type	Description
number	The bearing's applied impulse.

---

getBoundingBox(joint)

Returns the bounding box of a joint – the dimensions that a joint occupies when building.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The size of the joint's bounding box.

---

getColor(joint)

Returns the color of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Color	The joint's color.

---

getId(joint)

Returns the id of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
integer	The joint's id.

---

getLength(piston)

Returns the current length of a piston. The length is measured in blocks.

Parameters:

Type	Name	Description
Joint	piston	The piston.

Returns:

Type	Description
number	The piston's current length in blocks.

---

getLocalPosition(joint)

Returns the local position of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The joint's local position.

---

getLocalRotation(joint)

Returns the local rotation of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Quat	The joint's local rotation.

---

getShapeA(joint)

Returns the Shape a joint is attached to. This shape does always exist.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Shape	The joint's first shape.

---

getShapeB(joint)

Returns the Shape that is attached to a joint on another Body. This method returns nil if there is no shape attached to the joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Shape	The joint's second shape.

---

getShapeUuid(joint)

Returns the uuid string unique to a joint type.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Uuid	The joint's uuid.

---

getSticky(joint)

Returns the sticky directions of the joint for positive xyz and negative xyz.

A value of 1 means that the direction is sticky and a value of 0 means that the direction is not sticky.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3,Vec3	The negative xyz sticky and the positive xyz sticky.

---

getType(joint)

Returns the joint type of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
string	One of the joint's type found in (sm.joint.types).

---

getWorldPosition(joint)

Returns the world position of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The joint's world position.

---

getWorldRotation(joint)

Returns the world rotation of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Quat	The joint's world rotation.

---

getXAxis(joint)

Returns the local x-axis vector of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The joint's x-axis.

---

getYAxis(joint)

Returns the local y-axis vector of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The joint's y-axis.

---

getZAxis(joint)

Returns the local z-axis vector of a joint.

Parameters:

Type	Name	Description
Joint	joint	The joint.

Returns:

Type	Description
Vec3	The joint's z-axis.

---

isReversed(bearing)

Returns whether a bearing has been reversed using the Connect Tool. A reversed bearing rotates counterclockwise.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.

Returns:

Type	Description
boolean	Whether the bearing is reversed (rotating counterclockwise).

---

setMotorVelocity(bearing, targetVelocity, maxImpulse)

Sets the motor velocity for a bearing. The bearing will try to maintain the target velocity with the given amount of impulse/strength.

In Scrap Mechanic, the Gas Engine increases both velocity and impulse with every gear. The Electric Engine increases velocity, but maintains the same impulse for every gear, making it sturdier.

This method cancels the effects of setTargetAngle.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.
number	targetVelocity	The target velocity.
number	maxImpulse	The max impulse.

---

setTargetAngle(bearing, targetAngle, targetVelocity, maxImpulse)

Sets the target angle for a bearing. The bearing will try to reach the target angle with the target velocity and the given amount of impulse/strength.

The target angle is set to range between `-math.pi` and `+math.pi`. The bearing will always try to rotate in the direction closest to the target angle.

This method cancels the effects of setMotorVelocity.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.
number	targetAngle	The target angle.
number	targetVelocity	The target velocity.
number	maxImpulse	The max impulse.

---

setTargetLength(bearing, targetLength, targetVelocity, maxImpulse=100000)

Server only

Sets the target length for a piston. The piston will try to reach the target length with the target velocity and the given amount of impulse/strength.

The target length is measured in blocks.

This method cancels the effects of setMotorVelocity.

Parameters:

Type	Name	Description
Joint	bearing	The bearing.
number	targetLength	The target length.
number	targetVelocity	The target velocity.
number	maxImpulse=100000	The max impulse. (Defaults to impulse used in game)