API ‐ Script Environment

Datatypes

Additional types with methods and properties

AtomicInteger

An atomic integer, which can be accessed from multiple threads with an ID through parallel.atomicinteger

function Get(): number

• Fetches the value

function Set(Value: number)

• Sets the value

Color

An RGB color

function Color.new(R: number, G: number, B: number): Color

function Color.new(Color: vector): Color

• Returns a Color with the provided R, G, and B values
• Values are expected to be in the range 0 to 1
• This datatype is not hash consed! Two separate value-identical colors are not rawequal and will not behave as expected when used as table keys

.B: number

• The Blue channel

.G: number

• The Green channel

.R: number

• The Red channel

ColorGradient

Not implemented

EventConnection

A connection to an Event

function Disconnect()

• Disconnects the Connection, causing the callback to no longer be queued for resumption. May only be called once. Please note that the callback may still be invoked afterward if the Event occurred before Disconnecting

.Connected: boolean

• Whether the Connection is connected or not

.Signal: unknown

• The Event which :Connect was called upon to return this Connection

EventSignal

• An Event that can be connected to
• This datatype is not hash consed! Two separate value-identical signals are not rawequal and will not behave as expected when used as table keys (e.g. rawequal(game.OnFrameBegin, game.OnFrameBegin) == false)

function Connect((uknown) -> (unknown)): EventConnection

• Connect a callback to the Event

function Wait(): unknown

• Yields the thread until the Event is fired

GameObject

• A Game Object
• Game Objects have a "base" API (properties, methods, and events) that can be extended by giving them Components
• The base API will be documented on the Component APIs page
• This datatype is hash consed, t[game] and t[workspace.Parent] are guaranteed to access the same value as game and workspace.Parent are rawequal

GameObject.clearAllComponentDefinitions() -> ()

• Clears all previously defined component data

GameObject.component<C>({ read Name: string }) -> ComponentDefinition & C

• Defines a custom component
• Throws an error if one with this name was already defined

function GameObject.fromTemplate(Template: string): GameObject

• Creates a new Object based on the specified Component, adding additional Components to make it more complete (such as Mesh receiving Mesh, RigidBody and Transform to make it fully functional)

function GameObject.new(Components: { string }?): GameObject

• Creates an Object with only the specified Components, or a blank Object if no table is given

GameObject.validComponents: { string }

• A list of all valid component names which can be passed into .new

InputEvent

This is a union of KeyInputEvent, MouseInputEvent, and ScrollInputEvent

Matrix

• A 4x4 transformation matrix
• This datatype is not hash consed! Two separate value-identical matrices are not rawequal and will not behave as expected when used as table keys

Matrix.identity: Matrix

• An identity matrix, the same value as what gets returned with .new() with no arguments

function Matrix.lookAt(Eye: vector, Target: vector, Up: vector?): Matrix

• Creates a Matrix at position Eye oriented such that the .Forward vector moves toward Target

function Matrix.new(): Matrix

function Matrix.new(C1R1: number, C2R1: number, C3R1: number, C4R1: number, C1R2: number, C2R2: number, C3R2: number, C4R2: number, C1R3: number, C2R3: number, C3R3: number, C4R3: number, C1R4: number, C2R4: number, C3R4: number, C4R4: number): Matrix

• Returns a new identity matrix when given no arguments, and a matrix with each individual cell set when given 16 number arguments

function Matrix.rotated(X: number, Y: number, Z: number): Matrix

function Matrix.rotated(Angles: vector): Matrix

• Creates a Matrix which has been rotated by the given Euler angles (in radians) with the rotation order Y-X-Z

function Matrix.scaled(X: number, Y: number, Z: number): Matrix

function Matrix.scaled(Scale: vector): Matrix

• Creates a scaled Matrix

function Matrix.translated(Position: vector): Matrix

function Matrix.translated(X: number, Y: number, Z: number): Matrix

• Creates a Matrix which has been translated to the given coordinates (specified as either a vector or the individual X, Y, and Z components)

function ExtractAngles(): vector

• Extracts the orientation of the Matrix as euler angles in the YXZ rotation order

function Inverse(): Matrix

• Returns the inverse of the Matrix

function Lerp(Target: Matrix, Delta: number): Matrix

• Linearly interpolates to the given Matrix

function WithRotation(Rotation: vector): Matrix

• Constructs a new Matrix with the current Matrix's Translation and Scale, and with the provided Rotation

function WithScale(Scale: vector): Matrix

• Constructs a new Matrix with the current Matrix's Translation and Rotation, and with the provided Scale

function WithTranslation(Translation: vector): Matrix

• Constructs a new Matrix with the current Matrix's Rotation and Scale, and with the provided Translation

function __add(vector): Matrix

• Add a vector to a Matrix to directly offset its position by world space

__mul((self: Matrix, b: Matrix) -> Matrix) & ((self: Matrix, v: vector) -> vector)

• Two Matrices, or a Matrix and a vector, may be multiplied together with the * operator

function __sub(vector): Matrix

• Subtract a vector from a Matrix to directly offset its position by world space

.C1R1: number

• The value at Column 1, Row 1

.C1R2: number

• The value at Column 1, Row 2

.C1R3: number

• The value at Column 1, Row 3

.C1R4: number

• The value at Column 1, Row 4

.C2R1: number

• The value at Column 2, Row 1

.C2R2: number

• The value at Column 2, Row 2

.C2R3: number

• The value at Column 2, Row 3

.C2R4: number

• The value at Column 2, Row 4

.C3R1: number

• The value at Column 3, Row 1

.C3R2: number

• The value at Column 3, Row 2

.C3R3: number

• The value at Column 3, Row 3

.C3R4: number

• The value at Column 3, Row 4

.C4R1: number

• The value at Column 4, Row 1

.C4R2: number

• The value at Column 4, Row 2

.C4R3: number

• The value at Column 4, Row 3

.C4R4: number

• The value at Column 4, Row 4

.Forward: vector

• The Forward basis vector of the Matrix

.Right: vector

• The Right basis vector of the Matrix

.Scale: vector

• The current scale of the Matrix

.Translation: vector

• The translation of the Matrix

.Up: vector

• The Up basis vector of the Matrix

Mutex

A mutex which can be fetched with an ID through parallel.mutex

function Lock()

function TryLock(): boolean

• Attempts to lock the mutex if it is not already locked by another thread. Returns whether or not the locking succeeded

function Unlock()

NumberGradient

Not implemented

SharedBuffer

A buffer accessible without locking between mulitple parallel threads, which can be fetched through parallel.sharedbuffer

Pull(SharedBuffer, Start: number | --[[integer |]] nil, Length: number | --[[integer |]] nil) -> buffer

• Copies a section of the shared buffer into a regular buffer object

Push(SharedBuffer, Source: buffer, Start: number | --[[integer |]] nil, Length: number | --[[integer |]] nil) -> ()

• Copies a buffer into the shared buffer. If no Length is provided, then the full length of the source buffer is copied

.Size: number

• Size of the buffer, in bytes

VectorGradient

Not implemented

Libraries

Libraries specific to the Phoenix Engine Luau runtime. It is recommended that you use the modules under the @std alias instead.

Enum

• Contains enumerations
• See the Enums page for details

_RUNTIME

• Describes the Luau runtime

_RUNTIME.name: string

• The name of the runtime

_RUNTIME.url: string?

• URL associated with the runtime

_RUNTIME.version: { read display: string, git: { commit: string, url: string? } }

• Version information

debug

• Extensions to the standard Luau debug library are documented below

function debug.breakpoint((Line: number): number)) & (() -> ()

• Set a breakpoint at the closest possible line to the given target line within the calling function, returning the actual line the breakpoint landed on
• If a line is not specified, breaks into Debugger immediately, and returns no values
• If a Debugger is not attached (such as in non-developer mode or headless mode), has no effect

function debug.profilemessage(Message: string)

• Generates a profiler log message event

function debug.zonebegin(Name: string?)

• Begins a profiling zone for the current function, optionally accepting a name

function debug.zoneend()

• Ends the last profiling zone

function debug.zonetext(Text: string)

• Set additional debug text for the zone

imgui

• UI with Dear ImGui

function imgui.anyitemactive(): boolean

• ImGui::IsAnyItemActive

function imgui.begin(WindowTitle: string, WindowFlags: string? [ "" ], HasCloseButton: boolean? [ false ]): boolean, boolean

• ImGui::Begin
• WindowFlags may be a combination of any of the following sequences, optionally separated by ' ' or '|' characters: nt (no titlebar), nr (no resize), nm (no move), nc (no collapse), ns (no saved settings), ni (no interact), h (horizontal scrolling)

function imgui.beginchild(Name: string, Size: vector? [ 0, 0 ], ChildFlags: string? [ "" ], WindowFlags: string? [ "" ]): boolean

• ImGui::BeginChild
• ChildFlags may be a combination of any of the following sequences, optionally separated by ' ' or '|' characters: b (borders), wp (always use window padding), rx (resize X), ry (resize Y), ax (auto resize X), ay (auto resize Y), f (frame style)
• WindowFlags may be a combination of any of the following sequences, optionally separated by ' ' or '|' characters: nt (no titlebar), nr (no resize), nm (no move), nc (no collapse), ns (no saved settings), ni (no interact), h (horizontal scrolling)

function imgui.beginfullscreen(Name: string, OffsetX: number? [ 0 ], OffsetY: number? [ 0 ])

• Creates a Dear ImGui window which takes up the entire screen

function imgui.beginmainmenubar(): boolean

• ImGui::BeginMainMenuBar

function imgui.beginmenu(Name: string, Enabled: boolean?): boolean

• ImGui::BeginMenu

function imgui.beginmenubar(): boolean

• ImGui::BeginMenuBar

function imgui.beginpopup(Name: string): boolean

• ImGui::BeginPopup

function imgui.beginpopupmodal(Name: string, HasCloseButton: boolean? [ false ]): boolean

• ImGui::BeginPopupModal

function imgui.begintooltip(): boolean

• ImGui::BeginTooltip

function imgui.button(Text: string, Width: number?, Height: number?): boolean

• ImGui::Button

function imgui.checkbox(Name: string, Value: boolean): boolean

• ImGui::Checkbox

function imgui.closecurrentpopup()

• ImGui::CloseCurrentPopup

function imgui.collapsingheader(Label: string): boolean

• ImGui::CollapsingHeader

function imgui.combo(Text: string, Options: { string }, CurrentOption: number): number, boolean

• ImGui::Combo
• Returns the selected option index, as well as whether the option was changed

function imgui.contentregionavail(): vector

• ImGui::GetContentRegionAvail

function imgui.cursorposition(): vector

• Returns the current position of the Dear ImGui element cursor within the current window
• To set the cursor position, use .setcursorposition

function imgui.demowindow(HasCloseButton: boolean?): boolean

• Renders the Dear ImGui demo window (ImGui::ShowDemoWindow)

function imgui.dummy(Width: number? [ 0 ], Height: number? [ 0 ])

• ImGui::Dummy

function imgui.endchild()

• ImGui::EndChild

function imgui.endmainmenubar()

• ImGui::EndMainMenuBar

function imgui.endmenu()

• ImGui::EndMenu

function imgui.endmenubar()

• ImGui::EndMenuBar

function imgui.endpopup()

• ImGui::EndPopup

function imgui.endtooltip()

• ImGui::EndTooltip

function imgui.endw()

• ImGui::End, endw and not end because end is a Luau keyword

function imgui.focuskeyboardhere(Offset: number?)

• ImGui::SetKeyboardFocusHere

function imgui.getscrollmaxx(): number

• ImGui::GetScrollMaxX

function imgui.getscrollmaxy(): number

• ImGui::GetScrollMaxY

function imgui.getscrollx(): number

• ImGui::GetScrollX

function imgui.getscrolly(): number

• ImGui::GetScrollY

function imgui.getstylecolor(Token: EnumImGuiColor): { number }

• Gets the current applied style color for a given style token as an array of 4 numbers for RGBA

function imgui.image(ImagePath: string, Size: vector?, FlipVertically: boolean? [ false ], TintColor: { number }? [ { 1, 1, 1, 1 } ], LinearlySmooth: boolean? [ true ])

• ImGui::Image

function imgui.imagebutton(Name: string, Image: string, Size: vector?): boolean

• ImGui::ImageButton

function imgui.indent(Indent: number?)

• ImGui::Indent

function imgui.inputnumber(Text: string, Value: number): number, boolean

• ImGui::InputDouble

function imgui.inputstring(Name: string, Value: string, IsPassword: boolean?): string, boolean

• ImGui::InputText

function imgui.ispopupopen(Name: string): boolean

• ImGui::IsPopupOpen

function imgui.itemactive(): boolean

• ImGui::IsItemActive

function imgui.itemclicked(EnumMouseButton?): boolean

• ImGui::IsItemClicked

function imgui.itemdeactivatedafteredit(): boolean

• ImGui::IsItemDeactivatedAfterEdit

function imgui.itemhovered(): boolean

• ImGui::IsItemHovered

function imgui.menuitem(Text: string, Enabled: boolean? [ true ]): boolean

• ImGui::MenuItem

function imgui.newline()

• ImGui::Newline

function imgui.openpopup(Name: string)

• ImGui::OpenPopup

function imgui.popid()

• ImGui::PopID

function imgui.popstylecolor()

• ImGui::PopStyleColor

function imgui.pushid(Id: string)

• ImGui::PushID

function imgui.pushstylecolor(Token: EnumImGuiColor, Color: { number })

• ImGui::PushStyleColor
• Color is an array with 4 numbers representing R, G, B, and A

function imgui.radiobutton(Label: string, Active: boolean): boolean

• ImGui::RadioButton

function imgui.rgbaedit(Label: string, Color: { number }): boolean

• ImGui::ColorEdit4
• The table should have exactly 4 elements
• Note that this edits the table in-place

function imgui.rgbedit(Label: string, Color: { number }): boolean

• ImGui::ColorEdit3
• The table should have exactly 3 elements
• Note that this edits the table in-place

function imgui.sameline()

• ImGui::SameLine

function imgui.scalefactor(): number

• UI scale factor

function imgui.scrollherex()

• ImGui::SetScrollHereX

function imgui.scrollherey()

• ImGui::SetScrollHereY

function imgui.separator()

• ImGui::Separator

function imgui.separatortext(Text: string)

• ImGui::SeparatorText

imgui.setclipboardtext(Text: string) -> ()

• Sets clipboard text

imgui.setcursorposition((Position: vector) -> ()) & ((X: number, Y: number) -> ())

• Sets the position of the Dear ImGui element cursor within the current window

function imgui.setitemtooltip(Text: string)

• ImGui::SetItemTooltip

function imgui.setnextitemopen(Open: boolean?)

• Forces the state of the next item to be open or closed
• ImGui::SetNextItemOpen

function imgui.setnextitemwidth(Width: number)

• Sets the width of the next item
• ImGui::SetNextItemWidth

function imgui.setnextwindowfocus()

• ImGui::SetNextWindowFocus

function imgui.setnextwindowopen(Open: boolean? [ true ])

• ImGui::SetNextWindowCollapsed(!Open)

function imgui.setnextwindowposition(X: number, Y: number)

• `ImGui::SetNextWindowPos

function imgui.setnextwindowsize(Width: number, Height: number)

• ImGui::SetNextWindowSize

function imgui.setstylecolor(Token: EnumImGuiColor, Color: { number })

• Directly sets a style color. "Colors" are 4-channel RGBA

function imgui.settooltip(Tooltip: string)

• ImGui::SetTooltip

function imgui.setviewportdockspace(PositionX: number, PositionY: number, SizeX: number, SizeY: number)

• Sets the region of the window in which Dear ImGui windows can be docked

function imgui.setviewportdockspacedefault()

• Reverts the region of the window in which Dear ImGui windows can be docked to the default settings

function imgui.stylecolors(Theme: 'l' | 'd' | 'c')

• ImGui::StyleColorsDark/ImGui::StyleColorsLight/ImGui::StyleColorsClassic

function imgui.text(Text: string)

• ImGui::Text

function imgui.textlink(Text: string): boolean

• ImGui::TextLink

function imgui.textsize(Text: string): vector

• ImGui::CalcTextSize

function imgui.treenode(Text: string, Flags: string?): boolean

• ImGui::TreeNode
• Accepts flags: sl - Selected, sc - Span All Columns, fr - Framed, fw - Span Full Width, ao - Allow Overlap, ar - Open on Arrow, aw - Span Available Width, np - No Tree Push On Open, do - Default Open, dc - Open On Double Click, dlx - Draw Lines None, dln - Draw Lines to Nodes, dlf - Draw Lines Full, lf - Leaf, lw - Span Label Width, lsc - Span All Columns, b - Bullet, p - Frame Padding, c - Collapsing Header. and | are considered whitespace

function imgui.treepop()

• ImGui::TreePop

function imgui.urllink(Text: string, Url: string? [ Text ]): boolean

• Similar to imgui.textlink, however, will open the given URL upon being clicked
• Url will be Text if not provided
• ImGui::TextLinkOpenUrl

function imgui.windowappearing(): boolean

• ImGui::WindowAppearing

function imgui.windowhovered(Flags: string? [ nil ]): boolean

• ImGui::IsWindowHovered

function imgui.windowposition(): vector

• Returns the position of the current Dear ImGui window (ImGui::GetWindowPos)
• To set the position of the window, use .setnextwindowposition

function imgui.windowsize(): vector

• Returns the size of the current window

fs

• Interacting with the player's filesystem
• Several aliases may be used with functions in this library, these are unrelated to require aliases although the same syntax is used
• The following aliases are provided as part of the API:
• • self: The current script file
• • selfdir: The containing directory of the current script file
• • project: Path to the current project folder
• • home: The player's user profile directory
• • plugin: Only valid in Editor plugins. The directory of the plugin, if it is not a single-file .luau
• These may be used in a manner such as fs.write("@project/savefile.json", saveData)
• Other aliases may also exist, however they are strictly internal and should not be explicitly used
• Avoid overwriting the base alias as this may cause certain default assets to stop loading
• Aliases beginning with _ may only be defined or remove by the root Luau VM

function fs.copy(From: string, To: string)

• Copies the file/directory at the given path to a new path
• If unsuccessfully, throws an error message

function fs.cwd(): string

• Returns the Current Working Directory of the Engine

function fs.definealias(Alias: string, For: string)

• Defines an alias for the filesystem, such that @<Alias>/ refers to <For>/ to the Engine

function fs.execute(Command: string): string

• Executes a shell command

function fs.exists(Path: string): boolean

• Whether a filesystem entry exists at the provided path

function fs.home(): string

• Fetches the user's 'home' or profile directory
• Returns the Current Working Directory if it cannot be determined

function fs.isdirectory(string): boolean

• Returns whether the specified Path refers to a directory

function fs.isfile(string): boolean

• Returns whether the specified Path refers to a file

function fs.issymlink(Path: string): boolean

• Returns whether the node at the specified path is a symbolic link

function fs.lastwritten(Path: string): number

• Returns the timestamp for when the file was last modified, in seconds since epoch

function fs.listdir(Path: string, Filter: ('a' | 'f' | 'd')? [ 'a' ]): { [string]: 'f' | 'd' }

• Returns a table of all the entries in the specified directory
• The keys of the table is the path of the entry, while the values are the type of the entry
• f is file, d is directory, and a is all

function fs.mkdir(Path: string)

• Creates a directory at the given path
• Throws an error upon failure

function fs.move(CurrentPath: string, NewPath: string)

• Moves a file or folder to a new path

function fs.promptopen(DefaultLocation: string? [ './'  ], Filter: ( { string } | string)? [ '*.*' ], FilterName: string? [ 'All files' ], AllowMultipleFiles: boolean? [ false ]): { string }

• Prompts the player to select a file to open
• Returns the list of files the player selected, or an empty list if the player cancelled the dialog
• If the operation fails, returns nil instead

function fs.promptopenfolder(Title: string, DefaultDirectory: string?): string?

• Prompts the user to select a folder
• Returns nil if no selection was made

function fs.promptsave(DefaultLocation: string? [ './' ], Filter: ( { string } | string)? [ '*.*' ], FilterName: string? [ 'All files' ]): string?

• Prompts the player to select a path to save a file to
• Returns the path the player selected, or nil if they cancelled the dialog

function fs.read(Path: string): string?, string?

• Reads the file at the given address, and returns the contents
• If the file could not be read, returns nil and an error message

function fs.readsymlink(Path: string): string

• Returns what the target of the symlink at the given path is

function fs.remove(Path: string)

• Removes everything at the given path
• Throws an error upon failure

function fs.removealias(Alias: string)

• Removes an alias previously defined with fs.definealias

function fs.rename(Path: string, NewName: string)

• Renames the file at the given Path to have the NewName
• Throws an error upon failure

fs.resolvepath(Path: string) -> string

• Resolves the aliases of the path, converting it into the form ./path or leaving it as another qualified variant

fs.resolvepathabsolute(Path: string) -> string

• Same asfs.resolvepath, however converts path in the CWD-relative form (./path) to be absolute (relative to system root directory)

function fs.setunqualifiedroot(Alias: string)

• Changes the meaning of non-qualified paths (e.g.: not beginning with . or C: etc) to act as aliases to the given path + resources/ instead of referring to the CWD
• The default is ./

function fs.symlink(Path: string, Target: string)

• Creates a symlink at Path referring to Target

function fs.systemopen(Path: string)

• Opens the given path with the system's registered handler
• Can be a path to a folder, a file, or a URL

function fs.tempdir(): string

• Returns a path to the system's temporary directory (such as /tmp or %TEMP%)

function fs.watch(Path: string, Callback: (Path: string, Event: EnumFileSystemEvent) -> ()): () -> ()

• Watch a file or directory for changes
• Returns a function that, when called, disconnects the listener

function fs.write(Path: string, Contents: string | buffer, CreateDirectories: boolean? [ false ])

• Overwrites/creates the file at Path with the provided Contents
• Throws an error upon failure
• If CreateDirectories is true, will automatically create missing intermediate directories to the file

parallel

• Parallelization of Luau

function parallel.atomicinteger(Id: string, InitialValue: number?): AtomicInteger

• Creates/finds an atomic integer with a matching ID

function parallel.desynchronize()

• Yields the thread until the parallel phase

function parallel.mutex(Id: string): Mutex

• Create/find a mutex

function parallel.sharedbuffer(Id: string, Size: number --[[| integer]]): SharedBuffer

• Create/find a shared buffer

function parallel.spawn(FilePath: string, ...unknown)

• Spawns a new parallel routine in a parallel VM
• Passed arguments will be available to the spawned script through ... in the top-level scope

function parallel.synchronize()

• Yields the thread until the serial phase

function parallel.synchronized(): boolean

• Returns whether the current thread is synchronized with the main thread

json

• Encoding and decoding JSON files

function json.encode(Value: JsonEncodable, Indent: number?): string

• Encodes the provided value into a JSON string. The default indentation is 2 spaces

function json.parse(Json: string): JsonDecodable

• Decodes the JSON string and returns it as a value

task

• Scheduling of tasks (coroutines or functions)

function task.defer<A..., R...>(Task: ((A...) -> R...) | thread, A...): thread

• Schedules the given function or coroutine to be resumed at the next scheduler step

function task.delay<A..., R...>(Delay: number, Task: ((A...) -> R...) | thread, A...): thread

• Schedules the given function or coroutine to be resumed some number of seconds later

function task.load(Code: string, ChunkName: string?): thread?, string?

• Like loadstring in other runtimes, however does not compromise Global Import optimizations and returns a coroutine instead of a function
• If an error occurs, returns nil as the first value and the error message as the second value

function task.loadfile(File: string, ChunkName: string?): thread?, string?

• Similar to loadthread, however loads from a file instead of from a string directly

function task.setglobal(Coroutine: thread, Global: string, Value: unknown)

• Sets a global for a given coroutine

function task.spawn<A..., R...>(Task: ((A...) -> R...) | thread, A...): thread

• Runs the given function or coroutine immediately. If it yields, the calling thread continues running

function task.wait(SleepTime: number?): number

• Yields the thread for the specified number of seconds. Default is 0

system

• Information about the player's system

function system.freememory(): number

• The amount of free memory the system has, in bytes

function system.hostname(): string

• The name of the system

function system.threadcount(): number

• The number of CPU threads the system has available

function system.totalmemory(): number

• The total amount of memory the system has, including memory in use, in bytes

Globals

Additional global variables

_VMNAME: string

• A non-unique identifier for the current Luau VM

function appendlog<T...>(...: T...): ()

• Same as print, but does not prefix the log message with [INFO]

game: GameObject & EcDataModel

• The GameObject acting as the Data Model of the Engine

function warn<T...>(...: T...): ()

• Same as print, except generates a Warning message