docs

inc/system/system.audio.lua

@@ -1,14 +1,27 @@
+--- 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,11 +7,21 @@ 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
-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
+--- 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.toggle_popup() return keyp(INPUT_KEY_ENTER) end

inc/system/system.main.lua

@@ -44,6 +44,7 @@ local STATE_HANDLERS = {
 
 local initialized_game = false
 
+--- Initializes game state.
 local function init_game()
   if initialized_game then return end
 
@@ -51,6 +52,7 @@ 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,4 +1,10 @@
-
+--- 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
@@ -7,6 +13,13 @@ 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,12 +1,20 @@
+--- 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
@@ -17,6 +25,10 @@ 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()
@@ -34,6 +46,10 @@ 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 = {}
@@ -63,6 +79,15 @@ 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,
@@ -76,6 +101,10 @@ 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,
@@ -84,6 +113,9 @@ 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
@@ -97,6 +129,7 @@ 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
@@ -129,6 +162,10 @@ 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()
@@ -138,4 +175,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,9 +1,16 @@
+--- 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
@@ -11,4 +18,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