docs

inc/init/init.config.lua

@@ -22,7 +22,8 @@ local DEFAULT_CONFIG = {
   }
 }
 
-local Config = {
+-- Game configuration settings.
+Config = {
   screen = DEFAULT_CONFIG.screen,
   colors = DEFAULT_CONFIG.colors,
   player = DEFAULT_CONFIG.player,
@@ -34,10 +35,12 @@ 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)
@@ -46,6 +49,7 @@ 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,6 +4,8 @@ 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,
@@ -46,13 +48,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.
     sprites = {},
+    --- Current situation ID.
     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()
 
@@ -81,12 +87,15 @@ 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
 
@@ -94,6 +103,7 @@ 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()
@@ -105,4 +115,5 @@ 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,11 +6,14 @@ 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,
@@ -22,18 +25,24 @@ 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
@@ -41,6 +50,7 @@ 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
@@ -56,6 +66,9 @@ 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
@@ -64,6 +77,7 @@ 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,5 +1,10 @@
+-- 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
@@ -8,6 +13,8 @@ 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
@@ -47,6 +54,8 @@ 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,
@@ -67,6 +76,8 @@ 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,
@@ -94,14 +105,23 @@ 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