Lua API Reference

• Introduction

Game environment

Classes

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

Object Types 'userdata'

• AiState
• AreaTrigger
• BlueprintVisualization
• Body
• BuilderGuide
• Character
• ClientScriptableObject
• Color
• Container
• CullSphereGroup
• Effect
• Garage
• GuiInterface
• Harvestable
• Interactable
• Joint
• JsonGui
• JsonWidget
• 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.clientScriptableObject
• sm.color
• sm.construction
• sm.container
• sm.creation
• sm.cullSphereGroup
• sm.debris
• sm.debugDraw
• sm.debugGui
• sm.effect
• sm.event
• sm.game
• sm.garage
• sm.gui
• sm.gui.widget
• sm.harvestable
• sm.interactable
• sm.item
• sm.joint
• sm.json
• sm.jsonGui
• sm.lift
• sm.localPlayer
• sm.log
• sm.melee
• sm.menuCreation
• sm.message
• sm.noise
• sm.particle
• sm.pathNode
• sm.pathfinder
• sm.physics
• sm.pipeGraph
• 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
• Container
• Harvestable
• Interactable
• Portal
• Quat
• ScriptableObject
• Uuid
• Vec3
• World

Static Function Namespaces

• GLOBAL
• sm
• sm.color
• sm.container
• sm.debugDraw
• sm.debugGui
• sm.interactable
• sm.json
• sm.log
• sm.noise
• sm.quat
• sm.scriptableObject
• sm.terrainData
• sm.terrainGeneration
• sm.terrainHarvestable
• sm.terrainTile
• sm.tunnelGenerator
• sm.util
• sm.uuid
• sm.vec3
• sm.voxelTerrainCell

AreaTrigger

Associated namespace: sm.areaTrigger

A userdata object representing an area trigger in the game.

Values:

• id
• world

Functions:

• bindCanErase
• bindCanInteract
• bindOnDestroy
• bindOnEnter
• bindOnErase
• bindOnExit
• bindOnHostDestroy
• bindOnHostUnload
• bindOnInteract
• bindOnMelee
• bindOnProjectile
• bindOnStay
• destroy
• getCharacters
• getContents
• getHarvestables
• getHostInteractable
• getId
• getShapes
• getSize
• getUserData
• getWorld
• getWorldMax
• getWorldMin
• getWorldPosition
• getWorldRotation
• hasVoxelTerrainContact
• setCharacterDetection
• setDestroyOnErase
• setEraseTime
• setHarvestableDetection
• setIncludeShapesInContent
• setShapeDetection
• setSize
• setVoxelDestructible
• setWaterType
• setWorldPosition
• setWorldRotation

Operations:

Operation	Return type	Description
AreaTrigger == AreaTrigger	boolean	Checks if two instances of AreaTrigger refer to the same AreaTrigger.

---

id integer

Get:

Returns the id of an area trigger.

---

world World

Get:

Returns the world id of the area trigger. Keep in mind that area triggers can move between worlds, so world id might change!

---

bindCanErase(areaTrigger, callback, object?)

Client only

Bind a callback that checks if the area trigger can be erased.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindCanInteract(areaTrigger, callback, object?)

Client only

Bind the lua function to be used when checking for player interaction with the area trigger

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnDestroy(areaTrigger, callback, object?)

Bind the lua function to be called when the area trigger is destroyed

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnEnter(areaTrigger, callback, object?)

Binds an area trigger's onEnter event to a custom callback. The onEnter event is triggered when an object enters the trigger area.

The callback receives:

• self (table) – The class instance.
• trigger (AreaTrigger) – The area trigger instance.
• results (table) – A table of characters and/or bodies and/or harvestables and/or lifts and/or areaTriggers.

function MyClass.onEnter( self, trigger, results ) ...

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnErase(areaTrigger, callback, object?)

Client only

Bind the lua function to be used when an interactable area trigger is erased.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnExit(areaTrigger, callback, object?)

Binds an area trigger's onExit event to a custom callback. The onExit event is triggered when an object leaves the trigger area.

The callback receives:

• self (table) – The class instance.
• trigger (AreaTrigger) – The area trigger instance.
• results (table) – A table of characters and/or bodies and/or harvestables and/or lifts and/or areaTriggers.

function MyClass.onExit( self, trigger, results ) ...

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnHostDestroy(areaTrigger, callback, object?)

Bind the lua function to be used when an area trigger is destroyed.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. ( optional )

---

bindOnHostUnload(areaTrigger, callback, object?)

Bind the lua function to be used when an interactable area trigger's host object is unloaded.

Note: Only the game host can know if a host object is unloaded, to a connected client it will look like the host object was destroyed.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. ( optional )

---

bindOnInteract(areaTrigger, callback, object?)

Client only

Bind the lua function to be used when a player interacts with an area trigger

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnMelee(areaTrigger, callback, object?)

Server only

Bind the lua function to be used when the area trigger is hit by a melee attack.

Requires that areaTriggerProxyType has been set to sm.areaTrigger.areaTriggerProxyType.melee

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnProjectile(areaTrigger, callback, object?)

Binds an area trigger's onProjectile event to a custom callback. The onProjectile event is triggered if a projectile collides with the trigger area

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

bindOnStay(areaTrigger, callback, object?)

Binds an area trigger's onStay event to a custom callback. The onStay event is triggered every tick as long as an object is staying inside of the trigger area.

The callback receives:

• self (table) – The class instance.
• trigger (AreaTrigger) – The area trigger instance.
• results (table) – A table of characters and/or bodies and/or harvestables and/or lifts and/or areaTriggers.

function MyClass.onStay( self, trigger, results ) ...

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
string	callback	The name of the Lua function to bind.
table	object?	The object that will receive the callback. (optional)

---

destroy(areaTrigger)

Destroys an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger to be destroyed.

---

getCharacters(areaTrigger)

Gets the trigger collisions for characters inside the area trigger

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
table	A table of character trigger collisions.

---

getContents(areaTrigger)

Gets the contents of the area trigger.

Returns a table of characters and/or bodies and/or harvestables and/or lifts and/or areaTriggers.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
table	The table with the content.

---

getHarvestables(areaTrigger)

Gets the trigger collisions for harvestables inside the area trigger

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
table	A table of harvestable trigger collisions.

---

getHostInteractable(areaTrigger)

Returns the attached host interactable.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Interactable	The area trigger's host interactable.

---

getId(areaTrigger)

Returns the id of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
integer	The area trigger's id.

---

getShapes(areaTrigger)

Gets the trigger collisions for shapes inside the area trigger

Will only return one Shape for each Body that is colliding with the AreaTrigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
table	A table of shape trigger collisions.

---

getSize(areaTrigger)

Returns the size of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Vec3	The area trigger's size.

---

getUserData(areaTrigger)

Returns the user data set on the area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
table	The user data set on this trigger

---

getWorld(areaTrigger)

Returns the world id of the area trigger. Keep in mind that area triggers can move between worlds, so world id might change!

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger user.

Returns:

Type	Description
World	The _current_ world id of the area trigger.

---

getWorldMax(areaTrigger)

Returns the world max corner position of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Vec3	The area trigger's max corner position.

---

getWorldMin(areaTrigger)

Returns the world min corner position of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Vec3	The area trigger's min corner position.

---

getWorldPosition(areaTrigger)

Returns the world position of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Vec3	The area trigger's world position.

---

getWorldRotation(areaTrigger)

Returns the world rotation of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
Quat	The area trigger's world rotation.

---

hasVoxelTerrainContact(areaTrigger)

Returns true if the AreaTrigger is in contact with destructable terrain.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.

Returns:

Type	Description
boolean	Destructable terrain contact.

---

setCharacterDetection(areaTrigger, detectCharacters)

When set to true the area trigger can calculate which characters are inside of the trigger and get the collision information.

with a call to AreaTrigger: getCharacters

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	detectCharacters	Character detection on or off.

---

setDestroyOnErase(areaTrigger, destroyOnErase)

Sets whether the areatrigger should be destroyed immediately upon being erased or simply invoke the bound OnErase callback. True by default.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	destroyOnErase	Destroy on erase.

---

setEraseTime(areaTrigger, eraseTime)

Sets the time it takes to erase this trigger if it is erasable.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
number	eraseTime	The time it takes to erase this area trigger.

---

setHarvestableDetection(areaTrigger, detectHarvestables)

When set to true the area trigger can calculate which harvestables are inside of the trigger and get the collision information.

with a call to AreaTrigger: getHarvestables

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	detectHarvestables	Harvestable detection on or off.

---

setIncludeShapesInContent(areaTrigger, includeShapesInContent)

When set to true the area trigger will include individual shapes in its content list.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	includeShapesInContent	Include shapes in content on or off.

---

setShapeDetection(areaTrigger, detectShapes)

Shape detection is off by default. When set to true the area trigger can calculate which shapes are inside of the trigger

with a call to AreaTrigger: getShapes

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	detectShapes	Shape detection on or off.

---

setSize(areaTrigger, size)

Sets the new size of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
Vec3	size	The area trigger's new size.

---

setVoxelDestructible(areaTrigger, destructible)

Sets whether VoxelTerrain can destroy this area trigger by voxel addition.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
boolean	destructible	The state to set

---

setWaterType(areaTrigger, waterType)

Sets the liquid type of the area trigger. (See sm.areaTrigger.liquidType)

Only has an effect on area triggers with the 'water' proxy type; setting it on any other proxy type has no effect.

Currently only 'lava' has special behavior: it occasionally destroys submerged shapes. Lava behavior requires

shapes to be included in the content list via AreaTrigger: setIncludeShapesInContent.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
integer	waterType	The liquid type. (See sm.areaTrigger.liquidType)

---

setWorldPosition(areaTrigger, position)

Sets the new world position of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
Vec3	position	The area trigger's new world position.

---

setWorldRotation(areaTrigger, rotation)

Sets the new world rotation of an area trigger.

Parameters:

Type	Name	Description
AreaTrigger	areaTrigger	The area trigger instance.
Quat	rotation	The area trigger's new world rotation.