Lua Scripting API

Overview

Core scripts are written in Lua, using version 5.3.6 of the Lua library. Scripts are objects created and added to the hierarchy and/or templates, similar to other object types. Scripts added to the hierarchy will execute as soon as the game loads, while scripts inside templates execute with each newly spawned instance of the template.

Properties, functions, and events inherited by CoreObject types are listed below. Both properties and events are accessed with .propertyName and .eventName, while functions are accessed with :FunctionName(). Some types have class functions, which are accessed with .FunctionName().

Core Lua Types

At a high level, Core Lua types can be divided into two groups: Data structures and Objects. Data structures are owned by Lua, while Objects are owned by the engine and could be destroyed while still referenced by Lua. Objects all inherit from a single base type: Object. Data structures have no common parent. However, all data structures and Objects share a common type property, which is a string indicating its type. The value of the type property will match the section headings below, for example: Ability, Vector2, CoreObject, etc. All Core types also share an IsA() function. The IsA() function can be passed a type name, and will return true if the value is that type or one of its subtypes, or will return false if it is not. For example, myObject:IsA("StaticMesh").

A lowercase type denotes a basic Lua type, such as string and boolean. You can learn more about Lua types from the official manual here. An uppercase type is a Core Type, such as Player and CoreObject.

Core Lua Namespaces

Some sets of related functionality are grouped within namespaces, which are similar to the types above, but cannot be instantiated. They are only ever accessed by calling functions within these namespaces.

Core Lua Interfaces

Interfaces list properties, functions, and events that types which implement that interface must have. When a type implements an interface, the IsA() function will return true for the interface name. For example, someVehicle:IsA("Damageable") will return true, because the Vehicle type implements the Damageable interface.

Built-In Lua Functions

For security reasons, various built-in Lua functions have been restricted or removed entirely. The available functions are listed below. Note that Lua's built-in trigonometric functions use radians, while other functions in Core uses degrees. See the reference manual for more information on what they do.

MUIDs

MUIDs are internal identifiers for objects and assets within your game. They are guaranteed to be unique within the game and likely to be unique globally. You can copy a MUID to the clipboard automatically by right-clicking assets in Project Content or placed objects in the Hierarchy. The MUID will look something like this:

8D4B561900000092:Rabbit

The important part is the 16 digits at the start. The colon and everything after it are optional and are there to make it easier to read. Some Lua functions use MUIDs, for example FindObjectById and SpawnAsset. When used in a script, it needs to be surrounded by quotes to make it a string. For example:

local spawnTrans = script.parent:GetWorldTransform()
local anchor = World.FindObjectById('8D4B5619000000ED:Anchor')
World.SpawnAsset('8D4B561900000092:Rabbit', spawnTrans, anchor)