docs

.luacheckrc

@@ -11,7 +11,6 @@ globals = {
   "Print",
   "Input",
   "Audio",
-  "Config",
   "Context",
   "Meters",
   "Minigames",

inc/data/data.songs.lua

@@ -107,11 +107,8 @@ Songs = {
   }
 }
 
---- Converts beats to frames.
--- @param beat number The beat number.
--- @param bpm number Beats per minute.
--- @param[opt] fps number Frames per second (default: 60).
--- @return number The corresponding frame number.
+-- Helper function to calculate frame from beat
+-- Usage: frame_from_beat(beat_number, bpm, fps)
 function frame_from_beat(beat, bpm, fps)
   fps = fps or 60
   local seconds_per_beat = 60 / bpm
@@ -119,11 +116,8 @@ function frame_from_beat(beat, bpm, fps)
   return math.floor(beat * frames_per_beat)
 end
 
---- Converts beat notation to frame pattern.
--- @param beats table A table of beat data, e.g., {{1, "left"}, {2, "down"}}.
--- @param bpm number Beats per minute.
--- @param[opt] fps number Frames per second (default: 60).
--- @return table The generated pattern.
+-- Helper function to convert simple beat notation to frame pattern
+-- Usage: beats_to_pattern({{1, "left"}, {2, "down"}}, 120)
 function beats_to_pattern(beats, bpm, fps)
   fps = fps or 60
   local pattern = {}

inc/decision/decision.manager.lua

@@ -1,7 +1,5 @@
 local _decisions = {}
 
---- Registers a decision definition.
--- @param decision table The decision data table.
 function Decision.register(decision)
   if not decision or not decision.id then
     PopupWindow.show({"Error: Invalid decision object registered (missing id)!"})
@@ -24,15 +22,10 @@ function Decision.register(decision)
   _decisions[decision.id] = decision
 end
 
---- Gets a decision by ID.
--- @param id string The ID of the decision.
--- @return table The decision table or nil.
 function Decision.get(id)
   return _decisions[id]
 end
 
---- Gets all registered decisions.
--- @return table A table of all registered decisions.
 function Decision.get_all()
   return _decisions
 end

inc/init/init.config.lua

@@ -22,8 +22,7 @@ local DEFAULT_CONFIG = {
   }
 }
 
--- Game configuration settings.
-Config = {
+local Config = {
   screen = DEFAULT_CONFIG.screen,
   colors = DEFAULT_CONFIG.colors,
   player = DEFAULT_CONFIG.player,
@@ -35,12 +34,10 @@ local CONFIG_MAGIC_VALUE_ADDRESS = 2
 local CONFIG_SPLASH_DURATION_ADDRESS = 3
 local CONFIG_MAGIC_VALUE = 0xDE
 
---- Saves the current configuration.
 function Config.save()
   mset(CONFIG_MAGIC_VALUE, CONFIG_MAGIC_VALUE_ADDRESS, CONFIG_SAVE_BANK)
 end
 
---- Loads saved configuration.
 function Config.load()
   if mget(CONFIG_MAGIC_VALUE_ADDRESS, CONFIG_SAVE_BANK) == CONFIG_MAGIC_VALUE then
     Config.timing.splash_duration = mget(CONFIG_SPLASH_DURATION_ADDRESS, CONFIG_SAVE_BANK)
@@ -49,7 +46,6 @@ function Config.load()
   end
 end
 
---- Restores default configuration settings.
 function Config.restore_defaults()
   Config.timing.splash_duration = DEFAULT_CONFIG.timing.splash_duration
 end

inc/init/init.context.lua

@@ -4,8 +4,6 @@ local SAVE_GAME_MAGIC_VALUE = 0xCA
 
 local SAVE_GAME_CURRENT_SCREEN_ADDRESS = 6
 
---- Gets initial data for Context.
--- @return table Initial context data.
 local function get_initial_data()
   return {
     active_window = WINDOW_SPLASH,
@@ -48,17 +46,17 @@ on than meets the eye.]]
     minigame_button_mash = Minigames.get_default_button_mash(),
     minigame_rhythm = Minigames.get_default_rhythm(),
     meters = Meters.get_initial(),
-    --- Active sprites.
+    --- Table storing currently active sprites to be drawn.
+    -- Each entry is a table with `id`, `x`, `y`, and other drawing parameters.
     sprites = {},
-    --- Current situation ID.
+    --- The ID of the currently active situation.
+    -- Set by `Situation.apply()` and `nil` if no situation is active.
     current_situation = nil,
   }
 end
 
---- Global game context.
 Context = {}
 
---- Resets game context to initial state.
 local function reset_context_to_initial_state()
   local initial_data = get_initial_data()
 
@@ -87,15 +85,12 @@ end
 
 reset_context_to_initial_state()
 
---- Starts a new game.
 function Context.new_game()
   reset_context_to_initial_state()
   Context.game_in_progress = true
   MenuWindow.refresh_menu_items()
-  Context.screens[Context.current_screen].init()
 end
 
---- Saves the current game state.
 function Context.save_game()
   if not Context.game_in_progress then return end
 
@@ -103,7 +98,6 @@ function Context.save_game()
   mset(Context.current_screen, SAVE_GAME_CURRENT_SCREEN_ADDRESS, SAVE_GAME_BANK)
 end
 
---- Loads a saved game state.
 function Context.load_game()
   if mget(SAVE_GAME_MAGIC_VALUE_ADDRESS, SAVE_GAME_BANK) ~= SAVE_GAME_MAGIC_VALUE then
         Context.new_game()
@@ -115,5 +109,4 @@ function Context.load_game()
 
   Context.game_in_progress = true
   MenuWindow.refresh_menu_items()
-  Context.screens[Context.current_screen].init()
 end

inc/init/init.meters.lua

@@ -6,14 +6,11 @@ local COMBO_BASE_BONUS = 0.02
 local COMBO_MAX_BONUS = 0.16
 local COMBO_TIMEOUT_FRAMES = 600
 
--- Internal meters for tracking game progress and player stats.
 Meters.COLOR_ISM = Config.colors.red
 Meters.COLOR_WPM = Config.colors.blue
 Meters.COLOR_BM = Config.colors.black
 Meters.COLOR_BG = Config.colors.meter_bg
 
---- Gets initial meter values.
--- @return table A table of initial meter values.
 function Meters.get_initial()
   return {
     ism = METER_DEFAULT,
@@ -25,24 +22,18 @@ function Meters.get_initial()
   }
 end
 
---- Hides meters.
 function Meters.hide()
   if Context and Context.meters then Context.meters.hidden = true end
 end
 
---- Shows meters.
 function Meters.show()
   if Context and Context.meters then Context.meters.hidden = false end
 end
 
---- Gets max meter value.
--- @return number The maximum meter value.
 function Meters.get_max()
   return METER_MAX
 end
 
---- Gets combo multiplier.
--- @return number The current combo multiplier.
 function Meters.get_combo_multiplier()
   if not Context or not Context.meters then return 1 end
   local combo = Context.meters.combo
@@ -50,7 +41,6 @@ function Meters.get_combo_multiplier()
   return 1 + math.min(COMBO_MAX_BONUS, COMBO_BASE_BONUS * (2 ^ (combo - 1)))
 end
 
---- Updates all meters.
 function Meters.update()
   if not Context or not Context.game_in_progress or not Context.meters then return end
   local m = Context.meters
@@ -66,9 +56,6 @@ function Meters.update()
   end
 end
 
---- Adds amount to a meter.
--- @param key string The meter key (e.g., "wpm", "ism", "bm").
--- @param amount number The amount to add.
 function Meters.add(key, amount)
   if not Context or not Context.meters then return end
   local m = Context.meters
@@ -77,7 +64,6 @@ function Meters.add(key, amount)
   end
 end
 
---- Called on minigame completion.
 function Meters.on_minigame_complete()
   local m = Context.meters
   local gain = math.floor(METER_GAIN_PER_CHORE * Meters.get_combo_multiplier())

inc/init/init.minigames.lua

@@ -1,10 +1,5 @@
--- Manages minigame configurations and initial states.
 Minigames = {}
 
---- Applies parameters to defaults.
--- @param defaults table The default configuration table.
--- @param params table The parameters to apply.
--- @return table The updated configuration table.
 local function apply_params(defaults, params)
   if not params then return defaults end
   for k, v in pairs(params) do
@@ -13,8 +8,6 @@ local function apply_params(defaults, params)
   return defaults
 end
 
---- Gets default DDR minigame configuration.
--- @return table The default DDR minigame configuration.
 function Minigames.get_default_ddr()
   local arrow_size = 12
   local arrow_spacing = 30
@@ -54,8 +47,6 @@ function Minigames.get_default_ddr()
   }
 end
 
---- Gets default button mash minigame configuration.
--- @return table The default button mash minigame configuration.
 function Minigames.get_default_button_mash()
   return {
     bar_fill = 0,
@@ -76,8 +67,6 @@ function Minigames.get_default_button_mash()
   }
 end
 
---- Gets default rhythm minigame configuration.
--- @return table The default rhythm minigame configuration.
 function Minigames.get_default_rhythm()
   return {
     line_position = 0,
@@ -105,23 +94,14 @@ function Minigames.get_default_rhythm()
   }
 end
 
---- Configures DDR minigame.
--- @param params table Optional parameters to override defaults.
--- @return table The configured DDR minigame state.
 function Minigames.configure_ddr(params)
   return apply_params(Minigames.get_default_ddr(), params)
 end
 
---- Configures button mash minigame.
--- @param params table Optional parameters to override defaults.
--- @return table The configured button mash minigame state.
 function Minigames.configure_button_mash(params)
   return apply_params(Minigames.get_default_button_mash(), params)
 end
 
---- Configures rhythm minigame.
--- @param params table Optional parameters to override defaults.
--- @return table The configured rhythm minigame state.
 function Minigames.configure_rhythm(params)
   return apply_params(Minigames.get_default_rhythm(), params)
 end

inc/map/map.manager.lua

@@ -1,9 +1,5 @@
--- Manages game maps.
-
 local _maps = {}
 
---- Gets all registered maps as an array.
--- @return table An array of registered map data.
 function Map.get_maps_array()
   local maps_array = {}
   for _, map_data in pairs(_maps) do
@@ -12,8 +8,6 @@ function Map.get_maps_array()
   return maps_array
 end
 
---- Registers a map definition.
--- @param map_data table The map data table.
 function Map.register(map_data)
   if _maps[map_data.id] then
     trace("Warning: Overwriting map with id: " .. map_data.id)
@@ -21,15 +15,10 @@ function Map.register(map_data)
   _maps[map_data.id] = map_data
 end
 
---- Gets a map by ID.
--- @param map_id string The ID of the map.
--- @return table The map data table or nil.
 function Map.get_by_id(map_id)
   return _maps[map_id]
 end
 
---- Draws a map.
--- @param map_id string The ID of the map to draw.
 function Map.draw(map_id)
   local map_data = Map.get_by_id(map_id)
   if not map_data then
@@ -43,4 +32,4 @@ function Map.draw(map_id)
     map_data.to_x,
     map_data.to_y
   )
-end
+end

inc/screen/screen.manager.lua

@@ -1,7 +1,13 @@
 local _screens = {}
 
---- Registers a screen definition.
--- @param screen_data table The screen data table.
+--- Registers a new screen definition with the Screen manager.
+-- Overwrites existing screen if an ID conflict occurs.
+-- @param screen_data table A table containing the screen definition.
+--        Must include an `id` field (string).
+--        Optional fields:
+--        - `situations` (table): A table of situation IDs allowed on this screen. Defaults to an empty table.
+--        - `init` (function): Function to execute once when the screen becomes active. Defaults to an empty function.
+--        - `update` (function): Function to execute each frame while the screen is active. Defaults to an empty function.
 function Screen.register(screen_data)
   if _screens[screen_data.id] then
     trace("Warning: Overwriting screen with id: " .. screen_data.id)
@@ -18,9 +24,9 @@ function Screen.register(screen_data)
   _screens[screen_data.id] = screen_data
 end
 
---- Gets a screen by ID.
--- @param screen_id string The ID of the screen.
--- @return table The screen table or nil.
+--- Retrieves a registered screen by its ID.
+-- @param screen_id string The ID of the screen to retrieve.
+-- @return table The screen table, or `nil` if not found.
 function Screen.get_by_id(screen_id)
   return _screens[screen_id]
 end

inc/situation/situation.manager.lua

@@ -1,7 +1,12 @@
 local _situations = {}
 
---- Registers a situation definition.
--- @param situation table The situation data table.
+--- Registers a new situation with the Situation manager.
+-- Overwrites existing situation if an ID conflict occurs.
+-- @param situation table A table containing the situation definition.
+--        Must include an `id` field (string).
+--        Optional fields:
+--        - `handle` (function): Function to execute when the situation is applied. Defaults to an empty function.
+--        - `update` (function): Function to execute each frame while the situation is active. Defaults to an empty function.
 function Situation.register(situation)
   if not situation or not situation.id then
     PopupWindow.show({"Error: Invalid situation object registered (missing id)!"})
@@ -19,15 +24,19 @@ function Situation.register(situation)
   _situations[situation.id] = situation
 end
 
---- Gets a situation by ID.
--- @param id string The situation ID.
--- @return table The situation table or nil.
+--- Retrieves a registered situation by its ID.
+-- @param id string The ID of the situation to retrieve.
+-- @return table The situation table, or `nil` if not found.
 function Situation.get(id)
   return _situations[id]
 end
 
---- Applies a situation.
--- @param id string The situation ID to apply.
+--- Applies a situation, making it the current active situation.
+-- The situation's `handle` function is executed.
+-- This function first checks if the situation is valid and if it's allowed
+-- on the current screen (as defined in `Context.screens[Context.current_screen].situations`).
+-- If successful, `Context.current_situation` is updated with the ID of the applied situation.
+-- @param id string The ID of the situation to apply.
 function Situation.apply(id)
   local situation = Situation.get(id)
   if not situation then

inc/sprite/sprite.manager.lua

@@ -1,7 +1,15 @@
 local _sprites = {}
 
---- Registers a sprite definition.
+--- Registers a new sprite or complex sprite definition with the Sprite manager.
+-- Overwrites existing sprite if an ID conflict occurs.
 -- @param sprite_data table A table containing the sprite definition.
+--        Must include an `id` field (string) and either an `s` field (number, for simple sprites)
+--        or a `sprites` field (table, for complex sprites).
+--        For complex sprites, `sprites` is a table of sub-sprite definitions, each with:
+--        - `s` (number): Sprite index.
+--        - `x_offset` (number): X-offset relative to the parent sprite's position.
+--        - `y_offset` (number): Y-offset relative to the parent sprite's position.
+--        - Optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` for individual sub-sprites.
 function Sprite.register(sprite_data)
   if not sprite_data or not sprite_data.id then
     trace("Error: Invalid sprite object registered (missing id)!")
@@ -13,16 +21,19 @@ function Sprite.register(sprite_data)
   _sprites[sprite_data.id] = sprite_data
 end
 
---- Schedules a sprite for drawing.
--- @param id string The unique identifier of the sprite.
--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
--- @param[opt] colorkey number The color index for transparency.
--- @param[opt] scale number The scaling factor.
--- @param[opt] flip_x number Set to 1 to flip horizontally.
--- @param[opt] flip_y number Set to 1 to flip vertically.
--- @param[opt] rot number The rotation in degrees.
+--- Schedules a registered sprite to be drawn at a specific position with optional transformations.
+-- The sprite's parameters are stored in `Context.sprites` for deferred rendering by `Sprite.draw()`.
+-- If the sprite with the given `id` is already scheduled, its parameters will be updated.
+-- @param id string The unique identifier of the sprite to show. Must be registered via `Sprite.register`.
+-- @param x number The x-coordinate on the screen where the sprite will be drawn.
+-- @param y number The y-coordinate on the screen where the sprite will be drawn.
+-- @param[opt] colorkey number The color index to be treated as transparent (default: 0).
+-- @param[opt] scale number The scaling factor for the sprite (default: 1).
+-- @param[opt] flip_x number Set to 1 to flip the sprite horizontally (default: 0).
+-- @param[opt] flip_y number Set to 1 to flip the sprite vertically (default: 0).
+-- @param[opt] rot number The rotation of the sprite in degrees (default: 0).
 function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
+  -- Ensure the sprite exists before attempting to show it
   if not _sprites[id] then
     trace("Error: Attempted to show non-registered sprite with id: " .. id)
     return
@@ -40,28 +51,34 @@ function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
   }
 end
 
---- Hides a displayed sprite.
--- @param id string The unique identifier of the sprite.
+--- Hides a currently displayed sprite by removing it from the `Context.sprites` table.
+-- The sprite will no longer be drawn in subsequent frames.
+-- @param id string The unique identifier of the sprite to hide.
 function Sprite.hide(id)
   Context.sprites[id] = nil
 end
 
---- Draws all scheduled sprites.
+--- Draws all sprites currently scheduled in `Context.sprites`.
+-- This function retrieves the registered sprite definitions and applies the stored
+-- position and transformation parameters. It handles both simple and complex sprites.
 function Sprite.draw()
   for id, params in pairs(Context.sprites) do
     local sprite_data = _sprites[id]
     if not sprite_data then
       trace("Error: Sprite id " .. id .. " in Context.sprites is not registered.")
-      Context.sprites[id] = nil
+      Context.sprites[id] = nil -- Clean up invalid entry
+      -- We should probably continue to the next sprite instead of returning
+      -- so that other valid sprites can still be drawn.
     end
 
+    -- Use parameters from Context.sprites, or fall back to sprite_data, then to defaults
     local colorkey = params.colorkey or sprite_data.colorkey or 0
     local scale = params.scale or sprite_data.scale or 1
     local flip_x = params.flip_x or sprite_data.flip_x or 0
     local flip_y = params.flip_y or sprite_data.flip_y or 0
     local rot = params.rot or sprite_data.rot or 0
 
-    if sprite_data.sprites then
+    if sprite_data.sprites then -- Complex sprite
       for i = 1, #sprite_data.sprites do
         local sub_sprite = sprite_data.sprites[i]
         spr(
@@ -75,7 +92,7 @@ function Sprite.draw()
           sub_sprite.rot or rot
         )
       end
-    else
+    else -- Simple sprite
       spr(sprite_data.s, params.x, params.y, colorkey, scale, flip_x, flip_y, rot)
     end
   end

inc/system/system.audio.lua

@@ -1,27 +1,14 @@
---- Stops current music.
 function Audio.music_stop() music() end
---- Plays main menu music.
 function Audio.music_play_mainmenu() end
---- Plays waking up music.
 function Audio.music_play_wakingup() end
---- Plays room morning music.
 function Audio.music_play_room_morning() end
---- Plays room street 1 music.
 function Audio.music_play_room_street_1() end
---- Plays room street 2 music.
 function Audio.music_play_room_street_2() end
---- Plays room music.
 function Audio.music_play_room_() end
---- Plays room work music.
 function Audio.music_play_room_work() end
 
---- Plays select sound effect.
 function Audio.sfx_select() sfx(17, 'C-7', 30) end
---- Plays deselect sound effect.
 function Audio.sfx_deselect() sfx(18, 'C-7', 30) end
---- Plays beep sound effect.
 function Audio.sfx_beep() sfx(19, 'C-6', 30) end
---- Plays success sound effect.
 function Audio.sfx_success() sfx(16, 'C-7', 60) end
---- Plays bloop sound effect.
 function Audio.sfx_bloop() sfx(21, 'C-3', 60) end

inc/system/system.input.lua

@@ -7,21 +7,11 @@ local INPUT_KEY_SPACE = 48
 local INPUT_KEY_BACKSPACE = 51
 local INPUT_KEY_ENTER = 50
 
---- Checks if Up is pressed.
 function Input.up() return btnp(INPUT_KEY_UP) end
---- Checks if Down is pressed.
 function Input.down() return btnp(INPUT_KEY_DOWN) end
---- Checks if Left is pressed.
 function Input.left() return btnp(INPUT_KEY_LEFT) end
---- Checks if Right is pressed.
 function Input.right() return btnp(INPUT_KEY_RIGHT) end
---- Checks if Select is pressed.
 function Input.select() return btnp(INPUT_KEY_A) or keyp(INPUT_KEY_SPACE) end
---- Checks if Menu Confirm is pressed.
 function Input.menu_confirm() return btnp(INPUT_KEY_A) or keyp(INPUT_KEY_ENTER) end
---- Checks if Player Interact is pressed.
-function Input.player_interact() return btnp(INPUT_KEY_B) or keyp(INPUT_KEY_ENTER) end
---- Checks if Menu Back is pressed.
-function Input.menu_back() return btnp(INPUT_KEY_Y) or keyp(INPUT_KEY_BACKSPACE) end
---- Checks if Toggle Popup is pressed.
+function Input.player_interact() return btnp(INPUT_KEY_B) or keyp(INPUT_KEY_ENTER) end function Input.menu_back() return btnp(INPUT_KEY_Y) or keyp(INPUT_KEY_BACKSPACE) end
 function Input.toggle_popup() return keyp(INPUT_KEY_ENTER) end

inc/system/system.main.lua

@@ -44,7 +44,6 @@ local STATE_HANDLERS = {
 
 local initialized_game = false
 
---- Initializes game state.
 local function init_game()
   if initialized_game then return end
 
@@ -52,7 +51,6 @@ local function init_game()
   initialized_game = true
 end
 
---- Main game loop (TIC-80 callback).
 function TIC()
   init_game()
   cls(Config.colors.black)

inc/system/system.print.lua

@@ -1,10 +1,4 @@
---- Prints text with shadow.
--- @param text string The text to print.
--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
+
 function Print.text(text, x, y, color, fixed, scale)
   local shadow_color = Config.colors.black
   if color == shadow_color then shadow_color = Config.colors.light_grey end
@@ -13,13 +7,6 @@ function Print.text(text, x, y, color, fixed, scale)
   print(text, x, y, color, fixed, scale)
 end
 
---- Prints centered text with shadow.
--- @param text string The text to print.
--- @param x number The x-coordinate for centering.
--- @param y number The y-coordinate.
--- @param color number The color of the text.
--- @param[opt] fixed boolean If true, uses fixed-width font.
--- @param[opt] scale number The scaling factor.
 function Print.text_center(text, x, y, color, fixed, scale)
   scale = scale or 1
   local text_width = print(text, 0, -6, 0, fixed, scale)

inc/system/system.ui.lua

@@ -1,20 +1,12 @@
---- Draws the top bar.
--- @param title string The title text to display.
 function UI.draw_top_bar(title)
   rect(0, 0, Config.screen.width, 10, Config.colors.dark_grey)
   Print.text(title, 3, 2, Config.colors.green)
 end
 
---- Draws dialog window.
 function UI.draw_dialog()
   PopupWindow.draw()
 end
 
---- Draws a menu.
--- @param items table A table of menu items.
--- @param selected_item number The index of the currently selected item.
--- @param x number The x-coordinate for the menu.
--- @param y number The y-coordinate for the menu.
 function UI.draw_menu(items, selected_item, x, y)
   for i, item in ipairs(items) do
     local current_y = y + (i-1)*10
@@ -25,10 +17,6 @@ function UI.draw_menu(items, selected_item, x, y)
   end
 end
 
---- Updates menu selection.
--- @param items table A table of menu items.
--- @param selected_item number The current index of the selected item.
--- @return number The updated index of the selected item.
 function UI.update_menu(items, selected_item)
   if Input.up() then
     Audio.sfx_beep()
@@ -46,10 +34,6 @@ function UI.update_menu(items, selected_item)
   return selected_item
 end
 
---- Wraps text.
--- @param text string The text to wrap.
--- @param max_chars_per_line number The maximum characters per line.
--- @return table A table of wrapped lines.
 function UI.word_wrap(text, max_chars_per_line)
     if text == nil then return {""} end
     local lines = {}
@@ -79,15 +63,6 @@ function UI.word_wrap(text, max_chars_per_line)
     return lines
 end
 
---- Creates a numeric stepper.
--- @param label string The label for the stepper.
--- @param value_getter function Function to get the current value.
--- @param value_setter function Function to set the current value.
--- @param min number The minimum value.
--- @param max number The maximum value.
--- @param step number The step increment.
--- @param[opt] format string The format string for displaying the value.
--- @return table A numeric stepper control definition.
 function UI.create_numeric_stepper(label, value_getter, value_setter, min, max, step, format)
   return {
     label = label,
@@ -101,10 +76,6 @@ function UI.create_numeric_stepper(label, value_getter, value_setter, min, max,
   }
 end
 
---- Creates an action item.
--- @param label string The label for the action item.
--- @param action function The function to execute when the item is selected.
--- @return table An action item control definition.
 function UI.create_action_item(label, action)
   return {
     label = label,
@@ -113,9 +84,6 @@ function UI.create_action_item(label, action)
   }
 end
 
---- Draws decision selector.
--- @param decisions table A table of decision items.
--- @param selected_decision_index number The index of the selected decision.
 function UI.draw_decision_selector(decisions, selected_decision_index)
   local bar_height = 16
   local bar_y = Config.screen.height - bar_height
@@ -129,7 +97,6 @@ function UI.draw_decision_selector(decisions, selected_decision_index)
         Print.text(decision_label, text_x, text_y, Config.colors.item)         Print.text(">", Config.screen.width - 6, text_y, Config.colors.green)   end
 end
 
---- Draws meters.
 function UI.draw_meters()
   if not Context or not Context.game_in_progress or not Context.meters then return end
   if Context.meters.hidden then return end
@@ -162,10 +129,6 @@ function UI.draw_meters()
   end
 end
 
---- Updates decision selector.
--- @param decisions table A table of decision items.
--- @param selected_decision_index number The current index of the selected decision.
--- @return number The updated index of the selected decision.
 function UI.update_decision_selector(decisions, selected_decision_index)
   if Input.left() then
     Audio.sfx_beep()
@@ -175,4 +138,4 @@ function UI.update_decision_selector(decisions, selected_decision_index)
     selected_decision_index = Util.safeindex(decisions, selected_decision_index + 1)
   end
   return selected_decision_index
-end
+end

inc/system/system.util.lua

@@ -1,16 +1,9 @@
---- Utility functions.
 Util = {}
 
---- Safely wraps an index for an array.
--- @param array table The array to index.
--- @param index number The desired index (can be out of bounds).
--- @return number The wrapped index within the array's bounds.
 function Util.safeindex(array, index)
     return ((index - 1 + #array) % #array) + 1
 end
 
---- Navigates to a screen by its ID.
--- @param screen_id string The ID of the screen to go to.
 function Util.go_to_screen_by_id(screen_id)
   local screen_index = Context.screen_indices_by_id[screen_id]
   if screen_index then
@@ -18,4 +11,4 @@ function Util.go_to_screen_by_id(screen_id)
     Context.selected_decision_index = 1   else
     PopupWindow.show({"Error: Screen '" .. screen_id .. "' not found or not indexed!"})
   end
-end
+end

inc/window/window.audiotest.lua

@@ -6,10 +6,6 @@ AudioTestWindow = {
     last_pressed = false
 }
 
---- Generates menu items for audio test.
--- @param list_func table List of audio functions.
--- @param index_func number Current index of selected function.
--- @return table Generated menu items.
 function AudioTestWindow.generate_menuitems(list_func, index_func)
     return {
         {
@@ -38,8 +34,6 @@ function AudioTestWindow.generate_menuitems(list_func, index_func)
     }
 end
 
---- Generates list of audio functions.
--- @return table A sorted list of audio function names.
 function AudioTestWindow.generate_listfunc()
     local result = {}
 
@@ -54,13 +48,11 @@ function AudioTestWindow.generate_listfunc()
     return result
 end
 
---- Navigates back from audio test window.
 function AudioTestWindow.back()
     Audio.sfx_deselect()
     GameWindow.set_state(WINDOW_MENU)
 end
 
---- Initializes audio test window.
 function AudioTestWindow.init()
     AudioTestWindow.last_pressed = false
     AudioTestWindow.index_menu = 1
@@ -71,13 +63,11 @@ function AudioTestWindow.init()
     )
 end
 
---- Draws audio test window.
 function AudioTestWindow.draw()
     UI.draw_top_bar("Audio test")
     UI.draw_menu(AudioTestWindow.menuitems, AudioTestWindow.index_menu, 20, 50)
 end
 
---- Updates audio test window logic.
 function AudioTestWindow.update()
     if Input.up() then
         AudioTestWindow.index_menu = Util.safeindex(AudioTestWindow.menuitems, AudioTestWindow.index_menu - 1)

inc/window/window.configuration.lua

@@ -3,7 +3,6 @@ ConfigurationWindow = {
   selected_control = 1,
 }
 
---- Initializes configuration window.
 function ConfigurationWindow.init()
   ConfigurationWindow.controls = {
     UI.create_decision_item(
@@ -17,7 +16,6 @@ function ConfigurationWindow.init()
   }
 end
 
---- Draws configuration window.
 function ConfigurationWindow.draw()
   UI.draw_top_bar("Configuration")
 
@@ -57,7 +55,6 @@ function ConfigurationWindow.draw()
   Print.text("Press B to go back", x_start, 120, Config.colors.light_grey)
 end
 
---- Updates configuration window logic.
 function ConfigurationWindow.update()
   if Input.menu_back() then
     GameWindow.set_state(WINDOW_MENU)
@@ -91,4 +88,4 @@ function ConfigurationWindow.update()
       end
     end
   end
-end
+end

inc/window/window.game.lua

@@ -1,4 +1,6 @@
---- Draws the game window.
+--- Draws the main game window content.
+-- This includes the current screen's background, top bar, decisions, and all active sprites.
+-- @function GameWindow.draw
 function GameWindow.draw()
   local screen = Context.screens[Context.current_screen]
   Map.draw(screen.background)
@@ -18,7 +20,10 @@ function GameWindow.draw()
   Sprite.draw()
 end
 
---- Updates the game window logic.
+--- Updates the logic for the main game window.
+-- Handles input, navigates between screens, calls the current screen's and situation's update functions,
+-- and processes player decisions.
+-- @function GameWindow.update
 function GameWindow.update()
   local previous_screen_index = Context.current_screen
 
@@ -81,8 +86,10 @@ function GameWindow.update()
   end
 end
 
---- Sets the active window.
--- @param new_state number The ID of the new active window.
+--- Sets the active window state for the game.
+-- This function is typically called when transitioning between different game states (e.g., to a minigame).
+-- @param new_state number The ID of the new active window (e.g., `WINDOW_MENU`, `WINDOW_GAME`).
+-- @function GameWindow.set_state
 function GameWindow.set_state(new_state)
   Context.active_window = new_state
 end

inc/window/window.intro.lua

@@ -1,10 +1,8 @@
---- Draws the intro window.
 function IntroWindow.draw()
   local x = (Config.screen.width - 132) / 2
   Print.text(Context.intro.text, x, Context.intro.y, Config.colors.green)
 end
 
---- Updates the intro window logic.
 function IntroWindow.update()
   Context.intro.y = Context.intro.y - Context.intro.speed
 
@@ -20,4 +18,4 @@ function IntroWindow.update()
     if Input.menu_confirm() then
     GameWindow.set_state(WINDOW_MENU)
   end
-end
+end

inc/window/window.menu.lua

@@ -1,10 +1,8 @@
---- Draws the menu window.
 function MenuWindow.draw()
   UI.draw_top_bar("Main Menu")
   UI.draw_menu(Context.menu_items, Context.selected_menu_item, 108, 70)
 end
 
---- Updates the menu window logic.
 function MenuWindow.update()
   Context.selected_menu_item = UI.update_menu(Context.menu_items, Context.selected_menu_item)
 
@@ -17,43 +15,35 @@ function MenuWindow.update()
   end
 end
 
---- Starts a new game from the menu.
 function MenuWindow.new_game()
   Context.new_game()   GameWindow.set_state(WINDOW_GAME)
 end
 
---- Loads a game from the menu.
 function MenuWindow.load_game()
   Context.load_game()   GameWindow.set_state(WINDOW_GAME)
 end
 
---- Saves the current game from the menu.
 function MenuWindow.save_game()
   Context.save_game() end
 
---- Resumes the game from the menu.
 function MenuWindow.resume_game()
   GameWindow.set_state(WINDOW_GAME)
 end
 
---- Exits the game.
 function MenuWindow.exit()
   exit()
 end
 
---- Opens the configuration menu.
 function MenuWindow.configuration()
   ConfigurationWindow.init()
   GameWindow.set_state(WINDOW_CONFIGURATION)
 end
 
---- Opens the audio test menu.
 function MenuWindow.audio_test()
   AudioTestWindow.init()
   GameWindow.set_state(WINDOW_AUDIOTEST)
 end
 
---- Refreshes menu items.
 function MenuWindow.refresh_menu_items()
   Context.menu_items = {}
   if Context.game_in_progress then

inc/window/window.minigame.ddr.lua

@@ -1,13 +1,7 @@
---- Initializes DDR minigame state.
--- @param params table Optional parameters for configuration.
 function MinigameDDRWindow.init(params)
   Context.minigame_ddr = Minigames.configure_ddr(params)
 end
 
---- Starts the DDR minigame.
--- @param return_window number The window ID to return to after the minigame.
--- @param[opt] song_key string The key of the song to play.
--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameDDRWindow.start(return_window, song_key, params)
   MinigameDDRWindow.init(params)
   Context.minigame_ddr.return_window = return_window or WINDOW_GAME
@@ -28,7 +22,6 @@ function MinigameDDRWindow.start(return_window, song_key, params)
   Context.active_window = WINDOW_MINIGAME_DDR
 end
 
---- Spawns a random arrow.
 local function spawn_arrow()
   local mg = Context.minigame_ddr
   local target = mg.target_arrows[math.random(1, 4)]
@@ -39,8 +32,6 @@ local function spawn_arrow()
   })
 end
 
---- Spawns an arrow in a specific direction.
--- @param direction string The direction of the arrow ("left", "down", "up", "right").
 local function spawn_arrow_dir(direction)
   local mg = Context.minigame_ddr
   for _, target in ipairs(mg.target_arrows) do
@@ -55,28 +46,17 @@ local function spawn_arrow_dir(direction)
   end
 end
 
---- Checks if an arrow is hit.
--- @param arrow table The arrow data.
--- @return boolean True if the arrow is hit, false otherwise.
 local function check_hit(arrow)
   local mg = Context.minigame_ddr
   local distance = math.abs(arrow.y - mg.target_y)
   return distance <= mg.hit_threshold
 end
 
---- Checks if an arrow is missed.
--- @param arrow table The arrow data.
--- @return boolean True if the arrow is missed, false otherwise.
 local function check_miss(arrow)
   local mg = Context.minigame_ddr
   return arrow.y > mg.target_y + mg.hit_threshold
 end
 
---- Draws an arrow.
--- @param x number The x-coordinate.
--- @param y number The y-coordinate.
--- @param direction string The direction of the arrow.
--- @param color number The color of the arrow.
 local function draw_arrow(x, y, direction, color)
   local size = 12
   local half = size / 2
@@ -95,7 +75,6 @@ local function draw_arrow(x, y, direction, color)
   end
 end
 
---- Updates DDR minigame logic.
 function MinigameDDRWindow.update()
   local mg = Context.minigame_ddr
   if mg.bar_fill >= mg.max_fill then
@@ -188,7 +167,6 @@ function MinigameDDRWindow.update()
   end
 end
 
---- Draws DDR minigame.
 function MinigameDDRWindow.draw()
   local mg = Context.minigame_ddr
   if not mg then

inc/window/window.minigame.mash.lua

@@ -1,19 +1,13 @@
---- Initializes button mash minigame state.
--- @param params table Optional parameters for configuration.
 function MinigameButtonMashWindow.init(params)
   Context.minigame_button_mash = Minigames.configure_button_mash(params)
 end
 
---- Starts the button mash minigame.
--- @param return_window number The window ID to return to after the minigame.
--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameButtonMashWindow.start(return_window, params)
   MinigameButtonMashWindow.init(params)
   Context.minigame_button_mash.return_window = return_window or WINDOW_GAME
   Context.active_window = WINDOW_MINIGAME_BUTTON_MASH
 end
 
---- Updates button mash minigame logic.
 function MinigameButtonMashWindow.update()
   local mg = Context.minigame_button_mash
   if Input.select() then
@@ -39,7 +33,6 @@ function MinigameButtonMashWindow.update()
   end
 end
 
---- Draws button mash minigame.
 function MinigameButtonMashWindow.draw()
   local mg = Context.minigame_button_mash
   if mg.return_window == WINDOW_GAME then

inc/window/window.minigame.rhythm.lua

@@ -1,19 +1,13 @@
---- Initializes rhythm minigame state.
--- @param params table Optional parameters for configuration.
 function MinigameRhythmWindow.init(params)
   Context.minigame_rhythm = Minigames.configure_rhythm(params)
 end
 
---- Starts the rhythm minigame.
--- @param return_window number The window ID to return to after the minigame.
--- @param[opt] params table Optional parameters for minigame configuration.
 function MinigameRhythmWindow.start(return_window, params)
   MinigameRhythmWindow.init(params)
   Context.minigame_rhythm.return_window = return_window or WINDOW_GAME
   Context.active_window = WINDOW_MINIGAME_RHYTHM
 end
 
---- Updates rhythm minigame logic.
 function MinigameRhythmWindow.update()
   local mg = Context.minigame_rhythm
   mg.line_position = mg.line_position + (mg.line_speed * mg.line_direction)
@@ -56,7 +50,6 @@ function MinigameRhythmWindow.update()
   end
 end
 
---- Draws rhythm minigame.
 function MinigameRhythmWindow.draw()
   local mg = Context.minigame_rhythm
   if mg.return_window == WINDOW_GAME then

inc/window/window.popup.lua

@@ -5,18 +5,14 @@ local POPUP_HEIGHT = 80
 local TEXT_MARGIN_X = POPUP_X + 10
 local TEXT_MARGIN_Y = POPUP_Y + 10
 local LINE_HEIGHT = 8
---- Displays a popup window.
--- @param content_strings table A table of strings to display in the popup.
 function PopupWindow.show(content_strings)
   Context.popup.show = true
   Context.popup.content = content_strings or {}   GameWindow.set_state(WINDOW_POPUP) end
 
---- Hides the popup window.
 function PopupWindow.hide()
   Context.popup.show = false
   Context.popup.content = {}   GameWindow.set_state(WINDOW_GAME) end
 
---- Updates popup window logic.
 function PopupWindow.update()
   if Context.popup.show then
     if Input.menu_confirm() or Input.menu_back() then       PopupWindow.hide()
@@ -24,7 +20,6 @@ function PopupWindow.update()
   end
 end
 
---- Draws the popup window.
 function PopupWindow.draw()
   if Context.popup.show then
     rect(POPUP_X, POPUP_Y, POPUP_WIDTH, POPUP_HEIGHT, Config.colors.black)

inc/window/window.splash.lua

@@ -1,4 +1,3 @@
---- Draws the splash window.
 function SplashWindow.draw()
   local txt = "Definitely not an Impostor"
   local w = #txt * 6
@@ -7,7 +6,6 @@ function SplashWindow.draw()
   print(txt, x, y, 12)
 end
 
---- Updates the splash window logic.
 function SplashWindow.update()
   Context.splash_timer = Context.splash_timer - 1
   if Context.splash_timer <= 0 or Input.menu_confirm() then