Skip to main content

sm.gui​

The gui library contains various utility functions for handling user interfaces.
This library can only be used on the client.

Functions​

chatMessage​

sm.gui.chatMessage( message )

Sends a message in chat.

note

The message is not sent to other players.

Arguments:
  • message [ string ]: The message.

createAmmunitionContainerGui​

sm.gui.createAmmunitionContainerGui( destroyOnClose )
Client-Only

Creates an ammunition container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createBagIconGui​

sm.gui.createBagIconGui( destroyOnClose )
Client-Only

Creates a bag icon GUI.

warning

This function is deprecated. Do not use!

Use createWorldIconGui instead.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createBatteryContainerGui​

sm.gui.createBatteryContainerGui( destroyOnClose )
Client-Only

Creates a battery container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createBeaconIconGui​

sm.gui.createBeaconIconGui( destroyOnClose )
Client-Only

Creates a beacon icon GUI.

warning

This function is deprecated. Do not use!

Use createWorldIconGui instead.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createChallengeHUDGui​

sm.gui.createChallengeHUDGui( destroyOnClose )
Client-Only

Creates a challenge HUD GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createChallengeMessageGui​

sm.gui.createChallengeMessageGui( destroyOnClose )
Client-Only

Creates a challenge message GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createCharacterCustomizationGui​

sm.gui.createCharacterCustomizationGui( destroyOnClose )
Client-Only

Creates a character customization GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createChemicalContainerGui​

sm.gui.createChemicalContainerGui( destroyOnClose )
Client-Only

Creates a chemical container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createContainerGui​

sm.gui.createContainerGui( destroyOnClose )
Client-Only

Creates a container GUI, for showing two containers.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createCraftBotGui​

sm.gui.createCraftBotGui( destroyOnClose )
Client-Only

Creates a craftbot GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createDressBotGui​

sm.gui.createDressBotGui( destroyOnClose )
Client-Only

Creates a dressbot GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createEngineGui​

sm.gui.createEngineGui( destroyOnClose )
Client-Only

Creates an engine GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createFertilizerContainerGui​

sm.gui.createFertilizerContainerGui( destroyOnClose )
Client-Only

Creates a fertilizer container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createGasContainerGui​

sm.gui.createGasContainerGui( destroyOnClose )
Client-Only

Creates a gas container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createGuiFromLayout​

sm.gui.createGuiFromLayout( layout, destroyOnClose, settings )
Client-Only

Creates a custom GUI from a layout file.

Arguments:
  • layout [ string ]: The file path to the gui layout file.
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
  • settings [ table ]: Table with GUI settings, see table structure below.
'settings' Table Structure
{
    isHud = false,          --Whether the GUI is a HUD GUI or not.
    isInteractive = false,  --Whether the GUI can be interacted with or not.
    needsCursor = false,    --Whether the GUI frees player's cursor and makes it visible or not.
    hidesHotbar = false,    --Whether the GUI hides player's hotbar or not. NOTE: this hides only the hotbar, other parts of the hud like the health bar or the logbook icon have to be hidden manually!
    isOverlapped = false,   --Whether the GUI overlaps any non-hardcoded GUIs or not. NOTE: If multiple overlapping GUIs are created, the last one to be opened will be on top.
    backgroundAlpha = 1.0,  --How much the GUI blurs player's screen, a fraction between 0 and 1. 0 - no blur, 1 - black background.
}
Returns:

createHideoutGui​

sm.gui.createHideoutGui( destroyOnClose )
Client-Only

Creates a hideout GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createLogbookGui​

sm.gui.createLogbookGui( destroyOnClose )
Client-Only

Creates a logbook GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createMechanicStationGui​

sm.gui.createMechanicStationGui( destroyOnClose )
Client-Only

Creates a mechanic station GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createNameTagGui​

sm.gui.createNameTagGui( destroyOnClose )
Client-Only

Creates a name tag GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createQuestTrackerGui​

sm.gui.createQuestTrackerGui( destroyOnClose )
Client-Only

Creates a quest tracker GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createSeatGui​

sm.gui.createSeatGui( destroyOnClose )
Client-Only

Creates a seat GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createSeatUpgradeGui​

sm.gui.createSeatUpgradeGui( destroyOnClose )
Client-Only

Creates a seat upgrade GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createSeedContainerGui​

sm.gui.createSeedContainerGui( destroyOnClose )
Client-Only

Creates a seed container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createSteeringBearingGui​

sm.gui.createSteeringBearingGui( destroyOnClose )
Client-Only

Creates a steering bearing GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createSurvivalHudGui​

sm.gui.createSurvivalHudGui( destroyOnClose )
Client-Only

Creates a survival HUD GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createWaterContainerGui​

sm.gui.createWaterContainerGui( destroyOnClose )
Client-Only

Creates a water container GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createWaypointIconGui​

sm.gui.createWaypointIconGui( destroyOnClose )
Client-Only

Creates a waypoint icon GUI.

warning

This function is deprecated. Do not use!

Use createWorldIconGui instead.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createWidget​

sm.gui.createWidget()
warning

This function is removed and does nothing. Do not use!

Use createGuiFromLayout instead.

createWorkbenchGui​

sm.gui.createWorkbenchGui( destroyOnClose )
Client-Only

Creates a workbench GUI.

Arguments:
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

createWorldIconGui​

sm.gui.createWorldIconGui( width, height, layout, destroyOnClose )
Client-Only

Creates a world icon GUI from a layout file.

Arguments:
  • width [ int ]: The width.
  • height [ int ]: The height.
  • layout [ string ]: The path to the layout file. Defaults to $GAME_DATA/Gui/Layouts/Hud/Hud_WorldIcon.layout.
  • destroyOnClose [ bool ]: Whether the guiInterface is destroyed when closed or not. Defaults to false.
Returns:

displayAlertText​

sm.gui.displayAlertText( text, time )
Client-Only

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

Arguments:
  • text [ string ]: The alert text.
  • time [ number ]: The time in seconds for which the message is shown. Defaults to 4 seconds.

endFadeToBlack​

sm.gui.endFadeToBlack( duration )
Client-Only

Fades the screen back from a fade to black.

Arguments:
  • duration [ number ]: The animation duration.

exitToMenu​

sm.gui.exitToMenu()
Client-Only

Exits the current game and returns to the main menu.

note

Can only be used in the Challenge game mode.

getCurrentLanguage​

sm.gui.getCurrentLanguage()
Client-Only

Returns the user's current language setting.

Returns:
  • [ string ]: The language setting, e.g. "English".

getKeyBinding​

sm.gui.getKeyBinding( action, hypertext )
Client-Only

Returns the set binding for an action as a string.
If hypertext is enabled, the function returns a formatted string
that, if given to setInteractionText, will put the text in a highlight box
or display a certain image, depending on the action.

Arguments:
  • action [ string ]: The action.
  • hypertext [ bool ]: Whether the string should be hypertext formatted or not.
Returns:
  • [ string ]: The key bound to the action.

translateLocalizationTags​

sm.gui.translateLocalizationTags( text )
Client-Only

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

Arguments:
  • text [ string ]: The text containing the tags.
Returns:
  • [ string ]: The translated text.

getScreenSize​

sm.gui.getScreenSize()
Client-Only

Returns the size of the screen.

Returns:
  • [ int ]: The screen width.
  • [ int ]: The screen height.

hideGui​

sm.gui.hideGui( state )
Client-Only

Sets GUI visibility.

Arguments:
  • state [ bool ]: Whether the GUI is hidden or not.

setCenterIcon​

sm.gui.setCenterIcon( name )
Client-Only

Set the icon displayed at the center.

Arguments:
  • name [ string ]: The icon name.

setCharacterDebugText​

sm.gui.setCharacterDebugText( character, text, clear )
Client-Only

Set a text for the character that will be displayed above its head.

Arguments:
  • character [ Character ]: The character.
  • text [ string ]: The text to display.
  • clear [ bool ]: Whether the previous text should be overwritten or not.

setInteractionText​

sm.gui.setInteractionText( text1, binding1, text2, binding2, text3 )
Client-Only

Set the binding text displayed at the center.

Using hypertext formatting (see getKeyBinding), you can highlight the text in a box or display an image.
This hypertext can be customized to some extent, see the examples below.

Arguments:
  • text1 [ string ]: The leftmost segment.
  • binding1 [ string ]: The left white segment. Optional.
  • text2 [ string ]: The mid or end segment. Optional.
  • binding2 [ string ]: The right white segment. Optional.
  • text3 [ string ]: The rightmost segment. Optional.
Example hypertext highlighting
MyShape = class()

function MyShape.client_onUpdate( self, dt )
	--This string will display the letter 'E' inside an orange highlight box
	local string = "<p textShadow='false' bg='gui_keybinds_bg_orange' color='#66440C' spacing='9'>E</p>"
	--[[
		Parameters:
		'textShadow' - Whether the text should have a shadow applied or not.
		'bg' - The highlight box to be used. Valid are: 'gui_keybinds_bg', 'gui_keybinds_bg_orange' and 'gui_keybinds_bg_white'.
		'color' - The color of the text inside the highlight box.
		'spacing' - The space between the ends of the text and the ends of the highlight box.
		'E' - The text to display inside the box.
	]]
	sm.gui.setInteractionText( string )
end
Example hypertext image
MyShape = class()

function MyShape.client_onUpdate( self, dt )
	--This string will display an arrow pointing down.
	local string = "<img bg='gui_keybinds_bg' spacing='0'>icon_keybinds_arrow_down.png</img>"
	--[[
		Parameters:
		'bg' - The background box to be used. Valid are: 'gui_keybinds_bg', 'gui_keybinds_bg_orange' and 'gui_keybinds_bg_white'.
		'spacing' - The space between the edges of the image and the edges of the background box.
		'icon_keybinds_arrow_down.png' - The image to display. A custom image can be set using '$CONTENT_DATA/path/to/image.png'
	]]
	sm.gui.setInteractionText( string )
end

setProgressFraction​

sm.gui.setProgressFraction( progress )
Client-Only

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

Arguments:
  • progress [ number ]: The number that determines how much of the circle is filled.

startFadeToBlack​

sm.gui.startFadeToBlack( duration, timeout )
Client-Only

Fades the screen to black and back after timeout.

Arguments:
  • duration [ number ]: The animation duration.
  • timeout [ number ]: Time in seconds until the screen fades back.

ticksToTimeString​

sm.gui.ticksToTimeString( ticks )
Client-Only

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

Arguments:
  • ticks [ int ]: The ticks.
Returns:
  • [ string ]: The human time formatted string.