Introduction

Welcome to the Lua scripting reference pages for Scrap Mechanic!

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 offline, in json format and a lua documentation file.

Console

It's recommended to start the game with '-dev' launch option when scripting to get access to the Debug Console and to enable the script hot-reload feature. Use print to print 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.

In json "partList" element:

	"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( "Pressing E" )
		self.network:sendToServer( "sv_n_toggle" )
	else
		print( "Releasing 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

An other 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, serverEventCallback, implies that the the code will run in server mode and have access only to server only functions and client and server. 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. A client is running on every player's computer, including the host.

In a script class, clientEventCallback, implies that what the callback will be run in client mode, restricting Lua to only be able to call client only and client and server functions.