Ghostlight Lua API

Generated from the framework by shell.cmd docs. Lua names; methods are called with :, class functions with ..

Entities

Character

extends BasePawn · Spawned by server scripts.

A walking character. Lua: Character(location, rotation) default mannequin Character(location, rotation, "/Game/X/SK_Mesh", "/Game/X/ABP_Anim") Character(location, rotation, "/MyContent/BP_Zombie") a Blueprint subclass, with its own mesh and setup Nothing forces the mannequin: any skeletal mesh with an animation Blueprint for its skeleton works. The mannequin is only the fallback.

Constructor

Character(location: Vector, rotation: Rotator, SkeletalMesh: string, AnimationBlueprint: string) → Character

Constructor arguments after location and rotation. Empty keeps what the class (or Blueprint) set up, else the mannequin.

Methods

:GetMaxWalkSpeed() → number

:GetMesh() → string

Asset path of the skeletal mesh.

:IsFalling() → boolean

:Jump()

Jumps, as if the jump key were pressed.

:PlayAnimation(Animation: string, PlayRate: number) → number

Plays a montage or an animation sequence (through the DefaultSlot). Returns its length in seconds, or 0.

:SetAnimationBlueprint(AnimationBlueprint: string)

Sets the animation Blueprint by asset path ("/Game/X/ABP_Anim"); it must target the mesh's skeleton.

:SetAnimationValue(Name: string, Value: any)

Sets a variable on the animation Blueprint instance (bool, number, string, Vector, Rotator).

:SetCameraDistance(Distance: number)

Distance of the third-person camera behind the character.

:SetJumpZVelocity(Velocity: number)

:SetMaxWalkSpeed(Speed: number)

:SetMesh(SkeletalMesh: string)

Sets the skeletal mesh by asset path.

:StopAnimation()

Player

extends BaseEntity · Created by the framework, not by scripts.

A connected player. Created by the framework (one per player controller), never by scripts, and kept across package reloads. Fires Spawn when the player joins (Player.Subscribe("Spawn", fn)) and Destroy when they leave.

Methods

:GetControlledCharacter() → entity

The pawn this player controls, or nil.

:GetControlRotation() → Rotator

Where the player is looking.

:GetName() → string

Display name (player state).

:IsLocalPlayer() → boolean

True for the player at this machine.

:Possess(Pawn: entity)

Takes control of a character (or other pawn). Server only.

:UnPossess()

Releases the controlled pawn. Server only.

Prop

extends BaseActor · Spawned by server scripts.

A static mesh in the world, simulating physics by default. Lua: Prop(location, rotation, mesh_path).

Constructor

Prop(location: Vector, rotation: Rotator, StaticMesh: string) → Prop

Constructor arguments after location and rotation. An empty path uses the engine cube.

Methods

:AddImpulse(Impulse: Vector, VelocityChange: boolean)

Pushes the prop. With bVelocityChange the impulse ignores mass (a direct change in velocity).

:GetMesh() → string

:IsPhysicsEnabled() → boolean

:SetGravityEnabled(Enabled: boolean)

:SetMesh(StaticMesh: string)

:SetPhysicsEnabled(Enabled: boolean)

Whether the prop falls, tumbles and can be pushed. On by default.

WebUI

extends BaseEntity · Client scripts only.

An HTML page drawn over the game (Chromium), as in nanos world. Client scripts only: local hud = WebUI("HUD", "file://UI/index.html") -- in this package's folder hud:Subscribe("Ready", function() hud:CallEvent("SetHealth", 100) end) hud:Subscribe("Buy", function(item, count) ... end) -- page: Events.Call("Buy", "sword", 1) The page gets an Events object: Events.Subscribe(name, fn) receives CallEvent from Lua, Events.Call(name, ...) reaches ui:Subscribe(name, fn). Arguments travel as JSON. Events: Ready (page loaded), Fail(error), Destroy. Files are served from the package, also from the pak in packaged builds, and the page reloads when its folder changes.

Constructor

WebUI(Name: string, Path: string, Visibility: any, Transparent: any, AutoResize: any, Width: integer, Height: integer) → WebUI

WebUI(name, path, visibility, is_transparent, auto_resize, width, height). Path: "file://Folder/page.html" (inside the calling package) or an http(s):// URL. Visibility: WidgetVisibility.Visible (default), .VisibleNotHitTestable or .Hidden. auto_resize (default true) fills the screen; otherwise the page is width x height, centered (see SetLayout).

Methods

:BringToFront()

Draws this page above every other WebUI.

:CallEvent(Event: string, ...: ...)

Calls the page's Events.Subscribe(name, fn) handlers with the arguments (sent as JSON). Queued until the page is ready.

:ExecuteJavaScript(Code: string)

:GetName() → string

The name given to the constructor.

:GetURL() → string

The page's address (https://ui.ghostlight/<package>/... for package files).

:GetVisibility() → integer

:LoadHTML(Html: string)

Shows an HTML string (it can link files of the package that created this WebUI).

:LoadURL(Path: string)

Loads another page: "file://..." from the package that created this WebUI, or an http(s):// URL.

:RemoveFocus()

Returns keyboard focus to the game.

:SetFocus()

Gives the page keyboard focus (typing into its inputs). Pair with Input.SetMouseEnabled(true) for clicks.

:SetLayout(ScreenLocation: any, Size: any, AnchorsMin: any, AnchorsMax: any, Alignment: any)

Position and size on screen, like a UMG canvas slot (Vector2D or {X=, Y=} values): SetLayout(screen_location, size, anchors_min, anchors_max, alignment). Defaults: anchors (0,0)-(1,1) with zero offsets fill the screen.

:SetVisibility(Visibility: integer)

WidgetVisibility.Visible, .VisibleNotHitTestable (clicks go to the game) or .Hidden.

Entity mixins

BaseActor

extends BaseEntity

Entities that exist in the world: transform, visibility, attachment, dimension.

Methods

:AttachTo(Parent: entity, Socket: string, KeepWorldTransform: boolean)

Attaches to Parent (at Socket if given), keeping the world transform or snapping to the parent.

:Detach()

:GetAttachedEntities() → entity[]

:GetAttachedTo() → entity

:GetDimension() → integer

:GetLocation() → Vector

:GetRotation() → Rotator

:GetScale() → Vector

:GetVelocity() → Vector

:IsVisible() → boolean

:SetDimension(Dimension: integer)

Stored and replicated; visibility, collision and relevancy filtering come later. Fires DimensionChange(old, new).

:SetLifeSpan(Seconds: number)

Destroys the entity after Seconds (0 cancels).

:SetLocation(Location: Vector)

:SetRotation(Rotation: Rotator)

:SetScale(Scale: Vector)

:SetVisibility(Visible: boolean)

BaseEntity

The Lua API shared by entities, written once. A function whose first parameter is `Self` becomes an instance method (`entity:GetID()`); other static functions go on the class table (`Prop.Subscribe(...)`), where the class they are called through is available from FLuaCallContext. Classes get these through LuaBase: `LuaClass="Prop", LuaBase="BaseActor"`. Add a function here and every entity with this mixin in its chain has it.

Methods

:Destroy()

:GetID() → integer

Network-stable ID.

:GetValue(Key: string, Fallback: any) → any

:IsValid() → boolean

False once the entity is destroyed (dead handles answer this too).

:SetValue(Key: string, Value: any, SyncOnClients: boolean)

Stores plain Lua data (entities are kept by ID). Fires ValueChange.

:Subscribe(Event: string, Callback: function) → function

entity:Subscribe(event, callback): events of this entity only. Returns the callback.

:Unsubscribe(Event: string, Callback: function)

entity:Unsubscribe(event, callback?): without a callback, removes all of this side's callbacks for the event.

Class functions

BaseEntity.GetAll() → entity[]

Class.GetAll(): every live entity of that class (subclasses included), by ID.

BaseEntity.GetCount() → integer

BaseEntity.Subscribe(Event: string, Callback: function) → function

Class.Subscribe(event, callback): events of every entity of that class (subclasses included).

BaseEntity.Unsubscribe(Event: string, Callback: function)

BasePawn

extends BaseActor

Entities a player can control (Character, later vehicles).

Methods

:GetControlRotation() → Rotator

Where the controller aims (camera direction for players).

:GetPlayer() → Player

The Player controlling this pawn, or nil.

:IsPossessed() → boolean

Static classes

Client

Client: the local player and its camera. Client scripts only.

Functions

Client.GetCameraLocation() → Vector

Client.GetCameraRotation() → Rotator

Client.GetLocalPlayer() → Player

The Player at this machine (also in single player).

Console

Console: script logging. Extra arguments format the message with string.format.

Functions

Console.Error(Message: string, ...: ...)

Console.Log(Message: string, ...: ...)

Console.Warn(Message: string, ...: ...)

Events

Events: custom events, local (Call) and between server and client (CallRemote / BroadcastRemote).

Functions

Events.BroadcastRemote(Event: string, ...: ...)

Server only: to every client. Delivered next tick.

Events.Call(Event: string, ...: ...)

Calls local subscribers immediately.

Events.CallRemote(Event: string, ...: ...)

Client: CallRemote(event, ...) to the server. Server: CallRemote(event, player, ...) to one client. Delivered next tick.

Events.Subscribe(Event: string, Callback: function) → function

Subscribes to Events.Call on this side. Returns the callback.

Events.SubscribeRemote(Event: string, Callback: function) → function

Subscribes to remote events from the other side. Server handlers receive the sending player first.

Events.Unsubscribe(Event: string, Callback: function)

Without a callback, removes all of this side's callbacks for the event.

Events.UnsubscribeRemote(Event: string, Callback: function)

Input

Input: key actions for client scripts.

Functions

Input.Bind(Action: string, Event: string, Callback: function) → function

Input.Bind("SpawnBox", "Pressed" | "Released", callback). Returns the callback.

Input.GetKey(Action: string) → string

The key an action is mapped to, or an empty string.

Input.IsInputEnabled() → boolean

Input.IsMouseEnabled() → boolean

Input.Register(Action: string, Key: string)

Names an action and maps it to a key, e.g. Input.Register("SpawnBox", "E"). Keys use Unreal key names: "E", "SpaceBar", "LeftMouseButton", "LeftShift", "F1", ... Registering a name again remaps it.

Input.SetInputEnabled(Enabled: boolean)

Turns movement and camera input on or off (registered actions keep working).

Input.SetMouseEnabled(Enabled: boolean)

Shows the mouse cursor so WebUI pages can be clicked; the camera stops following the mouse meanwhile.

Input.Unbind(Action: string, Event: string, Callback: function)

Without a callback, removes all of this side's callbacks for the action and event.

Package

Package: the running package's lifecycle (Load, Unload) and sharing with other packages.

Functions

Package.Export(Name: string, Value: any)

Sets a global visible to every package on this side (packages otherwise keep their globals to themselves).

Package.GetName() → string

Package.Subscribe(Event: string, Callback: function) → function

"Load" fires after the package's scripts ran; "Unload" before it is unloaded or reloaded.

Timer

Timer: callbacks after a delay or on an interval, in game time.

Functions

Timer.ClearInterval(TimerId: integer)

Timer.ClearTimeout(TimerId: integer)

Timer.IsValid(TimerId: integer) → boolean

Timer.Pause(TimerId: integer)

Timer.Resume(TimerId: integer)

Timer.SetInterval(Callback: function, IntervalMs: integer, ...: ...) → integer

Calls Callback(...) every IntervalMs until cleared or until it returns false. Returns the timer ID.

Timer.SetTimeout(Callback: function, TimeoutMs: integer, ...: ...) → integer

Calls Callback(...) once after TimeoutMs. Returns the timer ID.

Trace

Trace: line and shape queries against the world.

Functions

Trace.LineSingle(Start: Vector, End: Vector, Ignore: entity[]) → table

First visible thing between Start and End, skipping the Ignore entities.

Value types

Vector

A 3D vector (location, direction, scale) in centimeters. Supports + - * / with vectors and numbers, unary -, == and tostring. Fields X, Y, Z are readable and writable.

Constructor

Vector(X: number, Y: number, Z: number) → Vector

Vector(x, y, z); Vector(n) sets all three; Vector() is zero.

Fields

X: number

Y: number

Z: number

Methods

:Size() → number

Length.

:SizeSquared() → number

Length squared (cheaper; good for comparisons).

:GetNormal() → Vector

A copy with length 1 (zero stays zero).

:Normalize() → Vector

Scales this vector to length 1 in place.

:Distance(Other: Vector) → number

Distance to another point.

:DistanceSquared(Other: Vector) → number

Distance squared to another point.

:Dot(Other: Vector) → number

Dot product.

:Cross(Other: Vector) → Vector

Cross product.

:Equals(Other: Vector, Tolerance: number) → boolean

Equal within a tolerance.

:IsZero() → boolean

:IsNearlyZero(Tolerance: number) → boolean

:Rotation() → Rotator

The rotation that points along this vector.

:Clone() → Vector

An independent copy.

:ToString() → string

Rotator

A rotation in degrees (Pitch, Yaw, Roll). Supports + - with rotators, * with numbers, unary -, == and tostring.

Constructor

Rotator(Pitch: number, Yaw: number, Roll: number) → Rotator

Rotator(pitch, yaw, roll); Rotator() is no rotation.

Fields

Pitch: number

Yaw: number

Roll: number

Methods

:GetForwardVector() → Vector

Unit vector pointing forward.

:GetRightVector() → Vector

Unit vector pointing right.

:GetUpVector() → Vector

Unit vector pointing up.

:RotateVector(V: Vector) → Vector

Rotates a vector by this rotation.

:UnrotateVector(V: Vector) → Vector

Rotates a vector by the inverse of this rotation.

:Normalize() → Rotator

Brings each angle into -180..180 in place.

:GetNormalized() → Rotator

A normalized copy.

:Equals(Other: Rotator, Tolerance: number) → boolean

Equal within a tolerance.

:IsZero() → boolean

:Clone() → Rotator

An independent copy.

:ToString() → string

Vector2D

A 2D vector for screen layout (WebUI:SetLayout). Supports + - and * with numbers or vectors, == and tostring. A plain table {X = , Y = } works wherever a Vector2D is expected.

Constructor

Vector2D(X: number, Y: number) → Vector2D

Vector2D(x, y); Vector2D(n) sets both.

Fields

X: number

Y: number

WidgetVisibility

Values for WebUI:SetVisibility and the WebUI constructor.

Values

Visible: integer

Shown and clickable (when the mouse is enabled).

Hidden: integer

Not shown.

VisibleNotHitTestable: integer

Shown; clicks go through to the game (HUDs).

Other

Events (page)

The JavaScript object put into every WebUI page served from a package. It talks to the WebUI that shows the page.

Functions

Events.Subscribe(name: string, callback: function) → function

Receives ui:CallEvent(name, ...) from Lua. Arguments arrive as JSON values (tables become objects or arrays).

Events.Unsubscribe(name: string, callback: function)

Without a callback, removes every handler for the event.

Events.Call(name: string, ...: ...)

Reaches ui:Subscribe(name, fn) in Lua, with the arguments as JSON.

require

require("Folder/File") loads Folder/File.lua next to the calling file, then from the package root, then from Shared/. require("package:Folder/File") loads from another package. Each file runs once per side; the result is cached.