Lua API for inso v0.3.7

called once after the beatmap loads, before play. events scheduled in on_init replay when seeking backwards.

called once per rendered frame. framerate-dependent and is not re-run when seeking.

called at a fixed rate in music time, decoupled from framerate. useful for simulation logic as it catches up in a loop on forward seek and replays deterministically. the rate is customizable by setting FixedUpdateRate in the inso file. note: if this is declared, the engine will call scheduled events using the fixed update timer for consistency.

called when the music time crosses a beat of the active uninherited timing point.

called when a new uninherited timing point becomes active.

called when playback is paused or resumed.

called when a gameplay key goes down. key is one of "k1", "k2", "m1", "m2".

called when a gameplay key goes up. key is one of "k1", "k2", "m1", "m2".

called when a keyboard key goes down. key is the SDL3 scancode name.

called when a keyboard key goes up. key is the SDL3 scancode name.

called when the cursor moves, with the new position in playfield (osupx) coordinates.

called when an object is judged. judgement is a Judgement enum value; timing_error_ms is signed (hit time minus perfect time). hitobject is nil for judgements spawned via judgement_spawn without one.

called before a judgement is committed. return nothing to let it pass, or return a Judgement value (and optionally a replacement timing error) to overwrite it - score, combo, hitsounds, animations and the judgement graphic all follow the overwritten result. Judgement.NONE is rejected; a judgement cannot be cancelled, overwrite to Judgement.IGNORED_HIT instead. judgements from judgement_spawn are not filtered.

called when the kiai state is set or unset.

called when the combo resets to 0, with the combo count that was lost. not called for breaks at 0 combo.

called once when the last scoring hitobject has been judged and the results screen appears (play mode only). seeking backward re-arms it.

loads and runs a lua file from the mapset folder, returning whatever it returns.

the cursor position in playfield (osupx) space.

shows or hides the built-in skin cursor. hide it to draw your own from a Drawable.

moves the built-in skin cursor (trail, click expand and all) to the given render layer. put it on a captured layer to warp it with the scene, or on Layer.PLATFORM to keep it above post-processing. default is Layer.CURSOR.

true if the named gameplay key is held. key is one of "k1", "k2", "m1", "m2".

true if the named gameplay key is not held. key is one of "k1", "k2", "m1", "m2".

true if the given keyboard key is held. accepts an sdl scancode name or a numeric scancode.

true if the given keyboard key is not held. accepts an sdl scancode name or a numeric scancode.

fires every callback registered under name. object callbacks get (self, ...), globals get (...).

fires trigger_event(name) after delay_ms of music time. scheduled from on_init it replays on backward seek; scheduled from a callback it fires once. safe to call again from within a callback.

runs callback on the first frame at or after music time time_ms. scheduled from on_init it replays on backward seek; scheduled from a callback it fires once. safe to call again from within a callback.

runs callback on the first frame at least delay_ms of music time from now. scheduled from on_init it replays on backward seek; scheduled from a callback it fires once. safe to call again from within a callback.

registers a callback not tied to any object; it receives only the extra args from trigger_event.

creates a judgement as if the game had posted it, but no graphic is created and validate_judgement is skipped. an attached hitobject attributes the judgement (per-object callbacks fire, slider combo rules apply) without counting as that object's own final judgement. calling this while a judgement is dispatching (on_judgement/validate_judgement) is an error.

the hitobject whose start time is exactly ms. errors if there's no object at that time.

all hitobjects with start times in [from_ms, to_ms].

all hitobjects currently within their visible time window.

like get_visible(), but also includes objects whose followpoint line is currently drawn (which can lead or trail their own approach window). use this set when positioning objects so their followpoints track the intended position before the object itself appears.

all hitobjects with every extra-bit in mask set. a zero mask returns nothing.

all hitobjects with at least one extra-bit in mask set. a zero mask returns nothing.

registers callback to run when name is triggered for this object; it receives (self, ...).

true if this object is a hitcircle.

true if this object is a slider.

true if this object is a spinner.

stops the object (and its slider body) from rendering until unhide(). persists across phase transitions; still hittable.

undoes hide().

renders this object like the hidden mod: no approach circle, the circle fades out before its hit time, slider bodies fade out over the slide. takes effect when the object's graphics spawn, so set it from on_init.

stops drawing the combo number on this object's circle.

undoes hide_combo_numbers().

suppresses the followpoints both leaving and arriving at this object.

undoes hide_followpoints().

suppresses only the followpoint arriving at this object from the previous one.

undoes hide_followpoint_in().

suppresses only the followpoint leaving this object toward the next one.

undoes hide_followpoint_out().

whether this slider's body snakes out of the head during the approach (default on). no-op on non-sliders; also gated by the user's snaking-in setting.

whether this slider's body retracts behind the ball on its final span (default on). no-op on non-sliders; also gated by the user's snaking-out setting.

the object's index into the beatmap's hitobject list.

the object's script-defined extra-bits mask used for filtering.

true if every bit in mask is set on this object.

true if at least one bit in mask is set on this object.

the object's current position in osupx before any script translation.

the object's note stacking level; 0 = unstacked. positive stacks offset up-left, negative (circles under a slider tail) down-right. the offset is already baked into the object's position.

the object's current position in osupx.

moves the object to an absolute osupx position.

moves the object to a screen-space pixel position, converted into playfield osupx.

the object's start time in ms.

sets the object's start time in ms.

the object's end time in ms (equals start time for circles).

sets the object's end time in ms.

the object's current lifecycle phase.

adds a custom element to draw while the object is in the given phase, replacing the default graphics. max 16 elements per phase.

removes all of the object's current drawables.

the object's hit animation length in ms.

overrides the object's hit animation length in ms.

the object's approach (preempt) time in ms.

overrides the object's approach (preempt) time in ms.

the object's approach rate, derived from its preempt time.

overrides the object's approach rate (converted to a preempt time).

the object's overall difficulty, derived from its ok hit window.

overrides the object's hit windows (converted from an overall difficulty).

the object's hit window half-widths in ms.

overrides the object's hit window half-widths in ms; expects marvelous <= good <= ok <= miss.

the object's circle size, derived from its radius.

the object's circle size radius in osupx.

overrides the object's circle size (converted to a radius).

overrides the object's circle size radius in osupx.

the slider's path length in osupx (0 for non-sliders).

the slider's velocity (0 for non-sliders).

the duration of one slider traversal in ms (0 for non-sliders).

the slider ball's current position in osupx (the head position for non-sliders).

the slider ball's position at the given music time in osupx.

the slider ball's current travel angle in radians (0 for non-sliders).

the slider ball's travel angle at the given music time in radians.

the radius multiplier of the slider follow circle (0 for non-sliders). default value is 2.4.

sets the radius multiplier of the slider follow circle.

overrides the element used for a slider part (ball, follow circle, ticks, repeats, ends).

creates a drawable from a texture name or an Element, on the current render layer. a texture name may be a mapset texture or a skin element via "skin:<name>" (e.g. "skin:cursor").

registers callback to run when name is triggered for this drawable; it receives (self, ...).

creates an independent copy of this drawable.

gets the underlying element type of the drawable.

sets the underlying element type of the drawable to the given element.

overrides this drawable's animation with the given list, replacing the element template's for this instance only.

the drawable's render layer.

moves the drawable to the given render layer.

sets the uv sub-rect in [0,1] space, picking a region of the texture.

the uv sub-rect's rotation in radians.

rotates the uv sub-rect around its center. set it equal to the drawable's angle and a rotated quad samples the screen region it covers with the content upright - the basis for angled scene cuts.

the drawable's position.

sets the drawable's position.

sets the drawable's position from a screen-space pixel position, converted into playfield osupx.

the drawable's size in osupx.

sets the drawable's size in osupx.

the drawable's size in screen-space pixels.

sets the drawable's size from a screen-space pixel size, converted into osupx.

the drawable's anchor point.

sets the drawable's anchor point.

makes the drawable cover the whole render target (size derived each frame, tracks resizes); pos still nudges it in osupx and set_pos_px in pixels. handy for compositing a captured layer.

pulses the drawable's size every beat: snaps up on the beat and eases back down before the next (the reverse arrow effect).

dims the drawable until shortly before its associated hitobject's hit time (or its own end time if unattached), matching approaching hitobjects.

the drawable's color as a packed rgba integer.

sets the drawable's color from a packed rgba integer (see Color.rgb / Color.rgba).

the drawable's linear velocity.

sets the drawable's linear velocity.

the drawable's linear acceleration.

sets the drawable's linear acceleration.

the drawable's rotation in radians.

sets the drawable's rotation in radians.

the drawable's angular velocity.

sets the drawable's angular velocity.

the drawable's animation playback rate multiplier (1 = normal).

sets the drawable's animation playback rate multiplier (1 = normal).

loops the drawable's animation list instead of playing it once; the period comes from animation:set_loop_period (defaulting to the list's own extent).

the drawable's start time in ms.

sets the drawable's start time in ms.

the drawable's end time in ms.

sets the drawable's end time in ms.

sets the drawable's start and end time in ms.

stops the drawable from rendering without destroying it; pair with show() to bring it back.

resumes rendering a hidden drawable.

permanently reaps the drawable next frame; its handle becomes invalid.

creates a quad element using the default shader. with a texture name (a mapset texture, or a skin element via "skin:<name>") it sets that texture, otherwise a blank white quad.

creates an independent copy of this element.

registers callback to run when name is triggered for this element; it receives (self, ...).

sets the element's texture by name: a mapset texture, or a skin element via "skin:<name>" (e.g. "skin:hitcircle").

sets the uv sub-rect in [0,1] space, picking a region of the texture.

sets the element's shader by mapset pipeline name.

composites the element as an already-premultiplied source (e.g. a captured render target sampled back out) using premultiplied-over blend instead of straight alpha. builtin quad shader only.

redirects this element's draws into the named render target instead of the screen.

attaches an animation list to the element.

marks the element as mesh-drawn, sourcing geometry from the named SSBO instead of the quad batch.

when enabled, the element tints with the hitobject's combo color.

creates an empty animation list to attach to an element. domain says what keyframe times mean, defaulting to TimeDomain.NORMALIZED.

appends a positional tween from (from_x, from_y) to (to_x, to_y) over [start, end].

appends a horizontal tween from from to to over [start, end], leaving the y position alone.

appends a vertical tween from from to to over [start, end], leaving the x position alone.

appends a scale tween from (from_x, from_y) to (to_x, to_y) over [start, end].

appends a horizontal scale tween from from to to over [start, end], leaving the height alone.

appends a vertical scale tween from from to to over [start, end], leaving the width alone.

appends a rotation tween in radians from from to to over [start, end].

appends a color tween between two packed rgba colors over [start, end].

appends an alpha tween from from to to over [start, end].

appends a keyframe that swaps to the named texture (and array layer) over [start, end].

spreads every layer of a texture array as evenly-spaced frames over [start, end].

sets what this list's keyframe times mean. NORMALIZED is [0,1] across the drawable's lifetime, MILLISECONDS counts from the drawable's start, MAP_MILLISECONDS is absolute map time like an osu storyboard. MAP_MILLISECONDS ignores the drawable's animation rate.

sets the loop period in ms for drawables flagged LOOP_ANIMATION. 0 (default) loops over the list's own extent. ignored in the NORMALIZED domain, which always loops over [0,1].

looks up a mapset buffer (SSBO) by name; returns nil if not found.

binds the buffer to a user SSBO slot (0-7, mapping to USER_0..USER_7).

writes one or more f32s at byte_offset (must be 4-byte aligned).

writes four f32s at vec4_index * 16 bytes.

the buffer's size in bytes.

plays a mapset sample once at the given volume and stereo pan.

starts looping a mapset sample and returns a handle you can stop().

stops a looping sound started by Sound.play_loop.

packs r, g, b (each 0-255) into an rgba integer with alpha 1.

packs r, g, b, a (each 0-255) into an rgba integer.

the current music playback time in ms.

the total length of the map's audio in ms.

the bpm at the current timing point.

the beat length in ms at the current timing point.

1 exactly on the beat, easing off to 0 right before the next. drive your own pulse effects with this.

the map's approach (preempt) time in ms.

the map's circle radius in osupx.

true if playback is currently paused.

declares a custom render layer positioned relative to a built-in anchor, returning its id. pass the id anywhere a Layer is taken (Drawable.new, set_cursor_layer, capture_layers, add_post_pass after). above=true draws it just after the anchor, false just before; ties among layers on the same anchor resolve in declaration order. capture it with capture_layers to route its drawables through a render target. declare these in on_init.

redirects every drawable in the given layers into the named render target.

stops redirecting the given layers into a render target.

force loads a skin by folder name, as listed in the skin dropdown (e.g. "gn"). the override lasts as long as the map: it never touches the configured skin, and opening any map restores it. hitobjects already on screen keep the old skin's sizes until they expire.

restores the configured skin, dropping a set_skin_override. a no-op if nothing was overridden. opening a map does this on its own.

queues a fullscreen shader pass sampling src (string or table) into dst, running after the 'after' layer (default HITOBJECTS), and returns its id for remove_post_pass. src/dst names may be a render target, 'screen' (the window), or 'backbuffer' (the whole-frame capture; requires [General] Backbuffer: 1).

drops a pass added by add_post_pass, using the id it returned. passes keep their id when others are removed. note that freeing the layers a pass samples does not stop the pass: it keeps sampling whatever the render target last held.

the running accuracy from 0 to 1 over objects judged so far. 1 before anything is judged.

the current combo.

the highest combo reached this play.

per-result totals over objects judged so far.

unstable rate over hits so far: 10x the standard deviation of hit timing errors. samples circle and slider head hits only.

the mean signed hit timing error in ms over hits so far. negative = early, positive = late.

the current hit window half-widths in ms.

sets the hit window half-widths in ms; expects marvelous <= good <= ok <= miss.

sets the playfield offset in osupx, on top of the base centering translation.

sets the playfield scale multiplier (1.0 = default size).

sets the playfield rotation in radians around the rotation anchor.

sets the rotation pivot in osupx (default 256, 192 = visible playfield center).

adds to the current playfield translation in osupx.

adds to the current playfield rotation in radians.

multiplies the current playfield size by the value.

returns the window size in pixels.

returns the window size in pixels (alias of get_size).

returns the window size in playfield osupx. set a drawable's size to this to fill the screen, then move it freely in osupx. assumes no playfield rotation; use drawable:set_fullscreen for the rotated case.

converts a screen-space pixel position into playfield osupx (full transform: translate/scale/rotate).

converts a playfield osupx position into screen-space pixels (full transform: translate/scale/rotate).

returns the window position in pixels.

sets the window size in pixels.

sets the window position in pixels.

fades the background drawable to opacity (0-1) and toggles window transparency below 1.

enables or disables debug mode.

writes a single float into the user param buffer at index (0-63).

writes a vec4 into the user param buffer at index (0-15).