From 8f34cbf8752b36e3acf0ca49d100f2934014962b Mon Sep 17 00:00:00 2001 From: Zsolt Tasnadi Date: Thu, 26 Feb 2026 10:21:48 +0100 Subject: [PATCH] docs for table properties --- inc/audio/audio.songs.lua | 2 + inc/decision/decision.manager.lua | 7 ++- inc/init/init.minigame.lua | 68 +++++++++++++++++++++++++++-- inc/map/map.manager.lua | 7 +++ inc/screen/screen.manager.lua | 7 +++ inc/situation/situation.manager.lua | 4 ++ inc/sprite/sprite.manager.lua | 8 ++++ 7 files changed, 99 insertions(+), 4 deletions(-) diff --git a/inc/audio/audio.songs.lua b/inc/audio/audio.songs.lua index 671e158..34343f1 100644 --- a/inc/audio/audio.songs.lua +++ b/inc/audio/audio.songs.lua @@ -124,6 +124,8 @@ end --- Converts beat notation to frame pattern. --- @within Songs -- @param beats table A table of beat data, e.g., {{1, "left"}, {2, "down"}}. +-- @param beats.1 number The beat number. +-- @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 table The generated pattern. diff --git a/inc/decision/decision.manager.lua b/inc/decision/decision.manager.lua index 459b0b2..62956bb 100644 --- a/inc/decision/decision.manager.lua +++ b/inc/decision/decision.manager.lua @@ -4,6 +4,10 @@ local _decisions = {} --- Registers a decision definition. --- @within Decision -- @param decision table The decision data table. +-- @param decision.id string Unique decision identifier. +-- @param decision.label string Display text for the decision. +-- @param[opt] decision.condition function Returns true if decision is available. Defaults to always true. +-- @param[opt] decision.handle function Called when the decision is selected. Defaults to noop. function Decision.register(decision) if not decision or not decision.id then PopupWindow.show({"Error: Invalid decision object registered (missing id)!"}) @@ -43,7 +47,8 @@ end --- Gets decision objects based on a screen's data. --- @within Decision --- @param screen_data table The data for the screen, containing a 'decisions' field (list of decision IDs). +-- @param screen_data table The data for the screen. +-- @param screen_data.decisions table Array of decision ID strings. -- @return table A table containing decision objects relevant to the screen. function Decision.get_for_screen(screen_data) if not screen_data or not screen_data.decisions then diff --git a/inc/init/init.minigame.lua b/inc/init/init.minigame.lua index 624fcb2..7f1294f 100644 --- a/inc/init/init.minigame.lua +++ b/inc/init/init.minigame.lua @@ -111,7 +111,32 @@ end --- Configures DDR minigame. --- @within Minigame --- @param params table Optional parameters to override defaults. +-- @param params table Optional parameters to override defaults (see Minigame.get_default_ddr). +-- @param[opt] params.bar_fill number Current fill level of the progress bar. +-- @param[opt] params.max_fill number Maximum fill value to win. +-- @param[opt] params.fill_per_hit number Fill gained per successful hit. +-- @param[opt] params.miss_penalty number Fill lost per miss. +-- @param[opt] params.bar_x number Progress bar X position. +-- @param[opt] params.bar_y number Progress bar Y position. +-- @param[opt] params.bar_width number Progress bar width. +-- @param[opt] params.bar_height number Progress bar height. +-- @param[opt] params.arrow_size number Size of arrow sprites. +-- @param[opt] params.arrow_spawn_timer number Timer for arrow spawning. +-- @param[opt] params.arrow_spawn_interval number Frames between arrow spawns. +-- @param[opt] params.arrow_fall_speed number Speed of falling arrows. +-- @param[opt] params.arrows table Array of active arrow objects. +-- @param[opt] params.target_y number Y position of the target line. +-- @param[opt] params.target_arrows table Array of target arrow positions with dir and x fields. +-- @param[opt] params.hit_threshold number Pixel distance for a valid hit. +-- @param[opt] params.button_pressed_timers table Per-button press animation timers. +-- @param[opt] params.button_press_duration number Duration of button press animation. +-- @param[opt] params.input_cooldowns table Per-direction cooldown timers (left, down, up, right). +-- @param[opt] params.input_cooldown_duration number Frames of input cooldown. +-- @param[opt] params.frame_counter number Global frame counter. +-- @param[opt] params.current_song table Currently playing song data. +-- @param[opt] params.pattern_index number Current index in song pattern. +-- @param[opt] params.use_pattern boolean Whether to use song pattern for spawning. +-- @param[opt] params.return_window string Window ID to return to after minigame. -- @return table The configured DDR minigame state. function Minigame.configure_ddr(params) return apply_params(Minigame.get_default_ddr(), params) @@ -119,7 +144,22 @@ end --- Configures button mash minigame. --- @within Minigame --- @param params table Optional parameters to override defaults. +-- @param params table Optional parameters to override defaults (see Minigame.get_default_button_mash). +-- @param[opt] params.bar_fill number Current fill level of the progress bar. +-- @param[opt] params.max_fill number Maximum fill value to win. +-- @param[opt] params.fill_per_press number Fill gained per button press. +-- @param[opt] params.base_degradation number Base rate of bar degradation per frame. +-- @param[opt] params.degradation_multiplier number Multiplier for degradation scaling. +-- @param[opt] params.button_pressed_timer number Button press animation timer. +-- @param[opt] params.button_press_duration number Duration of button press animation. +-- @param[opt] params.return_window string Window ID to return to after minigame. +-- @param[opt] params.bar_x number Progress bar X position. +-- @param[opt] params.bar_y number Progress bar Y position. +-- @param[opt] params.bar_width number Progress bar width. +-- @param[opt] params.bar_height number Progress bar height. +-- @param[opt] params.button_x number Button indicator X position. +-- @param[opt] params.button_y number Button indicator Y position. +-- @param[opt] params.button_size number Button indicator size. -- @return table The configured button mash minigame state. function Minigame.configure_button_mash(params) return apply_params(Minigame.get_default_button_mash(), params) @@ -127,7 +167,29 @@ end --- Configures rhythm minigame. --- @within Minigame --- @param params table Optional parameters to override defaults. +-- @param params table Optional parameters to override defaults (see Minigame.get_default_rhythm). +-- @param[opt] params.line_position number Current position of the moving line (0-1). +-- @param[opt] params.line_speed number Speed of the moving line per frame. +-- @param[opt] params.line_direction number Direction of line movement (1 or -1). +-- @param[opt] params.target_center number Center of the target zone (0-1). +-- @param[opt] params.target_width number Current width of the target zone. +-- @param[opt] params.initial_target_width number Starting width of the target zone. +-- @param[opt] params.min_target_width number Minimum width the target zone can shrink to. +-- @param[opt] params.target_shrink_rate number Multiplier applied to target width after each hit. +-- @param[opt] params.score number Current score. +-- @param[opt] params.max_score number Score needed to win. +-- @param[opt] params.button_pressed_timer number Button press animation timer. +-- @param[opt] params.button_press_duration number Duration of button press animation. +-- @param[opt] params.return_window string Window ID to return to after minigame. +-- @param[opt] params.bar_x number Progress bar X position. +-- @param[opt] params.bar_y number Progress bar Y position. +-- @param[opt] params.bar_width number Progress bar width. +-- @param[opt] params.bar_height number Progress bar height. +-- @param[opt] params.button_x number Button indicator X position. +-- @param[opt] params.button_y number Button indicator Y position. +-- @param[opt] params.button_size number Button indicator size. +-- @param[opt] params.press_cooldown number Current cooldown timer. +-- @param[opt] params.press_cooldown_duration number Frames of press cooldown. -- @return table The configured rhythm minigame state. function Minigame.configure_rhythm(params) return apply_params(Minigame.get_default_rhythm(), params) diff --git a/inc/map/map.manager.lua b/inc/map/map.manager.lua index 127e49a..b5d6042 100644 --- a/inc/map/map.manager.lua +++ b/inc/map/map.manager.lua @@ -18,6 +18,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. function Map.register(map_data) if _maps[map_data.id] then trace("Warning: Overwriting map with id: " .. map_data.id) diff --git a/inc/screen/screen.manager.lua b/inc/screen/screen.manager.lua index 0570f14..c0da2a9 100644 --- a/inc/screen/screen.manager.lua +++ b/inc/screen/screen.manager.lua @@ -4,6 +4,13 @@ local _screens = {} --- Registers a screen definition. --- @within Screen -- @param screen_data table The screen data table. +-- @param screen_data.id string Unique screen identifier. +-- @param screen_data.name string Display name of the screen. +-- @param screen_data.decisions table Array of decision ID strings available on this screen. +-- @param screen_data.background string Map ID used as background. +-- @param[opt] screen_data.situations table Array of situation ID strings. Defaults to {}. +-- @param[opt] screen_data.init function Called when the screen is entered. Defaults to noop. +-- @param[opt] screen_data.update function Called each frame while screen is active. Defaults to noop. function Screen.register(screen_data) if _screens[screen_data.id] then trace("Warning: Overwriting screen with id: " .. screen_data.id) diff --git a/inc/situation/situation.manager.lua b/inc/situation/situation.manager.lua index b65f054..371caa8 100644 --- a/inc/situation/situation.manager.lua +++ b/inc/situation/situation.manager.lua @@ -4,6 +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. function Situation.register(situation) if not situation or not situation.id then PopupWindow.show({"Error: Invalid situation object registered (missing id)!"}) diff --git a/inc/sprite/sprite.manager.lua b/inc/sprite/sprite.manager.lua index bb3b0a4..12fec49 100644 --- a/inc/sprite/sprite.manager.lua +++ b/inc/sprite/sprite.manager.lua @@ -5,6 +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. function Sprite.register(sprite_data) if not sprite_data or not sprite_data.id then trace("Error: Invalid sprite object registered (missing id)!")