-- ============================================================================
-- PSXSplash Lua API — EmmyLua Stubs
-- Generated for SplashEdit. DO NOT EDIT — regenerate from luaapi.cpp.
-- Place this file in your workspace root so the Lua Language Server picks it up.
-- ============================================================================

--- @meta

-- ============================================================================
-- Types
-- ============================================================================

--- A 3-component vector in 20.12 fixed-point space.
--- @class Vec3Table
--- @field x number
--- @field y number
--- @field z number

--- Opaque handle returned by Entity.Find / Entity.FindByIndex.
--- @alias EntityHandle table

-- ============================================================================
-- Entity API
-- ============================================================================

--- @class Entity
Entity = {}

--- Find a game object by its Lua script index.
--- @param scriptIndex number  The lua file index (0-based) assigned during export.
--- @return EntityHandle|nil   Handle for use with other Entity functions, or nil.
function Entity.Find(scriptIndex) end

--- Find a game object by its global object index.
--- @param index number  Object index (0-based) in the scene's game-object array.
--- @return EntityHandle|nil
function Entity.FindByIndex(index) end

--- Return the total number of game objects in the scene.
--- @return number
function Entity.GetCount() end

--- Activate or deactivate a game object.
--- @param entity EntityHandle
--- @param active boolean
function Entity.SetActive(entity, active) end

--- Check whether a game object is active.
--- @param entity EntityHandle
--- @return boolean
function Entity.IsActive(entity) end

--- Get the world-space position of an entity (20.12 fixed-point).
--- @param entity EntityHandle
--- @return Vec3Table
function Entity.GetPosition(entity) end

--- Set the world-space position of an entity.
--- @param entity EntityHandle
--- @param pos Vec3Table
function Entity.SetPosition(entity, pos) end

-- ============================================================================
-- Vec3 API
-- ============================================================================

--- @class Vec3
Vec3 = {}

--- Create a new vector.
--- @param x number
--- @param y number
--- @param z number
--- @return Vec3Table
function Vec3.new(x, y, z) end

--- Component-wise addition.
--- @param a Vec3Table
--- @param b Vec3Table
--- @return Vec3Table
function Vec3.add(a, b) end

--- Component-wise subtraction (a - b).
--- @param a Vec3Table
--- @param b Vec3Table
--- @return Vec3Table
function Vec3.sub(a, b) end

--- Scalar multiply.
--- @param v Vec3Table
--- @param s number
--- @return Vec3Table
function Vec3.mul(v, s) end

--- Dot product.
--- @param a Vec3Table
--- @param b Vec3Table
--- @return number
function Vec3.dot(a, b) end

--- Cross product.
--- @param a Vec3Table
--- @param b Vec3Table
--- @return Vec3Table
function Vec3.cross(a, b) end

--- Magnitude (Euclidean length).
--- @param v Vec3Table
--- @return number
function Vec3.length(v) end

--- Squared magnitude (cheaper than length).
--- @param v Vec3Table
--- @return number
function Vec3.lengthSq(v) end

--- Return a unit-length copy of v.
--- @param v Vec3Table
--- @return Vec3Table
function Vec3.normalize(v) end

--- Distance between two points.
--- @param a Vec3Table
--- @param b Vec3Table
--- @return number
function Vec3.distance(a, b) end

--- Squared distance (cheaper than distance).
--- @param a Vec3Table
--- @param b Vec3Table
--- @return number
function Vec3.distanceSq(a, b) end

--- Linear interpolation between a and b.
--- @param a Vec3Table
--- @param b Vec3Table
--- @param t number  0..1
--- @return Vec3Table
function Vec3.lerp(a, b, t) end

-- ============================================================================
-- Input API
-- ============================================================================

--- @class Input
Input = {}

--- Button constants (bitmask values matching psyqo::AdvancedPad::Button).
--- @type number
Input.CROSS     = 0
Input.CIRCLE    = 0
Input.SQUARE    = 0
Input.TRIANGLE  = 0
Input.L1        = 0
Input.R1        = 0
Input.L2        = 0
Input.R2        = 0
Input.START     = 0
Input.SELECT    = 0
Input.UP        = 0
Input.DOWN      = 0
Input.LEFT      = 0
Input.RIGHT     = 0
Input.L3        = 0
Input.R3        = 0

--- True on the single frame the button was pressed.
--- @param button number  One of Input.CROSS, Input.CIRCLE, …
--- @return boolean
function Input.IsPressed(button) end

--- True on the single frame the button was released.
--- @param button number
--- @return boolean
function Input.IsReleased(button) end

--- True every frame the button is held down.
--- @param button number
--- @return boolean
function Input.IsHeld(button) end

--- Get left analog stick axes.
--- @return number x  -128..127 (0 if digital pad)
--- @return number y  -128..127
function Input.GetAnalog() end

-- ============================================================================
-- Timer API
-- ============================================================================

--- @class Timer
Timer = {}

--- Frames elapsed since the scene was loaded.
--- @return number
function Timer.GetFrameCount() end

-- ============================================================================
-- Camera API
-- ============================================================================

--- @class Camera
Camera = {}

--- Get the camera's world-space position.
--- @return Vec3Table
function Camera.GetPosition() end

--- Set the camera's world-space position.
--- @param pos Vec3Table
function Camera.SetPosition(pos) end

--- Get the camera's rotation (currently returns {0,0,0}).
--- @return Vec3Table  Euler angles in radians
function Camera.GetRotation() end

--- Set the camera's rotation (not yet implemented).
--- @param rot Vec3Table  Euler angles in radians
function Camera.SetRotation(rot) end

--- Point the camera at a world position (not yet implemented).
--- @param target Vec3Table
function Camera.LookAt(target) end

-- ============================================================================
-- Audio API — SPU ADPCM playback
-- ============================================================================

--- @class Audio
Audio = {}

--- Play a sound clip by index. Returns the SPU voice used (1-23), or -1 on failure.
--- @param clipIndex number  0-based clip index (order of PSXAudioSource in scene)
--- @param volume? number  0..127 (default 100)
--- @param pan? number  0=left, 64=center, 127=right (default 64)
--- @return number voiceId
function Audio.Play(clipIndex, volume, pan) end

--- Stop a specific SPU voice (returned from Audio.Play).
--- @param voiceId number
function Audio.Stop(voiceId) end

--- Set volume (and optional pan) on a playing voice.
--- @param voiceId number
--- @param volume number  0..127
--- @param pan? number  0..127 (default 64)
function Audio.SetVolume(voiceId, volume, pan) end

--- Stop all playing sounds.
function Audio.StopAll() end

-- ============================================================================
-- Debug API
-- ============================================================================

--- @class Debug
Debug = {}

--- Print a message to the TTY / debug console.
--- @param message string
function Debug.Log(message) end

--- Draw a debug line (not yet implemented on PS1).
--- @param fromX number
--- @param fromY number
--- @param fromZ number
--- @param toX number
--- @param toY number
--- @param toZ number
function Debug.DrawLine(fromX, fromY, fromZ, toX, toY, toZ) end

--- Draw a debug box (not yet implemented on PS1).
--- @param minX number
--- @param minY number
--- @param minZ number
--- @param maxX number
--- @param maxY number
--- @param maxZ number
function Debug.DrawBox(minX, minY, minZ, maxX, maxY, maxZ) end

-- ============================================================================
-- PSXMath API
-- ============================================================================

--- @class PSXMath
PSXMath = {}

--- Clamp a value between min and max.
--- @param value number
--- @param min number
--- @param max number
--- @return number
function PSXMath.Clamp(value, min, max) end

--- Linear interpolation (a + (b-a)*t).
--- @param a number
--- @param b number
--- @param t number  0..1
--- @return number
function PSXMath.Lerp(a, b, t) end

--- Return -1, 0, or 1.
--- @param x number
--- @return number
function PSXMath.Sign(x) end

--- Absolute value.
--- @param x number
--- @return number
function PSXMath.Abs(x) end

--- Minimum of two values.
--- @param a number
--- @param b number
--- @return number
function PSXMath.Min(a, b) end

--- Maximum of two values.
--- @param a number
--- @param b number
--- @return number
function PSXMath.Max(a, b) end

-- ============================================================================
-- Event Callbacks
-- These are global functions you define in your script. The engine calls them
-- automatically based on the event mask resolved at load time.
-- ============================================================================

--- Called once when the game object is created.
--- @param self EntityHandle
function onCreate(self) end

--- Called every frame while the object is active.
--- WARNING: 33 MHz CPU — keep this function fast!
--- @param self EntityHandle
function onUpdate(self) end

--- Called when the object is destroyed / scene unloads.
--- @param self EntityHandle
function onDestroy(self) end

--- Called when the object is activated.
--- @param self EntityHandle
function onEnable(self) end

--- Called when the object is deactivated.
--- @param self EntityHandle
function onDisable(self) end

--- Called when this object's collider overlaps another.
--- @param self EntityHandle
--- @param other EntityHandle
function onCollideWithPlayer(self) end

--- Called when the player interacts with this object (PSXInteractable).
--- @param self EntityHandle
function onInteract(self) end

--- Called on the first frame two trigger volumes overlap.
--- @param self EntityHandle
--- @param other EntityHandle
function onTriggerEnter(self, other) end

--- Called every frame two trigger volumes continue overlapping.
--- @param self EntityHandle
--- @param other EntityHandle
function onTriggerStay(self, other) end

--- Called when two trigger volumes stop overlapping.
--- @param self EntityHandle
--- @param other EntityHandle
function onTriggerExit(self, other) end

--- Called when any controller button is pressed.
--- @param self EntityHandle
--- @param button number  One of Input.CROSS, Input.CIRCLE, …
function onButtonPress(self, button) end

--- Called when any controller button is released.
--- @param self EntityHandle
--- @param button number
function onButtonRelease(self, button) end