Add Tutorial Text API

Data/Scripts/Miscellaneous/GameManager/TutorialTextFeed.lua

@@ -0,0 +1,72 @@
+require("GameManager/TutorialTextView")
+
+---A fixed-capacity feed view. Appending a new line when at capacity evicts the
+---oldest (top-most) entry first. Rendering is driven by the IsActive flag set
+---by TutorialTextManager; no manager reference is needed.
+---
+---@class TutorialTextFeed : TutorialTextView
+---@field MaxLines integer Maximum number of lines to display at once.
+---@field _KeyOrder string[] Insertion-ordered list of active entry keys (oldest first).
+---@field _NextId integer Counter used to generate unique entry keys.
+TutorialTextFeed = setmetatable({}, {__index = TutorialTextView})
+TutorialTextFeed.__index = TutorialTextFeed
+
+---Creates a new Tutorial Text Feed.
+---@param name string The view name.
+---@param maxLines integer Maximum number of lines to display at once.
+---@return TutorialTextFeed
+function TutorialTextFeed:New(name, maxLines)
+    local self = TutorialTextView.New(TutorialTextView, name)
+    setmetatable(self, TutorialTextFeed)
+
+    self.MaxLines = maxLines
+    self._KeyOrder = {}
+    self._NextId = 0
+
+    return self
+end
+
+---Appends a new line to the bottom of the feed.
+---If the feed is at capacity, the oldest line is removed first.
+---Only renders to the screen when this view is active.
+---@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 TutorialTextFeed:Append(text, duration, color)
+    if #self._KeyOrder >= self.MaxLines then
+        local oldestKey = table.remove(self._KeyOrder, 1)
+        self.Entries[oldestKey] = nil
+        if self.IsActive then
+            Remove_Tutorial_Text(oldestKey)
+        end
+    end
+
+    self._NextId = self._NextId + 1
+    local key = self.Name .. "_" .. self._NextId
+
+    self:SetEntry(key, text, duration, color)
+    table.insert(self._KeyOrder, key)
+
+    if self.IsActive then
+        local entry = self.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 all entries from the feed.
+---Only clears the screen when this view is active.
+function TutorialTextFeed:Clear()
+    if self.IsActive then
+        for _, key in ipairs(self._KeyOrder) do
+            Remove_Tutorial_Text(key)
+        end
+    end
+    self.Entries = {}
+    self._KeyOrder = {}
+end
+
+function TutorialTextFeed:Debug()
+    return string.format("TutorialTextFeed '%s' (%d/%d lines)",
+        self.Name, #self._KeyOrder, self.MaxLines)
+end