psst

tools/LUA_VSCODE_SETUP.md

@@ -0,0 +1,49 @@
+# PSXSplash Lua — VS Code Autocomplete Setup
+
+Get full IntelliSense (autocomplete, hover docs, go-to-definition) for the
+PSXSplash Lua API in Visual Studio Code.
+
+## 1. Install the Lua Language Server extension
+
+Open VS Code → Extensions → search **sumneko.lua** → Install.
+
+## 2. Point the language server at the stubs
+
+Add (or merge) the following into your workspace `.vscode/settings.json`:
+
+```jsonc
+{
+    "Lua.workspace.library": [
+        // Path to the EmmyLua stubs shipped with SplashEdit
+        "${workspaceFolder}/splashedit/tools"
+    ],
+    "Lua.runtime.version": "Lua 5.2",
+    "Lua.diagnostics.globals": [
+        // Event callbacks the engine calls — not "undefined" globals
+        "onCreate", "onUpdate", "onDestroy",
+        "onEnable", "onDisable",
+        "onCollision", "onInteract",
+        "onTriggerEnter", "onTriggerStay", "onTriggerExit",
+        "onButtonPress", "onButtonRelease"
+    ]
+}
+```
+
+> If your Lua scripts live inside the Unity project
+> (`kitchensink/Assets/Lua/`), open that folder as the workspace root, then
+> adjust the `library` path to be relative to it, e.g.
+> `"../splashedit/tools"`.
+
+## 3. Verify
+
+Open any `.lua` script and type `Entity.` — you should see `Find`,
+`FindByIndex`, `GetCount`, etc. with full parameter docs.
+
+Hover over `Input.CROSS` to see its type annotation. Hover over `onUpdate`
+to see the performance warning.
+
+## Updating the stubs
+
+When the C++ API changes, regenerate `splash_api.lua` from the
+`RegisterAll()` function in `psxsplash/src/luaapi.cpp`. The stubs file is
+the single source of truth for editor autocomplete.

tools/LUA_VSCODE_SETUP.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: dacec9280b4291d4c9a93b1522687267
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

tools/imhex.hexproj.meta

@@ -1,5 +1,5 @@
 fileFormatVersion: 2
-guid: 871e1f08910e9f329ad3fce5d77c8785
+guid: 2e825620cbb189b42965419f16e3fbcf
 DefaultImporter:
   externalObjects: {}
   userData: 

tools/splash_api.lua

@@ -0,0 +1,383 @@
+-- ============================================================================
+-- 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 onCollision(self, other) 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

tools/splash_api.lua.meta

@@ -0,0 +1,10 @@
+fileFormatVersion: 2
+guid: f306660f23f57394496050343c2335f8
+ScriptedImporter:
+  internalIDToNameTable: []
+  externalObjects: {}
+  serializedVersion: 2
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
+  script: {fileID: 11500000, guid: 74e983e6cf3376944af7b469023d6e4d, type: 3}