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 BlockchainContract BlockchainToken BlockchainTokenAttribute
BlockchainTokenCollection BlockchainWallet BlockchainWalletCollection Box
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 Inventory InventoryItem ItemObject
LeaderboardEntry Light MaterialSlot MergedModel
NetReference NetworkContext Object PartyInfo
PhysicsObject Player PlayerSettings PlayerStart
PlayerTransferData PointLight Projectile Quaternion
RandomStream Rectangle Rotation Script
ScriptAsset SimpleCurve SmartAudio SmartObject
SpotLight StaticMesh Task Terrain
Transform TreadedVehicle Trigger UIButton
UIContainer UIControl UIEventRSVPButton UIImage
UIPanel UIPerkPurchaseButton UIProgressBar UIRewardPointsMeter
UIScrollPanel UIText UITextEntry 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.

Blockchain 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 Item

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 10, 2022