From 337f1fc1324d2b6c5874942d5e5d2753cdd61b5a Mon Sep 17 00:00:00 2001 From: Zsolt Tasnadi Date: Thu, 26 Feb 2026 17:41:06 +0100 Subject: [PATCH] ldoc return fixes --- inc/audio/audio.songs.lua | 7 +- inc/decision/decision.manager.lua | 44 +++++---- inc/init/init.context.lua | 21 ++-- inc/init/init.meter.lua | 17 ++-- inc/init/init.minigame.lua | 133 +++++++++++++------------- inc/map/map.manager.lua | 48 +++++----- inc/screen/screen.manager.lua | 34 +++---- inc/situation/situation.manager.lua | 30 +++--- inc/sprite/sprite.manager.lua | 34 +++---- inc/system/system.main.lua | 1 + inc/system/system.print.lua | 26 +++-- inc/system/system.ui.lua | 80 ++++++++-------- inc/system/system.util.lua | 7 +- inc/window/window.audiotest.lua | 13 +-- inc/window/window.game.lua | 2 +- inc/window/window.manager.lua | 14 +-- inc/window/window.minigame.ddr.lua | 10 +- inc/window/window.minigame.mash.lua | 8 +- inc/window/window.minigame.rhythm.lua | 6 +- inc/window/window.popup.lua | 4 +- inc/window/window.splash.lua | 2 - 21 files changed, 279 insertions(+), 262 deletions(-) diff --git a/inc/audio/audio.songs.lua b/inc/audio/audio.songs.lua index 050dbb8..322ef0a 100644 --- a/inc/audio/audio.songs.lua +++ b/inc/audio/audio.songs.lua @@ -128,9 +128,10 @@ end --- @param beats.2 string Arrow direction ("left", "down", "up", or "right"). --- @param bpm number Beats per minute. --- @param[opt] fps number Frames per second (default: 60). ---- @return result table The generated pattern, an array of arrow spawn entries. ---- @return result.frame number The frame number when the arrow should spawn. ---- @return result.dir string Arrow direction ("left", "down", "up", or "right"). +--- @return 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").
function beats_to_pattern(beats, bpm, fps) fps = fps or 60 local pattern = {} diff --git a/inc/decision/decision.manager.lua b/inc/decision/decision.manager.lua index 98a32cc..396529c 100644 --- a/inc/decision/decision.manager.lua +++ b/inc/decision/decision.manager.lua @@ -33,22 +33,24 @@ end --- Gets a decision by ID. --- @within Decision --- @param id string The ID of the decision. ---- @return result table The decision table or nil. ---- @return result.id string Unique decision identifier. ---- @return result.label string Display text for the decision. ---- @return result.condition function Returns true if decision is available. ---- @return result.handle function Called when the decision is selected. +--- @return 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. function Decision.get_by_id(id) return _decisions[id] end --- Gets all registered decisions. --- @within Decision ---- @return result table A table of all registered decisions, indexed by their IDs. ---- @return result.id string Unique decision identifier. ---- @return result.label string Display text for the decision. ---- @return result.condition function Returns true if decision is available. ---- @return result.handle function Called when the decision is selected. +--- @return 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. function Decision.get_all() return _decisions end @@ -57,11 +59,12 @@ end --- @within Decision --- @param screen_data table The data for the screen. --- @param screen_data.decisions table Array of decision ID strings. ---- @return result table An array of decision objects relevant to the screen. ---- @return result.id string Unique decision identifier. ---- @return result.label string Display text for the decision. ---- @return result.condition function Returns true if decision is available. ---- @return result.handle function Called when the decision is selected. +--- @return 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.
function Decision.get_for_screen(screen_data) if not screen_data or not screen_data.decisions then return {} @@ -80,11 +83,12 @@ end --- Filters a list of decision objects based on their condition function. --- @within Decision --- @param decisions_list table A table of decision objects. ---- @return result table An array of decisions for which condition() is true. ---- @return result.id string Unique decision identifier. ---- @return result.label string Display text for the decision. ---- @return result.condition function Returns true if decision is available. ---- @return result.handle function Called when the decision is selected. +--- @return 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.
function Decision.filter_available(decisions_list) local available = {} for _, decision in ipairs(decisions_list) do diff --git a/inc/init/init.context.lua b/inc/init/init.context.lua index 3272a3c..1fe23c1 100644 --- a/inc/init/init.context.lua +++ b/inc/init/init.context.lua @@ -8,16 +8,17 @@ Context = {} --- Gets initial data for Context. --- @within Context ---- @return result table Initial context data. ---- @return result.current_menu_item number Index of the currently selected menu item. ---- @return result.splash_timer number Remaining frames for the splash screen timer. ---- @return result.popup table Popup window state. Contains: `show` (boolean) whether popup is visible, `content` (table) array of strings to display. ---- @return result.game_in_progress boolean Whether a game is currently active. ---- @return result.minigame_ddr table DDR minigame state (see Minigame.get_default_ddr). ---- @return result.minigame_button_mash table Button mash minigame state (see Minigame.get_default_button_mash). ---- @return result.minigame_rhythm table Rhythm minigame state (see Minigame.get_default_rhythm). ---- @return result.meters table Meter values (see Meter.get_initial). ---- @return result.game table Current game progress state. Contains: `current_screen` (string) active screen ID, `current_situation` (string|nil) active situation ID. +--- @return result table Initial context data.
+--- 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).
+--- * game (table) Current game progress state. Contains: `current_screen` (string) active screen ID, `current_situation` (string|nil) active situation ID. function Context.initial_data() return { current_menu_item = 1, diff --git a/inc/init/init.meter.lua b/inc/init/init.meter.lua index 3a890a6..bd52363 100644 --- a/inc/init/init.meter.lua +++ b/inc/init/init.meter.lua @@ -33,14 +33,15 @@ end --- Gets initial meter values. --- @within Meter ---- @return result table A table of initial meter values. ---- @return result.ism number Initial ISM meter value. ---- @return result.wpm number Initial WPM meter value. ---- @return result.bm number Initial BM meter value. ---- @return result.combo number Current combo count. ---- @return result.combo_timer number Frames since last combo action. ---- @return result.hidden boolean Whether meters are hidden. ---- @return result.timer_progress number Clock timer revolution progress (0 to 1). +--- @return 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). function Meter.get_initial() return { ism = METER_DEFAULT, diff --git a/inc/init/init.minigame.lua b/inc/init/init.minigame.lua index c985707..b7e4fe0 100644 --- a/inc/init/init.minigame.lua +++ b/inc/init/init.minigame.lua @@ -16,32 +16,33 @@ end --- Gets default DDR minigame configuration. --- @within Minigame ---- @return result table The default DDR minigame configuration. ---- @return result.bar_fill number Current fill level of the progress bar. ---- @return result.max_fill number Maximum fill value to win. ---- @return result.fill_per_hit number Fill gained per successful hit. ---- @return result.miss_penalty number Fill lost per miss. ---- @return result.bar_x number Progress bar X position. ---- @return result.bar_y number Progress bar Y position. ---- @return result.bar_width number Progress bar width. ---- @return result.bar_height number Progress bar height. ---- @return result.arrow_size number Size of arrow sprites. ---- @return result.arrow_spawn_timer number Timer for arrow spawning. ---- @return result.arrow_spawn_interval number Frames between arrow spawns. ---- @return result.arrow_fall_speed number Speed of falling arrows. ---- @return result.arrows table Array of active arrow objects. ---- @return result.target_y number Y position of the target line. ---- @return result.target_arrows table Array of target arrow positions. Each entry has: `dir` (string) arrow direction, `x` (number) X position. ---- @return result.hit_threshold number Pixel distance for a valid hit. ---- @return result.button_pressed_timers table Per-button press animation timers. ---- @return result.button_press_duration number Duration of button press animation. ---- @return result.input_cooldowns table Per-direction cooldown timers (left, down, up, right). ---- @return result.input_cooldown_duration number Frames of input cooldown. ---- @return result.frame_counter number Global frame counter. ---- @return result.current_song table Currently playing song data. ---- @return result.pattern_index number Current index in song pattern. ---- @return result.use_pattern boolean Whether to use song pattern for spawning. ---- @return result.return_window string Window ID to return to after minigame. +--- @return 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. function Minigame.get_default_ddr() local arrow_size = 12 local arrow_spacing = 30 @@ -83,22 +84,23 @@ end --- Gets default button mash minigame configuration. --- @within Minigame ---- @return result table The default button mash minigame configuration. ---- @return result.bar_fill number Current fill level of the progress bar. ---- @return result.max_fill number Maximum fill value to win. ---- @return result.fill_per_press number Fill gained per button press. ---- @return result.base_degradation number Base rate of bar degradation per frame. ---- @return result.degradation_multiplier number Multiplier for degradation scaling. ---- @return result.button_pressed_timer number Button press animation timer. ---- @return result.button_press_duration number Duration of button press animation. ---- @return result.return_window string Window ID to return to after minigame. ---- @return result.bar_x number Progress bar X position. ---- @return result.bar_y number Progress bar Y position. ---- @return result.bar_width number Progress bar width. ---- @return result.bar_height number Progress bar height. ---- @return result.button_x number Button indicator X position. ---- @return result.button_y number Button indicator Y position. ---- @return result.button_size number Button indicator size. +--- @return 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.
function Minigame.get_default_button_mash() return { bar_fill = 0, @@ -124,29 +126,30 @@ end --- Gets default rhythm minigame configuration. --- @within Minigame ---- @return result table The default rhythm minigame configuration. ---- @return result.line_position number Current position of the moving line (0-1). ---- @return result.line_speed number Speed of the moving line per frame. ---- @return result.line_direction number Direction of line movement (1 or -1). ---- @return result.target_center number Center of the target zone (0-1). ---- @return result.target_width number Current width of the target zone. ---- @return result.initial_target_width number Starting width of the target zone. ---- @return result.min_target_width number Minimum width the target zone can shrink to. ---- @return result.target_shrink_rate number Multiplier applied to target width after each hit. ---- @return result.score number Current score. ---- @return result.max_score number Score needed to win. ---- @return result.button_pressed_timer number Button press animation timer. ---- @return result.button_press_duration number Duration of button press animation. ---- @return result.return_window string Window ID to return to after minigame. ---- @return result.bar_x number Progress bar X position. ---- @return result.bar_y number Progress bar Y position. ---- @return result.bar_width number Progress bar width. ---- @return result.bar_height number Progress bar height. ---- @return result.button_x number Button indicator X position. ---- @return result.button_y number Button indicator Y position. ---- @return result.button_size number Button indicator size. ---- @return result.press_cooldown number Current cooldown timer. ---- @return result.press_cooldown_duration number Frames of press cooldown. +--- @return 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.
function Minigame.get_default_rhythm() return { line_position = 0, diff --git a/inc/map/map.manager.lua b/inc/map/map.manager.lua index 2fa2a0d..a37e5de 100644 --- a/inc/map/map.manager.lua +++ b/inc/map/map.manager.lua @@ -6,14 +6,15 @@ local _maps = {} --- Gets all registered maps as an array. --- @within Map ---- @return result table An array of registered map data. ---- @return result.id string Unique map identifier. ---- @return result.from_x number Source tile X coordinate in the map sheet. ---- @return result.from_y number Source tile Y coordinate in the map sheet. ---- @return result.width number Width in tiles. ---- @return result.height number Height in tiles. ---- @return result.to_x number Destination X coordinate on screen. ---- @return result.to_y number Destination Y coordinate on screen. +--- @return 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.
function Map.get_maps_array() local maps_array = {} for _, map_data in pairs(_maps) do @@ -25,13 +26,13 @@ end --- Registers a map definition. --- @within Map --- @param map_data table The map data table. ---- @param map_data.id string Unique map identifier. ---- @param map_data.from_x number Source tile X coordinate in the map sheet. ---- @param map_data.from_y number Source tile Y coordinate in the map sheet. ---- @param map_data.width number Width in tiles. ---- @param map_data.height number Height in tiles. ---- @param map_data.to_x number Destination X coordinate on screen. ---- @param map_data.to_y number Destination Y coordinate on screen. +--- @param map_data.id string Unique map identifier.
+--- @param map_data.from_x number Source tile X coordinate in the map sheet.
+--- @param map_data.from_y number Source tile Y coordinate in the map sheet.
+--- @param map_data.width number Width in tiles.
+--- @param map_data.height number Height in tiles.
+--- @param map_data.to_x number Destination X coordinate on screen.
+--- @param map_data.to_y number Destination Y coordinate on screen.
function Map.register(map_data) if _maps[map_data.id] then trace("Warning: Overwriting map with id: " .. map_data.id) @@ -42,14 +43,15 @@ end --- Gets a map by ID. --- @within Map --- @param map_id string The ID of the map. ---- @return result table The map data table or nil. ---- @return result.id string Unique map identifier. ---- @return result.from_x number Source tile X coordinate in the map sheet. ---- @return result.from_y number Source tile Y coordinate in the map sheet. ---- @return result.width number Width in tiles. ---- @return result.height number Height in tiles. ---- @return result.to_x number Destination X coordinate on screen. ---- @return result.to_y number Destination Y coordinate on screen. +--- @return 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.
function Map.get_by_id(map_id) return _maps[map_id] end diff --git a/inc/screen/screen.manager.lua b/inc/screen/screen.manager.lua index 66b1b59..ded1086 100644 --- a/inc/screen/screen.manager.lua +++ b/inc/screen/screen.manager.lua @@ -30,28 +30,30 @@ end --- Gets a screen by ID. --- @within Screen --- @param screen_id string The ID of the screen. ---- @return result table The screen table or nil. ---- @return result.id string Unique screen identifier. ---- @return result.name string Display name of the screen. ---- @return result.decisions table Array of decision ID strings available on this screen. ---- @return result.background string Map ID used as background. ---- @return result.situations table Array of situation ID strings. ---- @return result.init function Called when the screen is entered. ---- @return result.update function Called each frame while screen is active. +--- @return 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. function Screen.get_by_id(screen_id) return _screens[screen_id] end --- Gets all registered screens. --- @within Screen ---- @return result table A table containing all registered screen data, indexed by their IDs. ---- @return result.id string Unique screen identifier. ---- @return result.name string Display name of the screen. ---- @return result.decisions table Array of decision ID strings available on this screen. ---- @return result.background string Map ID used as background. ---- @return result.situations table Array of situation ID strings. ---- @return result.init function Called when the screen is entered. ---- @return result.update function Called each frame while screen is active. +--- @return 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.
function Screen.get_all() return _screens end diff --git a/inc/situation/situation.manager.lua b/inc/situation/situation.manager.lua index 1915bbd..17d2e4e 100644 --- a/inc/situation/situation.manager.lua +++ b/inc/situation/situation.manager.lua @@ -4,10 +4,10 @@ local _situations = {} --- Registers a situation definition. --- @within Situation --- @param situation table The situation data table. ---- @param situation.id string Unique situation identifier. ---- @param[opt] situation.screen_id string ID of the screen this situation belongs to. ---- @param[opt] situation.handle function Called when the situation is applied. Defaults to noop. ---- @param[opt] situation.update function Called each frame while situation is active. Defaults to noop. +--- @param situation.id string Unique situation identifier.
+--- @param[opt] situation.screen_id string ID of the screen this situation belongs to.
+--- @param[opt] situation.handle function Called when the situation is applied. Defaults to noop.
+--- @param[opt] situation.update function Called each frame while situation is active. Defaults to noop.
function Situation.register(situation) if not situation or not situation.id then PopupWindow.show({"Error: Invalid situation object registered (missing id)!"}) @@ -28,11 +28,12 @@ end --- Gets a situation by ID. --- @within Situation --- @param id string The situation ID. ---- @return result table The situation table or nil. ---- @return result.id string Unique situation identifier. ---- @return result.screen_id string ID of the screen this situation belongs to. ---- @return result.handle function Called when the situation is applied. ---- @return result.update function Called each frame while situation is active. +--- @return 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.
function Situation.get_by_id(id) return _situations[id] end @@ -40,11 +41,12 @@ end --- Gets all registered situations, optionally filtered by screen ID. --- @within Situation --- @param screen_id string Optional. If provided, returns situations associated with this screen ID. ---- @return result table A table containing all registered situation data, indexed by their IDs, or an array filtered by screen_id. ---- @return result.id string Unique situation identifier. ---- @return result.screen_id string ID of the screen this situation belongs to. ---- @return result.handle function Called when the situation is applied. ---- @return result.update function Called each frame while situation is active. +--- @return 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.
function Situation.get_all(screen_id) if screen_id then local filtered_situations = {} diff --git a/inc/sprite/sprite.manager.lua b/inc/sprite/sprite.manager.lua index 6924961..d3b1250 100644 --- a/inc/sprite/sprite.manager.lua +++ b/inc/sprite/sprite.manager.lua @@ -5,14 +5,14 @@ local _active_sprites = {} --- Registers a sprite definition. --- @within Sprite --- @param sprite_data table A table containing the sprite definition. ---- @param sprite_data.id string Unique sprite identifier. ---- @param[opt] sprite_data.s number Sprite index for single-sprite mode. ---- @param[opt] sprite_data.colorkey number Default color index for transparency. ---- @param[opt] sprite_data.scale number Default scaling factor. ---- @param[opt] sprite_data.flip_x number Set to 1 to flip horizontally by default. ---- @param[opt] sprite_data.flip_y number Set to 1 to flip vertically by default. ---- @param[opt] sprite_data.rot number Default rotation in degrees. ---- @param[opt] sprite_data.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. +--- @param sprite_data.id string Unique sprite identifier.
+--- @param[opt] sprite_data.s number Sprite index for single-sprite mode.
+--- @param[opt] sprite_data.colorkey number Default color index for transparency.
+--- @param[opt] sprite_data.scale number Default scaling factor.
+--- @param[opt] sprite_data.flip_x number Set to 1 to flip horizontally by default.
+--- @param[opt] sprite_data.flip_y number Set to 1 to flip vertically by default.
+--- @param[opt] sprite_data.rot number Default rotation in degrees.
+--- @param[opt] sprite_data.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.
function Sprite.register(sprite_data) if not sprite_data or not sprite_data.id then trace("Error: Invalid sprite object registered (missing id)!") @@ -26,14 +26,14 @@ end --- Schedules a sprite for drawing. --- @within Sprite ---- @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. +--- @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.
function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot) if not _sprites[id] then trace("Error: Attempted to show non-registered sprite with id: " .. id) @@ -54,7 +54,7 @@ end --- Hides a displayed sprite. --- @within Sprite ---- @param id string The unique identifier of the sprite. +--- @param id string The unique identifier of the sprite.
function Sprite.hide(id) _active_sprites[id] = nil end diff --git a/inc/system/system.main.lua b/inc/system/system.main.lua index df3534a..bed938a 100644 --- a/inc/system/system.main.lua +++ b/inc/system/system.main.lua @@ -3,6 +3,7 @@ local initialized_game = false --- Initializes game state. --- @within Main +--- @return boolean initialized_game True if game has been initialized, false otherwise. local function init_game() if initialized_game then return end Context.reset() diff --git a/inc/system/system.print.lua b/inc/system/system.print.lua index 0b60cb3..b38b67d 100644 --- a/inc/system/system.print.lua +++ b/inc/system/system.print.lua @@ -1,13 +1,11 @@ ---- @section Print - --- Prints text with shadow. --- @within Print ---- @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. +--- @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 @@ -18,12 +16,12 @@ end --- Prints centered text with shadow. --- @within Print ---- @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. +--- @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) diff --git a/inc/system/system.ui.lua b/inc/system/system.ui.lua index fea3aaf..418cb2f 100644 --- a/inc/system/system.ui.lua +++ b/inc/system/system.ui.lua @@ -2,7 +2,7 @@ --- Draws the top bar. --- @within UI ---- @param title string The title text to display. +--- @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.light_blue) @@ -16,10 +16,10 @@ end --- Draws a menu. --- @within UI ---- @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. +--- @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 @@ -32,9 +32,9 @@ end --- Updates menu selection. --- @within UI ---- @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. +--- @param items table A table of menu items.
+--- @param selected_item number The current index of the selected item.
+--- @return number selected_item The updated index of the selected item. function UI.update_menu(items, selected_item) if Input.up() then Audio.sfx_beep() @@ -54,9 +54,9 @@ end --- Wraps text. --- @within UI ---- @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. +--- @param text string The text to wrap.
+--- @param max_chars_per_line number The maximum characters per line.
+--- @return result table A table of wrapped lines. function UI.word_wrap(text, max_chars_per_line) if text == nil then return {""} end local lines = {} @@ -88,22 +88,23 @@ end --- Creates a numeric stepper. --- @within UI ---- @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 result table A numeric stepper control definition. ---- @return result.label string The label for the stepper. ---- @return result.get function Function to get the current value. ---- @return result.set function Function to set the current value. ---- @return result.min number The minimum value. ---- @return result.max number The maximum value. ---- @return result.step number The step increment. ---- @return result.format string The format string for displaying the value. ---- @return result.type string Control type identifier ("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 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").
function UI.create_numeric_stepper(label, value_getter, value_setter, min, max, step, format) return { label = label, @@ -119,12 +120,13 @@ end --- Creates an action item. --- @within UI ---- @param label string The label for the action item. ---- @param action function The function to execute when the item is selected. ---- @return result table An action item control definition. ---- @return result.label string The label for the action item. ---- @return result.action function The function to execute when the item is selected. ---- @return result.type string Control type identifier ("action_item"). +--- @param label string The label for the action item.
+--- @param action function The function to execute when the item is selected.
+--- @return 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").
function UI.create_action_item(label, action) return { label = label, @@ -135,8 +137,8 @@ end --- Draws decision selector. --- @within UI ---- @param decisions table A table of decision items. ---- @param selected_decision_index number The index of the selected decision. +--- @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 @@ -244,9 +246,9 @@ end --- Updates decision selector. --- @within UI ---- @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. +--- @param decisions table A table of decision items.
+--- @param selected_decision_index number The current index of the selected decision.
+--- @return number selected_decision_index The updated index of the selected decision. function UI.update_decision_selector(decisions, selected_decision_index) if Input.left() then Audio.sfx_beep() @@ -256,4 +258,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 \ No newline at end of file diff --git a/inc/system/system.util.lua b/inc/system/system.util.lua index 40d0db9..0d9c322 100644 --- a/inc/system/system.util.lua +++ b/inc/system/system.util.lua @@ -5,14 +5,14 @@ --- @within Util --- @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. +--- @return number index 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. --- @within Util ---- @param screen_id string The ID of the screen to go to. +--- @param screen_id string The ID of the screen to go to.
function Util.go_to_screen_by_id(screen_id) local screen = Screen.get_by_id(screen_id) if screen then @@ -26,7 +26,8 @@ end --- Checks if a table contains a specific value. --- @within Util --- @param t table The table to check. ---- @param value any The value to look for. +--- @param value any The value to look for.
+--- @return boolean true if the value is found, false otherwise. function Util.contains(t, value) for i = 1, #t do if t[i] == value then diff --git a/inc/window/window.audiotest.lua b/inc/window/window.audiotest.lua index 8b21b14..13de851 100644 --- a/inc/window/window.audiotest.lua +++ b/inc/window/window.audiotest.lua @@ -9,11 +9,12 @@ AudioTestWindow = { --- Generates menu items for audio test. --- @within AudioTestWindow ---- @param list_func table List of audio functions. ---- @param index_func number Current index of selected function. ---- @return result table Generated menu items, an array of menu item tables. ---- @return result.label string Display text for the menu item. ---- @return result.decision function Called when the menu item is selected. +--- @param list_func table List of audio functions.
+--- @param index_func number Current index of selected function.
+--- @return 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.
function AudioTestWindow.generate_menuitems(list_func, index_func) return { { @@ -44,7 +45,7 @@ end --- Generates list of audio functions. --- @within AudioTestWindow ---- @return table A sorted list of audio function names. +--- @return result table A sorted list of audio function names. function AudioTestWindow.generate_listfunc() local result = {} diff --git a/inc/window/window.game.lua b/inc/window/window.game.lua index ec18904..8d4917c 100644 --- a/inc/window/window.game.lua +++ b/inc/window/window.game.lua @@ -72,7 +72,7 @@ end --- Sets the active window. --- @within GameWindow ---- @param new_state string The ID of the new active window. +--- @param new_state string The ID of the new active window.
function GameWindow.set_state(new_state) Window.set_current(new_state) end diff --git a/inc/window/window.manager.lua b/inc/window/window.manager.lua index 8265d9b..84e6af6 100644 --- a/inc/window/window.manager.lua +++ b/inc/window/window.manager.lua @@ -3,8 +3,8 @@ local _windows = {} --- Registers a window table. --- @within Window ---- @param id string The ID of the window (e.g., "splash", "menu"). ---- @param window_table table The actual window module table (e.g., SplashWindow). +--- @param id string The ID of the window (e.g., "splash", "menu").
+--- @param window_table table The actual window module table (e.g., SplashWindow).
function Window.register(id, window_table) _windows[id] = window_table end @@ -12,21 +12,23 @@ end --- Retrieves a registered window table by its ID. --- @within Window --- @param id string The ID of the window. ---- @return result table The window module table. ---- @return result.update function Called each frame to update window logic. ---- @return result.draw function Called each frame to draw the window. +--- @return 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.
function Window.get(id) return _windows[id] end --- Sets the currently active window. --- @within Window ---- @param id string The ID of the window to activate. +--- @param id string The ID of the window to activate.
function Window.set_current(id) Context.current_window = id end --- Gets the ID of the currently active window. +--- This function is used by the main game loop to update and draw the active window. --- @within Window --- @return string The ID of the active window. function Window.get_current_id() diff --git a/inc/window/window.minigame.ddr.lua b/inc/window/window.minigame.ddr.lua index 39d58fb..3caa3bd 100644 --- a/inc/window/window.minigame.ddr.lua +++ b/inc/window/window.minigame.ddr.lua @@ -2,16 +2,16 @@ --- Initializes DDR minigame state. --- @within MinigameDDRWindow ---- @param params table Optional parameters for configuration. +--- @param params table Optional parameters for configuration.
function MinigameDDRWindow.init(params) Context.minigame_ddr = Minigame.configure_ddr(params) end --- Starts the DDR minigame. --- @within MinigameDDRWindow ---- @param return_window string 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. +--- @param return_window string 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 "game" @@ -265,4 +265,4 @@ function MinigameDDRWindow.draw() else Print.text_center("RANDOM MODE", Config.screen.width / 2, debug_y, Config.colors.blue) end -end +end \ No newline at end of file diff --git a/inc/window/window.minigame.mash.lua b/inc/window/window.minigame.mash.lua index e170dc8..f001753 100644 --- a/inc/window/window.minigame.mash.lua +++ b/inc/window/window.minigame.mash.lua @@ -1,16 +1,14 @@ ---- @section MinigameButtonMashWindow - --- Initializes button mash minigame state. --- @within MinigameButtonMashWindow ---- @param params table Optional parameters for configuration. +--- @param params table Optional parameters for configuration.
function MinigameButtonMashWindow.init(params) Context.minigame_button_mash = Minigame.configure_button_mash(params) end --- Starts the button mash minigame. --- @within MinigameButtonMashWindow ---- @param return_window string The window ID to return to after the minigame. ---- @param[opt] params table Optional parameters for minigame configuration. +--- @param return_window string 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) local mg = Context.minigame_button_mash diff --git a/inc/window/window.minigame.rhythm.lua b/inc/window/window.minigame.rhythm.lua index c40607e..0690f05 100644 --- a/inc/window/window.minigame.rhythm.lua +++ b/inc/window/window.minigame.rhythm.lua @@ -2,15 +2,15 @@ --- Initializes rhythm minigame state. --- @within MinigameRhythmWindow ---- @param params table Optional parameters for configuration. +--- @param params table Optional parameters for configuration.
function MinigameRhythmWindow.init(params) Context.minigame_rhythm = Minigame.configure_rhythm(params) end --- Starts the rhythm minigame. --- @within MinigameRhythmWindow ---- @param return_window string The window ID to return to after the minigame. ---- @param[opt] params table Optional parameters for minigame configuration. +--- @param return_window string 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) local mg = Context.minigame_rhythm diff --git a/inc/window/window.popup.lua b/inc/window/window.popup.lua index d330de1..b7ec674 100644 --- a/inc/window/window.popup.lua +++ b/inc/window/window.popup.lua @@ -9,7 +9,7 @@ local LINE_HEIGHT = 8 --- Displays a popup window. --- @within PopupWindow ---- @param content_strings table A table of strings to display in the popup. +--- @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 {} @@ -49,4 +49,4 @@ function PopupWindow.draw() Print.text("[A] Close", TEXT_MARGIN_X, POPUP_Y + POPUP_HEIGHT - LINE_HEIGHT - 2, Config.colors.light_blue) end -end +end \ No newline at end of file diff --git a/inc/window/window.splash.lua b/inc/window/window.splash.lua index b8182c0..8b4795b 100644 --- a/inc/window/window.splash.lua +++ b/inc/window/window.splash.lua @@ -1,5 +1,3 @@ ---- @section SplashWindow - --- Draws the splash window. --- @within SplashWindow function SplashWindow.draw()