docs for table properties

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.

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

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)

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)

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)

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)!"})

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)!")