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

sm.gui

The gui library contains various utility functions for handling user interfaces.

This library can only be used on the client.

Constants:

• widgetStates

Functions:

bindDisplayMessageCallback

blockInGameMenu

chatMessage

computeTextSize

createAmmunitionContainerGui

createBagIconGui

createBatteryContainerGui

createBeaconIconGui

createChallengeHUDGui

createChallengeMessageGui

createCharacterCustomizationGui

createChemicalContainerGui

createCompassHudGui

createContainerGui

createCraftBotGui

createDressBotGui

createEngineGui

createFertilizerContainerGui

createGasContainerGui

createGlowstickContainerGui

createGuiFromLayout

createHideoutGui

createLogbookGui

createMechanicStationGui

createMininghubDispenserGui

createNameTagGui

createOreCrusherContainerGui

createPortableCrafterGui

createProspectorContainerGui

createQuestTrackerGui

createRefineryContainerGui

createSawbotGui

createSeatGui

createSeatUpgradeGui

createSeedContainerGui

createSteeringBearingGui

createSurvivalHudGui

createWaterContainerGui

createWaypointIconGui

createWidget

createWorkbenchGui

createWorldIconGui

displayAlertText

endFadeToBlack

exitToMenu

getCurrentLanguage

getItemIconFromUuid

getKeyBinding

getScreenSize

hasActiveGui

hideGui

hideHotbar

openGarageImportGui

setCenterIcon

setCharacterDebugText

setGarageButtonCallback

setGarageErrorCallback

setGarageImportGuiStorage

setInteractionText

setProgressFraction

startFadeToBlack

startFadeToBlackWaitForWorld

ticksToTimeString

translateLocalizationTags

---

sm.gui.widgetStates table

Widget states

disabled,

normal,

highlighted,

pushed,

disabled_checked,

normal_checked,

highlighted_checked,

pushed_checked

---

sm.gui.bindDisplayMessageCallback(callback)

Client only

Sets a target callback for generic notification popups

Parameters:

Type	Name	Description
string	callback	Function to be called when a alert message is called

---

sm.gui.blockInGameMenu(block)

Client only

Sets the blocking state for the in game menu.

Parameters:

Type	Name	Description
boolean	block	The new blocking state for the in game menu.

---

sm.gui.chatMessage(message)

Prints text in the chat gui.

Parameters:

Type	Name	Description
string	message	The message.

---

sm.gui.computeTextSize(text, font, align, maxWidth?, replaceTags?)

Client only

Calculates the 720 widget size required to display a text

Parameters:

Type	Name	Description
string	text	The text to compute.
string	font	The font to use.
string	align	The text alignment.
number	maxWidth?	The maximum desired widget width before wrapping (optional) (Defaults to -1)
boolean	replaceTags?	Should tags be replaced before calculating? (optional) (Defaults to true)

Returns:

Type	Description
{number, number}	The calculated width and height.

---

sm.gui.createAmmunitionContainerGui(destroyOnClose?)

Client only

Create a ammunition container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createBagIconGui(destroyOnClose?)

Client only

Create a bag icon GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createBatteryContainerGui(destroyOnClose?)

Client only

Create a battery container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createBeaconIconGui(destroyOnClose?)

Client only

Create a beacon icon GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createChallengeHUDGui(destroyOnClose?)

Client only

Create a challenge HUD GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createChallengeMessageGui(destroyOnClose?)

Client only

Create a challenge message HUD GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createCharacterCustomizationGui(destroyOnClose?)

Client only

Create a character customization GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createChemicalContainerGui(destroyOnClose?)

Client only

Create a chemical container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createCompassHudGui(destroyOnClose?)

Client only

Create a compass hud GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createContainerGui(destroyOnClose?)

Client only

Create a container GUI, for showing two containers.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createCraftBotGui(destroyOnClose?)

Client only

Create a craft bot GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createDressBotGui(destroyOnClose?)

Client only

Create a dress bot GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createEngineGui(destroyOnClose?)

Client only

Create a engine GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createFertilizerContainerGui(destroyOnClose?)

Client only

Create a fertilizer container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createGasContainerGui(destroyOnClose?)

Client only

Create a gas container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createGlowstickContainerGui(destroyOnClose?)

Client only

Create a glowstick container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createGuiFromLayout(layout, destroyOnClose?, settings?)

Client only

Create a GUI from a layout file.

Parameters:

Type	Name	Description
string	layout	Path to the layout file
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)
table	settings?	Table with bool settings for: isHud, isInteractive, needsCursor

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createHideoutGui(destroyOnClose?)

Client only

Create a hideout gui GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createLogbookGui(destroyOnClose?)

Client only

Create a log book GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createMechanicStationGui(destroyOnClose?)

Client only

Create a mechanic station dispenser GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createMininghubDispenserGui(destroyOnClose?)

Client only

Create a mining hub dispenser GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createNameTagGui(destroyOnClose?)

Client only

Create a name tag GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createOreCrusherContainerGui(destroyOnClose=false)

Client only

Create a ore crusher container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose=false	If true the gui is destroyed when closed, otherwise the gui can be reused.

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createPortableCrafterGui(destroyOnClose?)

Client only

Create a portable craftbot GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createProspectorContainerGui(destroyOnClose?)

Client only

Create a prospector container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createQuestTrackerGui(destroyOnClose?)

Client only

Create a quest tracker GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createRefineryContainerGui(destroyOnClose=false)

Client only

Create a refinery container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose=false	If true the gui is destroyed when closed, otherwise the gui can be reused.

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSawbotGui(destroyOnClose?)

Client only

Create a saw bot GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSeatGui(destroyOnClose?)

Client only

Create a seat GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSeatUpgradeGui(destroyOnClose?)

Client only

Create a seat upgrade GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSeedContainerGui(destroyOnClose?)

Client only

Create a seed container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSteeringBearingGui(destroyOnClose?)

Client only

Create a steering bearing upgrade GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createSurvivalHudGui(destroyOnClose?)

Client only

Create a survival hud GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createWaterContainerGui(destroyOnClose?)

Client only

Create a water container GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createWaypointIconGui(destroyOnClose?)

Client only

Create a waypoint icon GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createWidget()

Removed! Does nothing.

---

sm.gui.createWorkbenchGui(destroyOnClose?)

Client only

Create a workbench GUI.

Parameters:

Type	Name	Description
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.createWorldIconGui(width, height, layout?, destroyOnClose?)

Client only

Create a world icon GUI from a layout file.

Parameters:

Type	Name	Description
integer	width	The width.
integer	height	The height.
string	layout?	Path to the layout file (Defaults to "$GAME_DATA/Gui/Layouts/Hud/Hud_WorldIcon.layout")
boolean	destroyOnClose?	If true the gui is destroyed when closed, otherwise the gui can be reused. (Defaults to false)

Returns:

Type	Description
GuiInterface	The gui interface to the created gui.

---

sm.gui.displayAlertText(text, duration?, queued?)

Client only

Displays an alert message at the top of the screen for a set duration.

Parameters:

Type	Name	Description
string	text	The message to be displayed
number	duration?	The time in seconds during which the message is shown. Defaults to 4 seconds
boolean	queued?	If true the message is queued, otherwise it is displayed instantly. Defaults to false

---

sm.gui.endFadeToBlack(duration, force?)

Client only

Fades the screen back from a fade to black.

Parameters:

Type	Name	Description
number	duration	Animation duration
boolean	force?	If true, start the fade out from full black even if there was no fade to black active. (Defaults to false)

---

sm.gui.exitToMenu()

Client only

Exits the current game and returns to the main menu

---

sm.gui.getCurrentLanguage()

Client only

Returns the current users language setting.

Returns:

Type	Description
string	The language setting ex. "English".

---

sm.gui.getItemIconFromUuid(uuid)

Gets the item resource, group and name for an item icon from a uuid

Parameters:

Type	Name	Description
Uuid	uuid	The uuid.

Returns:

Type	Description
{string, string, string, string, string} The item resource, group, name, trackingType and shapeType.

---

sm.gui.getKeyBinding(action, hyper?)

Client only

Returns the set binding for an action as a string

Parameters:

Type	Name	Description
string	action	The action
boolean	hyper?	If the string should contain hyper text (Defaults to false)

Returns:

Type	Description
string	The key binding

---

sm.gui.getScreenSize()

Client only

Returns the size of the screen.

Returns:

Type	Description
integer,integer	The screen size as width and height.

---

sm.gui.hasActiveGui()

Client only

Returns whether the player has an active gui or not

Returns:

Type	Description
boolean	guiActive Whether the player has an active gui or not.

---

sm.gui.hideGui(visible)

Client only

Set gui visibility.

Parameters:

Type	Name	Description
boolean	visible	The gui visibility

---

sm.gui.hideHotbar(visible)

Client only

Set hotbar visibility.

Parameters:

Type	Name	Description
boolean	visible	The hotbar visibility

---

sm.gui.openGarageImportGui()

Client only

Open the garage creation import GUI

---

sm.gui.setCenterIcon()

Removed! Does nothing.

---

sm.gui.setCharacterDebugText(character, text, clear?)

Set a text for the character that will be displayed above its head. Only has effect in dev build.

Parameters:

Type	Name	Description
Character	character	The character.
string	text	The debug text.
boolean	clear?	If true the previous text will be overwritten. (Defaults to true)

---

sm.gui.setGarageButtonCallback(callback)

Client only

Sets a button callback to be called when the button is pressed.

Parameters:

Type	Name	Description
string	callback	Function to be called when button is pressed

---

sm.gui.setGarageErrorCallback(callback)

Client only

Sets a callback to be called when an error with the import is met.

Parameters:

Type	Name	Description
string	callback	Function to be called when error is met

---

sm.gui.setGarageImportGuiStorage(container)

Set the storage container for the garage creation import gui to use

Parameters:

Type	Name	Description
Container	container	The container import gui should use for materials.

---

sm.gui.setInteractionText(text1, binding1?, text2?, binding2?, text3?)

Client only

Set the binding text displayed at the center.

Parameters:

Type	Name	Description
string	text1	The leftmost segment.
string	binding1?	The left white segment.
string	text2?	The mid or end segment.
string	binding2?	The right white segment.
string	text3?	The rightmost segment.

---

sm.gui.setProgressFraction(progress)

Client only

Set the progress fraction filling the circle icon displayed at the center.

Parameters:

Type	Name	Description
number	progress	The fraction that determines how much of the circle is filled.

---

sm.gui.startFadeToBlack(duration, timeout)

Client only

Fades the screen to black and back after timeout.

Parameters:

Type	Name	Description
number	duration	Animation duration
number	timeout	Seconds until the fade fades back

---

sm.gui.startFadeToBlackWaitForWorld(duration, timeout)

Client only

Fades the screen to black, waits for the world to finish loading, then fades back.

First waits until timeout, then holds black until the world is ready or a max timeout is reached.

Parameters:

Type	Name	Description
number	duration	Animation duration
number	timeout	Seconds until the fade starts waiting for the world

---

sm.gui.ticksToTimeString(ticks)

Client only

Converts ticks to a HH:MM:SS string representation.

Parameters:

Type	Name	Description
integer	ticks	Game ticks

Returns:

Type	Description
string	time Human time formatted string

---

sm.gui.translateLocalizationTags(text)

Client only

Translates all localization tags in a text using the current language.

Parameters:

Type	Name	Description
string	text	The text containing localization tags

Returns:

Type	Description
string	The text with translated tags