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

Shape

Associated namespace: sm.shape

A userdata object representing a shape in the game.

Values:

• at
• body
• buildable
• buoyancy
• color
• connectable
• convertableToDynamic
• destructable
• erasable
• id
• interactable
• isBlock
• liftable
• localPosition
• localRotation
• mass
• material
• materialId
• paintable
• right
• stackedAmount
• stackedItem
• up
• usable
• uuid
• velocity
• worldPosition
• worldRotation
• xAxis
• yAxis
• zAxis

Functions:

• createJoint
• destroyBlock
• destroyPart
• destroyShape
• getAt
• getBody
• getBoundingBox
• getBuoyancy
• getClosestBlockLocalPosition
• getColor
• getId
• getInteractable
• getInterpolatedAt
• getInterpolatedRight
• getInterpolatedUp
• getInterpolatedWorldPosition
• getIsHarvest
• getIsStackable
• getJoints
• getLocalPosition
• getLocalRotation
• getMass
• getMaterial
• getMaterialId
• getNeighbours
• getPipedNeighbours
• getRight
• getShapeUuid
• getSticky
• getUp
• getVelocity
• getWorldPosition
• getWorldRotation
• getXAxis
• getYAxis
• getZAxis
• replaceShape
• setColor
• shapeExists
• shapesInSphere
• transformDirection
• transformLocalPoint
• transformPoint
• transformRotation

Operations:

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

---

at Vec3

Get:

Returns the direction of a shape's front side.

The direction is affected by the shape's rotation in the world.

---

body Body

Get:

Returns the Body a shape is part of.

---

buildable boolean

Get:

Check if a shape is buildable

---

buoyancy number

Get:

Returns the buoyancy multiplier of a shape.

---

color Color

Get:

Returns the color of a shape.

Set:

Server only

Sets the color of a shape. This is similar to coloring with the Paint Tool.

---

connectable boolean

Get:

Check if a shape is connectable

---

convertableToDynamic boolean

Get:

Check if a shape is convertible to dynamic form

---

destructable boolean

Get:

Check if a shape is destructable.

---

erasable boolean

Get:

Check if a shape is erasable.

---

id integer

Get:

Returns the id of a shape.

---

interactable Interactable

Get:

Returns the Interactable of a shape, if one exists. Otherwise the function will return nil.

---

isBlock boolean

Get:

Return true if a shape is a basicmaterial

---

liftable boolean

Get:

Check if a shape is liftable

---

localPosition Vec3

Get:

Returns the local grid postition of a shape.

---

localRotation Quat

Get:

Returns the local rotation of a shape.

---

mass number

Get:

Returns the mass of a shape.

---

material string

Get:

Returns the material of a shape.

---

materialId integer

Get:

Returns the material id of a shape.

---

paintable boolean

Get:

Check if a shape is paintable

---

right Vec3

Get:

Returns the direction of a shape's right side.

The direction is affected by the shape's rotation in the world.

---

stackedAmount integer

Get:

Return the amount that is stacked in the shape

Set:

Server only

Set the amount that is stacked in the shape

---

stackedItem Uuid

Get:

Return the item Uuid that is stacked in the shape

Set:

Server only

Set the item Uuid that is stacked in the shape

---

up Vec3

Get:

Returns the direction of a shape's top side.

The direction is affected by the shape's rotation in the world.

---

usable boolean

Get:

Check if a shape is interactable

---

uuid Uuid

Get:

Returns the uuid string unique to a shape/block type.

---

velocity Vec3

Get:

Returns the linear velocity of a shape.

---

worldPosition Vec3

Get:

Returns the world position of a shape.

---

worldRotation Quat

Get:

Returns the world rotation of a shape.

---

xAxis Vec3

Get:

Returns the local x-axis vector of a shape.

---

yAxis Vec3

Get:

Returns the local y-axis vector of a shape.

---

zAxis Vec3

Get:

Returns the local z-axis vector of a shape.

---

createJoint(shape, uuid, position, direction)

Server only

Create a new joint

Parameters:

Type	Name	Description
Shape	shape	The host shape.
Uuid	uuid	The uuid of the joint.
Vec3	position	The joint's grid position.
Vec3	direction	The joint's normal direction.

Returns:

Type	Description
Joint The created joint.

---

destroyBlock(shape, position, size=nil, attackLevel=0)

Server only

Destroy a block.

Parameters:

Type	Name	Description
Shape	shape	The block shape.
Vec3	position	The local position of the removal box corner.
Vec3	size=nil	The size of the removal box. Defaults to 1x1x1 (Optional)
integer	attackLevel=0	Determines which quality level of block the attack can destroy. Setting it to 0 (default) will destroy any block.

---

destroyPart(shape, attackLevel)

Server only

Destroy a part

Parameters:

Type	Name	Description
Shape	shape	The part.
integer	attackLevel	Determines which quality level of parts the attack can destroy. Setting it to 0 (default) will destroy any part.

---

destroyShape(shape, attackLevel)

Server only

Destroy a shape

Parameters:

Type	Name	Description
Shape	shape	The shape.
integer	attackLevel	Determines which quality level of shape the attack can destroy. Setting it to 0 (default) will destroy any shape.

---

getAt(shape)

Returns the direction of a shape's front side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's at-axis.

---

getBody(shape)

Returns the Body a shape is part of.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Body	The body which the shape is part of.

---

getBoundingBox(shape)

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

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

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

---

getBuoyancy(shape)

Returns the buoyancy multiplier of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
number	The buoyancy multiplier.

---

getClosestBlockLocalPosition(shape, position)

Transform a world position to the closest block's local position in a shape.

Parameters:

Type	Name	Description
Shape	shape	The block shape.
Vec3	position	The world position.

Returns:

Type	Description
Vec3	The closest position.

---

getColor(shape)

Returns the color of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Color	The shape's color.

---

getId(shape)

Returns the id of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
integer	The shape's id.

---

getInteractable(shape)

Returns the Interactable of a shape, if one exists. Otherwise the function will return nil.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Interactable	The interactable belonging to the shape.

---

getInterpolatedAt(shape)

Returns the interpolated direction of a shape's front side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's interpolated at-axis.

---

getInterpolatedRight(shape)

Returns the interpolated direction of a shape's right side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's interpolated right-axis.

---

getInterpolatedUp(shape)

Returns the interpolated direction of a shape's top side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's interpolated up-axis.

---

getInterpolatedWorldPosition(shape)

Returns the interpolated world position of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's interpolated world position.

---

getIsHarvest(The)

Return whether the shape uuid belongs to a harvest shape

Parameters:

Type	Name	Description
Uuid	The	shape uuid.

Returns:

Type	Description
boolean	True if the shape is harvestable.

---

getIsStackable(The)

Return whether the shape uuid belongs to a stackable shape

Parameters:

Type	Name	Description
Uuid	The	shape uuid.

Returns:

Type	Description
boolean	True if the shape is stackable.

---

getJoints(shape, onlyChildJoints=true, onlySubshapes=false)

Returns a table of all joints that are attached to the shape.

Will return all attached joints when onlyChildJoints is set to false.

Will only get the joints which are subshapes to the shape when onlySubshapes is set to true.

Parameters:

Type	Name	Description
Shape	shape	The shape.
boolean	onlyChildJoints=true	Filters what joints to return. Defaults to true (Optional)
boolean	onlySubshapes=false	Only get the joints which are subshapes to the shape. Defaults to false (Optional)

Returns:

Type	Description
table	The table of joints attached to the shape. {Joint, ..}

---

getLocalPosition(shape)

Returns the local grid postition of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's local position.

---

getLocalRotation(shape)

Returns the local rotation of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Quat	The shape's local rotation.

---

getMass(shape)

Returns the mass of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
number	The shape's mass.

---

getMaterial(shape)

Returns the material of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
string	The shape's material.

---

getMaterialId(shape)

Returns the material id of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
integer	The shape's material id.

---

getNeighbours(shape)

Server only

Returns a table of shapes which are neighbours to the shape

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
table	table of shapes. {Shape, ..}

---

getPipedNeighbours(shape)

Server only

Returns a table of shapes which are neighbours connected with pipes to the shape

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
table	table of shapes. {Shape, ..}

---

getRight(shape)

Returns the direction of a shape's right side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's right-axis.

---

getShapeUuid(shape)

Returns the uuid string unique to a shape/block type.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Uuid	The shape's uuid.

---

getSticky(shape)

Returns the sticky directions of the shape 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
Shape	shape	The shape.

Returns:

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

---

getUp(shape)

Returns the direction of a shape's top side.

The direction is affected by the shape's rotation in the world.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's up-axis.

---

getVelocity(shape)

Returns the linear velocity of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's linear velocity.

---

getWorldPosition(shape)

Returns the world position of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's world position.

---

getWorldRotation(shape)

Returns the world rotation of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Quat	The shape's world rotation.

---

getXAxis(shape)

Returns the local x-axis vector of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's x-axis.

---

getYAxis(shape)

Returns the local y-axis vector of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's y-axis.

---

getZAxis(shape)

Returns the local z-axis vector of a shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
Vec3	The shape's z-axis.

---

replaceShape(shape, uuid)

Server only

Creates a new Shape from Uuid to replace the given Shape.

Parameters:

Type	Name	Description
Shape	shape	The shape.
Uuid	uuid	The uuid of the new shape.

---

setColor(shape, color)

Server only

Sets the color of a shape. This is similar to coloring with the Paint Tool.

Parameters:

Type	Name	Description
Shape	shape	The shape.
Color	color	The color.

---

shapeExists(shape)

Return true if a shape exists.

Parameters:

Type	Name	Description
Shape	shape	The shape.

Returns:

Type	Description
boolean	Whether the shape exists.

---

shapesInSphere(center, radius)

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.

Returns:

Type	Description
table	The table of found shapes. {Shape, ..}

---

transformDirection(shape, vector)

Transform a world direction to the local shape transform.

Parameters:

Type	Name	Description
Shape	shape	The shape.
Vec3	vector	The untransformed direction.

Returns:

Type	Description
Vec3	The transformed direction.

---

transformLocalPoint(shape, vector)

Transform a local point to world space.

local worldPos = self.shape:transformLocalPoint( localPos )

Parameters:

Type	Name	Description
Shape	shape	The shape.
Vec3	vector	The local point.

Returns:

Type	Description
Vec3	The world point.

---

transformPoint(shape, vector)

Transform a world point to the local shape transform.

local localPos = self.shape:transformPoint( worldPos )

Parameters:

Type	Name	Description
Shape	shape	The shape.
Vec3	vector	The world point.

Returns:

Type	Description
Vec3	The local point.

---

transformRotation(shape, quat)

Transform a world rotation to the local shape transform.

local worldUp = sm.vec3.new( 0, 0, 1 )
local worldRot = sm.vec3.getRotation( worldUp, worldDir )
local localRot = self.shape:transformRotation( worldRot )

Parameters:

Type	Name	Description
Shape	shape	The shape.
Quat	quat	The untransformed quaternion.

Returns:

Type	Description
Quat	The transformed quaternion.