From 330be19737cae8c0c7c8078404ed0cf7b8d595ea Mon Sep 17 00:00:00 2001 From: manason Date: Sat, 13 May 2023 09:21:33 -0700 Subject: [PATCH] refactor(server): more annotations, minor refactor, and printing within deprecated functions --- client/events.lua | 4 ++- client/functions.lua | 3 ++ server/events.lua | 2 ++ server/exports.lua | 83 ++++++++++++++++++++++++++++++-------------- server/functions.lua | 3 ++ shared/gangs.lua | 6 ++++ shared/items.lua | 4 +-- shared/jobs.lua | 9 +++++ 8 files changed, 84 insertions(+), 30 deletions(-) diff --git a/client/events.lua b/client/events.lua index 3f1d8cf05..4bd741267 100644 --- a/client/events.lua +++ b/client/events.lua @@ -160,7 +160,7 @@ RegisterNetEvent('QBCore:NotifyV2', function(props) QBCore.Functions.NotifyV2(props) end) ----@deprecated. Use event 'QBCore:NotifyV2' instead. +---@deprecated Use event 'QBCore:NotifyV2' instead. ---@see client/functions.lua:QBCore.Functions.Notify RegisterNetEvent('QBCore:Notify', function(text, notifyType, duration) QBCore.Functions.Notify(text, notifyType, duration) @@ -171,6 +171,7 @@ end) -- Client Callback ---@deprecated call a function instead RegisterNetEvent('QBCore:Client:TriggerClientCallback', function(name, ...) + print(string.format("%s invoked deprecated event QBCore:Client:TriggerClientCallback. Call a function instead", GetInvokingResource())) QBCore.Functions.TriggerClientCallback(name, function(...) TriggerServerEvent('QBCore:Server:TriggerClientCallback', name, ...) end, ...) @@ -179,6 +180,7 @@ end) -- Server Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead RegisterNetEvent('QBCore:Client:TriggerCallback', function(name, ...) + print(string.format("%s invoked deprecated event QBCore:Client:TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource())) if QBCore.ServerCallbacks[name] then QBCore.ServerCallbacks[name](...) QBCore.ServerCallbacks[name] = nil diff --git a/client/functions.lua b/client/functions.lua index f25a3a872..974803cce 100644 --- a/client/functions.lua +++ b/client/functions.lua @@ -140,11 +140,13 @@ end -- Client Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead function QBCore.Functions.CreateClientCallback(name, cb) + print(string.format("%s invoked deprecated function CreateClientCallback. Use ox_lib callback functions instead.", GetInvokingResource())) QBCore.ClientCallbacks[name] = cb end ---@deprecated call a function instead function QBCore.Functions.TriggerClientCallback(name, cb, ...) + print(string.format("%s invoked deprecated function TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource())) if not QBCore.ClientCallbacks[name] then return end QBCore.ClientCallbacks[name](cb, ...) end @@ -152,6 +154,7 @@ end -- Server Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Client/ instead function QBCore.Functions.TriggerCallback(name, cb, ...) + print(string.format("%s invoked deprecated function TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource())) QBCore.ServerCallbacks[name] = cb TriggerServerEvent('QBCore:Server:TriggerCallback', name, ...) end diff --git a/server/events.lua b/server/events.lua index 85a043449..34e14edd2 100644 --- a/server/events.lua +++ b/server/events.lua @@ -160,6 +160,7 @@ end) -- Client Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead RegisterNetEvent('QBCore:Server:TriggerClientCallback', function(name, ...) + print(string.format("%s invoked deprecated event QBCore:Server:TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource())) if QBCore.ClientCallbacks[name] then QBCore.ClientCallbacks[name](...) QBCore.ClientCallbacks[name] = nil @@ -169,6 +170,7 @@ end) -- Server Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead RegisterNetEvent('QBCore:Server:TriggerCallback', function(name, ...) + print(string.format("%s invoked deprecated event QBCore:Server:TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource())) local src = source QBCore.Functions.TriggerCallback(name, src, function(...) TriggerClientEvent('QBCore:Client:TriggerCallback', src, name, ...) diff --git a/server/exports.lua b/server/exports.lua index 6421a2a26..221b519ce 100644 --- a/server/exports.lua +++ b/server/exports.lua @@ -1,4 +1,8 @@ -- Add or change (a) method(s) in the QBCore.Functions table +---@param methodName string +---@param handler function +---@return boolean success +---@return string message local function SetMethod(methodName, handler) if type(methodName) ~= "string" then return false, "invalid_method_name" @@ -15,6 +19,10 @@ QBCore.Functions.SetMethod = SetMethod exports("SetMethod", SetMethod) -- Add or change (a) field(s) in the QBCore table +---@param fieldName string +---@param data any +---@return boolean success +---@return string message local function SetField(fieldName, data) if type(fieldName) ~= "string" then return false, "invalid_field_name" @@ -31,6 +39,10 @@ QBCore.Functions.SetField = SetField exports("SetField", SetField) -- Single add job function which should only be used if you planning on adding a single job +---@param jobName string +---@param job Job +---@return boolean success +---@return string message local function AddJob(jobName, job) if type(jobName) ~= "string" then return false, "invalid_job_name" @@ -51,39 +63,36 @@ QBCore.Functions.AddJob = AddJob exports('AddJob', AddJob) -- Multiple Add Jobs +---@param jobs table +---@return boolean success +---@return string message +---@return Job? errorJob job causing the error message. Only present if success is false. local function AddJobs(jobs) - local shouldContinue = true - local message = "success" - local errorItem = nil for key, value in pairs(jobs) do if type(key) ~= "string" then - message = 'invalid_job_name' - shouldContinue = false - errorItem = jobs[key] - break + return false, 'invalid_job_name', jobs[key] end if QBCore.Shared.Jobs[key] then - message = 'job_exists' - shouldContinue = false - errorItem = jobs[key] - break + return false, 'job_exists', jobs[key] end QBCore.Shared.Jobs[key] = value end - if not shouldContinue then return false, message, errorItem end TriggerClientEvent('QBCore:Client:OnSharedUpdateMultiple', -1, 'Jobs', jobs) TriggerEvent('QBCore:Server:UpdateObject') - return true, message, nil + return true, 'success' end QBCore.Functions.AddJobs = AddJobs exports('AddJobs', AddJobs) -- Single Remove Job +---@param jobName string +---@return boolean success +---@return string message local function RemoveJob(jobName) if type(jobName) ~= "string" then return false, "invalid_job_name" @@ -104,6 +113,10 @@ QBCore.Functions.RemoveJob = RemoveJob exports('RemoveJob', RemoveJob) -- Single Update Job +---@param jobName string +---@param job Job +---@return boolean success +---@return string message local function UpdateJob(jobName, job) if type(jobName) ~= "string" then return false, "invalid_job_name" @@ -124,7 +137,9 @@ QBCore.Functions.UpdateJob = UpdateJob exports('UpdateJob', UpdateJob) -- Single add item +---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead. local function AddItem(itemName, item) + print(string.format("%s invoked deprecated function AddItem. This is incompatible with ox_inventory", GetInvokingResource())) if type(itemName) ~= "string" then return false, "invalid_item_name" end @@ -144,7 +159,9 @@ QBCore.Functions.AddItem = AddItem exports('AddItem', AddItem) -- Single update item +---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead. local function UpdateItem(itemName, item) + print(string.format("%s invoked deprecated function UpdateItem. This is incompatible with ox_inventory", GetInvokingResource())) if type(itemName) ~= "string" then return false, "invalid_item_name" end @@ -161,7 +178,9 @@ QBCore.Functions.UpdateItem = UpdateItem exports('UpdateItem', UpdateItem) -- Multiple Add Items +---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead. local function AddItems(items) + print(string.format("%s invoked deprecated function AddItems. This is incompatible with ox_inventory", GetInvokingResource())) local shouldContinue = true local message = "success" local errorItem = nil @@ -194,7 +213,9 @@ QBCore.Functions.AddItems = AddItems exports('AddItems', AddItems) -- Single Remove Item +---@deprecated incompatible with ox_inventory. Update ox_inventory item config instead. local function RemoveItem(itemName) + print(string.format("%s invoked deprecated function RemoveItem. This is incompatible with ox_inventory", GetInvokingResource())) if type(itemName) ~= "string" then return false, "invalid_item_name" end @@ -214,6 +235,10 @@ QBCore.Functions.RemoveItem = RemoveItem exports('RemoveItem', RemoveItem) -- Single Add Gang +---@param gangName string +---@param gang Gang +---@return boolean success +---@return string message local function AddGang(gangName, gang) if type(gangName) ~= "string" then return false, "invalid_gang_name" @@ -234,39 +259,35 @@ QBCore.Functions.AddGang = AddGang exports('AddGang', AddGang) -- Multiple Add Gangs +---@param gangs table +---@return boolean success +---@return string message +---@return Gang? errorGang present if success is false. Gang that caused the error message. local function AddGangs(gangs) - local shouldContinue = true - local message = "success" - local errorItem = nil - for key, value in pairs(gangs) do if type(key) ~= "string" then - message = "invalid_gang_name" - shouldContinue = false - errorItem = gangs[key] - break + return false, 'invalid_gang_name', gangs[key] end if QBCore.Shared.Gangs[key] then - message = "gang_exists" - shouldContinue = false - errorItem = gangs[key] - break + return false, 'gang_exists', gangs[key] end QBCore.Shared.Gangs[key] = value end - if not shouldContinue then return false, message, errorItem end TriggerClientEvent('QBCore:Client:OnSharedUpdateMultiple', -1, 'Gangs', gangs) TriggerEvent('QBCore:Server:UpdateObject') - return true, message, nil + return true, 'success' end QBCore.Functions.AddGangs = AddGangs exports('AddGangs', AddGangs) -- Single Remove Gang +---@param gangName string +---@return boolean success +---@return string message local function RemoveGang(gangName) if type(gangName) ~= "string" then return false, "invalid_gang_name" @@ -287,6 +308,10 @@ QBCore.Functions.RemoveGang = RemoveGang exports('RemoveGang', RemoveGang) -- Single Update Gang +---@param gangName string +---@param gang Gang +---@return boolean success +---@return string message local function UpdateGang(gangName, gang) if type(gangName) ~= "string" then return false, "invalid_gang_name" @@ -306,6 +331,8 @@ end QBCore.Functions.UpdateGang = UpdateGang exports('UpdateGang', UpdateGang) +---@param InvokingResource string +---@return string version local function GetCoreVersion(InvokingResource) ---@diagnostic disable-next-line: missing-parameter local resourceVersion = GetResourceMetadata(GetCurrentResourceName(), 'version') @@ -318,6 +345,8 @@ end QBCore.Functions.GetCoreVersion = GetCoreVersion exports('GetCoreVersion', GetCoreVersion) +---@param playerId integer server id +---@param origin string reason local function ExploitBan(playerId, origin) local name = GetPlayerName(playerId) CreateThread(function() diff --git a/server/functions.lua b/server/functions.lua index 71f57d6ec..0aa9170da 100644 --- a/server/functions.lua +++ b/server/functions.lua @@ -253,6 +253,7 @@ end -- Client Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead function QBCore.Functions.TriggerClientCallback(name, source, cb, ...) + print(string.format("%s invoked deprecated function TriggerClientCallback. Use ox_lib callback functions instead.", GetInvokingResource())) QBCore.ClientCallbacks[name] = cb TriggerClientEvent('QBCore:Client:TriggerClientCallback', source, name, ...) end @@ -260,11 +261,13 @@ end -- Server Callback ---@deprecated use https://overextended.github.io/docs/ox_lib/Callback/Lua/Server instead function QBCore.Functions.CreateCallback(name, cb) + print(string.format("%s invoked deprecated function CreateCallback. Use ox_lib callback functions instead.", GetInvokingResource())) QBCore.ServerCallbacks[name] = cb end ---@deprecated call a function instead function QBCore.Functions.TriggerCallback(name, source, cb, ...) + print(string.format("%s invoked deprecated function TriggerCallback. Use ox_lib callback functions instead.", GetInvokingResource())) if not QBCore.ServerCallbacks[name] then return end QBCore.ServerCallbacks[name](source, cb, ...) end diff --git a/shared/gangs.lua b/shared/gangs.lua index 608104d25..b63a211b7 100644 --- a/shared/gangs.lua +++ b/shared/gangs.lua @@ -1,4 +1,10 @@ QBShared = QBShared or {} + +---@class Gang +---@field label string +---@field grades table + +---@type table QBShared.Gangs = { ['none'] = { label = 'No Gang', diff --git a/shared/items.lua b/shared/items.lua index ad945ac55..e082f8c5d 100644 --- a/shared/items.lua +++ b/shared/items.lua @@ -83,7 +83,7 @@ QBShared.Items = { ['weapon_militaryrifle'] = {['name'] = 'weapon_militaryrifle', ['label'] = 'Military Rifle', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_RIFLE', ['image'] = 'weapon_militaryrifle.png', ['unique'] = true, ['useable'] = true, ['description'] = 'Weapon Militaryrifle'}, ['weapon_tacticalrifle'] = {['name'] = 'weapon_tacticalrifle', ['label'] = 'Service Carbine', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_RIFLE', ['image'] = 'weapon_carbinerifle.png', ['unique'] = true, ['useable'] = true, ['description'] = 'Weapon Tactical Rifle'}, - + -- Light Machine Guns ['weapon_mg'] = {['name'] = 'weapon_mg', ['label'] = 'Machinegun', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_MG', ['image'] = 'weapon_mg.png', ['unique'] = true, ['useable'] = false, ['description'] = 'An automatic gun that fires bullets in rapid succession for as long as the trigger is pressed'}, ['weapon_combatmg'] = {['name'] = 'weapon_combatmg', ['label'] = 'Combat MG', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_MG', ['image'] = 'weapon_combatmg.png', ['unique'] = true, ['useable'] = false, ['description'] = 'A combat version of an automatic gun that fires bullets in rapid succession for as long as the trigger is pressed'}, @@ -98,7 +98,7 @@ QBShared.Items = { ['weapon_heavysniper_mk2'] = {['name'] = 'weapon_heavysniper_mk2', ['label'] = 'Heavy Sniper Mk II', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_SNIPER', ['image'] = 'weapon_heavysniper_mk2.png', ['unique'] = true, ['useable'] = true, ['description'] = 'Weapon Heavysniper MK2'}, ['weapon_marksmanrifle_mk2'] = {['name'] = 'weapon_marksmanrifle_mk2', ['label'] = 'Marksman Rifle Mk II', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_SNIPER', ['image'] = 'weapon_marksmanrifle_mk2.png', ['unique'] = true, ['useable'] = true, ['description'] = 'Weapon Marksmanrifle MK2'}, ['weapon_precisionrifle'] = {['name'] = 'weapon_precisionrifle', ['label'] = 'Precision Rifle', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_SNIPER', ['image'] = 'weapon_marksmanrifle_mk2.png', ['unique'] = true, ['useable'] = true, ['description'] = 'Weapon Precision Rifle'}, - + -- Heavy Weapons ['weapon_rpg'] = {['name'] = 'weapon_rpg', ['label'] = 'RPG', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_RPG', ['image'] = 'weapon_rpg.png', ['unique'] = true, ['useable'] = false, ['description'] = 'A rocket-propelled grenade launcher'}, ['weapon_grenadelauncher'] = {['name'] = 'weapon_grenadelauncher', ['label'] = 'Grenade Launcher', ['weight'] = 1000, ['type'] = 'weapon', ['ammotype'] = 'AMMO_GRENADELAUNCHER', ['image'] = 'weapon_grenadelauncher.png', ['unique'] = true, ['useable'] = false, ['description'] = 'A weapon that fires a specially-designed large-caliber projectile, often with an explosive, smoke or gas warhead'}, diff --git a/shared/jobs.lua b/shared/jobs.lua index e584e54e6..43685ae3d 100644 --- a/shared/jobs.lua +++ b/shared/jobs.lua @@ -1,5 +1,14 @@ QBShared = QBShared or {} QBShared.ForceJobDefaultDutyAtLogin = true -- true: Force duty state to jobdefaultDuty | false: set duty state from database last saved + +---@class Job +---@field label string +---@field type? string +---@field defaultDuty boolean +---@field offDutyPay boolean +---@field grades table + +---@type table QBShared.Jobs = { ['unemployed'] = { label = 'Civilian',