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

Tool

Associated namespace: sm.tool

A userdata object representing a tool in the game.

Values:

• id

Functions:

• getAnimationInfo
• getCameraWeights
• getDirection
• getFpAnimationInfo
• getFpBonePos
• getId
• getMovementSpeedFraction
• getMovementVelocity
• getOwner
• getPosition
• getRelativeMoveDirection
• getTpBoneDir
• getTpBonePos
• isCrouching
• isEquipped
• isInFirstPersonView
• isLocal
• isOnGround
• isSprinting
• setBlockSprint
• setCrossHairAlpha
• setDispersionFraction
• setFpColor
• setFpRenderables
• setInteractionTextSuppressed
• setMovementAnimation
• setMovementSlowDown
• setTpColor
• setTpRenderables
• updateAnimation
• updateCamera
• updateFpAnimation
• updateFpCamera
• updateJoint
• updateMovementAnimation

---

id integer

Get:

Returns the id of a tool.

---

getAnimationInfo(tool, name)

Client only

Returns general information for a third person view animation.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The name.

Returns:

Type	Description
table	A table containing "name", "duration" and "looping".

---

getCameraWeights()

Client only

Get the current weights for the tool's local camera settings.

Returns:

Type	Description
{number, number}	The third-person weight and the first-person weight

---

getDirection(tool)

Client only

Returns the direction of where the player is viewing or aiming.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
Vec3	The player's view direction.

---

getFpAnimationInfo(tool, name)

Client only

Returns general information for a first person view animation.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The name.

Returns:

Type	Description
table	A table containing "name", "duration" and "looping".

---

getFpBonePos(tool, jointName)

Client only

Returns the world position for a bone in the first person view animation skeleton.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	jointName	The joint name.

Returns:

Type	Description
Vec3	The joint position.

---

getId(tool)

Returns the id of a tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
integer	The tool's id.

---

getMovementSpeedFraction(tool)

Client only

Returns the fraction of the player's movement speed in proportion to its maximum. This is affected by sprinting, crouching, blocking, aiming, etc.

sprinting	1.0
walking	0.5
crouching	0.375
aiming	0.3125

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
number	The player's movement speed fraction.

---

getMovementVelocity(tool)

Client only

Returns the movement velocity of the player.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
Vec3	The player's velocity.

---

getOwner(tool)

Returns the player that owns the tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
Player	The tool's owner.

---

getPosition(tool)

Client only

Returns the world position of the player.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
Vec3	The player's world position.

---

getRelativeMoveDirection(tool)

Client only

Returns the relative movement direction of the player. This is the direction the player wants to move based on movement input.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
Vec3	The player's relative movement direction.

---

getTpBoneDir(tool, jointName)

Client only

Returns the world direction for a bone in the third person view animation skeleton.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	jointName	The joint name.

Returns:

Type	Description
Vec3	The joint direction.

---

getTpBonePos(tool, jointName)

Client only

Returns the world position for a bone in the third person view animation skeleton.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	jointName	The joint name.

Returns:

Type	Description
Vec3	The joint position.

---

isCrouching(tool)

Client only

Returns whether the player is currently crouching.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	Whether the player is crouching.

---

isEquipped(tool)

Client only

Returns whether the the tool is equipped or not.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	whether the the tool is equipped or not.

---

isInFirstPersonView(tool)

Client only

Returns whether the player is in first person view where the viewpoint is rendered from the player's perspective. Otherwise, the player is in third person view where the camera is behind the player.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	Whether the player is in first person view.

---

isLocal(tool)

Client only

Returns whether the player holding the tool is the as sm.localPlayer.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	Whether the player is the local player.

---

isOnGround(tool)

Client only

Returns whether the player is currently standing on the ground.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	Whether the player is on the ground.

---

isSprinting(tool)

Client only

Returns whether the player is currently sprinting.

Parameters:

Type	Name	Description
Tool	tool	The tool.

Returns:

Type	Description
boolean	Whether the player is sprinting.

---

setBlockSprint(tool, block)

Client only

Sets whether the player is unable to sprint. Sprinting is normally blocked when the player is attacking, blocking, aiming, etc.

Parameters:

Type	Name	Description
Tool	tool	The tool.
boolean	block	Whether the player's sprinting is blocked.

---

setCrossHairAlpha(tool, alpha)

Client only

Sets the opacity of the crosshair. An alpha value of 0 makes the crosshair transparent.

Parameters:

Type	Name	Description
Tool	tool	The tool.
number	alpha	The alpha value for the crosshair.

---

setDispersionFraction(tool, dispersion)

Client only

Sets the tool's dispersion fraction. This represents the accuracy of the tool, and affects the size of the player's crosshair.

A dispersion value of 0 is perfect accuracy, whereas 1 is the worst.

Parameters:

Type	Name	Description
Tool	tool	The tool.
number	dispersion	The dispersion fraction.

---

setFpColor(tool, color)

Client only

Sets the color to be used for the tool in first person view.

Parameters:

Type	Name	Description
Tool	tool	The tool.
Color	color	The color.

---

setFpRenderables(tool, renderables)

Client only

Sets the renderables (files containing model data) to be used for the character in first person view.

Parameters:

Type	Name	Description
Tool	tool	The tool.
table	renderables	The table of renderables names {string, ..}

---

setInteractionTextSuppressed(tool, suppressed)

Client only

Sets whether interaction texts are suppressed for the player. This means the player won't be able to see "Press E to use", and similar texts, when looking at an interactable.

Parameters:

Type	Name	Description
Tool	tool	The tool.
boolean	suppressed	Whether interaction texts are suppressed.

---

setMovementAnimation(tool, name, animation)

Client only

Sets the current third person view movement animation to be used by the tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The name.
string	animation	The animation.

---

setMovementSlowDown(tool, slowDown)

Client only

Sets whether the player is slowed down. This is similar to crouching and normally occurs when the player is aiming.

Parameters:

Type	Name	Description
Tool	tool	The tool.
boolean	slowDown	Whether the player movement is slowed down.

---

setTpColor(tool, color)

Client only

Sets the color to be used for the tool in third person view.

Parameters:

Type	Name	Description
Tool	tool	The tool.
Color	color	The color.

---

setTpRenderables(tool, renderables)

Client only

Sets the renderables (files containing model data) to be used for the character in third person view.

Parameters:

Type	Name	Description
Tool	tool	The tool.
table	renderables	The table of renderables names. {string, ..}

---

updateAnimation(tool, name, time, weight=-1.0)

Client only

Updates a third person view animation.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The animation name.
number	time	The time.
number	weight=-1.0	The weight.

---

updateCamera(tool, distance, fov, offset, weight)

Client only

Updates the third person view camera for the tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.
number	distance	The distance.
number	fov	The fov.
Vec3	offset	The offset.
number	weight	The weight.

---

updateFpAnimation(tool, name, time, weight=-1.0, looping=false)

Client only

Updates a first person view animation.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The name.
number	time	The time.
number	weight=-1.0	The weight.
boolean	looping=false	The looping.

---

updateFpCamera(tool, fov, offset, weight, bobbing)

Client only

Updates the first person view camera for the tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.
number	fov	The fov.
Vec3	offset	The offset.
number	weight	The weight.
number	bobbing	The bobbing.

---

updateJoint(tool, name, rotation, weight=-1.0)

Client only

Sets the rotation and weight for a bone in the animation skeleton.

Parameters:

Type	Name	Description
Tool	tool	The tool.
string	name	The name.
Vec3	rotation	The rotation.
number	weight=-1.0	The weight.

---

updateMovementAnimation(tool, time, weight=-1.0)

Client only

Updates the currently set third person view movement animation for the tool.

Parameters:

Type	Name	Description
Tool	tool	The tool.
number	time	The time.
number	weight=-1.0	The weight.