docs

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)!"})
@@ -8,16 +15,28 @@ function Situation.register(situation)
   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
@@ -34,4 +53,3 @@ function Situation.apply(id)
   Context.current_situation = id
   situation.handle()
 end
-