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.


AIActivity	AIActivityHandler	Ability	AbilityPhaseSettings
AbilityTarget	AnimatedMesh	AreaLight	Audio
BindingSet	Camera	CameraCapture	Color
CoreFriendCollection	CoreFriendCollectionEntry	CoreGameCollectionEntry	CoreGameEvent
CoreGameEventCollection	CoreGameInfo	CoreMesh	CoreObject
CoreObjectReference	CorePlayerProfile	CurveKey	CustomMaterial
Damage	DamageableObject	DateTime	Decal
Equipment	Event	EventListener	Folder
FourWheeledVehicle	HitResult	Hook	HookListener
IKAnchor	ImpactData	LeaderboardEntry	Light
MaterialSlot	MergedModel	NetReference	NetworkContext
Object	PartyInfo	PhysicsObject	Player
PlayerSettings	PlayerStart	PlayerTransferData	PointLight
Projectile	Quaternion	RandomStream	Rotation
Script	ScriptAsset	SimpleCurve	SmartAudio
SmartObject	SpotLight	StaticMesh	Task
Terrain	Transform	TreadedVehicle	Trigger
UIButton	UIContainer	UIControl	UIEventRSVPButton
UIImage	UIPanel	UIPerkPurchaseButton	UIProgressBar
UIRewardPointsMeter	UIScrollPanel	UIText	Vector2
Vector3	Vector4	Vehicle	Vfx
VoiceChatChannel	Weapon	WorldText

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.


Chat	CoreDebug	CoreLuaFunctions	CoreMath
CorePlatform	CoreSocial	CoreString	Environment
Events	Game	Input	Leaderboards
Storage	Teams	UI	VoiceChat
World

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.


Damageable

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.

Built-In Lua Functions

assert
collectgarbage (modified to only accept a count parameter to get current Lua memory usage)
error
getmetatable (modified)
ipairs
next
pairs
pcall
print (modified so it goes to Unreal logs and the Event log)
rawequal
rawget (modified)
rawset (modified)
require (modified)
select
setmetatable (modified)
tonumber
tostring
type
_G (modified so it is separate from _ENV)
_VERSION
xpcall
coroutine.create
coroutine.isyieldable
coroutine.resume
coroutine.running
coroutine.status
coroutine.wrap
coroutine.yield
math.abs
math.acos
math.asin
math.atan
math.ceil
math.cos
math.deg
math.exp
math.floor
math.fmod
math.huge
math.log
math.max
math.maxinteger
math.min
math.mininteger
math.modf
math.pi
math.rad
math.random
math.randomseed
math.sin
math.sqrt
math.tan
math.tointeger
math.type
math.ult
os.clock
os.date
os.difftime
os.time
string.byte
string.char
string.find
string.format
string.gmatch
string.gsub
string.len
string.lower
string.match
string.pack
string.packsize
string.rep
string.reverse
string.sub
string.unpack
string.upper
table.concat
table.insert
table.move
table.pack
table.remove
table.sort
table.unpack
utf8.char
utf8.charpattern
utf8.codes
utf8.codepoint
utf8.len
utf8.offset

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)

Last update: October 21, 2021