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

`Get(): number`

Fetches the value

`Set(Value: number)`

Sets the value

`Color`

An RGB color

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

`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

`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)

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

Connect a callback to the Event

`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.fromComponents(Components: { string }?): GameObject`

Creates an Object with only the specified Components

`GameObject.fromId(Id: number): GameObject?`

Finds an Object by its internal ID. Do not rely on the ID

`GameObject.new(MainComponent: 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)

`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

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

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

`Matrix.new(): Matrix`

`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

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

`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

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

`Matrix.scaled(Scale: vector): Matrix`

Creates a scaled Matrix

`Matrix.translated(Position: vector): Matrix`

`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)

`ExtractAngles(): vector`

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

`Inverse(): Matrix`

Returns the inverse of the Matrix

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

Linearly interpolates to the given Matrix

`WithRotation(Rotation: vector): Matrix`

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

`WithScale(Scale: vector): Matrix`

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

`WithTranslation(Translation: vector): Matrix`

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

`__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

`__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

`Lock()`

`TryLock(): boolean`

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

`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

`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

`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

`debug.profilemessage(Message: string)`

Generates a profiler log message event

`debug.zonebegin(Name: string?)`

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

`debug.zoneend()`

Ends the last profiling zone

`debug.zonetext(Text: string)`

Set additional debug text for the zone

`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

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

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

`fs.cwd(): string`

Returns the Current Working Directory of the Engine

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

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

`fs.execute(Command: string): string`

Executes a shell command

`fs.home(): string`

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

`fs.isdirectory(string): boolean`

Returns whether the specified Path refers to a directory

`fs.isfile(string): boolean`

Returns whether the specified Path refers to a file

`fs.issymlink(Path: string): boolean`

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

`fs.lastwritten(Path: string): number`

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

`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

`fs.mkdir(Path: string)`

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

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

Moves a file or folder to a new path

`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

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

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

`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

`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

`fs.readsymlink(Path: string): string`

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

`fs.remove(Path: string)`

Removes everything at the given path
Throws an error upon failure

`fs.removealias(Alias: string)`

Removes an alias previously defined with fs.definealias

`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 as`fs.resolvepath`, however converts path in the CWD-relative form (`./path`) to be absolute (relative to system root directory)

`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 ./

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

Creates a symlink at Path referring to Target

`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

`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

`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

`imgui`

UI with Dear ImGui

`imgui.anyitemactive(): boolean`

ImGui::IsAnyItemActive

`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)

`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)

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

Creates a Dear ImGui window which takes up the entire screen

`imgui.beginmainmenubar(): boolean`

ImGui::BeginMainMenuBar

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

ImGui::BeginMenu

`imgui.beginmenubar(): boolean`

ImGui::BeginMenuBar

`imgui.beginpopup(Name: string): boolean`

ImGui::BeginPopup

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

ImGui::BeginPopupModal

`imgui.begintooltip(): boolean`

ImGui::BeginTooltip

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

ImGui::Button

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

ImGui::Checkbox

`imgui.closecurrentpopup()`

ImGui::CloseCurrentPopup

`imgui.collapsingheader(Label: string): boolean`

ImGui::CollapsingHeader

`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

`imgui.contentregionavail(): vector`

ImGui::GetContentRegionAvail

`imgui.cursorposition(): vector`

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

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

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

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

ImGui::Dummy

`imgui.endchild()`

ImGui::EndChild

`imgui.endmainmenubar()`

ImGui::EndMainMenuBar

`imgui.endmenu()`

ImGui::EndMenu

`imgui.endmenubar()`

ImGui::EndMenuBar

`imgui.endpopup()`

ImGui::EndPopup

`imgui.endtooltip()`

ImGui::EndTooltip

`imgui.endw()`

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

`imgui.focuskeyboardhere(Offset: number?)`

ImGui::SetKeyboardFocusHere

`imgui.getscrollmaxx(): number`

ImGui::GetScrollMaxX

`imgui.getscrollmaxy(): number`

ImGui::GetScrollMaxY

`imgui.getscrollx(): number`

ImGui::GetScrollX

`imgui.getscrolly(): number`

ImGui::GetScrollY

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

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

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

ImGui::Image

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

ImGui::ImageButton

`imgui.indent(Indent: number?)`

ImGui::Indent

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

ImGui::InputDouble

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

ImGui::InputText

`imgui.ispopupopen(Name: string): boolean`

ImGui::IsPopupOpen

`imgui.itemactive(): boolean`

ImGui::IsItemActive

`imgui.itemclicked(EnumMouseButton?): boolean`

ImGui::IsItemClicked

`imgui.itemdeactivatedafteredit(): boolean`

ImGui::IsItemDeactivatedAfterEdit

`imgui.itemhovered(): boolean`

ImGui::IsItemHovered

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

ImGui::MenuItem

`imgui.newline()`

ImGui::Newline

`imgui.openpopup(Name: string)`

ImGui::OpenPopup

`imgui.popid()`

ImGui::PopID

`imgui.popstylecolor()`

ImGui::PopStyleColor

`imgui.pushid(Id: string)`

ImGui::PushID

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

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

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

ImGui::RadioButton

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

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

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

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

`imgui.sameline()`

ImGui::SameLine

`imgui.scalefactor(): number`

UI scale factor

`imgui.scrollherex()`

ImGui::SetScrollHereX

`imgui.scrollherey()`

ImGui::SetScrollHereY

`imgui.separator()`

ImGui::Separator

`imgui.separatortext(Text: string)`

ImGui::SeparatorText

imgui.setcursorposition((Position: vector) -> ()) & ((X: number, Y: number) -> ())* Sets the position of the Dear ImGui element cursor within the current window

`imgui.setitemtooltip(Text: string)`

ImGui::SetItemTooltip

`imgui.setnextitemopen(Open: boolean?)`

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

`imgui.setnextitemwidth(Width: number)`

Sets the width of the next item
ImGui::SetNextItemWidth

`imgui.setnextwindowfocus()`

ImGui::SetNextWindowFocus

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

ImGui::SetNextWindowCollapsed(!Open)

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

`ImGui::SetNextWindowPos

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

ImGui::SetNextWindowSize

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

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

`imgui.settooltip(Tooltip: string)`

ImGui::SetTooltip

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

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

`imgui.setviewportdockspacedefault()`

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

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

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

`imgui.text(Text: string)`

ImGui::Text

`imgui.textlink(Text: string): boolean`

ImGui::TextLink

`imgui.textsize(Text: string): vector`

ImGui::CalcTextSize

`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

`imgui.treepop()`

ImGui::TreePop

`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

`imgui.windowappearing(): boolean`

ImGui::WindowAppearing

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

ImGui::IsWindowHovered

`imgui.windowposition(): vector`

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

`imgui.windowsize(): vector`

Returns the size of the current window

`json`

Encoding and decoding JSON files

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

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

`json.parse(Json: string): JsonDecodable`

Decodes the JSON string and returns it as a value

`parallel`

Parallelization of Luau

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

Creates/finds an atomic integer with a matching ID

`parallel.desynchronize()`

Yields the thread until the parallel phase

`parallel.mutex(Id: string): Mutex`

Create/find a mutex

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

Create/find a shared buffer

`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

`parallel.synchronize()`

Yields the thread until the serial phase

`parallel.synchronized(): boolean`

Returns whether the current thread is synchronized with the main thread

`task`

Scheduling of tasks (coroutines or functions)

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

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

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

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

`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

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

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

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

Sets a global for a given coroutine

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

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

Globals

Additional global variables

`_VMNAME: string`

A non-unique identifier for the current Luau VM

`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

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

Same as print, except generates a Warning message

`workspace: GameObject & EcWorkspace`

Shorthand for game.Workspace