API ‐ Components

The Engine has a compositional object system. GameObjects have "base" APIs (properties, methods, events) that can be extended by giving them "components." These are transparent to scripts, adding a Component immediately makes their properties etc accessible via the Object. All components, as well as the base API, are described below.

`GameObject`

Properties:

Enabled: boolean: If this is false, the Engine will not render, compute physics for or otherwise update this Object and its subtree
Name: string: The name of the Object, usually what was passed into GameObject.new
ObjectId: number : The ID of the Object, an integer. Remains the same throughout the session, but not guaranteed between sessions
Parent: GameObject?: The hierarchal parent of the Object, or nil if it does not have one
Serializes: boolean: Whether or not the Object should be saved with the scene if it is serialized with scene.save, and whether :Duplicate will duplicate it (only applies to descendants)

Methods:

AddComponent(keyof<Creatables>) : (): Adds the specified Component to the Object. Will error if it already has it (use :HasComponent to check beforehand)
AddTag(string) : (): Adds a Collections tag to the Object. Has no effect if the Object already has the tag
Destroy() : (): Marks the Object as "pending for destruction". This may or may not remove the Object from memory immediately, depending on whether the Engine is keeping a internal reference to it
Duplicate<T>(self & T) : (GameObject & T): Creates a duplicate of the Object
FindChild(string) : (GameObject?): Returns a child Object with the given name, or nil if one doesn't exist
FindChildWithComponent(keyof<Creatables>) : (GameObject): Returns a child Object which has the given component, or nil if one doesn't exist
ForEachChild(self, Callback: (Object: GameObject) -> boolean?) : (): For all children of the Object, invokes the callback. If the callback explicitly returns false, iteration ends early. Callback cannot yield
ForEachDescendant(self, Callback: (Object: GameObject) -> boolean?) : (): For all descendants of the Object, invokes the callback. If the callback explicitly returns false, iteration ends early. Callback cannot yield
GetChildren() : { GameObject }: Returns a list of the Object's direct children
GetComponents() : keyof<Creatables>: Returns a list of the names of all Components that the Object currently has
GetDescendants() : { GameObject }: Returns all descendants of the Object (i.e. its children, and their children, etc)
GetFullName() : (string): Returns the full, hierarchal path of the Object
GetTags() : { string }: Returns a list of all tags the Object has
HasComponent(keyof<Creatables>) : (boolean): Returns whether or not the Object has the given Component
HasTag(string) : (boolean): Returns whether or not the Object has the given Collections tag
MergeWith(GameObject) : (): Merges the Objects together, replacing descendants with the same name
RemoveComponent(keyof<Creatables>) : (): Removes the specified Component from the Object. Will error if does not have it (use :HasComponent to check beforehand)
RemoveTag(string) : (): Removes the given Collections tag from the Object. Has no effect if the Object does not have the tag

Events:

OnTagAdded(string): Fires when the Object receives a new tag, passing the tag to the callback
OnTagRemoved(string): Fires when the Object loses a tag, passing the tag to the callback

`Animation`

Represents an Animation
Not functional currently

Properties:

Animation: string: The animation file
Looped: boolean: Whether the Animation should loop when it reaches the end
Playing: boolean: Whether the Animation is playing
Ready: boolean : Whether the Animation can be played
Weight: number: The influence the Animation has over the rig

`AssetManager`

Used to manipulate assets within the Engine

Methods:

GetMeshData(string) : MeshAssetData: Returns the provided mesh data associated with the provided path
ImportModel(string) : GameObject & Model: Imports the glTF 2.0 model at the provided path and returns it as a Model GameObject
LoadScene(string) : ({ GameObject }?, string): Loads GameObjects from the scene file at the provided path, returning a list of the root objects or nil and an error message upon failure
QueueLoadTexture(string, boolean, boolean) : (): Queues a texture to be loaded
SaveMesh(string, string) : (): Saves the mesh data at the provided path to a file
SaveScene(self, RootNodes: { GameObject }, Path: string) : (boolean, string?): Saves the list of GameObjects to the provided path, returning whether the operation succeeded
SetMeshData(self, Id: string, MeshData: MeshAssetData | buffer) : (): Associates the provided mesh data with the provided path
UnloadMaterial(string) : (): Removes the given Material path from the Engine's cache
UnloadMesh(string) : (): Removes the given Mesh path from the Engine's cache
UnloadTexture(string) : (): Removes the given texture from the Engine's cache, forcing it to be reloaded upon next use

`Bone`

Represents a Bone of a Mesh
Created automatically when the asset of a Mesh component finishes loading

Properties:

IsActive: boolean : Whether or not the Bone Object is actively affecting a Mesh
SkeletalBoneId: number : The internal ID of the bone, valid range is 0-255
TargetMesh: GameObject : The Mesh component containing Object the Bone is currently targeting. Note that this property is read-only, and will only either be equal to the Mesh that created the Bone, or nil
Transform: Matrix: The transformation of the Bone

`Camera`

A 3D camera

Properties:

FieldOfView: number: The field-of-view. By default, 90
UseSimpleController: boolean: Whether it is affected by the built-in controller (W/A/S/D horizontal movement, Q/E vertical, Mouse to look around)

`Collections`

Manage Collections of Objects with tags
An Object can have any number of tags
Tags can be added to Objects with Object:AddTag, removed with Object:RemoveTag, and checked with Object:HasTag

Methods:

GetCollections() : { string }: Returns a list of all collections that the Collections system has recognized. They may be empty. Order is not guaranteed
GetTagAddedSignal(string) : EventSignal<GameObject>: Returns a signal that fires when the given tag is added to any Objects
GetTagRemovedSignal(string) : EventSignal<GameObject>: Returns a signal that fires when the given tag is removed from any Objects, including when an Object with a tag is :Destroy'd
GetTagged(string) : { GameObject }: Returns a list containing all Objects with the given tag

`DataModel`

The root of the scene

Properties:

AreScriptsBound: boolean : If this is true, attempting to change .LiveScripts will throw an error
LiveScripts: string: May either refer to a directory of Scripts, or a single Script, to run when the DataModel is bound
Time: number : Number of seconds since the Engine started running
VM: string: The Luau Virtual Machine that Scripts bound to this Data Model will run in

Methods:

BindToClose(self, Callback: () -> ()) : (): Sets a callback that is invoked when the datamodel is being destroyed. May only be called once. Callback cannot yield
GetService<T>(self, Service: keyof<Services> & T) : GameObject & index<Services, T>: Gets the Object representing the specified Service. If it does not exist yet in the Data Model, it is created

Events:

OnFrameBegin(number): Fires at the beginning of a frame, passing in the time elapsed since the last frame (delta time)

`DeveloperTools`

Built-in development tools

Properties:

DocumentationShown: boolean: Whether the Documentation tool is enabled
ExplorerShown: boolean: Whether the Explorer tool is enabled
InfoShown: boolean: Whether the Info tool is enabled
Initialized: boolean : Whether developer tools were ever initialized
MaterialsShown: boolean: Whether the Materials tool is enabled
PropertiesShown: boolean: Whether the Properties tool is enabled
RendererShown: boolean: Whether the Renderer tool is enabled
ScriptsShown: boolean: Whether the Scripts tool is enabled
SettingsShown: boolean: Whether the Settings tool is enabled
ShadersShown: boolean: Whether the Shaders tool is enabled

Methods:

GetExplorerSelections() : ({ GameObject }): Returns what is currently selected in the Explorer
GetToolNames() : { string }: Returns a list of valid Engine tools
Initialize() : (): Initializes the developer tools system if it was not already initialized
IsToolEnabled(string) : (boolean): Returns whether the given tool is enabled
OpenTextDocument(string, number?) : (): Opens a text file. This requires Developer Mode to be enabled to have any effect
SetExplorerRoot(GameObject) : (): Changes the Root of the built-in Explorer's hierarchy view
SetExplorerSelections({ GameObject }) : (): Changes the built-in Explorer's Object selections to the specified Objects
SetToolEnabled(string, boolean) : (): Enabled/disables the given tool

`DirectionalLight`

Intended to model a large light source infinitely far away, like the Sun

Properties:

Brightness: number: How bright the Light is
Direction: vector: The direction light is emitted from
LightColor: Color: The color of the Light
ShadowViewDistance: number: How far back the shadow view is offset from the focus
ShadowViewFarPlane: number: The Far Z plane of the shadow view. Should be greater than ShadowViewNearPlane
ShadowViewMoveWithCamera: boolean: Sets the focus of the shadow view to be the Scene Camera
ShadowViewNearPlane: number: The Near Z plane of the shadow view. Should be less than ShadowViewFarPlane. Shouldn't be 0
ShadowViewOffset: vector: Offset of the shadow view from the focus, after ShadowViewDistance is applied
ShadowViewSize: number: Size of the shadow view. Sets ShadowViewSizeH and ShadowViewSizeV to the assigned value if they are equal. Is -1 if they are not equal
ShadowViewSizeH: number: Horizontal size of the shadow view
ShadowViewSizeV: number: Vertical size of the shadow view
Shadows: boolean: Whether the Light can render shadows

`Engine`

Inspect and manipulate various parts of the Engine

Properties:

BoundDataModel: GameObject : The DataModel object that is currently bound
CommitHash: string : The Git commit that was used to produce this Engine build
Framerate: number : The Engine's current framerate
FramerateCap: number: The maximum framerate the Engine will reach before attempting to self-limit
IsHeadless: boolean : Whether the Engine is currently running in headless mode
TargetPlatform: string : The target platform the Engine was compiled for (Windows or Linux, usually)
Version: string : The version of the Engine build

Methods:

BindDataModel( GameObject & DataModel ) : (): Switches Data Models to the specified Object
CloseVM(string) : (): Closes the specified Luau VM, releasing its resources
CreateVM(string) : (): Creates a new Luau VM with the given name. The workspace and game globals of the VM are taken from the currently-bound DataModel
Exit(number?) : (): Shuts down the Engine and exits the process with the specified Exit Code (or 0 by default)
GetCliArguments() : { string }: Returns the list of launch arguments given to the Engine. The first item is always a path to the Engine executable
GetConfigValue(self, Key: string) : (JsonSerializable): Returns the value associated with the given Key in the Engine's loaded configuration (phoenix.conf)
RunInVM(string, string, string?) : (boolean, string?): Runs the given code in the specified VM. Returns false and an error message upon failure or if the code does not finish executing (yield or break)
SaveConfig() : (boolean, string): Saves the Engine's current configuration state to the configuration file (phoenix.conf)
SetConfigValue(self, Key: string, Value: JsonSerializable) : (): Sets Key to Value in the Engine's loaded configuration without saving it to file
ShowMessageBox(self, Title: string, Message: string, Buttons: 'ok' | 'okcancel' | 'yesno' | 'yesnocancel' | nil, Icon: 'info' | 'warning' | 'error' | 'question' | nil, DefaultButton: number?) : (number): Shows a message box to the player with the given specification. The returned number with be the selected option: 0 for Cancel/No, 1 for Ok/Yes, 2 for No in yesnocancel. This is a blocking operation and no scripts or other parts of the Engine run until the message is dismissed. Avoid using quotes and backticks in the message

`Environment`

World lighting and ambiance

Properties:

AmbientLight: Color: Base environment ambient light color (Uniform: Phoenix_LightAmbient)
Fog: boolean: Fog enablement (Uniform: Phoenix_Fog)
FogColor: Color: Color of the fog (Uniform: Phoenix_FogColor)
GammaCorrection: number: Post-processor gamma correction amount (Uniform: Phoenix_Gamma)
PostProcess: boolean: Post-processor enablement (Uniform: Phoenix_PostFxEnabled)

`History`

Service for implementing Undo/Redo systems

Properties:

ActionHistorySize: number : The total number of Actions that have finished being recorded
CanRedo: boolean : Whether :Redo will succeed
CanUndo: boolean : Whether :Undo will succeed
CurrentActionName: string? : The name of the Action currently being recorded, or nil if no recording is in progress
CurrentWaypoint: number : The ID of the Action that was last finished
IsRecordingAction: boolean : Whether an Action is currently being recorded by History
TargetDataModel: GameObject: The DataModel that History will track

Methods:

ClearHistory() : (): Clears all recorded history
DiscardAction(number) : (): Discards the Action by its ID
EnableRecording() : (): Enables the main functionality of this service
FinishAction(number) : (): Finishes the Action by its ID. Only one Action may be active at a time
GetActionData(number) : HistoryAction: Retrives information about a previously-recorded Action by its Index (Indexes, separate from IDs, are in the range 0 <= Index < ActionHistorySize)
GetCannotRedoReason() : (string): Returns a message explaining why .CanRedo is false
GetCannotUndoReason() : (string): Returns a message explaining why .CanUndo is false
GetCurrentActionData() : HistoryAction?: Retrieves information about the current Action being recorded
Redo() : (): Forwards the state of the scene to how it was before the last Undo. If .CanRedo is false, will throw an error
TryBeginAction(string) : (number?): Attempts to begin an "Action." Returns the ID of the action. May fail and return nil. Only one Action may be active at a time
Undo() : (): Reverses the state of the scene to how it was before the last Action began. If .CanUndo is false, will throw an error

`Interface`

Contains the player's interface elements
See UITransform, UIFrame, UIText, UIImage, and UIButton

No members defined

`Logging`

Engine logging

Methods:

Write(self, Message: string, Type: EnumLogType, ExtraTags: string?) : (): Log a message

Events:

OnMessaged(number, string, string, unknown): Fires whenever a Log Message is created

`Mesh`

A mesh composed of triangles

Properties:

CastsShadows: boolean: Whether it casts shadows
FaceCulling: EnumFaceCulling: Which faces of the mesh to cull based on viewing direction. See the FaceCulling enum
Material: string: The name of the .mtl in the resources/materials/ directory it should use
MeshAsset: string: The path to the underlying .hxmesh file, or a built-in identifier like !Quad or !Cube
MetalnessFactor: number: Metalness modifier
RoughnessFactor: number: Roughness modifier
Tint: Color: The Color it should be tinted with
Transparency: number: Its transparency/translucency

`Model`

A container

Properties:

ImportPath: string: The original file a model was imported from

`Network`

Networking

Methods:

MakeHttpRequestAsync(self, { Url: string, Method: nil | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', Headers: { [string]: string }?, Body: string? }) : ({ Ok: boolean, Status: number, Headers: { [string]: string }, Body: string }): Makes an HTTP request to the provided URL. Ok will be false upon failure, and Body will contain the error message

`ParticleEmitter`

An emitter of 2D particles

Properties:

BilinearFiltering: boolean: Whether the particle image is smoothened
Emitting: boolean: Whether the emitter should emit new particles
Image: string: The path to the image to use for the particles
Lifetime: vector: The X and Y components act as a range of how long any particle can last, in seconds
ParticlesAreAttached: boolean: Whether the particles are attached to and move with the emitter
Rate: number: An integer indicating how many particles should be emitted per second (must be above or equal to 0)

`Physics`

Manipulate the Physics simulation of the Engine

Properties:

DebugCollisionAabbs: boolean: Whether physics collision AABBs are rendered
DebugContactPoints: boolean: Whether Contact Points are rendered
DebugSpatialHeat: boolean: Whether Spatial Heat (spatial hash density) debug rendering is enabled
Gravity: vector: The gravitational field strength
Simulating: boolean: Whether the Physics simulation is running. IMPORTANT: The Editor sets this value to true and false when starting/stopping playtests
Timescale: number: Slow-down or speed-up the simulation by changing this value from 1

`PlayerInput`

Checking player inputs

Properties:

Cursor: EnumCursor: The look of the cursor. See Enum.Cursor. Setting this property is slow as it needs to poll the OS, avoid placing it in hot loops
CursorMode: EnumCursorMode: The current mode/behaviour of the cursor. Refer to the Enum.CursorMode enumeration
IsKeyboardSunk: boolean : Whether the Engine is currently using keyboard input (such as for Dear ImGui). Do not process keyboard input if this is true
IsMouseSunk: boolean : Whether the Engine is currently using mouse input (such as for Dear ImGui). Do not process mouse input if this is true

Methods:

GetCursorPosition() : (vector): Returns the current position of the mouse cursor relative to the window as a vector
IsKeyPressed(self, Key: EnumKey) : (boolean): Returns whether the specified key (e.g. Enum.Key.A, Enum.Key.One) is currently being pressed
IsMouseButtonPressed(self, Button: EnumMouseButton) : (boolean): Returns whether the specified mouse button (Enum.MouseButton.Left/Middle/Right) is currently being pressed
ResetViewportInputRect() : (): Resets the Engine's understanding of where the viewport is on screen back to the default (occupying the entire window)
SetViewportInputRect(vector, vector) : (): Configures the Engine to act as through the Viewport is at the given position with the given size. Does not change where the viewport is actually rendered

Events:

KeyEvent(InputEvent): Fires whenever a key-related event occurs
MouseButtonEvent(InputEvent): Fires whenever a mouse-button-related event occurs
ScrollEvent(InputEvent): Fires whenever the player scrolls with a scroll device (such as the mouse wheel)

`PointLight`

A light source emitting light omnidirectionally from its Transform

Properties:

Brightness: number: How bright the Light is
LightColor: Color: The color of the Light
Range: number: How far light is emitted. If >= 0, the Range is used and attenuation is linear, otherwise it uses the formula F = 1/D^2 * B to mirror real-world attenuation, where F is the final brightness, D is the distance of a point from the Light, and B is the Brightness property's value

`Renderer`

Interfacing with the Engine's rendering systems

Properties:

DebugWireframeRendering: boolean: Whether the Wireframe rendering debug mode is enabled
IsFullscreen: boolean: Whether the Window is currently fullscreened
Resolution: vector: The size of the window, in pixels
VSync: boolean: Whether Vertical Synchronization is enabled

Methods:

SetShaderTextureVariable(string, string, string, boolean, boolean) : (): Sets a variable in a shader program to a 2D texture sampler for the provided image. The program will be loaded if it is not already in memory
SetShaderVariable(self, Shader: string, Variable: string, Value: boolean | number | vector | Color | Matrix, Type: EnumValueType?) : (): Sets a variable in a shader program (qualified uniform). The program will be loaded if it is not already in memory. Type is required when passing a vector, to differentiate between Vector2 and Vector3. See Enum.ValueType

`RigidBody`

Something rigid that participates in the Physics simulation

Properties:

AngularVelocity: vector: Its rotational velocity
CollisionType: EnumCollisionType: Determines how collisions are detected. See the CollisionType enum
Density: number: Its density (Mass = Density * Size)
Friction: number: Fraction of Velocity it should lose per second while in contact with another object while PhysicsDynamics is true
GravityFactor: number: Influence of the force of gravity
HullsFile: string: The file containing a set of convex hull meshes to load. Used for when .CollisionType is Hulls
LinearVelocity: vector: Its velocity
PhysicsCollisions: boolean: Whether other physics objects can collide with it
PhysicsDynamics: boolean: Whether the Physics engine should apply forces to it
PhysicsRotations: boolean: Whether the Physics engine will apply angular impulses to rotate the object on collisions. Prefer to keep this at false as the simulation is not very precise
Restitution: number: Restitution

`Sound`

A sound

Properties:

FinishedLoading: boolean : Whether the Sound has finished loading the SoundFile
Length: number : The length of the sound in seconds
LoadSucceeded: boolean : Whether or not the sound loaded successfully
Looped: boolean: Whether playback should loop once it reaches the end
Playing: boolean: Whether the Sound is currently playing (or requested to play, if .Playing is set to true by a Script before it has finished loading)
Position: number: The time-position of playback in number of seconds from the beginning of the file
SoundFile: string: The sound file to be played
Speed: number: The speed at which the sound plays, within the range of 0.01 to 100
Volume: number: The volume at which the sound plays. Must be positive

Methods:

Play() : (): Plays the Sound from the beginning

Events:

OnLoaded(boolean): Fires when the Sound finishes loading, and whether it loaded successfully or not

`SpotLight`

A light which emits in a conical shape

Properties:

Angle: number: The Field-of-View (in radians) of light emission
Brightness: number: How bright the Light is
LightColor: Color: The color of the Light
Range: number: How far light is emitted

`Transform`

Gives a physical position and size to an Object

Properties:

LocalSize: vector: The Object's scale factor, relative to it's parent Transform ancestor or the world origin
LocalTransform: Matrix: The Object's transformation, relative to it's parent Transform ancestor or the world origin
Size: vector : The Object's world-space scale factor
Transform: Matrix : The Object's world-space transformation

`TreeLink`

The Engine, for rendering and physics, will pretend the children of this Object's Target are the children of the node
This is not intended to act like a transparent proxy

Properties:

Target: GameObject?: The target to link

`UIButton`

Button behaviour

Events:

OnClicked(): nil

`UIFrame`

A frame

Properties:

BackgroundColor: Color: The color of the frame
BackgroundTransparency: number: Its transparency

`UIImage`

An image element

Properties:

Image: string: The path to the image
ImageTint: Color: The color the image is tinted with
ImageTransparency: number: Its transparency

`UIText`

Text (not functional)

Properties:

Text: string: The text string to be displayed

`UITransform`

Offsets the element tree

Properties:

Position: vector: The 2D position, from 0-1
Rotation: number: The 2D rotation (not functional)
Size: vector: The 2D scale, from 0-1
ZIndex: number: The ordering indexing, higher being further in front (not functional)

`Workspace`

The container used for storing the main parts of a scene (3D objects)
If this is Destroy'd, the application closes

Properties:

SceneCamera: GameObject & Camera & Transform: The Camera the Player sees the world through. If set to nil, a fallback is created at the origin

Methods:

GetObjectsInAabb (Position: vector, Size: vector, IgnoreList: { GameObject }?) : { GameObject & RigidBody & Transform }: Get a list of Objects whose bounds are within the AABB
Raycast (Origin: vector, CastVector: vector, FilterList: { GameObject }?, FilterIsIgnoreList: boolean?) : { Object: GameObject & RigidBody & Transform, Position: vector, Normal: vector }?: Cast a ray. This currently treats collisions as Axis-Aligned Bounding Boxes!
ScreenPointToVector(vector, number?) : (vector): Converts the provided screen coordinates to a world-space direction. Length is optional and 1.0 by default
WorldToScreenPoint(vector) : (vector, number): Converts the provided world coordinate (vector) into its location in screen-space pixel coordinates, additionally returning the depth