Add Tutorial Text API

Data/Scripts/Miscellaneous/GameManager/TutorialTextManager.lua

@@ -0,0 +1,168 @@
+require("GameManager/TutorialTextView")
+
+---Manages multiple named tutorial text views, rendering only the active view.
+---
+---Views hold their own state independently. Only the current view is rendered
+---to the screen. Switching views clears the screen and renders the new view's
+---current state.
+---
+---@class TutorialTextManager
+---@field Views table<string, TutorialTextView> All registered views by name.
+---@field CurrentViewName string|nil The name of the currently active view.
+TutorialTextManager = {}
+TutorialTextManager.__index = TutorialTextManager
+
+---Creates a new Tutorial Text Manager.
+---@return TutorialTextManager
+function TutorialTextManager:New()
+    local self = setmetatable({}, TutorialTextManager)
+
+    self.Views = {}
+    self.CurrentViewName = nil
+
+    return self
+end
+
+---Registers a new view. If a view with the given name already exists it is returned as-is.
+---@param name string The view name.
+---@return TutorialTextView
+function TutorialTextManager:AddView(name)
+    if not self.Views[name] then
+        self.Views[name] = TutorialTextView:New(name)
+    end
+    return self.Views[name]
+end
+
+---Registers an existing view instance (e.g. a TutorialTextFeed).
+---If a view with the same name already exists it is returned as-is.
+---@param view TutorialTextView The view to register.
+---@return TutorialTextView
+function TutorialTextManager:RegisterView(view)
+    if not self.Views[view.Name] then
+        self.Views[view.Name] = view
+    end
+    return self.Views[view.Name]
+end
+
+---Returns a registered view by name, or nil if it does not exist.
+---@param name string The view name.
+---@return TutorialTextView|nil
+function TutorialTextManager:GetView(name)
+    return self.Views[name]
+end
+
+---Switches the active view. Clears the screen then renders the new view's current state.
+---@param name string The view name to activate.
+function TutorialTextManager:SetCurrentView(name)
+    if self.CurrentViewName == name then
+        return
+    end
+
+    local oldView = self.Views[self.CurrentViewName]
+    if oldView then
+        oldView.IsActive = false
+    end
+
+    self:_ClearScreen()
+    self.CurrentViewName = name
+
+    local newView = self.Views[name]
+    if newView then
+        newView.IsActive = true
+        self:_RenderView(newView)
+    end
+end
+
+---Sets or updates a text entry in a view.
+---If the view is currently active the change is immediately rendered to the screen.
+---@param viewName string The view to update.
+---@param key string The unique key for this entry.
+---@param text string The display text.
+---@param duration number|nil Duration in seconds, defaults to -1 (infinite).
+---@param color ColorStruct|nil The text color, defaults to white.
+function TutorialTextManager:UpdateEntry(viewName, key, text, duration, color)
+    local view = self.Views[viewName]
+    if not view then
+        return
+    end
+
+    view:SetEntry(key, text, duration, color)
+
+    if self.CurrentViewName == viewName then
+        local entry = view.Entries[key]
+        Add_Tutorial_Text(entry.Key, entry.Text, entry.Duration,
+            entry.Color.R, entry.Color.G, entry.Color.B, entry.Color.A)
+    end
+end
+
+---Removes a text entry from a view.
+---If the view is currently active the entry is immediately removed from the screen.
+---@param viewName string The view to update.
+---@param key string The key to remove.
+function TutorialTextManager:RemoveEntry(viewName, key)
+    local view = self.Views[viewName]
+    if not view then
+        return
+    end
+
+    view:RemoveEntry(key)
+
+    if self.CurrentViewName == viewName then
+        Remove_Tutorial_Text(key)
+    end
+end
+
+---Clears all entries from a view.
+---If the view is currently active all entries are immediately removed from the screen.
+---@param viewName string The view to clear.
+function TutorialTextManager:ClearView(viewName)
+    local view = self.Views[viewName]
+    if not view then
+        return
+    end
+
+    if self.CurrentViewName == viewName then
+        self:_ClearScreen()
+    end
+
+    view:Clear()
+end
+
+---Removes all views and clears the screen.
+function TutorialTextManager:Reset()
+    self:_ClearScreen()
+    self.Views = {}
+    self.CurrentViewName = nil
+end
+
+---Renders all entries of a view to the screen.
+---@param view TutorialTextView
+function TutorialTextManager:_RenderView(view)
+    for _, entry in pairs(view.Entries) do
+        Add_Tutorial_Text(entry.Key, entry.Text, entry.Duration,
+            entry.Color.R, entry.Color.G, entry.Color.B, entry.Color.A)
+    end
+end
+
+---Removes all entries of the current view from the screen.
+function TutorialTextManager:_ClearScreen()
+    if not self.CurrentViewName then
+        return
+    end
+
+    local view = self.Views[self.CurrentViewName]
+    if not view then
+        return
+    end
+
+    for key in pairs(view.Entries) do
+        Remove_Tutorial_Text(key)
+    end
+end
+
+function TutorialTextManager:Debug()
+    local count = 0
+    for _ in pairs(self.Views) do count = count + 1 end
+    return string.format("TutorialTextManager (views: %d, current: '%s')",
+        count, self.CurrentViewName or "none")
+end