Skip to main content

Introduction​

Welcome! 👋
This is an improved version of the Scrap Mechanic Lua API Reference at https://scrapmechanic.com/api/index.html.

A compiled version of this website will always be available here.

In this documentation, you will find details specific to Scrap Mechanic's Lua scripting.
For more general information on how the Lua scripting language works, you can review the official Lua documentation.

Scrap Mechanic uses Lua version 5.1. Check the official Manual for more information.

The documentation is also available as a (hopefully) up-to-date Lua documentation file.

note

This documentation is for Scrap Mechanic Version 0.6.0 or later.

The previous documentation for Scrap Mechanic Version 0.5.1 is no longer available, as the content was not preserved.

If you encounter any errors, malfunctions, broken links or missing information, please report them here. If you yourself want to contribute to this documentation, you can do so here.

Console​

It is recommended to start the game with the -dev launch option in steam to get access to the
Debug Console and enable the script hot-reload feature.
Use print to print data to the console.

Classes​

Classes act as the entry point from the game to the world of Lua.
A script class is for example a buildable part with a "scripted" json object:

"scripted": {
	"filename": "$CONTENT_DATA/Scripts/MyShape.lua",
	"classname": "MyShape",
	"data": {
		"hello": "Hello world!"
	}
},
Lua Script: 
-- MyShape.lua - Interactable part example script

-- Creates a new class
MyShape = class()

-- Sets ShapeClass constants
MyShape.maxParentCount = 1
MyShape.maxChildCount = 0
MyShape.connectionInput = sm.interactable.connectionType.none
MyShape.connectionOutput = sm.interactable.connectionType.logic
MyShape.colorNormal = sm.color.new( 0x777777ff )
MyShape.colorHighlight = sm.color.new( 0x888888ff )

-- Called on creation
function MyShape:server_onCreate()
	print( self.data.hello )
end

-- Called on creation
function MyShape:client_onCreate()
	self.cl = { time = 0 }
end

-- Called every tick
function MyShape:client_onFixedUpdate( timeStep )
	self.cl.time = self.cl.time + timeStep
end

-- Called on interact
function MyShape:client_onInteract( character, state )
	if state then
		print( "Pressed E" )
		self.network:sendToServer( "sv_n_toggle" )
	else
		print( "Released E" )
	end
	print( "Shape has existed for", self.cl.time, "seconds" )
end

function MyShape:sv_n_toggle() 
	-- Toggle on and off
	self.interactable.active = not self.interactable.active
end

Static Functions​

Static Functions can be called from Lua to do certain things in the game,
such as creating a part using sm.shape.createPart.

The createPart function will return a userdata object of type Shape which can be used to reference the part.
This reference is valid as long as the part still exists in the game.

Userdata​

Userdata is a Lua concept to define custom objects.
Scrap Mechanic uses userdata to add game objects such as a Shape and utility objects such as Vec3.
They are similar to instances in object-oriented programming.
The userdata objects have a set of member values and functions.

Here is an example where the member function getColor is called on the Shape userdata:

local color = myShape.getColor( myShape ) -- All userdata functions require the object itself as first parameter.

Or with : syntactic sugar which adds the userdata itself as the first parameter:

local color = myShape:getColor()

Userdata can also be used as parameters to other functions.
The color returned by getColor is another userdata type; Color. That color can be used as a parameter to setColor:

local color = myShape:getColor()
myOtherShape:setColor( color ) -- Copy the color from myShape to myOtherShape

Userdata can also have member values; which are actually convenience for calling a get or set member function.
This does exactly the same thing as the above:

local color = myShape.color
myOtherShape.color = color -- Copy the color from myShape to myOtherShape

Another way to get a Color userdata object is to call sm.color.new.
Here is an example where the shape color is set to red:

local color = sm.color.new( 1.0, 0.0, 0.0 )
myShape.color = color -- Set shape to red

Sandboxes​

When Lua code is run by the game, they are run in a "sandbox".
The sandbox makes sure no functions can be called that the sandbox does not allow in the current context.
One reason for the sandbox to exist is to enforce a server/client structure, this is to help make sure the scripts work when playing multiplayer.
The sandbox also makes sure no harmful code can be written in Lua by restricting file access and the ability to run executables.

Server​

The server side simulates the game world and communicates with all clients that are currently playing, including the host itself.
The server side is only running on the hosting player's computer.

In a script class, serverCallback implies that the the code will run in server mode and can only access functions marked as server or server and client.
To check if a script is running in server mode at runtime you can also use sm.isServerMode.

Client​

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

In a script class, clientCallback implies that the the code will run in server mode and can only access functions marked as client or server and client.