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

Character

Associated namespace: sm.character

A userdata object representing a character in the game.

Values:

• clientPublicData
• color
• direction
• id
• mass
• movementSpeedFraction
• publicData
• velocity
• worldPosition

Functions:

• addRenderable
• applyTumblingImpulse
• bindAnimationCallback
• getActiveAnimations
• getAnimationInfo
• getCanSwim
• getCharacterType
• getClientPublicData
• getColor
• getCurrentMovementNoiseRadius
• getCurrentMovementSpeed
• getDirection
• getGlowMultiplier
• getHeight
• getId
• getLockingInteractable
• getMass
• getMovementSpeedFraction
• getPlayer
• getPublicData
• getRadius
• getSurfaceNormal
• getTpBonePos
• getTpBoneRot
• getTumblingExtent
• getTumblingLinearVelocity
• getTumblingWorldPosition
• getTumblingWorldRotation
• getUnit
• getVelocity
• getWorld
• getWorldPosition
• isAiming
• isClimbing
• isCrouching
• isDefaultColor
• isDiving
• isDowned
• isOnGround
• isPlayer
• isSprinting
• isSwimming
• isTumbling
• removeAnimationCallbacks
• removeRenderable
• setAllowTumbleAnimations
• setClientPublicData
• setClimbing
• setColor
• setDiving
• setDowned
• setGlowMultiplier
• setLockingInteractable
• setMovementEffects
• setMovementSpeedFraction
• setMovementWeights
• setNameTag
• setPublicData
• setSwimming
• setTumbling
• setUpDirection
• setWorldPosition
• updateAnimation

Operations:

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

---

clientPublicData table

Get:

Client only

Returns client public data from a character.

Set:

Client only

Sets client public data on a character.

---

color Color

Get:

Returns the base color of a character.

Set:

Server only

Sets the character color.

---

direction Vec3

Get:

Returns the direction of where a character is viewing or aiming.

---

id integer

Get:

Returns the id of a character.

---

mass number

Get:

Returns the mass of a character.

---

movementSpeedFraction number

Get:

Gets the current fraction multiplier applied on the character's movement speed.

Set:

Sets a fraction multiplier to the character's movement speed.

---

publicData table

Get:

Server only

Returns (server) public data from a character.

Set:

Server only

Sets (server) public data on a character.

---

velocity Vec3

Get:

Returns the velocity of a character.

---

worldPosition Vec3

Get:

Returns the world position of a character.

---

addRenderable(character, renderable)

Client only

Adds a renderable (file containing model data) to be used for the character in third person view.

Parameters:

Type	Name	Description
Character	character	The character.
string	renderable	The renderable path.

---

applyTumblingImpulse(character, impulse)

Applies impulse to the characters tumbling shape.

Parameters:

Type	Name	Description
Character	character	The character.
Vec3	impulse	The impulse.

---

bindAnimationCallback(character, animationName, triggerTime, callback)

Binds a character's animation to a callback function.

Parameters:

Type	Name	Description
Character	character	The character.
string	animationName	The name of the animation.
number	triggerTime	The required time that will have elapsed in the animation when the callback is triggered.
string	callback	The name of the Lua function to bind.

---

getActiveAnimations(character)

Returns the set of active animations.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
table	The set of active animatons { { name = string, weight = number }, ...}

---

getAnimationInfo(character, name)

Client only

Parameters:

Type	Name	Description
Character	character	The character.
string	name	The name.

Returns:

Type	Description
table	The animation info { name = string, duration = number, looping = boolean }.

---

getCanSwim(character)

Returns whether the character will float or sink in liquid.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	True if the character will float, false if the character will sink.

---

getCharacterType(character)

Returns the uuid of the character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Uuid	The character type.

---

getClientPublicData(character)

Client only

Returns client public data from a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
table	The client public data.

---

getColor(character)

Returns the base color of a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Color	The character color.

---

getCurrentMovementNoiseRadius(character)

Returns the radius around the character where it can be heard.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The noise radius of the character.

---

getCurrentMovementSpeed(character)

Returns the current movement speed of the character depending on state and multiplier.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The current movement speed.

---

getDirection(character)

Returns the direction of where a character is viewing or aiming.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The character's view direction.

---

getGlowMultiplier(character)

Client only

Gets the glow multiplier.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The glow multiplier (0.0 - 1.0).

---

getHeight(character)

Returns the height of a character

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The character's height.

---

getId(character)

Returns the id of a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
integer	The character's id.

---

getLockingInteractable(character)

Get the Interactable that the Character is locked to.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Interactable	The interactable.

---

getMass(character)

Returns the mass of a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The character's mass.

---

getMovementSpeedFraction(character)

Gets the current fraction multiplier applied on the character's movement speed.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The movement speed fraction.

---

getPlayer(character)

Returns the player controlling the character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Player	The player controlling the character.

---

getPublicData(character)

Server only

Returns (server) public data from a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
table	The public data.

---

getRadius(character)

Returns the radius of a character

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
number	The character's radius.

---

getSurfaceNormal(character)

Returns the normal of the character's contact with a surface. Defaults to a zero vector when no contact is found.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The surface normal.

---

getTpBonePos(character, jointName)

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

Parameters:

Type	Name	Description
Character	character	The character.
string	jointName	The joint name.

Returns:

Type	Description
Vec3	The joint position.

---

getTpBoneRot(character, jointName)

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

Parameters:

Type	Name	Description
Character	character	The character.
string	jointName	The joint name.

Returns:

Type	Description
Quat	The joint rotation.

---

getTumblingExtent(character)

Returns the extent of the characters tumbeling shape.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The tumbling shape's extent.

---

getTumblingLinearVelocity(character)

Returns the linear velocity of the characters tumbling shape.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The tumbling shape's linear velocity.

---

getTumblingWorldPosition(character)

Returns the world position of the characters tumbeling shape.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The tumbling shape's world position.

---

getTumblingWorldRotation(character)

Returns the world rotation of the characters tumbeling shape.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Quat	The tumbling shape's world rotation.

---

getUnit(character)

Returns the unit controlling the character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Unit	The unit controlling the character.

---

getVelocity(character)

Returns the velocity of a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The character's velocity.

---

getWorld(character)

Returns the world a character exists in.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
World	The world the character exists in.

---

getWorldPosition(character)

Returns the world position of a character.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
Vec3	The character's world position.

---

isAiming(character)

Returns whether a character is currently aiming with a weapon.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	Whether the character is aiming.

---

isClimbing(character, state)

Get the character climbing state.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

isCrouching(character)

Returns whether a character is currently crouching.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	Whether the character is crouching.

---

isDefaultColor(character)

Returns true if the current character color is its default color.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	True if the color is the base color.

---

isDiving(character, state)

Get the character diving state.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

isDowned(character, state)

Get the character downed state.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

isOnGround(character)

Returns whether the character is currently standing on the ground.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	Whether the character is on the ground.

---

isPlayer(character)

Returns whether a character is owned by a player.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	Whether the character is owned by a player.

---

isSprinting(character)

Returns whether a character is currently sprinting.

Parameters:

Type	Name	Description
Character	character	The character.

Returns:

Type	Description
boolean	Whether the character is sprinting.

---

isSwimming(character, state)

Get the character swimming state.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

isTumbling(character, state)

Get the character tumbling state.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

removeAnimationCallbacks(character)

Removes all of a character's animation callbacks.

Parameters:

Type	Name	Description
Character	character	The character.

---

removeRenderable(character, renderable)

Client only

Removes a renderable (file containing model data) that was used for the character in third person view.

Parameters:

Type	Name	Description
Character	character	The character.
string	renderable	The renderable path.

---

setAllowTumbleAnimations(character, allow)

Client only

Enables or disables event animations.

When set to false no animations can play while tumble is active, and when set to true the animations will play while tumbling.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	allow	The state.

---

setClientPublicData(character, data)

Client only

Sets client public data on a character.

Parameters:

Type	Name	Description
Character	character	The character.
table	data	The client public data.

---

setClimbing(character, state)

Server only

Sets whether the character is climbing.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

setColor(character, color)

Server only

Sets the character color.

Parameters:

Type	Name	Description
Character	character	The character.
Color	color	The character color.

---

setDiving(character, state)

Server only

Sets whether the character is diving.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

setDowned(character, state)

Server only

Sets whether the character is downed.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

setGlowMultiplier(character, value)

Client only

Sets a value to multiply the glow from asg texture with.

Parameters:

Type	Name	Description
Character	character	The character.
number	value	The glow multiplier (0.0 - 1.0).

---

setLockingInteractable(character, interactable)

Set the Interactable that the Character is locked to. Set Interactable to nil to unlock.

Parameters:

Type	Name	Description
Character	character	The character.
Interactable	interactable	The interactable.

Returns:

Type	Description
boolean	True if the character was successfully locked or unlocked.

---

setMovementEffects(character, Effect)

Sets the movement effect set filepath.

Parameters:

Type	Name	Description
Character	character	The character.
string	Effect	set filepath The effect set filepath.

---

setMovementSpeedFraction(character, fraction)

Sets a fraction multiplier to the character's movement speed.

Parameters:

Type	Name	Description
Character	character	The character.
number	fraction	The movement speed fraction.

---

setMovementWeights(character, lower, upper)

Client only

Sets the weights for movement animations on a character's upper and lower body.

For a value of 0 no movement animations will play, and for a value of 1 the movement animations will fully play unless otherwise overridden.

Parameters:

Type	Name	Description
Character	character	The character.
number	lower	The lower weight.
number	upper	The upper weight.

---

setNameTag(character, name, color=nil, requiresLoS=false, renderDistance=10000, fadeDistance=9500)

Client only

Sets the name tag display value for the character

Parameters:

Type	Name	Description
Character	character	The character.
string	name	The new name tag text value.
color	color=nil	The color of the name. (defaults to white)
bool	requiresLoS=false	Whether broken line of sight will hide the name tag.
float	renderDistance=10000	Max distance the name tag will render in.
float	fadeDistance=9500	Distance where fade out will start.

---

setPublicData(character, data)

Server only

Sets (server) public data on a character.

Parameters:

Type	Name	Description
Character	character	The character.
table	data	The public data.

---

setSwimming(character, state)

Server only

Sets whether the character is swimming.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

setTumbling(character, state)

Server only

Sets whether the character is tumbling.

Parameters:

Type	Name	Description
Character	character	The character.
boolean	state	The state.

---

setUpDirection(character, up)

Client only

Sets the upward direction of the character's graphics.

Parameters:

Type	Name	Description
Character	character	The character.
Vec3	up	The direction.

---

setWorldPosition(character, The)

Server only

Sets the world position of a character.

Parameters:

Type	Name	Description
Character	character	The character.
Vec3	The	character's new world position.

---

updateAnimation(character, name, time, weight=nil, additive=nil)

Client only

Updates a character animation.

Parameters:

Type	Name	Description
Character	character	The character.
string	name	The animation name.
number	time	The time.
number	weight=nil	The weight. Defaults to -1.0. (Optional)
boolean	additive=nil	Whether the animation will be added to the default animation. Defaults to false. (Optional)