docs

Makefile

@@ -204,7 +204,22 @@ install_precommit_hook:
 	@chmod +x .git/hooks/pre-commit
 	@echo "Pre-commit hook installed successfully."
 
-.PHONY: all build export watch import_assets export_assets clean lint ci-version ci-export ci-upload ci-update install_precommit_hook
+docs: build
+	@echo "==> Checking for ldoc..."
+	@if ! command -v ldoc &> /dev/null; then \
+		echo "ldoc not found, attempting to install with luarocks..."; \
+		if command -v luarocks &> /dev/null; then \
+			luarocks install ldoc; \
+		else \
+			echo "Error: luarocks not found. Please install luarocks and then ldoc manually."; \
+			exit 1; \
+		fi; \
+	fi
+	@echo "==> Running ldoc..."
+	@ldoc ${OUTPUT} -d docs
+	@echo "==> Documentation generated."
+
+.PHONY: all build export watch import_assets export_assets clean lint ci-version ci-export ci-upload ci-update install_precommit_hook docs
 
 #-- <WAVES>
 #-- 000:224578acdeeeeddcba95434567653100

inc/decision/decision.go_to_home.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Util.go_to_screen_by_id("home")
   end,
+  condition = function() return true end
 })

inc/decision/decision.go_to_office.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Util.go_to_screen_by_id("office")
   end,
+  condition = function() return true end
 })

inc/decision/decision.go_to_toilet.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Util.go_to_screen_by_id("toilet")
   end,
+  condition = function() return true end
 })

inc/decision/decision.go_to_walking_to_home.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Util.go_to_screen_by_id("walking_to_home")
   end,
+  condition = function() return true end
 })

inc/decision/decision.go_to_walking_to_office.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Util.go_to_screen_by_id("walking_to_office")
   end,
+  condition = function() return true end
 })

inc/decision/decision.have_a_coffee.lua

@@ -4,4 +4,5 @@ Decision.register({
   handle = function()
     Situation.apply("drink_coffee")
   end,
+  condition = function() return true end
 })

inc/decision/decision.play_button_mash.lua

@@ -2,4 +2,5 @@ Decision.register({
   id = "play_button_mash",
   label = "Play Button Mash",
   handle = function() Meters.hide() MinigameButtonMashWindow.start(WINDOW_GAME) end,
+  condition = function() return true end
 })

inc/decision/decision.play_ddr.lua

@@ -2,4 +2,5 @@ Decision.register({
   id = "play_ddr",
   label = "Play DDR (Random)",
   handle = function() Meters.hide() MinigameDDRWindow.start(WINDOW_GAME, nil) end,
+  condition = function() return true end
 })

inc/decision/decision.play_rhythm.lua

@@ -2,4 +2,5 @@ Decision.register({
   id = "play_rhythm",
   label = "Play Rhythm Game",
   handle = function() Meters.hide() MinigameRhythmWindow.start(WINDOW_GAME) end,
+  condition = function() return true end
 })

inc/init/init.context.lua

@@ -46,7 +46,11 @@ on than meets the eye.]]
     minigame_button_mash = Minigames.get_default_button_mash(),
     minigame_rhythm = Minigames.get_default_rhythm(),
     meters = Meters.get_initial(),
+    --- Table storing currently active sprites to be drawn.
+    -- Each entry is a table with `id`, `x`, `y`, and other drawing parameters.
     sprites = {},
+    --- The ID of the currently active situation.
+    -- Set by `Situation.apply()` and `nil` if no situation is active.
     current_situation = nil,
   }
 end
@@ -85,7 +89,6 @@ 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
 
 function Context.save_game()
@@ -106,5 +109,4 @@ function Context.load_game()
 
   Context.game_in_progress = true
   MenuWindow.refresh_menu_items()
-  Context.screens[Context.current_screen].init()
 end

inc/screen/screen.manager.lua

@@ -1,5 +1,13 @@
 local _screens = {}
 
+--- Registers a new screen definition with the Screen manager.
+-- Overwrites existing screen if an ID conflict occurs.
+-- @param screen_data table A table containing the screen definition.
+--        Must include an `id` field (string).
+--        Optional fields:
+--        - `situations` (table): A table of situation IDs allowed on this screen. Defaults to an empty table.
+--        - `init` (function): Function to execute once when the screen becomes active. Defaults to an empty function.
+--        - `update` (function): Function to execute each frame while the screen is active. Defaults to an empty function.
 function Screen.register(screen_data)
   if _screens[screen_data.id] then
     trace("Warning: Overwriting screen with id: " .. screen_data.id)
@@ -16,6 +24,9 @@ function Screen.register(screen_data)
   _screens[screen_data.id] = screen_data
 end
 
+--- Retrieves a registered screen by its ID.
+-- @param screen_id string The ID of the screen to retrieve.
+-- @return table The screen table, or `nil` if not found.
 function Screen.get_by_id(screen_id)
   return _screens[screen_id]
 end

inc/situation/situation.manager.lua

@@ -1,5 +1,12 @@
 local _situations = {}
 
+--- Registers a new situation with the Situation manager.
+-- Overwrites existing situation if an ID conflict occurs.
+-- @param situation table A table containing the situation definition.
+--        Must include an `id` field (string).
+--        Optional fields:
+--        - `handle` (function): Function to execute when the situation is applied. Defaults to an empty function.
+--        - `update` (function): Function to execute each frame while the situation is active. Defaults to an empty function.
 function Situation.register(situation)
   if not situation or not situation.id then
     PopupWindow.show({"Error: Invalid situation object registered (missing id)!"})
@@ -17,10 +24,19 @@ function Situation.register(situation)
   _situations[situation.id] = situation
 end
 
+--- Retrieves a registered situation by its ID.
+-- @param id string The ID of the situation to retrieve.
+-- @return table The situation table, or `nil` if not found.
 function Situation.get(id)
   return _situations[id]
 end
 
+--- Applies a situation, making it the current active situation.
+-- The situation's `handle` function is executed.
+-- This function first checks if the situation is valid and if it's allowed
+-- on the current screen (as defined in `Context.screens[Context.current_screen].situations`).
+-- If successful, `Context.current_situation` is updated with the ID of the applied situation.
+-- @param id string The ID of the situation to apply.
 function Situation.apply(id)
   local situation = Situation.get(id)
   if not situation then
@@ -37,4 +53,3 @@ function Situation.apply(id)
   Context.current_situation = id
   situation.handle()
 end
-

inc/sprite/sprite.manager.lua

@@ -1,5 +1,15 @@
 local _sprites = {}
 
+--- Registers a new sprite or complex sprite definition with the Sprite manager.
+-- Overwrites existing sprite if an ID conflict occurs.
+-- @param sprite_data table A table containing the sprite definition.
+--        Must include an `id` field (string) and either an `s` field (number, for simple sprites)
+--        or a `sprites` field (table, for complex sprites).
+--        For complex sprites, `sprites` is a table of sub-sprite definitions, each with:
+--        - `s` (number): Sprite index.
+--        - `x_offset` (number): X-offset relative to the parent sprite's position.
+--        - `y_offset` (number): Y-offset relative to the parent sprite's position.
+--        - Optional `colorkey`, `scale`, `flip_x`, `flip_y`, `rot` for individual sub-sprites.
 function Sprite.register(sprite_data)
   if not sprite_data or not sprite_data.id then
     trace("Error: Invalid sprite object registered (missing id)!")
@@ -11,6 +21,17 @@ function Sprite.register(sprite_data)
   _sprites[sprite_data.id] = sprite_data
 end
 
+--- Schedules a registered sprite to be drawn at a specific position with optional transformations.
+-- The sprite's parameters are stored in `Context.sprites` for deferred rendering by `Sprite.draw()`.
+-- If the sprite with the given `id` is already scheduled, its parameters will be updated.
+-- @param id string The unique identifier of the sprite to show. Must be registered via `Sprite.register`.
+-- @param x number The x-coordinate on the screen where the sprite will be drawn.
+-- @param y number The y-coordinate on the screen where the sprite will be drawn.
+-- @param[opt] colorkey number The color index to be treated as transparent (default: 0).
+-- @param[opt] scale number The scaling factor for the sprite (default: 1).
+-- @param[opt] flip_x number Set to 1 to flip the sprite horizontally (default: 0).
+-- @param[opt] flip_y number Set to 1 to flip the sprite vertically (default: 0).
+-- @param[opt] rot number The rotation of the sprite in degrees (default: 0).
 function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
   -- Ensure the sprite exists before attempting to show it
   if not _sprites[id] then
@@ -30,10 +51,16 @@ function Sprite.show(id, x, y, colorkey, scale, flip_x, flip_y, rot)
   }
 end
 
+--- Hides a currently displayed sprite by removing it from the `Context.sprites` table.
+-- The sprite will no longer be drawn in subsequent frames.
+-- @param id string The unique identifier of the sprite to hide.
 function Sprite.hide(id)
   Context.sprites[id] = nil
 end
 
+--- Draws all sprites currently scheduled in `Context.sprites`.
+-- This function retrieves the registered sprite definitions and applies the stored
+-- position and transformation parameters. It handles both simple and complex sprites.
 function Sprite.draw()
   for id, params in pairs(Context.sprites) do
     local sprite_data = _sprites[id]

inc/sprite/sprite.norman.lua

@@ -1,17 +1,17 @@
 Sprite.register({
   id = "norman",
   sprites = {
-    -- Body
+    -- Body (sprite index 0)
     { s = 0, x_offset = 0, y_offset = 0 },
-    -- Head
+    -- Head (sprite index 1)
     { s = 1, x_offset = 0, y_offset = -8 },
-    -- Left Arm
+    -- Left Arm (sprite index 2)
     { s = 2, x_offset = -4, y_offset = 4 },
-    -- Right Arm
+    -- Right Arm (sprite index 3, flipped)
     { s = 3, x_offset = 4, y_offset = 4, flip_x = 1 }, -- Flipped arm
-    -- Left Leg
+    -- Left Leg (sprite index 4)
     { s = 4, x_offset = -2, y_offset = 8 },
-    -- Right Leg
+    -- Right Leg (sprite index 5, flipped)
     { s = 5, x_offset = 2, y_offset = 8, flip_x = 1 } -- Flipped leg
   }
 })

inc/window/window.game.lua

@@ -1,3 +1,6 @@
+--- Draws the main game window content.
+-- This includes the current screen's background, top bar, decisions, and all active sprites.
+-- @function GameWindow.draw
 function GameWindow.draw()
   local screen = Context.screens[Context.current_screen]
   Map.draw(screen.background)
@@ -17,6 +20,10 @@ function GameWindow.draw()
   Sprite.draw()
 end
 
+--- Updates the logic for the main game window.
+-- Handles input, navigates between screens, calls the current screen's and situation's update functions,
+-- and processes player decisions.
+-- @function GameWindow.update
 function GameWindow.update()
   local previous_screen_index = Context.current_screen
 
@@ -79,6 +86,10 @@ function GameWindow.update()
   end
 end
 
+--- Sets the active window state for the game.
+-- This function is typically called when transitioning between different game states (e.g., to a minigame).
+-- @param new_state number The ID of the new active window (e.g., `WINDOW_MENU`, `WINDOW_GAME`).
+-- @function GameWindow.set_state
 function GameWindow.set_state(new_state)
   Context.active_window = new_state
-  end
+end