FumeNodes/jim_bridge
1
0
Fork 0
mirror of https://github.com/jimathy/jim_bridge.git synced 2026-08-17 05:56:02 +01:00
Code Issues Packages Projects Releases Wiki Activity

refactor + attempt better support for other inventories

Browse Source
This commit is contained in:
Jim Shield
2025-03-08 13:44:05 +00:00
committed by GitHub
parent 31a7ac2951
commit 6bfb549fd0
31 changed files with 3151 additions and 2536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
shared/scaleforms/bigMessageInstance.lua
View File

@@ -1,6 +1,17 @@
BigMessage = {}
--[[
BigMessage Module
-----------------
This module provides a flexible way to display large, attention-grabbing messages
on screen using a Scaleform movie ("MP_BIG_MESSAGE_FREEMODE"). It supports multiple
message types (mission passed, colored shard, old-style, simple shard, rank-up, weapon purchased,
and large multiplayer messages), including customizable transitions and durations.
]]
local BigMessage = {}
BigMessage.__index = BigMessage
--- Creates a new BigMessage instance.
--- @return table table A new BigMessage object.
function BigMessage:new()
local self = setmetatable({}, BigMessage)
self.scaleform = nil
@@ -15,6 +26,7 @@ function BigMessage:new()
return self
end
--- Loads the Scaleform movie if it has not been loaded yet.
function BigMessage:Load()
if self.scaleform then return end
self.scaleform = RequestScaleformMovie("MP_BIG_MESSAGE_FREEMODE")
@@ -23,7 +35,8 @@ function BigMessage:Load()
end
end
-- Dispose of the scaleform
--- Disposes of the Scaleform movie.
--- If manualDispose is true, executes a transition before disposing.
function BigMessage:Dispose()
if not self.scaleform then return end
@@ -34,8 +47,8 @@ function BigMessage:Dispose()
ScaleformMovieMethodAddParamBool(self.transitionPreventAutoExpansion)
EndScaleformMovieMethod()
-- Wait a fraction of the transition duration (in milliseconds)
Wait((self.transitionDuration * 0.5) * 1000)
self.manualDispose = false
end
@@ -46,8 +59,10 @@ function BigMessage:Dispose()
self.isDisplaying = false
end
--- Updates the display by drawing the Scaleform movie fullscreen.
function BigMessage:Update()
if not self.scaleform then return end
DrawScaleformMovieFullscreen(self.scaleform, 255, 255, 255, 255, 0)
if self.manualDispose then return end
@@ -60,6 +75,7 @@ function BigMessage:Update()
ScaleformMovieMethodAddParamBool(self.transitionPreventAutoExpansion)
EndScaleformMovieMethod()
self.transitionExecuted = true
-- Extend duration slightly for smooth transition
self.duration = self.duration + ((self.transitionDuration * 0.5) * 1000)
else
self:Dispose()
@@ -67,14 +83,20 @@ function BigMessage:Update()
end
end
--- Sets the transition properties for disposing the message.
--- @param transition string The transition function name (default: "TRANSITION_OUT").
--- @param duration number The duration for the transition (default: 0.4).
--- @param preventAutoExpansion boolean Whether to prevent auto-expansion (default: true).
function BigMessage:SetTransition(transition, duration, preventAutoExpansion)
self.transition = transition or "TRANSITION_OUT"
self.transitionDuration = duration or 0.4
self.transitionPreventAutoExpansion = preventAutoExpansion or true
end
--- Starts a thread to continuously update the HUD until the message is done.
function BigMessage:StartUpdate()
if self.isDisplaying then return end
self.isDisplaying = true
CreateThread(function()
while self.isDisplaying do
@@ -85,10 +107,13 @@ function BigMessage:StartUpdate()
end
--- Displays a mission passed message.
---
--- @param msg string The main message to display.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param msg string The message to display.
--- @param duration number|nil The duration (in milliseconds) to display the message (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose the Scaleform after display (default: false).
--- @usage
--- ```lua
--- BigMessage:ShowMissionPassedMessage("MISSION PASSED", 5000)
--- ```
function BigMessage:ShowMissionPassedMessage(msg, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -109,13 +134,12 @@ function BigMessage:ShowMissionPassedMessage(msg, duration, manualDispose)
end
--- Displays a colored shard message.
---
--- @param msg string The main message to display.
--- @param msg string The main message.
--- @param desc string The description text.
--- @param textColor number The color index for the text.
--- @param bgColor number The color index for the background.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param textColor number The text color index.
--- @param bgColor number The background color index.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose the Scaleform (default: false).
function BigMessage:ShowColoredShard(msg, desc, textColor, bgColor, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -134,12 +158,9 @@ function BigMessage:ShowColoredShard(msg, desc, textColor, bgColor, duration, ma
end
--- Displays an old-style mission passed message.
---
--- @param msg string The main message to display.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
---
--- @return void
--- @param msg string The message.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowOldMessage(msg, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -155,13 +176,10 @@ function BigMessage:ShowOldMessage(msg, duration, manualDispose)
end
--- Displays a simple shard message.
---
--- @param msg string The main message to display.
--- @param msg string The main message.
--- @param subtitle string The subtitle text.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
---
--- @return void
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowSimpleShard(msg, subtitle, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -178,12 +196,11 @@ function BigMessage:ShowSimpleShard(msg, subtitle, duration, manualDispose)
end
--- Displays a rank-up message.
---
--- @param msg string The main message to display.
--- @param msg string The main message.
--- @param subtitle string The subtitle text.
--- @param rank number The rank level achieved.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowRankupMessage(msg, subtitle, rank, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -203,12 +220,11 @@ function BigMessage:ShowRankupMessage(msg, subtitle, rank, duration, manualDispo
end
--- Displays a weapon purchased message.
---
--- @param bigMessage string The main message to display.
--- @param bigMessage string The main message.
--- @param weaponName string The name of the weapon purchased.
--- @param weaponHash number The hash identifier of the weapon.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param weaponHash number The weapon hash.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowWeaponPurchasedMessage(bigMessage, weaponName, weaponHash, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -228,10 +244,9 @@ function BigMessage:ShowWeaponPurchasedMessage(bigMessage, weaponName, weaponHas
end
--- Displays a large multiplayer message.
---
--- @param msg string The main message to display.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param msg string The main message.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowMpMessageLarge(msg, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -254,11 +269,10 @@ function BigMessage:ShowMpMessageLarge(msg, duration, manualDispose)
end
--- Displays a "Wasted" multiplayer message.
---
--- @param msg string The main message to display.
--- @param msg string The main message.
--- @param subtitle string The subtitle text.
--- @param duration number|nil The duration in milliseconds the message should be displayed. Defaults to 5000.
--- @param manualDispose boolean|nil Whether to manually dispose of the scaleform after the message. Defaults to false.
--- @param duration number|nil Duration in milliseconds (default: 5000).
--- @param manualDispose boolean|nil Whether to manually dispose (default: false).
function BigMessage:ShowMpWastedMessage(msg, subtitle, duration, manualDispose)
duration = duration or 5000
self:Load()
@@ -274,4 +288,19 @@ function BigMessage:ShowMpWastedMessage(msg, subtitle, duration, manualDispose)
self:StartUpdate()
end
--- Starts the update loop for displaying the message.
function BigMessage:StartUpdate()
if self.isDisplaying then return end
self.isDisplaying = true
CreateThread(function()
while self.isDisplaying do
Wait(0)
self:Update()
end
end)
end
-- Create an instance of BigMessage and return it.
BigMessage = BigMessage:new()
return BigMessage

47
shared/scaleforms/countDownHandler.lua
View File

@@ -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)

47
shared/scaleforms/debugScaleform.lua
View File

@@ -1,41 +1,44 @@
-------------------------------------------------------------
-- Debug Text Display Functionality
-------------------------------------------------------------
--- Displays debug information on the player's screen.
--- Draws debug text on the screen if debugMode is enabled.
---
--- This function renders a semi-transparent box with multiple lines of text for debugging purposes.
--- It is controlled by the `debugMode` flag and can be positioned dynamically on the screen.
--- Calculates a background rectangle based on the number of text lines and renders each line on-screen.
---
--- @param textTable table A table containing strings to display.
--- @param loc vector2|nil Optional. The screen position to display the debug box. Defaults to `vec2(0.05, 0.65)`.
--- @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
--- debugScaleForm({
--- "Player Position: X=123.45 Y=678.90 Z=12.34",
--- "Current Action: Running",
--- })
---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
-- Define the display position (top left corner)
local loc = loc or vec2(0.05, 0.65)
loc = loc or vec2(0.05, 0.65)
-- Calculate dynamic height based on the number of lines in the textTable
local lineHeight = 0.025 -- Height of each line of text
local totalHeight = #textTable * lineHeight -- Dynamic height based on number of lines
local boxPadding = 0.01 -- Padding to add around the text inside the box
local size = vec2(0.18, totalHeight + boxPadding * 2) -- Width remains fixed, height is dynamic
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
local textLine = textTable[i]
SetTextScale(0.30, 0.30)
BeginTextCommandDisplayText("STRING")
AddTextComponentSubstringKeyboardDisplay(textLine)
AddTextComponentSubstringKeyboardDisplay(textTable[i])
EndTextCommandDisplayText(loc.x + 0.005, loc.y + (i - 1) * lineHeight + 0.01)
end
end
end
end

41
shared/scaleforms/instructionalButtons.lua
View File

@@ -1,30 +1,45 @@
--- Creates instructional buttons using the detected polyzone library (ox_lib or PolyZone).
-------------------------------------------------------------
-- Instructional Buttons Functionality
-------------------------------------------------------------
--- Loads and draws instructional buttons on-screen using a scaleform movie.
---
--- This function generates instructional buttons on the player's screen based on the provided information.
--- It supports different polyzone libraries by automatically detecting which one is active.
--- 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 A table containing the instructional buttons configuration.
--- - **keys** (`table`): A list of control keys to display.
--- - **text** (`string`): The description text for the buttons.
--- @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
--- @usage
--- ```lua
--- makeInstructionalButtons({
--- { keys = { 38 }, text = "Interact" },
--- { keys = { 47 }, text = "Pick Up" },
--- })
---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)
@@ -37,8 +52,11 @@ function makeInstructionalButtons(info)
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)
@@ -46,5 +64,6 @@ function makeInstructionalButtons(info)
ScaleformMovieMethodAddParamInt(80)
EndScaleformMovieMethod()
-- Final full-screen draw with full opacity.
DrawScaleformMovieFullscreen(build, 255, 255, 255, 255, 0)
end

242
shared/scaleforms/scaleform_basic.lua Normal file
View File

@@ -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

18
shared/scaleforms/timerBars.lua
View File

@@ -1,3 +1,21 @@
--- Creates and displays a timer HUD on the screen.
--- Draws a title (if provided) and a series of timer bars from the supplied data.
---
--- @param title string|nil Optional title to display at the top of the HUD.
--- @param data table A table of timer bar entries. Each entry should include:
--- - stat (string): The statistic name.
--- - value (string): The value to display.
--- - multi (number|nil): Optional, indicates multiple checkpoints (e.g., progress levels).
--- @param alpha number|nil Optional alpha value (transparency) for the HUD; defaults to 255.
---
--- @usage
--- ```lua
--- createTimerHud("Timer", {
--- { stat = "Health", value = "85%" },
--- { stat = "Armor", value = "50%", multi = 2 },
--- { stat = "Stamina", value = "100%" },
--- }, 255)
--- ```
function createTimerHud(title, data, alpha)
loadTextureDict("timerbars")