simple refractor with local functions

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "githubPullRequests.ignoredPullRequestBranches": ["main"]
+}

lib/utility/client/utility.lua

@@ -1,80 +1,163 @@
+---@class Utility
 Utility = Utility or {}
 local blipIDs = {}
 local spawnedPeds = {}
 
----commentThis will create a prop with the passed model string at the coords and heading specified optionally networked or not.
----@param model string | number
----@param coords table
+-- === Local Helpers ===
+
+---Get the hash of a model (string or number)
+---@param model string|number
+---@return number
+local function getModelHash(model)
+    if type(model) ~= 'number' then
+        return joaat(model)
+    end
+    return model
+end
+
+---Ensure a model is loaded into memory
+---@param model string|number
+---@return boolean, number
+local function ensureModelLoaded(model)
+    local hash = getModelHash(model)
+    if not IsModelValid(hash) and not IsModelInCdimage(hash) then return false, hash end
+    RequestModel(hash)
+    local count = 0
+    while not HasModelLoaded(hash) and count < 30000 do
+        Wait(0)
+        count = count + 1
+    end
+    return HasModelLoaded(hash), hash
+end
+
+---Add a text entry if possible
+---@param key string
+---@param text string
+local function addTextEntryOnce(key, text)
+    if not AddTextEntry then return end
+    AddTextEntry(key, text)
+end
+
+---Create a blip safely and store its reference
+---@param coords vector3
+---@param sprite number
+---@param color number
+---@param scale number
+---@param label string
+---@param shortRange boolean
+---@param displayType number
+---@return number
+local function safeAddBlip(coords, sprite, color, scale, label, shortRange, displayType)
+    local blip = AddBlipForCoord(coords.x, coords.y, coords.z)
+    SetBlipSprite(blip, sprite or 8)
+    SetBlipColour(blip, color or 3)
+    SetBlipScale(blip, scale or 0.8)
+    SetBlipDisplay(blip, displayType or 2)
+    SetBlipAsShortRange(blip, shortRange)
+    addTextEntryOnce(label, label)
+    BeginTextCommandSetBlipName(label)
+    EndTextCommandSetBlipName(blip)
+    table.insert(blipIDs, blip)
+    return blip
+end
+
+---Remove a blip safely from the stored list
+---@param blip number
+---@return boolean
+local function safeRemoveBlip(blip)
+    for i, storedBlip in ipairs(blipIDs) do
+        if storedBlip == blip then
+            RemoveBlip(storedBlip)
+            table.remove(blipIDs, i)
+            return true
+        end
+    end
+    return false
+end
+
+---Add a text entry if possible (shortcut)
+---@param text string
+local function safeAddTextEntry(text)
+    if not AddTextEntry then return end
+    AddTextEntry(text, text)
+end
+
+-- === Public Utility Functions ===
+
+---Create a prop with the given model and coordinates
+---@param model string|number
+---@param coords vector3
 ---@param heading number
 ---@param networked boolean
----@return number | nil
-Utility.CreateProp = function(model, coords, heading, networked)
-    Utility.LoadModel(model)
-    if not HasModelLoaded(model) then return nil, Prints.Error("Model Has Not Loaded") end
-    local propEntity = CreateObject(model, coords.x, coords.y, coords.z, networked, false, false)
+---@return number|nil
+function Utility.CreateProp(model, coords, heading, networked)
+    local loaded, hash = ensureModelLoaded(model)
+    if not loaded then return nil, Prints and Prints.Error and Prints.Error("Model Has Not Loaded") end
+    local propEntity = CreateObject(hash, coords.x, coords.y, coords.z, networked, false, false)
     SetEntityHeading(propEntity, heading)
-    SetModelAsNoLongerNeeded(model)
+    SetModelAsNoLongerNeeded(hash)
     return propEntity
 end
 
----This will get the street name and crossing name at the specified coordinates.
----@param coords table
----@return string
----@return string
-Utility.GetStreetNameAtCoords = function(coords)
+---Get street and crossing names at given coordinates
+---@param coords vector3
+---@return string, string
+function Utility.GetStreetNameAtCoords(coords)
     local streetHash, crossingHash = GetStreetNameAtCoord(coords.x, coords.y, coords.z)
-    local streetName = GetStreetNameFromHashKey(streetHash)
-    local crossingName = GetStreetNameFromHashKey(crossingHash)
-    return streetName, crossingName
+    return GetStreetNameFromHashKey(streetHash), GetStreetNameFromHashKey(crossingHash)
 end
 
----This will create a vehicle with the passed model string at the coords and heading specified.
----@param model string
----@param coords table
+---Create a vehicle with the given model and coordinates
+---@param model string|number
+---@param coords vector3
 ---@param heading number
 ---@param networked boolean
----@return number| nil
----@return table
-Utility.CreateVehicle = function(model, coords, heading, networked)
-    Utility.LoadModel(model)
-    if not HasModelLoaded(model) then return nil, {}, Prints.Error("Model Has Not Loaded") end
-    local vehicle = CreateVehicle(model, coords.x, coords.y, coords.z, heading, networked, false)
+---@return number|nil, table
+function Utility.CreateVehicle(model, coords, heading, networked)
+    local loaded, hash = ensureModelLoaded(model)
+    if not loaded then return nil, {}, Prints and Prints.Error and Prints.Error("Model Has Not Loaded") end
+    local vehicle = CreateVehicle(hash, coords.x, coords.y, coords.z, heading, networked, false)
     SetVehicleHasBeenOwnedByPlayer(vehicle, true)
     SetVehicleNeedsToBeHotwired(vehicle, false)
     SetVehRadioStation(vehicle, "OFF")
-    SetModelAsNoLongerNeeded(model)
-    return vehicle, { networkid = NetworkGetNetworkIdFromEntity(vehicle) or 0, coords = GetEntityCoords(vehicle), heading = GetEntityHeading(vehicle), }
+    SetModelAsNoLongerNeeded(hash)
+    return vehicle, {
+        networkid = NetworkGetNetworkIdFromEntity(vehicle) or 0,
+        coords = GetEntityCoords(vehicle),
+        heading = GetEntityHeading(vehicle),
+    }
 end
 
----This will create a ped with the passed model string at the coords and heading specified.
----@param model string
----@param coords table
+---Create a ped with the given model and coordinates
+---@param model string|number
+---@param coords vector3
 ---@param heading number
 ---@param networked boolean
----@return number| nil
-Utility.CreatePed = function(model, coords, heading, networked, settings)
-    Utility.LoadModel(model)
-    if not HasModelLoaded(model) then return nil, Prints.Error("Model Has Not Loaded") end
-    local spawnedEntity = CreatePed(0, model, coords.x, coords.y, coords.z, heading, networked, false)
-    SetModelAsNoLongerNeeded(model)
+---@param settings table|nil
+---@return number|nil
+function Utility.CreatePed(model, coords, heading, networked, settings)
+    local loaded, hash = ensureModelLoaded(model)
+    if not loaded then return nil, Prints and Prints.Error and Prints.Error("Model Has Not Loaded") end
+    local spawnedEntity = CreatePed(0, hash, coords.x, coords.y, coords.z, heading, networked, false)
+    SetModelAsNoLongerNeeded(hash)
     table.insert(spawnedPeds, spawnedEntity)
     return spawnedEntity
 end
 
----This will display a busy spinner with the passed text.
+---Show a busy spinner with the given text
 ---@param text string
 ---@return boolean
-Utility.StartBusySpinner = function(text)
-    AddTextEntry(text, text)
+function Utility.StartBusySpinner(text)
+    safeAddTextEntry(text)
     BeginTextCommandBusyString(text)
     AddTextComponentSubstringPlayerName(text)
     EndTextCommandBusyString(0)
     return true
 end
 
----This will stop a busy spinner if one is currently active.
+---Stop the busy spinner if active
 ---@return boolean
-Utility.StopBusySpinner = function()
+function Utility.StopBusySpinner()
     if BusyspinnerIsOn() then
         BusyspinnerOff()
         return true
@@ -82,64 +165,38 @@ Utility.StopBusySpinner = function()
     return false
 end
 
----comment Creates a blip at the specified coordinates with the specified parameters. If sprite/color/scale/label are not provided, default values will be used.
----@param coords table
+---Create a blip at the given coordinates
+---@param coords vector3
 ---@param sprite number
 ---@param color number
 ---@param scale number
 ---@param label string
 ---@param shortRange boolean
 ---@param displayType number
----@return integer
-Utility.CreateBlip = function(coords, sprite, color, scale, label, shortRange, displayType)
-    local blip = AddBlipForCoord(coords.x, coords.y, coords.z)
-    SetBlipSprite(blip, sprite or 8)
-    SetBlipColour(blip, color or 3)
-    SetBlipScale(blip, scale or 0.8)
-    SetBlipDisplay(blip, displayType or 2)
-    SetBlipAsShortRange(blip, shortRange)
-    AddTextEntry(label, label)
-    BeginTextCommandSetBlipName(label)
-    EndTextCommandSetBlipName(blip)
-    table.insert(blipIDs, blip)
-    return blip
+---@return number
+function Utility.CreateBlip(coords, sprite, color, scale, label, shortRange, displayType)
+    return safeAddBlip(coords, sprite, color, scale, label, shortRange, displayType)
 end
 
----This will remove a blip if it exists in the blipIDs table.
+---Remove a blip if it exists
 ---@param blip number
 ---@return boolean
-Utility.RemoveBlip = function(blip)
-    local success = false
-    for i, storedBlip in ipairs(blipIDs) do
-        if storedBlip == blip then
-            RemoveBlip(storedBlip)
-            table.remove(blipIDs, i)
-            success = true
-            break
-        end
-    end
-    return success
+function Utility.RemoveBlip(blip)
+    return safeRemoveBlip(blip)
 end
 
----Loads a model into memory. If the model is not valid or not in the game files, it will return false.
----@param model string | number
+---Load a model into memory
+---@param model string|number
 ---@return boolean
-Utility.LoadModel = function(model)
-    if type(model) ~= 'number' then model = joaat(model) end -- Use GetHashKey instead of joaat for client
-    if not IsModelValid(model) and not IsModelInCdimage(model) then return false end
-    RequestModel(model)
-    local count = 0
-    while not HasModelLoaded(model) and count < 30000 do
-        Wait(0)
-        count = count + 1
-    end
-    return HasModelLoaded(model)
+function Utility.LoadModel(model)
+    local loaded = ensureModelLoaded(model)
+    return loaded
 end
 
----This function will request an animation dictionary and wait until it is loaded. If the dictionary is not valid, it will return false.
+---Request an animation dictionary
 ---@param dict string
 ---@return boolean
-Utility.RequestAnimDict = function(dict)
+function Utility.RequestAnimDict(dict)
     RequestAnimDict(dict)
     local count = 0
     while not HasAnimDictLoaded(dict) and count < 30000 do
@@ -149,10 +206,10 @@ Utility.RequestAnimDict = function(dict)
     return HasAnimDictLoaded(dict)
 end
 
----This will remove a ped if it exists in the spawnedPeds table. It will also delete the entity if it exists.
+---Remove a ped if it exists
 ---@param entity number
 ---@return boolean
-Utility.RemovePed = function(entity)
+function Utility.RemovePed(entity)
     local success = false
     if DoesEntityExist(entity) then
         DeleteEntity(entity)
@@ -167,45 +224,44 @@ Utility.RemovePed = function(entity)
     return success
 end
 
----This will use a native text input menu to allow the user to enter text. It will return the entered text or false if cancelled.
+---Show a native input menu and return the result
 ---@param text string
 ---@param length number
----@return string
-Utility.NativeInputMenu = function(text, length)
-    local maxLength = Math.Clamp(length, 1, 50)
-    local menutText = text or 'enter text'
-    AddTextEntry(menutText, menutText)
-    DisplayOnscreenKeyboard(1, menutText, "", "", "", "", "", maxLength)
-    while(UpdateOnscreenKeyboard() == 0) do
+---@return string|boolean
+function Utility.NativeInputMenu(text, length)
+    local maxLength = Math and Math.Clamp and Math.Clamp(length, 1, 50) or math.min(math.max(length or 10, 1), 50)
+    local menuText = text or 'enter text'
+    safeAddTextEntry(menuText)
+    DisplayOnscreenKeyboard(1, menuText, "", "", "", "", "", maxLength)
+    while (UpdateOnscreenKeyboard() == 0) do
         DisableAllControlActions(0)
         Wait(0)
     end
-    if(GetOnscreenKeyboardResult()) then
-        local result = GetOnscreenKeyboardResult()
-        return result
+    if (GetOnscreenKeyboardResult()) then
+        return GetOnscreenKeyboardResult()
     end
     return false
 end
 
----This will get the current skin data of the entity passed. It will return a table with the clothing and props data.
+---Get the skin data of a ped
 ---@param entity number
 ---@return table
-Utility.GetEntitySkinData = function(entity)
-    local skinData = {}
+function Utility.GetEntitySkinData(entity)
+    local skinData = { clothing = {}, props = {} }
     for i = 0, 11 do
-        skinData.clothing[i] = {GetPedDrawableVariation(entity, i), GetPedTextureVariation(entity, i)}
+        skinData.clothing[i] = { GetPedDrawableVariation(entity, i), GetPedTextureVariation(entity, i) }
     end
     for i = 0, 13 do
-        skinData.props[i] = {GetPedPropIndex(entity, i), GetPedPropTextureIndex(entity, i)}
+        skinData.props[i] = { GetPedPropIndex(entity, i), GetPedPropTextureIndex(entity, i) }
     end
     return skinData
 end
 
----This will set the skin data of the entity passed. It will set the clothing and props data from the skinData table.
+---Apply skin data to a ped
 ---@param entity number
 ---@param skinData table
 ---@return boolean
-Utility.SetEntitySkinData = function(entity, skinData)
+function Utility.SetEntitySkinData(entity, skinData)
     for i = 0, 11 do
         SetPedComponentVariation(entity, i, skinData.clothing[i][1], skinData.clothing[i][2], 0)
     end
@@ -215,9 +271,9 @@ Utility.SetEntitySkinData = function(entity, skinData)
     return true
 end
 
----This will reload the skin data of the entity passed. It will set the clothing and props data from the skinData table and delete any attached objects.
+---Reload the player's skin and remove attached objects
 ---@return boolean
-Utility.ReloadSkin = function()
+function Utility.ReloadSkin()
     local skinData = Utility.GetEntitySkinData(cache.ped)
     Utility.SetEntitySkinData(cache.ped, skinData)
     for _, props in pairs(GetGamePool("CObject")) do
@@ -230,20 +286,20 @@ Utility.ReloadSkin = function()
     return true
 end
 
----This will display a native help text on the screen. It will add a text entry and display it for the specified duration.
+---Show a native help text
 ---@param text string
 ---@param duration number
-Utility.HelpText = function(text, duration)
-    AddTextEntry(text, text)
+function Utility.HelpText(text, duration)
+    safeAddTextEntry(text)
     BeginTextCommandDisplayHelp(text)
     EndTextCommandDisplayHelp(0, false, true, duration or 5000)
 end
 
----This will display 3D help text at the specified coordinates.
----@param coords table
+---Draw 3D help text in the world
+---@param coords vector3
 ---@param text string
 ---@param scale number
-Utility.Draw3DHelpText = function(coords, text, scale)
+function Utility.Draw3DHelpText(coords, text, scale)
     local onScreen, x, y = GetScreenCoordFromWorldCoord(coords.x, coords.y, coords.z)
     if onScreen then
         SetTextScale(scale or 0.35, scale or 0.35)
@@ -259,19 +315,19 @@ Utility.Draw3DHelpText = function(coords, text, scale)
     end
 end
 
----This will display a native help text on the screen. It will add a text entry and display it for the specified duration.
+---Show a native notification
 ---@param text string
-Utility.NotifyText = function(text)
-    AddTextEntry(text, text)
+function Utility.NotifyText(text)
+    safeAddTextEntry(text)
     SetNotificationTextEntry(text)
     DrawNotification(false, true)
 end
 
----This will teleport a player to the specified coordinates. If a condition function is passed it will verify that condition is met and then it will fade the screen out and in, freeze the player during the teleport to allow for collisions to load, and call the afterTeleportFunction if provided.
----@param coords table
----@param conditionFunction function | optional
----@param afterTeleportFunction function | optional
-Utility.TeleportPlayer = function(coords, conditionFunction, afterTeleportFunction)
+---Teleport the player to given coordinates
+---@param coords vector3
+---@param conditionFunction function|nil
+---@param afterTeleportFunction function|nil
+function Utility.TeleportPlayer(coords, conditionFunction, afterTeleportFunction)
     if conditionFunction ~= nil then
         if not conditionFunction() then
             return
@@ -297,22 +353,19 @@ Utility.TeleportPlayer = function(coords, conditionFunction, afterTeleportFuncti
     end
 end
 
----This will get a model hash from a string or number.
----@param model string | number
+---Get the hash from a model
+---@param model string|number
 ---@return number
-Utility.GetEntityHashFromModel = function(model)
-    if type(model) ~= 'number' then model = joaat(model) end -- Use GetHashKey instead of joaat for client
-    return model
+function Utility.GetEntityHashFromModel(model)
+    return getModelHash(model)
 end
 
----commentThis will get the closest player, the distance to that player from the coords and the server ID of that player.
----@param coords table
----@param distanceScope number
----@param includeMe boolean
----@return integer
----@return integer
----@return integer
-Utility.GetClosestPlayer = function(coords, distanceScope, includeMe)
+---Get the closest player to given coordinates
+---@param coords vector3|nil
+---@param distanceScope number|nil
+---@param includeMe boolean|nil
+---@return number, number, number
+function Utility.GetClosestPlayer(coords, distanceScope, includeMe)
     local players = GetActivePlayers()
     local closestPlayer = 0
     local selfPed = cache.ped
@@ -334,33 +387,20 @@ Utility.GetClosestPlayer = function(coords, distanceScope, includeMe)
     return closestPlayer, closestDistance, GetPlayerServerId(closestPlayer)
 end
 
----This function is is deprecated and will be removed in the future. Please use Pont.Register instead.
----@param pointID string
----@param pointCoords table
----@param pointDistance number
----@param _onEnter function
----@param _onExit function
----@param _nearby function
-Utility.RegisterPoint = function(pointID, pointCoords, pointDistance, _onEnter, _onExit, _nearby)
+-- Deprecated point functions (no changes)
+function Utility.RegisterPoint(pointID, pointCoords, pointDistance, _onEnter, _onExit, _nearby)
     return Point.Register(pointID, pointCoords, pointDistance, nil, _onEnter, _onExit, _nearby)
 end
 
----This function is is deprecated and will be removed in the future. Please use Point.Get instead.
----@param pointID string
-Utility.GetPointById = function(pointID)
+function Utility.GetPointById(pointID)
     return Point.Get(pointID)
 end
 
----This function is is deprecated and will be removed in the future. Please use Point.GetAll instead.
----@return table | nil
-Utility.GetActivePoints = function()
+function Utility.GetActivePoints()
     return Point.GetAll()
 end
 
----This function is is deprecated and will be removed in the future. Please use Point.Remove instead.
----@param pointID string
----@return nil
-Utility.RemovePoint = function(pointID)
+function Utility.RemovePoint(pointID)
     return Point.Remove(pointID)
 end
 
@@ -379,5 +419,4 @@ AddEventHandler('onResourceStop', function(resource)
 end)
 
 exports('Utility', Utility)
-
-return Utility
+return Utility