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.
Sets if the camera should be controlled by the PsxPlayer. Set false if you want to use the lua functions below to control the camera. Returns the camera's world position as vec3{x, y, z}.
Set camera position. Accepts three numbers or a vec3 table.
Returns the camera's world rotation as Vec3 {x, y, z}
Set camera rotation in pi-units. Applied as Y * X * Z rotation matrix. Accepts Vec3
Moves the camera forward based on it's rotation and a fixed point number stepAmount
Moves the camera backward based on it's rotation and a fixed point number stepAmount
Moves the camera left based on it's rotation and a fixed point number stepAmount
Moves the camera right based on it's rotation and a fixed point number stepAmount
Returns the camera's forward vector as Vec3 {x, y, z}
Returns the current projection plane distance (H register). Default is 120. Higher values = narrower FOV (more telephoto), lower = wider FOV.
Set the projection H register. Clamped to 1-1024. Use this to change the field of view at runtime.
The relationship between H and vertical FOV is: $\text{vFOV} = 2 \cdot \arctan\left(\frac{120}{H}\right)$
| H | Approx. Vertical FOV |
|---|---|
| 60 | ~127° (ultra wide) |
| 120 | ~90° (default) |
| 200 | ~62° |
| 400 | ~33° (telephoto) |
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.LookAt() exists but is a placeholder - it does not correctly point the camera at the target.
Check out the example script
"Lua Free Cam" in the patterns section uses these camera functions.
Player¶
Control the PsxPlayer
Returns the player's position as Vec3{x, y, z}.
Set player position. Accepts three numbers or a Vec3 table.
Returns the player's rotation as Vec3 {x, y, z}
Set players rotation. Accepts Vec3
Check out the example script
"PsxPlayer Position and Rotation" in the patterns section.
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
SkinnedAnim¶
Control bone-based skinned mesh animations. See Skinned Meshes.
Each skinned object can play one clip at a time. Clips are referenced by the object name (the GameObject with a PSXSkinnedObjectExporter) and the clip name (the Unity AnimationClip asset name).
SkinnedAnim.Play¶
SkinnedAnim.Play(objectName, clipName)
SkinnedAnim.Play(objectName, clipName, {
loop = true, -- Loop the animation (default: false)
onComplete = function() -- Called when a non-looping clip finishes
-- ...
end
})
Start playing a skinned animation clip. If the object is already playing, the new clip replaces it immediately.
-- Play idle loop
SkinnedAnim.Play("MyCharacter", "idle", { loop = true })
-- Play attack, then return to idle
SkinnedAnim.Play("MyCharacter", "attack", {
onComplete = function()
SkinnedAnim.Play("MyCharacter", "idle", { loop = true })
end
})
SkinnedAnim.Stop¶
Stop the skinned animation on the given object. The mesh freezes at its current pose. Also releases any onComplete callback.
SkinnedAnim.IsPlaying¶
Returns true if the named skinned object is currently playing an animation.
SkinnedAnim.GetClip¶
Returns the name of the currently active clip, or nil if the object is not playing or not found.
local clip = SkinnedAnim.GetClip("MyCharacter")
if clip == "idle" then
SkinnedAnim.Play("MyCharacter", "walk", { loop = true })
end
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.