Lua Script API

Welcome to Lua Scripting in Scrap Mechanic! Scripting is an advanced feature and it's expected you already know something about it.

In this documentation, you will find details on all events/classes/functions specific to Scrap Mechanic's Lua scripting. For more general information on how the scripting language of Lua works and what it does on its own, you can review the Official Lua Documentation.

Server

The server is the part of Scrap Mechanic that simulates the game world and communicates with all clients that are currently playing. The server is only running on the hosting player's computer.

In scripting, a serverEvent, serverMethod or serverMember implies that something can only be called or modified while the script is running in server mode. To check if a script is running in server mode, see sm.isServerMode.

Client

The client is the part of Scrap Mechanic that a player sees and interacts with – e.g. graphics, audio, player input. A client is running on every player's computer, including the host.

In scripting, a clientEvent, clientMethod or clientMember implies that something can only be called or modified while the script is running in client mode. To check if a script is running in client mode, see sm.isServerMode.

Userdata

Userdata is the data structure Scrap Mechanic uses to define custom objects in Lua. They are similar to instances in object-oriented programming.

A userdata instance contains an identifier that is used to access an object in the game, such as a shape object, which is represented as {<Shape>, id = 1}.

Userdata can be passed into global namespace functions (such as sm.shape.getColor(shape)) or into userdata methods directly (such as shape:getColor()).

Console

The console displays errors occurring in the script and expressions printed with print().

To activate the console, type /console in chat.

sm

The sm namespace contain all API features related to Scrap Mechanic.

sm.version

read-only string – The current version of the game: 0.3.3.

sm.isHost

Returns whether the game is currently running on the hosting player's computer.

read-only bool – Whether the game is running on the host.

sm.isServerMode( )

Returns whether the script is currently running in server mode. Otherwise, it is running in client mode. Server mode only occurs when sm.isHost is true.

Returns: bool – Whether the script is running in server mode.
sm.exists( object )

Returns whether an object exists in the game. This is useful for checking whether a reference to a shape or character is valid.

Parameters: object (any) – The object instance.
Returns: bool – Whether the object exists.
dofile( filename )

Opens the named file and executes its contents as a Lua chunk. In case of errors, dofile propagates the error to its caller.

Parameters: filename (string) – The name of the file to be loaded.
class( base=nil )

Creates a new class object.

Parameters: base (string) – An optional base class to inherit from.
print( *args )

Prints data to the console. This is useful for debugging.

Note

If the game is running with the -dev flag, any output will be added to the game logs.

Parameters: *args (any) – The arguments to be printed.
type( object )

Returns the type of an object as a string. This includes standard Lua types and userdata types specific to this API.

Parameters: object (any) – The object instance.
Returns: string – The object type.