Lua API Reference¶
Complete reference for every function available in SplashEdit Lua scripts.
Entity¶
Manage game objects in the scene.
Finding Objects¶
Find an object by its GameObject name (string). Returns the object ornil.
Find an object by its array index (0-based). Returns the object or nil.
Find the first object with a matching Lua script file index. Returns the object or nil.
Returns the total number of objects in the scene.
Iterate all active objects. The callback receives (object, index) for each. Skips inactive objects.
Active State¶
Show or hide an object. FiresonEnable or onDisable callbacks.
Returns true if the object is active.
Position¶
Returns a Vec3 table{x, y, z} in world coordinates.
Set position instantly (no physics, no interpolation).
-- Example
local pos = Entity.GetPosition(self)
Entity.SetPosition(self, Vec3.new(pos.x + 1, pos.y, pos.z))
Rotation¶
Get the Y-axis rotation as an angle in pi-units. Set the Y-axis rotation. Angle is in pi-units (1 = 180 degrees,FixedPoint.new(1) / 2 = 90 degrees).
Self Properties¶
Object scripts have shorthand access via self:
self.position -- {x, y, z} (read/write)
self.active -- boolean (read/write)
self.rotation -- {x, y, z} (read/write)
self.rotationY -- angle in pi-units (read/write)
Vec3¶
3D vector math. All functions return new tables.
Vec3.new(x, y, z) -- Create vector
Vec3.add(a, b) -- a + b
Vec3.sub(a, b) -- a - b
Vec3.mul(v, scalar) -- v * scalar
Vec3.dot(a, b) -- Dot product (scalar)
Vec3.cross(a, b) -- Cross product (vector)
Vec3.length(v) -- Magnitude ||v||
Vec3.lengthSq(v) -- Squared magnitude (faster, no sqrt)
Vec3.normalize(v) -- Unit vector (length = 1)
Vec3.distance(a, b) -- Distance between two points
Vec3.distanceSq(a, b) -- Squared distance (faster)
Vec3.lerp(a, b, t) -- Linear interpolation: a + (b-a)*t
Examples¶
local a = Vec3.new(1, 0, 0)
local b = Vec3.new(0, 1, 0)
local sum = Vec3.add(a, b) -- {1, 1, 0}
local cross = Vec3.cross(a, b) -- {0, 0, 1}
local dot = Vec3.dot(a, b) -- 0
local one = FixedPoint.new(1)
local mid = Vec3.lerp(a, b, one / 2) -- {0.5, 0.5, 0}
local dist = Vec3.distance(a, b) -- ~1.41
Use squared versions for comparisons
Vec3.distanceSq and Vec3.lengthSq avoid a square root. If you're comparing distances (e.g., "is the player within range?"), compare squared distances instead.
Input¶
Controller button constants and state queries.
Button Constants¶
Input.CROSS Input.CIRCLE Input.SQUARE Input.TRIANGLE
Input.L1 Input.L2 Input.R1 Input.R2
Input.START Input.SELECT
Input.UP Input.DOWN Input.LEFT Input.RIGHT
Input.L3 Input.R3
State Queries¶
Returnstrue only on the frame the button was pressed (edge trigger). Use in onButtonPress callbacks.
Returns true only on the frame the button was released.
Returns true every frame while the button is held down.
Read analog stick position. stick 0 = left stick, 1 = right stick. Returns two values: x, y in range -127 to +127 (0 = centered).
Camera¶
Control the scene camera.
Returns the camera's world position as{x, y, z}.
Set camera position. Accepts three numbers or a Vec3 table.
Set camera rotation in pi-units. Applied as Y * X * Z rotation matrix.
Navigation controller override
In scenes with a PSXPlayer and navigation regions, the navigation controller continuously overrides camera position and rotation. Manual camera changes via these functions will be overwritten on the next frame. The Camera API is primarily useful during cutscenes, which temporarily suspend the navigation controller.
Incomplete functions
Camera.GetRotation() exists but always returns {0, 0, 0} - rotation decomposition is not implemented.
Camera.LookAt() exists but is a placeholder - it does not correctly point the camera at the target.
UI¶
Canvas and element manipulation. See UI System for setup.
Canvas Operations¶
UI.FindCanvas(name) -- Find canvas by name -> index or -1
UI.SetCanvasVisible(nameOrIndex, bool) -- Show/hide (accepts name string or index number)
UI.IsCanvasVisible(nameOrIndex) -- Check visibility -> boolean
Element Lookup¶
UI.FindElement(canvasIndex, name) -- Find element by name -> handle or -1
UI.GetElementCount(canvasIndex) -- Number of elements in canvas
UI.GetElementByIndex(canvasIndex, i) -- Get element by position -> handle
UI.GetElementType(handle) -- 0=Image, 1=Box, 2=Text, 3=Progress
Visibility¶
Text¶
Progress Bar¶
Color¶
UI.SetColor(handle, r, g, b) -- RGB 0-255
UI.GetColor(handle) -- Returns r, g, b (three values)
UI.SetProgressColors(handle, bgR, bgG, bgB, fillR, fillG, fillB)
Position & Size¶
UI.SetPosition(handle, x, y)
UI.GetPosition(handle) -- Returns x, y
UI.SetSize(handle, w, h)
UI.GetSize(handle) -- Returns w, h
Audio¶
Play sound effects and music. See Audio for setup.
Play a clip. Returns channel number (0-23) or -1 if all voices busy.nameOrIndex: clip name (string) or index (number)volume: 0-128 (default 100)pan: 0-127, where 0=left, 64=center, 127=right (default 64)
Audio.Find(name) -- Find clip by name -> index or nil
Audio.Stop(channel) -- Stop a specific channel
Audio.SetVolume(channel, volume, pan) -- Adjust mid-playback
Audio.StopAll() -- Stop all channels
Scene¶
Multi-scene management.
Request a scene transition. The load is deferred to end-of-frame - code after this call still executes. Returns the current scene's index (matches the order in the Control Panel Scenes tab, 0-based).Persist¶
Cross-scene persistent data storage. Survives scene loads but is lost on power-off.
Persist.Set(key, value) -- Store a number with a string key
Persist.Get(key) -- Retrieve -> number or nil if not set
Limits
Maximum 16 key-value pairs. Values are numbers only. Silently fails if the table is full.
Cutscene¶
Control cutscene playback. Only one at a time. See Cutscenes.
Cutscene.Play(name)
Cutscene.Play(name, {
loop = true, -- Loop the cutscene
onComplete = function() -- Called when cutscene ends (not per-loop)
-- ...
end
})
Cutscene.Stop() -- Stop current cutscene
Cutscene.IsPlaying() -- Check if any cutscene is playing -> boolean
Animation¶
Control animation playback. Multiple simultaneous instances. See Animations.
Animation.Play(name)
Animation.Play(name, {
loop = true,
onComplete = function()
-- ...
end
})
Animation.Stop(name) -- Stop all instances of named animation
Animation.Stop() -- Stop ALL animations
Animation.IsPlaying(name) -- True if any instance is active -> boolean
Controls¶
Enable/disable player input globally.
Controls.SetEnabled(bool) -- true = player can move, false = frozen
Controls.IsEnabled() -- Check state -> boolean
Use this during cutscenes, dialogue, or any time the player shouldn't move.
Interact¶
Enable/disable interaction on specific objects.
Interact.SetEnabled(object, bool) -- Enable/disable + hide prompt
Interact.IsEnabled(object) -- Check state -> boolean
Timer¶
Frame counting.
Returns the number of frames since the current scene loaded. Resets to 0 on each scene load.PSXMath¶
Integer math utilities.
PSXMath.Clamp(value, min, max) -- Clamp to range
PSXMath.Lerp(a, b, t) -- Linear interpolation: a + (b-a)*t
PSXMath.Sign(value) -- Returns -1, 0, or 1
PSXMath.Abs(value) -- Absolute value
PSXMath.Min(a, b) -- Minimum
PSXMath.Max(a, b) -- Maximum
All operate on fixed-point numbers. Use FixedPoint.new(1) / 2 for fractional arguments like t in Lerp.
FixedPoint¶
Create fixed-point numbers explicitly.
Creates a fixed-point value from an integer.FixedPoint.new(1) = 1.0.
Useful for creating precise step sizes:
Debug¶
Development tools.
Print to the console. Visible in PCSX-Redux stdout when running on emulator.