refactor + attempt better support for other inventories

shared/scaleforms/countDownHandler.lua

@@ -1,6 +1,18 @@
+--[[
+    CountdownHandler Module
+    -------------------------
+    This module provides a countdown HUD using a Scaleform movie ("COUNTDOWN").
+    It handles loading, updating, and disposing of the scaleform, as well as
+    playing sounds and displaying messages for each countdown tick.
+
+    TriggerNetEvent(getScript()..":startCountdown", 5, 25)
+]]
+
 CountdownHandler = {}
 CountdownHandler.__index = CountdownHandler
 
+--- Creates a new CountdownHandler instance.
+--- @return table table A new CountdownHandler object.
 function CountdownHandler:new()
     local self = setmetatable({}, CountdownHandler)
     self.scaleform = nil
@@ -9,14 +21,18 @@ function CountdownHandler:new()
     return self
 end
 
+--- Loads the "COUNTDOWN" scaleform movie.
 function CountdownHandler:Load()
-    if self.scaleform then return end
+    if self.scaleform then
+        return
+    end
     self.scaleform = RequestScaleformMovie("COUNTDOWN")
     while not HasScaleformMovieLoaded(self.scaleform) do
         Wait(0)
     end
 end
 
+--- Disposes of the currently loaded scaleform movie.
 function CountdownHandler:Dispose()
     if self.scaleform then
         SetScaleformMovieAsNoLongerNeeded(self.scaleform)
@@ -24,15 +40,19 @@ function CountdownHandler:Dispose()
     end
 end
 
+--- Updates the HUD by drawing the scaleform movie fullscreen.
 function CountdownHandler:Update()
     if self.scaleform then
         DrawScaleformMovieFullscreen(self.scaleform, 255, 255, 255, 255, 0)
     end
 end
 
+--- Displays a message on the countdown HUD.
+--- @param message string The message to display.
 function CountdownHandler:ShowMessage(message)
     local r, g, b, a = self.colour.r, self.colour.g, self.colour.b, self.colour.a
 
+    -- Set the message in the scaleform.
     BeginScaleformMovieMethod(self.scaleform, "SET_MESSAGE")
     ScaleformMovieMethodAddParamPlayerNameString(message)
     ScaleformMovieMethodAddParamInt(r)
@@ -41,6 +61,7 @@ function CountdownHandler:ShowMessage(message)
     ScaleformMovieMethodAddParamBool(true)
     EndScaleformMovieMethod()
 
+    -- Trigger a fade effect (optional).
     BeginScaleformMovieMethod(self.scaleform, "FADE_MP")
     ScaleformMovieMethodAddParamPlayerNameString(message)
     ScaleformMovieMethodAddParamInt(r)
@@ -49,17 +70,14 @@ function CountdownHandler:ShowMessage(message)
     EndScaleformMovieMethod()
 end
 
---- Starts the countdown with the specified number and HUD color.
----
---- @param number number|nil The starting number for the countdown. Defaults to 3.
---- @param hudColour number|nil The HUD color index. Defaults to 18.
----
---- @return boolean `true` when the countdown has finished.
----
+--- Starts the countdown HUD.
+--- @param number number|nil The starting number for the countdown (default: 3).
+--- @param hudColour number|nil The HUD colour index (default: 18).
+--- @return boolean boolean True when the countdown has finished.
 --- @usage
 --- ```lua
---- -- Start a countdown of 5 seconds with HUD color 25
 --- if CountdownHandler:Start(5, 25) then
+---     -- When run in an if statement, the script will wait until its finished to continue
 ---     print("Countdown Complete")
 --- end
 --- ```
@@ -68,6 +86,7 @@ function CountdownHandler:Start(number, hudColour)
     number = number or 3
     hudColour = hudColour or 18
 
+    -- Get HUD colour using framework function; alternatives could be added here.
     local r, g, b, a = GetHudColour(hudColour)
     self.colour = { r = r, g = g, b = b, a = a }
 
@@ -81,18 +100,17 @@ function CountdownHandler:Start(number, hudColour)
         end
     end)
 
-    -- Begin the countdown
+    -- Countdown logic
     CreateThread(function()
         local currentNumber = number
         while currentNumber > 0 do
-            -- Play countdown sound
             playSound("Count")
             self:ShowMessage(tostring(currentNumber))
             Wait(1000)
             currentNumber = currentNumber - 1
         end
-        playSound("Go")
 
+        playSound("Go")
         self:ShowMessage("GO")
         finished = true
 
@@ -101,14 +119,15 @@ function CountdownHandler:Start(number, hudColour)
         self:Dispose()
         finished = true
     end)
+
     while not finished do Wait(10) end
     return true
 end
 
--- Create an instance of CountdownHandler
+-- Create a singleton instance of CountdownHandler.
 CountdownHandler = CountdownHandler:new()
 
--- Optional: Register an event to start the countdown
+-- Register an event to start the countdown.
 RegisterNetEvent(getScript()..":startCountdown", function(number, hudColour)
     CountdownHandler:Start(number, hudColour)
 end)