Skip to content

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 CoreGameInfo
CoreMesh CoreObject CoreObjectReference CorePlayerProfile
CurveKey CustomMaterial Damage DamageableObject
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
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: September 20, 2021