refactor + attempt better support for other inventories

shared/scaleforms/scaleform_basic.lua

@@ -0,0 +1,242 @@
+--[[
+    Instructional Buttons & Debug Text Module
+    -------------------------------------------
+    This module provides functions for:
+      • Displaying instructional buttons on-screen via a scaleform movie.
+      • Drawing debug text with a background rectangle when debugMode is enabled.
+      • Rendering 3D text in the world.
+      • Displaying help messages and spinners.
+]]
+
+-------------------------------------------------------------
+-- Instructional Buttons Functionality
+-------------------------------------------------------------
+
+--- Loads and draws instructional buttons on-screen using a scaleform movie.
+---
+--- Requests the "instructional_buttons" scaleform, clears previous data, sets clear space,
+--- creates data slots for each button option provided in `info`, and then draws the scaleform fullscreen.
+---
+--- @param info table An array of tables, where each table represents a button option:
+---     - keys (table): An array of key codes (e.g., {38, 29}) to display.
+---     - text (string): The label for the button.
+---
+--- @usage
+--- ```lua
+---CreateThread(function()
+---    while true do
+---         makeInstructionalButtons({
+---             { keys = {38, 29}, text = "Open Menu" },
+---             { keys = {45}, text = "Close Menu" }
+---         })
+---         Wait(0)
+---    end
+---end)
+--- ```
+function makeInstructionalButtons(info)
+    local build = RequestScaleformMovie("instructional_buttons")
+    while not HasScaleformMovieLoaded(build) do Wait(0) end
+
+    -- Draw the scaleform fullscreen (initial draw).
+    DrawScaleformMovieFullscreen(build, 255, 255, 255, 0, 0)
+
+    -- Clear previous instructions.
+    BeginScaleformMovieMethod(build, "CLEAR_ALL")
+    EndScaleformMovieMethod()
+
+    -- Set clear spacing between buttons.
+    BeginScaleformMovieMethod(build, "SET_CLEAR_SPACE")
+    ScaleformMovieMethodAddParamInt(200)
+    EndScaleformMovieMethod()
+
+    -- Add each button option to the scaleform.
+    for i = 1, #info do
+        BeginScaleformMovieMethod(build, "SET_DATA_SLOT")
+        ScaleformMovieMethodAddParamInt(i - 1)
+        for k = 1, #info[i].keys do
+            ScaleformMovieMethodAddParamPlayerNameString(GetControlInstructionalButton(2, info[i].keys[k], true))
+        end
+        BeginTextCommandScaleformString("STRING")
+        AddTextComponentSubstringKeyboardDisplay(info[i].text)
+        EndTextCommandScaleformString()
+        EndScaleformMovieMethod()
+    end
+
+    -- Draw the instructional buttons.
+    BeginScaleformMovieMethod(build, "DRAW_INSTRUCTIONAL_BUTTONS")
+    EndScaleformMovieMethod()
+
+    -- Set a translucent black background.
+    BeginScaleformMovieMethod(build, "SET_BACKGROUND_COLOUR")
+    ScaleformMovieMethodAddParamInt(0)
+    ScaleformMovieMethodAddParamInt(0)
+    ScaleformMovieMethodAddParamInt(0)
+    ScaleformMovieMethodAddParamInt(80)
+    EndScaleformMovieMethod()
+
+    -- Final full-screen draw with full opacity.
+    DrawScaleformMovieFullscreen(build, 255, 255, 255, 255, 0)
+end
+
+-------------------------------------------------------------
+-- Debug Text Display Functionality
+-------------------------------------------------------------
+
+--- Draws debug text on the screen if debugMode is enabled.
+---
+--- Calculates a background rectangle based on the number of text lines and renders each line on-screen.
+---
+--- @param textTable table An array of strings to display.
+--- @param loc vector2 (Optional) Top-left coordinate for the text box (default: vec2(0.05, 0.65)).
+---
+--- @usage
+--- ```lua
+---CreateThread(function()
+---    while true do
+---         debugScaleForm(
+---             {
+---                 "Line 1: Debug info",
+---                 "Line 2: More info"
+---             }
+---         )
+---         Wait(0)
+---    end
+---end)
+--- ```
+function debugScaleForm(textTable, loc)
+    if debugMode then
+        loc = loc or vec2(0.05, 0.65)
+
+        local lineHeight = 0.025        -- Height per line.
+        local totalHeight = #textTable * lineHeight
+        local boxPadding = 0.01         -- Padding around the text.
+        local size = vec2(0.18, totalHeight + boxPadding * 2)
+
+        -- Draw background rectangle.
+        DrawRect(loc.x + size.x / 2, loc.y + size.y / 2, size.x, size.y, 0, 0, 0, 255)
+
+        -- Render each line of text.
+        for i = 1, #textTable do
+            SetTextScale(0.30, 0.30)
+            BeginTextCommandDisplayText("STRING")
+            AddTextComponentSubstringKeyboardDisplay(textTable[i])
+            EndTextCommandDisplayText(loc.x + 0.005, loc.y + (i - 1) * lineHeight + 0.01)
+        end
+    end
+end
+
+-------------------------------------------------------------
+-- 3D Text Rendering
+-------------------------------------------------------------
+
+--- Draws 3D text at specified world coordinates.
+---
+--- Configures text properties, draws the text, and displays a background rectangle behind it.
+---
+--- @param coord table A vector3 with x, y, and z coordinates.
+--- @param text string The text to display.
+--- @param highlight boolean (Optional) If true, highlights parts of the text.
+---
+--- @usage
+--- ```lua
+--- CreateThread(function()
+---     while true do
+---         DrawText3D(vector3(100, 200, 300), "Hello World", true)
+---         Wait(0)
+---     end
+--- end)
+--- ```
+function DrawText3D(coord, text, highlight)
+    SetTextScale(0.30, 0.30)
+    SetTextFont(0)
+    SetTextProportional(1)
+    SetTextColour(255, 255, 255, 215)
+    SetTextEntry("STRING")
+    SetTextCentre(true)
+
+    local totalLength = string.len(text)
+    local textMaxLength = 99 -- max 99
+    local text = totalLength > textMaxLength and text:sub(1, totalLength - (totalLength - textMaxLength)) or text
+    AddTextComponentString(highlight and text:gsub("%~w~", "~y~") or text)
+    SetDrawOrigin(coord.x, coord.y, coord.z, 0)
+    DrawText(0.0, 0.0)
+    local count, length = GetLineCountAndMaxLength(text)
+
+    local padding = 0.005
+    local heightFactor = (count / 43) + padding
+    local weightFactor = (length / 150) + padding
+
+    local height = (heightFactor / 2) - padding / 1
+    local width = (weightFactor / 2) - padding / 1
+
+    DrawRect(0.0, height, width, heightFactor, 0, 0, 0, 150)
+    ClearDrawOrigin()
+end
+
+--- Calculates the number of lines and the maximum line length from the given text.
+---
+--- @param text string The text to analyze.
+--- @return number, number The line count and maximum line length.
+---
+--- @usage
+--- ```lua
+--- local count, maxLen = GetLineCountAndMaxLength("Hello World")
+--- ```
+function GetLineCountAndMaxLength(text)
+    local lineCount, maxLength = 0, 0
+    for line in text:gmatch("[^\n]+") do
+        lineCount += 1
+        local lineLength = string.len(line)
+        if lineLength > maxLength then
+            maxLength = lineLength
+        end
+    end
+    if lineCount == 0 then lineCount = 1 end
+    return lineCount, maxLength
+end
+
+-------------------------------------------------------------
+-- Additional UI Helpers
+-------------------------------------------------------------
+
+--- Displays a help message on the screen.
+---
+--- @param text string The message to display.
+---
+--- @usage
+--- ```lua
+--- DisplayHelpMsg("Press E to interact")
+--- ```
+function DisplayHelpMsg(text)
+    BeginTextCommandDisplayHelp("STRING")
+    AddTextComponentScaleform(text)
+    EndTextCommandDisplayHelp(0, true, false, -1)
+end
+
+--- Displays a "Saving/Loading" spinner with a custom message.
+---
+--- @param text string The message to display alongside the spinner.
+---
+--- @usage
+--- ```lua
+--- displaySpinner("Saving data...")
+--- ```
+function displaySpinner(text)
+    BeginTextCommandBusyspinnerOn('STRING')
+    AddTextComponentSubstringPlayerName(text)
+    EndTextCommandBusyspinnerOn(4)
+end
+
+--- Stops the "Saving/Loading" spinner.
+---
+--- This function should only be called client-side.
+---
+--- @usage
+--- ```lua
+--- stopSpinner()
+--- ```
+function stopSpinner()
+    if not isServer() then
+        BusyspinnerOff()
+    end
+end