ldoc

Contents

• Config
• Minigame
• Meter
• Context
• Util
• Print
• Input
• Focus
• UI
• Audio
• Songs
• Sprite
• Situation
• Decision
• Map
• Screen
• Window
• SplashWindow
• IntroWindow
• MenuWindow
• ConfigurationWindow
• AudioTestWindow
• PopupWindow
• MinigameButtonMashWindow
• MinigameRhythmWindow
• MinigameDDRWindow
• GameWindow
• Main

Modules

• impostor.original

Module impostor.original

Return initial data for Config

Config

Config.reset ()	Restores default configuration settings.
Config.save ()	Saves the current configuration.
Config.load ()	Loads saved configuration.

Minigame

Minigame.get_default_ddr ()	Gets default DDR minigame configuration.
Minigame.get_default_button_mash ()	Gets default button mash minigame configuration.
Minigame.get_default_rhythm ()	Gets default rhythm minigame configuration.
Minigame.configure_ddr (params)	Configures DDR minigame.
Minigame.configure_button_mash (params)	Configures button mash minigame.
Minigame.configure_rhythm (params)	Configures rhythm minigame.

Meter

Meter.set_timer_duration (frames)	Sets the number of frames for one full timer revolution.
Meter.set_timer_decay (amount)	Sets the degradation amount applied to all meters per revolution.
Meter.get_initial ()	Gets initial meter values.
Meter.hide ()	Hides meters.
Meter.show ()	Shows meters.
Meter.get_max ()	Gets max meter value.
Meter.get_combo_multiplier ()	Gets combo multiplier.
Meter.update ()	Updates all meters.
Meter.add (key, amount)	Adds amount to a meter.
Meter.get_timer_decay_percentage ()	Gets the timer decay as a percentage of the max meter value.
Meter.on_minigame_complete ()	Called on minigame completion.

Context

Context.initial_data ()	Gets initial data for Context.
Context.reset ()	Resets game context to initial state.
Context.new_game ()	Starts a new game.
Context.save_game ()	Saves the current game state.
Context.load_game ()	Loads a saved game state.

Util

Util.safeindex (array, index)	Safely wraps an index for an array.
Util.go_to_screen_by_id (screen_id)	Navigates to a screen by its ID.
Util.contains (t, value)	Checks if a table contains a specific value.

Print

Print.text (text, x, y, color[, fixed[, scale]])	Prints text with shadow.
Print.text_center (text, x, y, color[, fixed[, scale]])	Prints centered text with shadow.

Input

Input.up ()	Checks if Up is pressed.
Input.down ()	Checks if Down is pressed.
Input.left ()	Checks if Left is pressed.
Input.right ()	Checks if Right is pressed.
Input.select ()	Checks if Select is pressed.
Input.menu_confirm ()	Checks if Menu Confirm is pressed.
Input.player_interact ()	Checks if Player Interact is pressed.
Input.menu_back ()	Checks if Menu Back is pressed.
Input.toggle_popup ()	Checks if Toggle Popup is pressed.

Focus

Focus.start (cx, cy[, params])	Starts a focus overlay that reveals content through an expanding circle.
Focus.close (cx, cy[, params])	Starts a closing focus overlay that hides content by shrinking the visible circle.
Focus.start_driven (cx, cy[, params])	Starts a driven focus overlay whose radius is controlled externally via Focus.set_percentage().
Focus.set_percentage (pct)	Sets the visible radius as a percentage of the full screen extent.
Focus.is_active ()	Checks whether the focus overlay is currently active.
Focus.stop ()	Stops the focus overlay immediately.
Focus.update ()	Updates the focus overlay animation.
Focus.draw ()	Draws the focus overlay (black screen with circular cutout).

UI

UI.draw_top_bar (title)	Draws the top bar.
UI.draw_dialog ()	Draws dialog window.
UI.draw_menu (items, selected_item, x, y)	Draws a menu.
UI.update_menu (items, selected_item)	Updates menu selection.
UI.word_wrap (text, max_chars_per_line)	Wraps text.
UI.create_numeric_stepper (label, value_getter, value_setter, min, max, step[, format])	Creates a numeric stepper.
UI.create_action_item (label, action)	Creates an action item.
UI.draw_decision_selector (decisions, selected_decision_index)	Draws decision selector.
UI.draw_timer ()	Draws the clock timer indicator as a circular progress bar in the top-left area.
UI.draw_meters ()	Draws meters.
UI.update_decision_selector (decisions, selected_decision_index)	Updates decision selector.

Audio

Audio.music_stop ()	Stops current music.
Audio.music_play_mainmenu ()	Plays main menu music.
Audio.music_play_wakingup ()	Plays waking up music.
Audio.music_play_room_morning ()	Plays room morning music.
Audio.music_play_room_street_1 ()	Plays room street 1 music.
Audio.music_play_room_street_2 ()	Plays room street 2 music.
Audio.music_play_room_ ()	Plays room music.
Audio.music_play_room_work ()	Plays room work music.
Audio.sfx_select ()	Plays select sound effect.
Audio.sfx_deselect ()	Plays deselect sound effect.
Audio.sfx_beep ()	Plays beep sound effect.
Audio.sfx_success ()	Plays success sound effect.
Audio.sfx_bloop ()	Plays bloop sound effect.

Songs

frame_from_beat (beat, bpm[, fps])	Converts beats to frames.
beats_to_pattern (beats, bpm, fps)	Converts beat notation to frame pattern.

Sprite

Sprite.register (sprite_data)	Registers a sprite definition.
Sprite.show (id, x, y[, colorkey[, scale[, flip_x[, flip_y[, rot]]]]])	Schedules a sprite for drawing.
Sprite.hide (id)	Hides a displayed sprite.
Sprite.draw ()	Draws all scheduled sprites.

Situation

Situation.register (situation)	Registers a situation definition.
Situation.get_by_id (id)	Gets a situation by ID.
Situation.get_all (screen_id)	Gets all registered situations, optionally filtered by screen ID.
Situation.apply (id, current_screen_id)	Applies a situation, checking screen compatibility and returning the new situation ID if successful.

Decision

Decision.register (decision)	Registers a decision definition.
Decision.get_by_id (id)	Gets a decision by ID.
Decision.get_all ()	Gets all registered decisions.
Decision.get_for_screen (screen_data)	Gets decision objects based on a screen's data.
Decision.filter_available (decisions_list)	Filters a list of decision objects based on their condition function.

Map

Map.get_maps_array ()	Gets all registered maps as an array.
Map.register (map_data)	Registers a map definition.
Map.get_by_id (map_id)	Gets a map by ID.
Map.draw (map_id)	Draws a map.

Screen

Screen.register (screen_data)	Registers a screen definition.
Screen.get_by_id (screen_id)	Gets a screen by ID.
Screen.get_all ()	Gets all registered screens.

Window

Window.register (id, window_table)	Registers a window table.
Window.get (id)	Retrieves a registered window table by its ID.
Window.set_current (id)	Sets the currently active window.
Window.get_current_id ()	Gets the ID of the currently active window.
Window.get_current_handler ()	Gets the handler function for the currently active window.

SplashWindow

SplashWindow.draw ()	Draws the splash window.
SplashWindow.update ()	Updates the splash window logic.

IntroWindow

IntroWindow.draw ()	Draws the intro window.
IntroWindow.update ()	Updates the intro window logic.

MenuWindow

MenuWindow.draw ()	Draws the menu window.
MenuWindow.update ()	Updates the menu window logic.
MenuWindow.new_game ()	Starts a new game from the menu.
MenuWindow.load_game ()	Loads a game from the menu.
MenuWindow.save_game ()	Saves the current game from the menu.
MenuWindow.resume_game ()	Resumes the game from the menu.
MenuWindow.exit ()	Exits the game.
MenuWindow.configuration ()	Opens the configuration menu.
MenuWindow.audio_test ()	Opens the audio test menu.
MenuWindow.refresh_menu_items ()	Refreshes menu items.

ConfigurationWindow

ConfigurationWindow.init ()	Initializes configuration window.
ConfigurationWindow.draw ()	Draws configuration window.
ConfigurationWindow.update ()	Updates configuration window logic.

AudioTestWindow

AudioTestWindow.generate_menuitems (list_func, index_func)	Generates menu items for audio test.
AudioTestWindow.generate_listfunc ()	Generates list of audio functions.
AudioTestWindow.back ()	Navigates back from audio test window.
AudioTestWindow.init ()	Initializes audio test window.
AudioTestWindow.draw ()	Draws audio test window.
AudioTestWindow.update ()	Updates audio test window logic.

PopupWindow

PopupWindow.show (content_strings)	Displays a popup window.
PopupWindow.hide ()	Hides the popup window.
PopupWindow.update ()	Updates popup window logic.
PopupWindow.draw ()	Draws the popup window.

MinigameButtonMashWindow

MinigameButtonMashWindow.init (params)	Initializes button mash minigame state.
MinigameButtonMashWindow.start (return_window[, params])	Starts the button mash minigame.
MinigameButtonMashWindow.update ()	Updates button mash minigame logic.
MinigameButtonMashWindow.draw ()	Draws button mash minigame.

MinigameRhythmWindow

MinigameRhythmWindow.init (params)	Initializes rhythm minigame state.
MinigameRhythmWindow.start (return_window[, params])	Starts the rhythm minigame.
MinigameRhythmWindow.update ()	Updates rhythm minigame logic.
MinigameRhythmWindow.draw ()	Draws rhythm minigame.

MinigameDDRWindow

MinigameDDRWindow.init (params)	Initializes DDR minigame state.
MinigameDDRWindow.start (return_window[, song_key[, params]])	Starts the DDR minigame.
MinigameDDRWindow.update ()	Updates DDR minigame logic.
MinigameDDRWindow.draw ()	Draws DDR minigame.

GameWindow

GameWindow.draw ()	Draws the game window.
GameWindow.update ()	Updates the game window logic.
GameWindow.set_state (new_state)	Sets the active window.

Main

TIC ()

Main game loop (TIC-80 callback).

Config

Config.reset ()

Restores default configuration settings.

Config.save ()

Saves the current configuration.

Config.load ()

Loads saved configuration.

Minigame

Minigame.get_default_ddr ()

Gets default DDR minigame configuration.

Returns:

result table The default DDR minigame configuration.
Fields:
* bar_fill (number) Current fill level of the progress bar.
* max_fill (number) Maximum fill value to win.
* fill_per_hit (number) Fill gained per successful hit.
* miss_penalty (number) Fill lost per miss.
* bar_x (number) Progress bar X position.
* bar_y (number) Progress bar Y position.
* bar_width (number) Progress bar width.
* bar_height (number) Progress bar height.
* arrow_size (number) Size of arrow sprites.
* arrow_spawn_timer (number) Timer for arrow spawning.
* arrow_spawn_interval (number) Frames between arrow spawns.
* arrow_fall_speed (number) Speed of falling arrows.
* arrows (table) Array of active arrow objects.
* target_y (number) Y position of the target line.
* target_arrows (table) Array of target arrow positions. Each entry has: `dir` (string) arrow direction, `x` (number) X position.
* hit_threshold (number) Pixel distance for a valid hit.
* button_pressed_timers (table) Per-button press animation timers.
* button_press_duration (number) Duration of button press animation.
* input_cooldowns (table) Per-direction cooldown timers (left, down, up, right).
* input_cooldown_duration (number) Frames of input cooldown.
* frame_counter (number) Global frame counter.
* current_song (table) Currently playing song data.
* pattern_index (number) Current index in song pattern.
* use_pattern (boolean) Whether to use song pattern for spawning.
* return_window (string) Window ID to return to after minigame.

Minigame.get_default_button_mash ()

Gets default button mash minigame configuration.

Returns:

result table The default button mash minigame configuration.
Fields:
* bar_fill (number) Current fill level of the progress bar.
* max_fill (number) Maximum fill value to win.
* fill_per_press (number) Fill gained per button press.
* base_degradation (number) Base rate of bar degradation per frame.
* degradation_multiplier (number) Multiplier for degradation scaling.
* button_pressed_timer (number) Button press animation timer.
* button_press_duration (number) Duration of button press animation.
* return_window (string) Window ID to return to after minigame.
* bar_x (number) Progress bar X position.
* bar_y (number) Progress bar Y position.
* bar_width (number) Progress bar width.
* bar_height (number) Progress bar height.
* button_x (number) Button indicator X position.
* button_y (number) Button indicator Y position.
* button_size (number) Button indicator size.

Minigame.get_default_rhythm ()

Gets default rhythm minigame configuration.

Returns:

result table The default rhythm minigame configuration.
Fields:
* line_position (number) Current position of the moving line (0-1).
* line_speed (number) Speed of the moving line per frame.
* line_direction (number) Direction of line movement (1 or -1).
* target_center (number) Center of the target zone (0-1).
* target_width (number) Current width of the target zone.
* initial_target_width (number) Starting width of the target zone.
* min_target_width (number) Minimum width the target zone can shrink to.
* target_shrink_rate (number) Multiplier applied to target width after each hit.
* score (number) Current score.
* max_score (number) Score needed to win.
* button_pressed_timer (number) Button press animation timer.
* button_press_duration (number) Duration of button press animation.
* return_window (string) Window ID to return to after minigame.
* bar_x (number) Progress bar X position.
* bar_y (number) Progress bar Y position.
* bar_width (number) Progress bar width.
* bar_height (number) Progress bar height.
* button_x (number) Button indicator X position.
* button_y (number) Button indicator Y position.
* button_size (number) Button indicator size.
* press_cooldown (number) Current cooldown timer.
* press_cooldown_duration (number) Frames of press cooldown.

Minigame.configure_ddr (params)

Configures DDR minigame.

Parameters:

• params table Optional parameters to override defaults (see Minigame.get_default_ddr).
  • bar_fill number Current fill level of the progress bar. (optional)
  • max_fill number Maximum fill value to win. (optional)
  • fill_per_hit number Fill gained per successful hit. (optional)
  • miss_penalty number Fill lost per miss. (optional)
  • bar_x number Progress bar X position. (optional)
  • bar_y number Progress bar Y position. (optional)
  • bar_width number Progress bar width. (optional)
  • bar_height number Progress bar height. (optional)
  • arrow_size number Size of arrow sprites. (optional)
  • arrow_spawn_timer number Timer for arrow spawning. (optional)
  • arrow_spawn_interval number Frames between arrow spawns. (optional)
  • arrow_fall_speed number Speed of falling arrows. (optional)
  • arrows table Array of active arrow objects. (optional)
  • target_y number Y position of the target line. (optional)
  • target_arrows table Array of target arrow positions with dir and x fields. (optional)
  • hit_threshold number Pixel distance for a valid hit. (optional)
  • button_pressed_timers table Per-button press animation timers. (optional)
  • button_press_duration number Duration of button press animation. (optional)
  • input_cooldowns table Per-direction cooldown timers (left, down, up, right). (optional)
  • input_cooldown_duration number Frames of input cooldown. (optional)
  • frame_counter number Global frame counter. (optional)
  • current_song table Currently playing song data. (optional)
  • pattern_index number Current index in song pattern. (optional)
  • use_pattern boolean Whether to use song pattern for spawning. (optional)
  • return_window string Window ID to return to after minigame. (optional)

Returns:

result table The configured DDR minigame state (see Minigame.get_default_ddr for fields).

Minigame.configure_button_mash (params)

Configures button mash minigame.

Parameters:

• params table Optional parameters to override defaults (see Minigame.get_default_button_mash).
  • bar_fill number Current fill level of the progress bar. (optional)
  • max_fill number Maximum fill value to win. (optional)
  • fill_per_press number Fill gained per button press. (optional)
  • base_degradation number Base rate of bar degradation per frame. (optional)
  • degradation_multiplier number Multiplier for degradation scaling. (optional)
  • button_pressed_timer number Button press animation timer. (optional)
  • button_press_duration number Duration of button press animation. (optional)
  • return_window string Window ID to return to after minigame. (optional)
  • bar_x number Progress bar X position. (optional)
  • bar_y number Progress bar Y position. (optional)
  • bar_width number Progress bar width. (optional)
  • bar_height number Progress bar height. (optional)
  • button_x number Button indicator X position. (optional)
  • button_y number Button indicator Y position. (optional)
  • button_size number Button indicator size. (optional)

Returns:

result table The configured button mash minigame state (see Minigame.get_default_button_mash for fields).

Minigame.configure_rhythm (params)

Configures rhythm minigame.

Parameters:

• params table Optional parameters to override defaults (see Minigame.get_default_rhythm).
  • line_position number Current position of the moving line (0-1). (optional)
  • line_speed number Speed of the moving line per frame. (optional)
  • line_direction number Direction of line movement (1 or -1). (optional)
  • target_center number Center of the target zone (0-1). (optional)
  • target_width number Current width of the target zone. (optional)
  • initial_target_width number Starting width of the target zone. (optional)
  • min_target_width number Minimum width the target zone can shrink to. (optional)
  • target_shrink_rate number Multiplier applied to target width after each hit. (optional)
  • score number Current score. (optional)
  • max_score number Score needed to win. (optional)
  • button_pressed_timer number Button press animation timer. (optional)
  • button_press_duration number Duration of button press animation. (optional)
  • return_window string Window ID to return to after minigame. (optional)
  • bar_x number Progress bar X position. (optional)
  • bar_y number Progress bar Y position. (optional)
  • bar_width number Progress bar width. (optional)
  • bar_height number Progress bar height. (optional)
  • button_x number Button indicator X position. (optional)
  • button_y number Button indicator Y position. (optional)
  • button_size number Button indicator size. (optional)
  • press_cooldown number Current cooldown timer. (optional)
  • press_cooldown_duration number Frames of press cooldown. (optional)

Returns:

result table The configured rhythm minigame state (see Minigame.get_default_rhythm for fields).

Meter

Meter.set_timer_duration (frames)

Sets the number of frames for one full timer revolution.

Parameters:

• frames number Frames per revolution (controls degradation speed).

Meter.set_timer_decay (amount)

Sets the degradation amount applied to all meters per revolution.

Parameters:

• amount number Amount to subtract from each meter per revolution.

Meter.get_initial ()

Gets initial meter values.

Returns:

result table Initial meter values.
Fields:
* ism (number) Initial ISM meter value.
* wpm (number) Initial WPM meter value.
* bm (number) Initial BM meter value.
* combo (number) Current combo count.
* combo_timer (number) Frames since last combo action.
* hidden (boolean) Whether meters are hidden.
* timer_progress (number) Clock timer revolution progress (0 to 1).

Meter.hide ()

Hides meters.

Meter.show ()

Shows meters.

Meter.get_max ()

Gets max meter value.

Returns:

number The maximum meter value.

Meter.get_combo_multiplier ()

Gets combo multiplier.

Returns:

number The current combo multiplier.

Meter.update ()

Updates all meters.

Meter.add (key, amount)

Adds amount to a meter.

Parameters:

• key string The meter key (e.g., "wpm", "ism", "bm").
• amount number The amount to add.

Meter.get_timer_decay_percentage ()

Gets the timer decay as a percentage of the max meter value.

Returns:

number The decay percentage per revolution (e.g. 2 means -2%).

Meter.on_minigame_complete ()

Called on minigame completion.

Context

Context.initial_data ()

Gets initial data for Context.

Returns:

result table Initial context data or nil.
Fields:
* current_menu_item (number) Index of the currently selected menu item.
* splash_timer (number) Remaining frames for the splash screen timer.
* popup (table) Popup window state. Contains: `show` (boolean) whether popup is visible, `content` (table) array of strings to display.
* game_in_progress (boolean) Whether a game is currently active.
* minigame_ddr (table) DDR minigame state (see Minigame.get_default_ddr).
* minigame_button_mash (table) Button mash minigame state (see Minigame.get_default_button_mash).
* minigame_rhythm (table) Rhythm minigame state (see Minigame.get_default_rhythm).
* meters (table) Meter values (see Meter.get_initial).
* stat_screen_active (boolean) Whether the stat screen overlay is currently shown.
* game (table) Current game progress state. Contains: `current_screen` (string) active screen ID, `current_situation` (string|nil) active situation ID.

Context.reset ()

Resets game context to initial state.

Context.new_game ()

Starts a new game.

Context.save_game ()

Saves the current game state.

Context.load_game ()

Loads a saved game state.

Util

Util.safeindex (array, index)

Safely wraps an index for an array.

Parameters:

• array table The array to index.
• index number The desired index (can be out of bounds).

Returns:

number index The wrapped index within the array's bounds.

Util.go_to_screen_by_id (screen_id)

Navigates to a screen by its ID.

Parameters:

• screen_id string The ID of the screen to go to.
  

Util.contains (t, value)

Checks if a table contains a specific value.

Parameters:

• t table The table to check.
• value any The value to look for.
  

Returns:

boolean true if the value is found, false otherwise.

Print

Print.text (text, x, y, color[, fixed[, scale]])

Prints text with shadow.

Parameters:

• text string The text to print.
  
• x number The x-coordinate.
  
• y number The y-coordinate.
  
• color number The color of the text.
  
• fixed boolean If true, uses fixed-width font.
  (optional)
• scale number The scaling factor.
  (optional)

Print.text_center (text, x, y, color[, fixed[, scale]])

Prints centered text with shadow.

Parameters:

• text string The text to print.
  
• x number The x-coordinate for centering.
  
• y number The y-coordinate.
  
• color number The color of the text.
  
• fixed boolean If true, uses fixed-width font.
  (optional)
• scale number The scaling factor.
  (optional)

Input

Input.up ()

Checks if Up is pressed.

Input.down ()

Checks if Down is pressed.

Input.left ()

Checks if Left is pressed.

Input.right ()

Checks if Right is pressed.

Input.select ()

Checks if Select is pressed.

Input.menu_confirm ()

Checks if Menu Confirm is pressed.

Input.player_interact ()

Checks if Player Interact is pressed.

Input.menu_back ()

Checks if Menu Back is pressed.

Input.toggle_popup ()

Checks if Toggle Popup is pressed.

Focus

Focus.start (cx, cy[, params])

Starts a focus overlay that reveals content through an expanding circle.

Parameters:

• cx number The x-coordinate of the circle center.
• cy number The y-coordinate of the circle center.
• params table Optional parameters: `speed` (number) expansion rate in pixels/frame, `initial_radius` (number) starting radius in pixels (default 0), `on_complete` (function) callback when overlay disperses. (optional)

Focus.close (cx, cy[, params])

Starts a closing focus overlay that hides content by shrinking the visible circle.

Parameters:

• cx number The x-coordinate of the circle center.
• cy number The y-coordinate of the circle center.
• params table Optional parameters: `speed` (number) shrink rate in pixels/frame, `on_complete` (function) callback when screen is fully covered. (optional)

Focus.start_driven (cx, cy[, params])

Starts a driven focus overlay whose radius is controlled externally via Focus.set_percentage(). The radius maps linearly from initial_radius (at 0%) to the screen corner distance (at 100%).

Parameters:

• cx number The x-coordinate of the circle center.
• cy number The y-coordinate of the circle center.
• params table Optional parameters: `initial_radius` (number) radius at 0% (default 0). (optional)

Focus.set_percentage (pct)

Sets the visible radius as a percentage of the full screen extent. Only has effect when the overlay is in driven mode (started via Focus.start_driven).

Parameters:

• pct number A value from 0 to 1 (0 = initial_radius, 1 = full screen).

Focus.is_active ()

Checks whether the focus overlay is currently active.

Returns:

boolean Whether the focus overlay is active.

Focus.stop ()

Stops the focus overlay immediately.

Focus.update ()

Updates the focus overlay animation. No-op in driven mode.

Focus.draw ()

Draws the focus overlay (black screen with circular cutout). Must be called after all other drawing to appear on top of every visual layer.

UI

UI.draw_top_bar (title)

Draws the top bar.

Parameters:

• title string The title text to display.
  

UI.draw_dialog ()

Draws dialog window.

UI.draw_menu (items, selected_item, x, y)

Draws a menu.

Parameters:

• items table A table of menu items.
  
• selected_item number The index of the currently selected item.
  
• x number The x-coordinate for the menu.
  
• y number The y-coordinate for the menu.
  

UI.update_menu (items, selected_item)

Updates menu selection.

Parameters:

• items table A table of menu items.
  
• selected_item number The current index of the selected item.
  

Returns:

number selected_item The updated index of the selected item.

UI.word_wrap (text, max_chars_per_line)

Wraps text.

Parameters:

• text string The text to wrap.
  
• max_chars_per_line number The maximum characters per line.
  

Returns:

result table A table of wrapped lines.

UI.create_numeric_stepper (label, value_getter, value_setter, min, max, step[, format])

Creates a numeric stepper.

Parameters:

• label string The label for the stepper.
  
• value_getter function Function to get the current value.
  
• value_setter function Function to set the current value.
  
• min number The minimum value.
  
• max number The maximum value.
  
• step number The step increment.
  
• format string The format string for displaying the value.
  (optional)

Returns:

result table A numeric stepper control definition or nil.
Fields:
* label (string) The label for the stepper.
* get (function) Function to get the current value.
* set (function) Function to set the current value.
* min (number) The minimum value.
* max (number) The maximum value.
* step (number) The step increment.
* format (string) The format string for displaying the value.
* type (string) Control type identifier ("numeric_stepper").

UI.create_action_item (label, action)

Creates an action item.

Parameters:

• label string The label for the action item.
  
• action function The function to execute when the item is selected.
  

Returns:

result table An action item control definition or nil.
Fields:
* label (string) The label for the action item.
* action (function) The function to execute when the item is selected.
* type (string) Control type identifier ("action_item").

UI.draw_decision_selector (decisions, selected_decision_index)

Draws decision selector.

Parameters:

• decisions table A table of decision items.
  
• selected_decision_index number The index of the selected decision.
  

UI.draw_timer ()

Draws the clock timer indicator as a circular progress bar in the top-left area. Color transitions: white (0-50%), yellow (50-75%), red (75-100%).

UI.draw_meters ()

Draws meters.

UI.update_decision_selector (decisions, selected_decision_index)

Updates decision selector.

Parameters:

• decisions table A table of decision items.
  
• selected_decision_index number The current index of the selected decision.
  

Returns:

number selected_decision_index The updated index of the selected decision.

Audio

Audio.music_stop ()

Stops current music.

Audio.music_play_mainmenu ()

Plays main menu music.

Audio.music_play_wakingup ()

Plays waking up music.

Audio.music_play_room_morning ()

Plays room morning music.

Audio.music_play_room_street_1 ()

Plays room street 1 music.

Audio.music_play_room_street_2 ()

Plays room street 2 music.

Audio.music_play_room_ ()

Plays room music. TODO: function name is incomplete, determine the correct room identifier

Audio.music_play_room_work ()

Plays room work music.

Audio.sfx_select ()

Plays select sound effect.

Audio.sfx_deselect ()

Plays deselect sound effect.

Audio.sfx_beep ()

Plays beep sound effect.

Audio.sfx_success ()

Plays success sound effect.

Audio.sfx_bloop ()

Plays bloop sound effect.

Songs

frame_from_beat (beat, bpm[, fps])

Converts beats to frames.

Parameters:

• beat number The beat number.
• bpm number Beats per minute.
• fps number Frames per second (default: 60). (optional)

Returns:

number The corresponding frame number.

beats_to_pattern (beats, bpm, fps)

Converts beat notation to frame pattern.

Parameters:

• beats table A table of beat data, e.g., {{1, "left"}, {2, "down"}}.
  • 1 number The beat number.
  • 2 string Arrow direction ("left", "down", "up", or "right").
• bpm number Beats per minute.
• fps number Frames per second (default: 60). (optional)

Returns:

result table The generated pattern or nil.
Fields:
* frame (number) The frame number when the arrow should spawn.
* dir (string) Arrow direction ("left", "down", "up", or "right").

Sprite

Sprite.register (sprite_data)

Registers a sprite definition.

Parameters:

• sprite_data table A table containing the sprite definition.
  • id string Unique sprite identifier.
    
  • s number Sprite index for single-sprite mode.
    (optional)
  • colorkey number Default color index for transparency.
    (optional)
  • scale number Default scaling factor.
    (optional)
  • flip_x number Set to 1 to flip horizontally by default.
    (optional)
  • flip_y number Set to 1 to flip vertically by default.
    (optional)
  • rot number Default rotation in degrees.
    (optional)
  • sprites table Array of sub-sprite tables for composite sprites. Each entry has: `s` (number) sprite index, `x_offset` (number) horizontal offset, `y_offset` (number) vertical offset, and optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` overrides.
    (optional)

Sprite.show (id, x, y[, colorkey[, scale[, flip_x[, flip_y[, rot]]]]])

Schedules a sprite for drawing.

Parameters:

• id string The unique identifier of the sprite.
  
• x number The x-coordinate.
  
• y number The y-coordinate.
  
• colorkey number The color index for transparency.
  (optional)
• scale number The scaling factor.
  (optional)
• flip_x number Set to 1 to flip horizontally.
  (optional)
• flip_y number Set to 1 to flip vertically.
  (optional)
• rot number The rotation in degrees.
  (optional)

Sprite.hide (id)

Hides a displayed sprite.

Parameters:

• id string The unique identifier of the sprite.
  

Sprite.draw ()

Draws all scheduled sprites.

Situation

Situation.register (situation)

Registers a situation definition.

Parameters:

• situation table The situation data table.
  • id string Unique situation identifier.
    
  • screen_id string ID of the screen this situation belongs to.
    (optional)
  • handle function Called when the situation is applied. Defaults to noop.
    (optional)
  • update function Called each frame while situation is active. Defaults to noop.
    (optional)

Situation.get_by_id (id)

Gets a situation by ID.

Parameters:

• id string The situation ID.

Returns:

result table The situation table or nil.
Fields:
* id (string) Unique situation identifier.
* screen_id (string) ID of the screen this situation belongs to.
* handle (function) Called when the situation is applied.
* update (function) Called each frame while situation is active.

Situation.get_all (screen_id)

Gets all registered situations, optionally filtered by screen ID.

Parameters:

• screen_id string Optional. If provided, returns situations associated with this screen ID.

Returns:

result table A table containing all registered situation data, indexed by their IDs, or an array filtered by screen_id.
Fields:
* id (string) Unique situation identifier.
* screen_id (string) ID of the screen this situation belongs to.
* handle (function) Called when the situation is applied.
* update (function) Called each frame while situation is active.

Situation.apply (id, current_screen_id)

Applies a situation, checking screen compatibility and returning the new situation ID if successful.

Parameters:

• id string The situation ID to apply.
• current_screen_id string The ID of the currently active screen.

Returns:

string|nil The ID of the applied situation if successful, otherwise nil.

Decision

Decision.register (decision)

Registers a decision definition.

Parameters:

• decision table The decision data table.
  • id string Unique decision identifier.
  • label string Display text for the decision.
  • condition function Returns true if decision is available. Defaults to always true. (optional)
  • handle function Called when the decision is selected. Defaults to noop. (optional)

Decision.get_by_id (id)

Gets a decision by ID.

Parameters:

• id string The ID of the decision.

Returns:

table|nil result The decision table or nil.
Fields:
* id (string) Unique decision identifier.
* label (string) Display text for the decision.
* condition (function) Returns true if decision is available.
* handle (function) Called when the decision is selected.

Decision.get_all ()

Gets all registered decisions.

Returns:

result table A table of all registered decisions, indexed by their IDs.
Fields:
* id (string) Unique decision identifier.
* label (string) Display text for the decision.
* condition (function) Returns true if decision is available.
* handle (function) Called when the decision is selected.

Decision.get_for_screen (screen_data)

Gets decision objects based on a screen's data.

Parameters:

• screen_data table The data for the screen.
  • decisions table Array of decision ID strings.

Returns:

result table An array of decision objects relevant to the screen or nil.
Fields:
* id (string) Unique decision identifier.
* label (string) Display text for the decision.
* condition (function) Returns true if decision is available.
* handle (function) Called when the decision is selected.

Decision.filter_available (decisions_list)

Filters a list of decision objects based on their condition function.

Parameters:

• decisions_list table A table of decision objects.

Returns:

result table An array of decisions for which condition() is true or nil.
Fields:
* id (string) Unique decision identifier.
* label (string) Display text for the decision.
* condition (function) Returns true if decision is available.
* handle (function) Called when the decision is selected.

Map

Map.get_maps_array ()

Gets all registered maps as an array.

Returns:

result table An array of registered map data.
Fields:
* id (string) Unique map identifier.
* from_x (number) Source tile X coordinate in the map sheet.
* from_y (number) Source tile Y coordinate in the map sheet.
* width (number) Width in tiles.
* height (number) Height in tiles.
* to_x (number) Destination X coordinate on screen.
* to_y (number) Destination Y coordinate on screen.

Map.register (map_data)

Registers a map definition.

Parameters:

• map_data table The map data table.
  • id string Unique map identifier.
    
  • from_x number Source tile X coordinate in the map sheet.
    
  • from_y number Source tile Y coordinate in the map sheet.
    
  • width number Width in tiles.
    
  • height number Height in tiles.
    
  • to_x number Destination X coordinate on screen.
    
  • to_y number Destination Y coordinate on screen.
    

Map.get_by_id (map_id)

Gets a map by ID.

Parameters:

• map_id string The ID of the map.

Returns:

result table The map data table or nil.
Fields:
* id (string) Unique map identifier.
* from_x (number) Source tile X coordinate in the map sheet.
* from_y (number) Source tile Y coordinate in the map sheet.
* width (number) Width in tiles.
* height (number) Height in tiles.
* to_x (number) Destination X coordinate on screen.
* to_y (number) Destination Y coordinate on screen.

Map.draw (map_id)

Draws a map.

Parameters:

• map_id string The ID of the map to draw.

Screen

Screen.register (screen_data)

Registers a screen definition.

Parameters:

• screen_data table The screen data table.
  • id string Unique screen identifier.
  • name string Display name of the screen.
  • decisions table Array of decision ID strings available on this screen.
  • background string Map ID used as background.
  • situations table Array of situation ID strings. Defaults to {}. (optional)
  • init function Called when the screen is entered. Defaults to noop. (optional)
  • update function Called each frame while screen is active. Defaults to noop. (optional)
  • draw function Called after the focus overlay to draw screen-specific overlays. Defaults to noop. (optional)

Screen.get_by_id (screen_id)

Gets a screen by ID.

Parameters:

• screen_id string The ID of the screen.

Returns:

table|nil screen The screen table or nil.
Fields:
* id (string) Unique screen identifier.
* name (string) Display name.
* decisions (table) Array of decision ID strings.
* background (string) Map ID used as background.
* situations (table) Array of situation ID strings.
* init (function) Called when the screen is entered.
* update (function) Called each frame while screen is active.

Screen.get_all ()

Gets all registered screens.

Returns:

result table A table containing all registered screen data, indexed by their IDs or nil.
Fields:
* id (string) Unique screen identifier.
* name (string) Display name of the screen.
* decisions (table) Array of decision ID strings available on this screen.
* background (string) Map ID used as background.
* situations (table) Array of situation ID strings.
* init (function) Called when the screen is entered.
* update (function) Called each frame while screen is active.

Window

Window.register (id, window_table)

Registers a window table.

Parameters:

• id string The ID of the window (e.g., "splash", "menu").
  
• window_table table The actual window module table (e.g., SplashWindow).
  

Window.get (id)

Retrieves a registered window table by its ID.

Parameters:

• id string The ID of the window.

Returns:

result table The window module table or nil.
Fields:
* update (function) Called each frame to update window logic.
* draw (function) Called each frame to draw the window.

Window.set_current (id)

Sets the currently active window.

Parameters:

• id string The ID of the window to activate.
  

Window.get_current_id ()

Gets the ID of the currently active window. This function is used by the main game loop to update and draw the active window.

Returns:

string The ID of the active window.

Window.get_current_handler ()

Gets the handler function for the currently active window. This function is used by the main game loop to update and draw the active window.

Returns:

function A function that updates and draws the current window.

SplashWindow

SplashWindow.draw ()

Draws the splash window.

SplashWindow.update ()

Updates the splash window logic.

IntroWindow

IntroWindow.draw ()

Draws the intro window.

IntroWindow.update ()

Updates the intro window logic.

MenuWindow

MenuWindow.draw ()

Draws the menu window.

MenuWindow.update ()

Updates the menu window logic.

MenuWindow.new_game ()

Starts a new game from the menu.

MenuWindow.load_game ()

Loads a game from the menu.

MenuWindow.save_game ()

Saves the current game from the menu.

MenuWindow.resume_game ()

Resumes the game from the menu.

MenuWindow.exit ()

Exits the game.

MenuWindow.configuration ()

Opens the configuration menu.

MenuWindow.audio_test ()

Opens the audio test menu.

MenuWindow.refresh_menu_items ()

Refreshes menu items.

ConfigurationWindow

ConfigurationWindow.init ()

Initializes configuration window.

ConfigurationWindow.draw ()

Draws configuration window.

ConfigurationWindow.update ()

Updates configuration window logic.

AudioTestWindow

AudioTestWindow.generate_menuitems (list_func, index_func)

Generates menu items for audio test.

Parameters:

• list_func table List of audio functions.
  
• index_func number Current index of selected function.
  

Returns:

result table Generated menu items, an array of menu item tables or nil.
Fields:
* label (string) Display text for the menu item.
* decision (function) Called when the menu item is selected.

AudioTestWindow.generate_listfunc ()

Generates list of audio functions.

Returns:

result table A sorted list of audio function names.

AudioTestWindow.back ()

Navigates back from audio test window.

AudioTestWindow.init ()

Initializes audio test window.

AudioTestWindow.draw ()

Draws audio test window.

AudioTestWindow.update ()

Updates audio test window logic.

PopupWindow

PopupWindow.show (content_strings)

Displays a popup window.

Parameters:

• content_strings table A table of strings to display in the popup.
  

PopupWindow.hide ()

Hides the popup window.

PopupWindow.update ()

Updates popup window logic.

PopupWindow.draw ()

Draws the popup window.

MinigameButtonMashWindow

MinigameButtonMashWindow.init (params)

Initializes button mash minigame state.

Parameters:

• params table Optional parameters for configuration.
  

MinigameButtonMashWindow.start (return_window[, params])

Starts the button mash minigame.

Parameters:

• return_window string The window ID to return to after the minigame.
  
• params table Optional parameters for minigame configuration.
  (optional)

MinigameButtonMashWindow.update ()

Updates button mash minigame logic.

MinigameButtonMashWindow.draw ()

Draws button mash minigame.

MinigameRhythmWindow

MinigameRhythmWindow.init (params)

Initializes rhythm minigame state.

Parameters:

• params table Optional parameters for configuration.
  

MinigameRhythmWindow.start (return_window[, params])

Starts the rhythm minigame.

Parameters:

• return_window string The window ID to return to after the minigame.
  
• params table Optional parameters for minigame configuration.
  (optional)

MinigameRhythmWindow.update ()

Updates rhythm minigame logic.

MinigameRhythmWindow.draw ()

Draws rhythm minigame.

MinigameDDRWindow

MinigameDDRWindow.init (params)

Initializes DDR minigame state.

Parameters:

• params table Optional parameters for configuration.
  

MinigameDDRWindow.start (return_window[, song_key[, params]])

Starts the DDR minigame.

Parameters:

• return_window string The window ID to return to after the minigame.
  
• song_key string The key of the song to play.
  (optional)
• params table Optional parameters for minigame configuration.
  (optional)

MinigameDDRWindow.update ()

Updates DDR minigame logic.

MinigameDDRWindow.draw ()

Draws DDR minigame.

GameWindow

GameWindow.draw ()

Draws the game window.

GameWindow.update ()

Updates the game window logic.

GameWindow.set_state (new_state)

Sets the active window.

Parameters:

• new_state string The ID of the new active window.
  

Main

TIC ()

Main game loop (TIC-80 callback).