Lua API

This page documents every callable in the current Generic Script Lua surface. vparamix.params.declare() is setup-only. finite(), number(), error(), and the math library work during setup or update. The remaining runtime callables are available only inside the global update() function.

Program contract

local params = vparamix.params

local output = params.declare({
    { name = "Pulse", min = 0, max = 1, default = 0 },
})

function update()
    output.set("Pulse", params.get("TimeSeconds") % 2)
end

Setup must call vparamix.params.declare() exactly once and define a global update(). Setup and update() return nothing.

update

update()

VParamix calls this global function once per Script frame after setup succeeds. It must set every declared output and return nothing.

vparamix.params.declare

vparamix.params.declare(definitions: VParamixParameterDefinition[]) -> VParamixOutputWriter

Declares the program's complete output set during setup and returns an output writer. definitions must be a dense array of 1–256 tables.

An output name cannot collide with a predefined source or an earlier program's output. Catalog order decides ownership when two programs declare the same name.

output.set

output.set(name: string, value: number)

Sets a finite numeric value for a declared output. It returns nothing. Every declared output must be set during each successful update(). Repeated writes use the last value, and successful values are clamped to the declaration range. Unknown names, nonnumeric values, nonfinite values, or missing outputs fail the entire update.

Input values

vparamix.params.get

vparamix.params.get(name: string) -> number

Returns the current regular source value, VTube Studio state value, or previous successful output of a Script program. A known but unavailable source returns its declared default.

vparamix.params.get_previous

vparamix.params.get_previous(name: string) -> number

Returns the value this program observed for the same input during its previous successful update. Before the first successful observation, it returns the input's known default.

vparamix.face.get

vparamix.face.get(name: string) -> number

Returns a current approved raw face-tracking value, including supported blendshapes, FaceFound, head rotation and position, and eye rotation.

vparamix.face.get_previous

vparamix.face.get_previous(name: string) -> number

Returns the raw face value this program observed during its previous successful update, or the known default before one exists.

All four getters require an exact parameter name. An unknown name fails the update. Reading a face parameter through vparamix.params, or a regular parameter through vparamix.face, reports the correct namespace and fails the update.

Timing

dt

dt() -> number

Returns seconds since this program's previous successful update, or 0 initially. Failed updates do not advance it.

time

time() -> number

Returns seconds since this program's runtime clock started, or 0 in stateless evaluation.

vts_ups

vts_ups() -> number

Returns the configured VTube Studio updates per second, not measured network throughput.

Conversion and validation

finite

finite(value: number) -> boolean

Returns false for NaN and positive or negative infinity; otherwise returns true.

number

number(value: any) -> number

Converts a number unchanged, true to 1, false to 0, and a numeric string to its number. Other values and invalid numeric strings return 0.

error

error(message: string)

Stops evaluation with message. During update(), all staged outputs, state, and VTS actions are discarded.

Saved state

save

save(id: string, value: number) -> number

Stores a numeric value under a program-private string ID and returns value. The value is retained only when the update succeeds. Each program retains at most 256 IDs. Once full, writes to existing IDs still work, while a new ID is not retained.

load

load(id: string, default: number) -> number

Returns the value saved earlier in the current update, then the value retained from the previous successful update, or default when the ID does not exist.

function update()
    local count = load("count", 0)
    if keyboard.pressed("Space") then
        count = save("count", count + 1)
    end
    output.set("Count", count)
end

Random values

Random helpers are available during update(); math.random and math.randomseed are not available.

rand

rand() -> number

Returns a uniform value in [0, 1).

rand_float

rand_float() -> number
rand_float(max: number) -> number
rand_float(min: number, max: number) -> number

With no arguments, returns a uniform value in [0, 1). One argument returns rand() * max; negative bounds are allowed. Two arguments return min + rand() * (max - min).

rand_bool

rand_bool(probability?: number) -> boolean

Returns true with the supplied probability. The default is 0.5, and the probability is clamped to 0..1.

Keyboard

Keyboard functions use canonical key IDs such as Space, KeyQ, ControlLeft, and UpArrow. Use -- @inspect source=keyboard to choose a valid ID in the editor. Unknown IDs and empty combinations return false.

keyboard.down

keyboard.down(key_id: string) -> boolean

Returns whether the key, or every key encoded by that canonical ID, is currently down.

keyboard.pressed

keyboard.pressed(key_id: string) -> boolean

Returns whether all mapped keys are down and at least one was up during the previous successful update.

keyboard.released

keyboard.released(key_id: string) -> boolean

Returns whether all mapped keys were down previously and at least one is now up.

keyboard.combo

keyboard.combo(keys: string[]) -> boolean

Returns whether every key ID in the dense string array is down.

keyboard.combo_pressed

keyboard.combo_pressed(keys: string[]) -> boolean

Returns whether the complete combination has just become down.

keyboard.shortcut_pressed

keyboard.shortcut_pressed(action_key: string, modifiers: string[]) -> boolean

Returns whether the action key transitioned down while every modifier is down.

local shortcut = keyboard.shortcut_pressed("KeyQ", { "ControlLeft", "ShiftLeft" })

Math

VParamix exposes Lua 5.4's math library except math.random and math.randomseed. Use rand(), rand_float(), or rand_bool() for random values. Angles are in radians unless a function says otherwise.

math.abs

math.abs(x: number) -> number

Returns the absolute value of x. The result keeps the integer or float subtype of the argument.

math.acos

math.acos(x: number) -> number

Returns the arc cosine of x in radians.

math.asin

math.asin(x: number) -> number

Returns the arc sine of x in radians.

math.atan

math.atan(y: number, x?: number) -> number

Returns the arc tangent of y / x in radians, using both signs to select the correct quadrant. x defaults to 1.

math.ceil

math.ceil(x: number) -> number

Returns the smallest integral value greater than or equal to x. The result is an integer when it fits the integer range, or a float otherwise.

math.cos

math.cos(x: number) -> number

Returns the cosine of x radians.

math.deg

math.deg(x: number) -> number

Converts x from radians to degrees.

math.exp

math.exp(x: number) -> number

Returns e raised to the power x.

math.floor

math.floor(x: number) -> number

Returns the largest integral value less than or equal to x. The result is an integer when it fits the integer range, or a float otherwise.

math.fmod

math.fmod(x: number, y: number) -> number

Returns the remainder of x / y when the quotient is rounded toward zero. The result follows Lua's integer-or-float rules.

math.log

math.log(x: number, base?: number) -> number

Returns the logarithm of x. Without base, it returns the natural logarithm.

math.max

math.max(x: number, ...: number) -> number

Returns the greatest supplied value. At least one argument is required.

math.min

math.min(x: number, ...: number) -> number

Returns the least supplied value. At least one argument is required.

math.modf

math.modf(x: number) -> number, number

Returns the integral part of x, followed by its fractional part. The fractional result is always a float.

math.rad

math.rad(x: number) -> number

Converts x from degrees to radians.

math.sin

math.sin(x: number) -> number

Returns the sine of x radians.

math.sqrt

math.sqrt(x: number) -> number

Returns the square root of x.

math.tan

math.tan(x: number) -> number

Returns the tangent of x radians.

math.tointeger

math.tointeger(x: any) -> integer | nil

Returns x as an integer when it has an exact integer representation; otherwise returns nil.

math.type

math.type(x: any) -> "integer" | "float" | nil

Returns the numeric subtype of x, or nil when x is not a number.

math.ult

math.ult(m: integer, n: integer) -> boolean

Returns whether m is less than n when both integers are compared as unsigned values.

Math constants