docs

Reviewed-on: http://git.teletype.hu/games/impostor/pulls/10

.gitignore

@@ -1,4 +1,4 @@
 .local
 impostor.lua
 prompts
-docs
+docs

.luacheckrc

@@ -4,7 +4,9 @@
 globals = {
   "Util",
   "Decision",
+  "Situation",
   "Screen",
+  "Sprite",
   "UI",
   "Print",
   "Input",
@@ -12,12 +14,23 @@ globals = {
   "Context",
   "Meters",
   "Minigames",
+  "SplashWindow",
+  "IntroWindow",
+  "MenuWindow",
+  "GameWindow",
+  "PopupWindow",
+  "ConfigurationWindow",
+  "AudioTestWindow",
+  "MinigameButtonMashWindow",
+  "MinigameRhythmWindow",
+  "MinigameDDRWindow",
   "mset",
   "mget",
   "btnp",
   "keyp",
   "music",
   "sfx",
+  "spr",
   "rect",
   "rectb",
   "circ",

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

impostor.inc

@@ -5,7 +5,12 @@ init/init.minigames.lua
 init/init.meters.lua
 system/system.util.lua
 init/init.windows.lua
+sprite/sprite.manager.lua
+sprite/sprite.norman.lua
+situation/situation.manager.lua
+situation/situation.drink_coffee.lua
 decision/decision.manager.lua
+decision/decision.have_a_coffee.lua
 decision/decision.go_to_home.lua
 decision/decision.go_to_toilet.lua
 decision/decision.go_to_walking_to_office.lua

inc/decision/decision.have_a_coffee.lua

@@ -0,0 +1,8 @@
+Decision.register({
+  id = "have_a_coffee",
+  label = "Have a Coffee",
+  handle = function()
+    Situation.apply("drink_coffee")
+  end,
+  condition = function() return true end
+})

inc/init/init.context.lua

@@ -45,7 +45,13 @@ on than meets the eye.]]
     minigame_ddr = Minigames.get_default_ddr(),
     minigame_button_mash = Minigames.get_default_button_mash(),
     minigame_rhythm = Minigames.get_default_rhythm(),
-    meters = Meters.get_initial()
+    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
 

inc/init/init.modules.lua

@@ -1,21 +1,22 @@
-local SplashWindow = {}
-local IntroWindow = {}
-local MenuWindow = {}
-local GameWindow = {}
-local PopupWindow = {}
-local ConfigurationWindow = {}
-local AudioTestWindow = {}
-local MinigameButtonMashWindow = {}
-local MinigameRhythmWindow = {}
-local MinigameDDRWindow = {}
+SplashWindow = {}
+IntroWindow = {}
+MenuWindow = {}
+GameWindow = {}
+PopupWindow = {}
+ConfigurationWindow = {}
+AudioTestWindow = {}
+MinigameButtonMashWindow = {}
+MinigameRhythmWindow = {}
+MinigameDDRWindow = {}
 Util = {}
 Meters = {}
 Minigames = {}
 Decision = {}
+Situation = {}
 Screen = {}
 Map = {}
 UI = {}
 Print = {}
 Input = {}
-
+Sprite = {}
 Audio = {}

inc/screen/screen.manager.lua

@@ -1,20 +1,32 @@
 local _screens = {}
 
-function Screen.get_screens_array()
-  local screens_array = {}
-  for _, screen_data in pairs(_screens) do
-    table.insert(screens_array, screen_data)
-  end
-  return screens_array
-end
-
+--- 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)
   end
+  if not screen_data.situations then
+    screen_data.situations = {}
+  end
+  if not screen_data.init then
+    screen_data.init = function() end
+  end
+  if not screen_data.update then
+    screen_data.update = function() end
+  end
   _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/screen/screen.office.lua

@@ -6,5 +6,9 @@ Screen.register({
     "play_rhythm",
     "play_ddr",
     "go_to_walking_to_home",
-  }
+    "have_a_coffee",
+  },
+  situations = {
+    "drink_coffee",
+  },
 })

inc/situation/situation.drink_coffee.lua

@@ -0,0 +1,7 @@
+Situation.register({
+  id = "drink_coffee",
+  handle = function()
+    Audio.sfx_select()
+    Sprite.show("norman", 100, 100)
+  end,
+})

inc/situation/situation.manager.lua

@@ -0,0 +1,55 @@
+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)!"})
+    return
+  end
+  if not situation.handle then
+    situation.handle = function() end
+  end
+  if not situation.update then
+    situation.update = function() end
+  end
+  if _situations[situation.id] then
+    trace("Warning: Overwriting situation with id: " .. situation.id)
+  end
+  _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
+    trace("Error: No situation found with id: " .. id)
+    return
+  end
+
+  local current_screen_obj = Screen.get_by_id(Context.current_screen)
+  if current_screen_obj and not current_screen_obj.situations[id] then
+    trace("Info: Situation " .. id .. " cannot be applied to current screen (id: " .. Context.current_screen .. ").")
+    return
+  end
+
+  Context.current_situation = id
+  situation.handle()
+end

inc/sprite/sprite.manager.lua

@@ -0,0 +1,99 @@
+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)!")
+    return
+  end
+  if _sprites[sprite_data.id] then
+    trace("Warning: Overwriting sprite with id: " .. sprite_data.id)
+  end
+  _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
+    trace("Error: Attempted to show non-registered sprite with id: " .. id)
+    return
+  end
+
+  Context.sprites[id] = {
+    id = id,
+    x = x,
+    y = y,
+    colorkey = colorkey,
+    scale = scale,
+    flip_x = flip_x,
+    flip_y = flip_y,
+    rot = 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]
+    if not sprite_data then
+      trace("Error: Sprite id " .. id .. " in Context.sprites is not registered.")
+      Context.sprites[id] = nil -- Clean up invalid entry
+      -- We should probably continue to the next sprite instead of returning
+      -- so that other valid sprites can still be drawn.
+    end
+
+    -- Use parameters from Context.sprites, or fall back to sprite_data, then to defaults
+    local colorkey = params.colorkey or sprite_data.colorkey or 0
+    local scale = params.scale or sprite_data.scale or 1
+    local flip_x = params.flip_x or sprite_data.flip_x or 0
+    local flip_y = params.flip_y or sprite_data.flip_y or 0
+    local rot = params.rot or sprite_data.rot or 0
+
+    if sprite_data.sprites then -- Complex sprite
+      for i = 1, #sprite_data.sprites do
+        local sub_sprite = sprite_data.sprites[i]
+        spr(
+          sub_sprite.s,
+          params.x + (sub_sprite.x_offset or 0),
+          params.y + (sub_sprite.y_offset or 0),
+          sub_sprite.colorkey or colorkey,
+          sub_sprite.scale or scale,
+          sub_sprite.flip_x or flip_x,
+          sub_sprite.flip_y or flip_y,
+          sub_sprite.rot or rot
+        )
+      end
+    else -- Simple sprite
+      spr(sprite_data.s, params.x, params.y, colorkey, scale, flip_x, flip_y, rot)
+    end
+  end
+end

inc/sprite/sprite.norman.lua

@@ -0,0 +1,17 @@
+Sprite.register({
+  id = "norman",
+  sprites = {
+    -- Body (sprite index 0)
+    { s = 0, x_offset = 0, y_offset = 0 },
+    -- Head (sprite index 1)
+    { s = 1, x_offset = 0, y_offset = -8 },
+    -- Left Arm (sprite index 2)
+    { s = 2, x_offset = -4, y_offset = 4 },
+    -- Right Arm (sprite index 3, flipped)
+    { s = 3, x_offset = 4, y_offset = 4, flip_x = 1 }, -- Flipped arm
+    -- Left Leg (sprite index 4)
+    { s = 4, x_offset = -2, y_offset = 8 },
+    -- 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)
@@ -14,9 +17,16 @@ function GameWindow.draw()
       UI.draw_decision_selector(available_decisions, Context.selected_decision_index)
     end
   end
+  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
+
   if Input.menu_back() then
     Context.active_window = WINDOW_MENU
     MenuWindow.refresh_menu_items()
@@ -36,6 +46,19 @@ function GameWindow.update()
     Context.selected_decision_index = 1   end
 
   local screen = Context.screens[Context.current_screen]
+  screen.update()
+
+  if previous_screen_index ~= Context.current_screen then
+    screen.init()
+  end
+
+  if Context.current_situation then
+    local current_situation_obj = Situation.get(Context.current_situation)
+    if current_situation_obj and current_situation_obj.update then
+      current_situation_obj.update()
+    end
+  end
+
   if screen and screen.decisions and #screen.decisions > 0 then
     local available_decisions = {}
     for _, decision_id in ipairs(screen.decisions) do
@@ -63,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