From 8c309e248ea446b1e707803193d4f427dc9cc3a1 Mon Sep 17 00:00:00 2001 From: "Mr.Crowley" Date: Sat, 23 Aug 2025 22:53:49 -0500 Subject: [PATCH] Added behaviors and documentation to oxlibs zones Will provide file in example when more features are implimented --- examples/behaviorTemplate.lua | 20 +++ fxmanifest.lua | 5 +- lib/entities/client/behaviors.lua | 61 ++++++++ lib/entities/client/behaviors/init.lua | 20 +++ lib/entities/client/behaviors/particles.lua | 56 +++++++ lib/entities/client/behaviors/targets.lua | 54 +++++++ lib/entities/client/client_entity.lua | 162 +++++++++++++------- lib/particles/client/particles.lua | 116 ++++++-------- lib/points/client/points.lua | 9 +- modules/target/qb-target/client.lua | 10 +- modules/zones/oxlib/client.lua | 39 +++++ 11 files changed, 418 insertions(+), 134 deletions(-) create mode 100644 examples/behaviorTemplate.lua create mode 100644 lib/entities/client/behaviors.lua create mode 100644 lib/entities/client/behaviors/init.lua create mode 100644 lib/entities/client/behaviors/particles.lua create mode 100644 lib/entities/client/behaviors/targets.lua diff --git a/examples/behaviorTemplate.lua b/examples/behaviorTemplate.lua new file mode 100644 index 0000000..383eb5f --- /dev/null +++ b/examples/behaviorTemplate.lua @@ -0,0 +1,20 @@ +-- -- Make sure to include filename in the init (prefix of the .lua)Utility = Utility or Require("lib/utility/client/utility.lua") +-- local ParticlesBehaviors = { +-- tag = "isTemplate", +-- default = { +-- } + +-- } + +-- function ParticlesBehaviors.OnSpawn(entityData) +-- end + + +-- function ParticlesBehaviors.OnRemove(entityData) +-- end + +-- function ParticlesBehaviors.OnUpdate(entityData) + +-- end + +-- return ParticlesBehaviors diff --git a/fxmanifest.lua b/fxmanifest.lua index 361d07c..5e430ad 100644 --- a/fxmanifest.lua +++ b/fxmanifest.lua @@ -73,9 +73,8 @@ files { 'web/dist/assets/*.css', 'web/dist/assets/*.js', 'locales/*.json', - 'lib/**/client/*.lua', - 'lib/**/shared/*.lua', - 'lib/**/server/*.lua', + 'lib/**/**/*.lua', + 'lib/**/**/**/*.lua', 'modules/**', 'settings/*.lua', 'lib/init.lua', diff --git a/lib/entities/client/behaviors.lua b/lib/entities/client/behaviors.lua new file mode 100644 index 0000000..8641d03 --- /dev/null +++ b/lib/entities/client/behaviors.lua @@ -0,0 +1,61 @@ +Behaviors = { + All = {}, + isSetup = false, +} + +function Behaviors.Setup() + if Behaviors.isSetup then return end + Behaviors.isSetup = true + local behaviors = Require("lib/entities/client/behaviors/init.lua") + for _, behavior in ipairs(behaviors) do + Behaviors.Create(behavior.tag, behavior) + end +end + +function Behaviors.Create(behaviorId, behavior) + if not behaviorId or not behavior then return end + if Behaviors.All[behaviorId] then + print(string.format("[ClientEntity] Behavior %s already exists", behaviorId)) + return + end + Behaviors.All[behaviorId] = behavior +end + +function Behaviors.Get(behaviorId) + return Behaviors.All[behaviorId] +end + +function Behaviors.Remove(behaviorId) + if not Behaviors.All[behaviorId] then return end + Behaviors.All[behaviorId] = nil + return true +end + +function Behaviors.Trigger(actionName, clientEntityData, ...) + if not clientEntityData or not actionName then return end + for tag, behavior in pairs(Behaviors.All) do + local hasBehaviorArgs = Behaviors.Has(tag, clientEntityData) -- this is everything that's contained inside the object's individual tag + if hasBehaviorArgs and behavior[actionName] then + behavior[actionName](clientEntityData, hasBehaviorArgs, ...) + end + end +end + +function Behaviors.Inherit(behaviorId, clientEntityData, defaultData) + if not Behaviors.All[behaviorId] then + print(string.format("[ClientEntity] Behavior %s does not exist", behaviorId)) + return false + end + if not clientEntityData or not clientEntityData.id then + print("[ClientEntity] Invalid client entity data provided for inheritance") + return false + end + clientEntityData[behaviorId] = defaultData or {} -- Mark the entity as having this behavior + return true +end + +function Behaviors.Has(behaviorId, clientEntityData) + return clientEntityData and clientEntityData[behaviorId] +end + +return Behaviors \ No newline at end of file diff --git a/lib/entities/client/behaviors/init.lua b/lib/entities/client/behaviors/init.lua new file mode 100644 index 0000000..8c70fff --- /dev/null +++ b/lib/entities/client/behaviors/init.lua @@ -0,0 +1,20 @@ +local fileList = { + "particles", + "targets", +} + +local path = "lib/entities/client/behaviors/" + +local function loadAllResources() + local modules = {} + for _, fileName in ipairs(fileList) do + local filePath = path .. fileName .. ".lua" + local required = Require(filePath) + if required then + table.insert(modules, required) + end + end + return modules +end + +return loadAllResources() \ No newline at end of file diff --git a/lib/entities/client/behaviors/particles.lua b/lib/entities/client/behaviors/particles.lua new file mode 100644 index 0000000..418569b --- /dev/null +++ b/lib/entities/client/behaviors/particles.lua @@ -0,0 +1,56 @@ +Utility = Utility or Require("lib/utility/client/utility.lua") +local ParticlesBehaviors = { + tag = "particles", + default = { + dict = "cut_exile3", + ptfx = "cs_ex3_wheel_spin", + offset = vector3(0, 0, 0), + rotation = vector3(0, 0, 0), + size = 1.0, + color = vector3(255, 255, 255), + loopLength = 5000, + } + +} + +function ParticlesBehaviors.OnSpawn(entityData) + if not entityData.particles then return end + if entityData.particles.dict then -- single particle + entityData.particles = {entityData.particles} + end + + for _, particleData in ipairs(entityData.particles) do + local position = vector3(entityData.coords.x, entityData.coords.y, entityData.coords.z) + local rotation = vector3(entityData.rotation.x, entityData.rotation.y, entityData.rotation.z) + position = position + (particleData.offset?.xyz or vector3(0, 0, 0)) + rotation = rotation + (particleData.rotation?.xyz or vector3(0, 0, 0)) + particleData.playing = Particle.Play( + particleData.dict or ParticlesBehaviors.default.dict, + particleData.ptfx or ParticlesBehaviors.default.ptfx, + position, + rotation, + particleData.size or ParticlesBehaviors.default.size, + particleData.color or ParticlesBehaviors.default.color, + particleData.looped, + particleData.loopLength or ParticlesBehaviors.default.loopLength + ) + end +end + + +function ParticlesBehaviors.OnRemove(entityData) + if not entityData.particles then return end + for _, particleData in ipairs(entityData.particles) do + if particleData.playing then + Particle.Stop(particleData.playing) + particleData.playing = nil + end + end +end + +-- function ParticlesBehaviors.OnUpdate(entityData) +-- if not entityData.particles then return end + +-- end + +return ParticlesBehaviors diff --git a/lib/entities/client/behaviors/targets.lua b/lib/entities/client/behaviors/targets.lua new file mode 100644 index 0000000..81135c2 --- /dev/null +++ b/lib/entities/client/behaviors/targets.lua @@ -0,0 +1,54 @@ + +local Targets = { + tag = "targets", + default = { + label = "Default Target Label", + distance = 2, + } +} + + +function Targets.OnSpawn(entityData) + if not entityData.spawned or not entityData.target then return end + if entityData.targets?.label then + entityData.newTargets = {entityData.targets} + else + entityData.newTargets = entityData.targets or {} + end + for k, v in pairs(entityData.newTargets) do + local onSelect = v.onSelect + if onSelect then + v.onSelect = function(entity) + onSelect(entityData, entity) + end + end + end + Target.AddLocalEntity(entityData.spawned, entityData.newTargets) + entityData.oldTargets = entityData.newTargets +end + +function Targets.OnRemove(entityData) + if not entityData.spawned or not entityData.newTargets then return end + Target.RemoveLocalEntity(entityData.spawned) +end + +function Targets.OnUpdate(entityData) + if not entityData.spawned or not entityData.newTargets then return end + for i, target in ipairs(entityData.oldTargets) do + local newTarget = entityData.targets.label + if newTarget then + entityData.newTargets = {entityData.targets} + end + newTarget = entityData.newTargets[i] + if newTarget + and target.label ~= newTarget.label + or target.distance ~= newTarget.distance + or target.description ~= newTarget.description + then + Targets.OnRemove(entityData) + Targets.OnSpawn(entityData) + end + end +end + +return Targets \ No newline at end of file diff --git a/lib/entities/client/client_entity.lua b/lib/entities/client/client_entity.lua index 85a3fab..7892405 100644 --- a/lib/entities/client/client_entity.lua +++ b/lib/entities/client/client_entity.lua @@ -1,12 +1,17 @@ Utility = Utility or Require("lib/utility/client/utility.lua") Ids = Ids or Require("lib/utility/shared/ids.lua") Point = Point or Require("lib/points/client/points.lua") - +Behaviors = Behaviors or Require("lib/entities/client/behaviors.lua") local Entities = {} -- Stores entity data received from server ClientEntity = {} -- Renamed from BaseEntity +ClientEntity.Behaviors = Behaviors + + + + +-------------------- local function SpawnEntity(entityData) - entityData = entityData and entityData.args if entityData.spawned and DoesEntityExist(entityData.spawned) then return end -- Already spawned local loaded, model = Utility.LoadModel(entityData.model) if not loaded then @@ -39,13 +44,15 @@ local function SpawnEntity(entityData) if entityData.OnSpawn then pcall(function (...) return entityData.OnSpawn(entityData) - end) + end) end + Behaviors.Trigger("OnSpawn", entityData) end local function RemoveEntity(entityData) entityData = entityData and entityData.args or entityData if not entityData then return end + Behaviors.Trigger("OnRemove", entityData) if entityData.OnRemove then pcall(function (...) return entityData.OnRemove(entityData) @@ -59,13 +66,48 @@ local function RemoveEntity(entityData) end end +local function UpdateEntity(_entityData) + local entityData = ClientEntity.Get(_entityData.id) + if not entityData then return end + if entityData.oldCoords and entityData.oldCoords ~= entityData.coords then + local dist = #(entityData.coords.xyz - entityData.oldCoords.xyz) + if dist > 0.1 then + ClientEntity.UpdateCoords(entityData.id, entityData.coords) + end + entityData.oldCoords = entityData.coords + end + + if not entityData.oldRotation or entityData.oldRotation ~= entityData.rotation then + if entityData.spawned and DoesEntityExist(entityData.spawned) then + if entityData.entityType == 'object' then + SetEntityRotation(entityData.spawned, entityData.rotation.x, entityData.rotation.y, entityData.rotation.z, 2, true) + else -- Ped/Vehicle heading + SetEntityHeading(entityData.spawned, type(entityData.rotation) == 'number' and entityData.rotation or entityData.rotation.z) + end + end + entityData.oldRotation = entityData.rotation + end + if entityData.OnUpdate then + pcall(function (...) + return entityData.OnUpdate(entityData) + end) + end + Behaviors.Trigger("OnUpdate", entityData) +end + --- Registers an entity received from the server and sets up proximity spawning. -- @param entityData table Data received from the server via 'community_bridge:client:CreateEntity' function ClientEntity.Create(entityData) entityData.id = entityData.id or Ids.CreateUniqueId(Entities) - if Entities[entityData.id] then return Entities[entityData.id] end -- Already registered - Entities[entityData.id] = entityData - return Point.Register(entityData.id, entityData.coords, entityData.spawnDistance or 50.0, entityData, SpawnEntity, RemoveEntity, function() end) + if Entities[entityData.id] then return Entities[entityData.id] end + entityData.rotation = entityData.rotation or vector3(0.0, 0.0, entityData.heading or 0.0) + entityData.oldCoords = entityData.oldCoords or vector3(0.0, 0.0, 0.0) + entityData.oldRotation = entityData.rotation + + local entityPoint = Point.Register(entityData.id, entityData.coords, entityData.spawnDistance or 50.0, entityData, SpawnEntity, RemoveEntity, UpdateEntity) + Entities[entityData.id] = entityPoint + Behaviors.Trigger("OnCreate", entityPoint) + return entityPoint end --Depricated use ClientEntity.Create instead @@ -97,61 +139,68 @@ function ClientEntity.Destroy(id) end ClientEntity.Unregister = ClientEntity.Destroy + + +function ClientEntity.Set(id, key, value) + local entityData = ClientEntity.Get(id) + if not entityData then return print(string.format("[ClientEntity] SetKey: Entity %s does not exist", id)) end + entityData[key] = value +end + --- Updates the data for a registered entity. -- @param id string|number The ID of the entity to update. -- @param data table The data fields to update. -function ClientEntity.Update(id, data) - local entityData = Entities[id] - -- print(string.format("[ClientEntity] Updating entity %s", id)) - if not entityData then return end +-- function ClientEntity.Update(id, data) +-- local entityData = ClientEntity.Get(id) +-- if not entityData then return end - local needsPointUpdate = false - for key, value in pairs(data) do - if key == 'coords' and #(entityData.coords - value) > 0.1 then - needsPointUpdate = true - end - if key == 'spawnDistance' and entityData.spawnDistance ~= value then - needsPointUpdate = true - end - entityData[key] = value - end +-- local needsPointUpdate = false +-- for key, value in pairs(data) do +-- if key == 'coords' and #(entityData.coords - value) > 0.1 then +-- needsPointUpdate = true +-- end +-- if key == 'spawnDistance' and entityData.spawnDistance ~= value then +-- needsPointUpdate = true +-- end +-- entityData[key] = value +-- end - -- If entity is currently spawned, apply updates - if entityData.spawned and DoesEntityExist(entityData.spawned) then - if data.coords then - SetEntityCoords(entityData.spawned, entityData.coords.x, entityData.coords.y, entityData.coords.z, false, false, false, true) - end - if data.rotation then - if entityData.entityType == 'object' then - SetEntityRotation(entityData.spawned, entityData.rotation.x, entityData.rotation.y, entityData.rotation.z, 2, true) - else -- Ped/Vehicle heading - SetEntityHeading(entityData.spawned, type(entityData.rotation) == 'number' and entityData.rotation or entityData.rotation.z) - end - end - if data.freeze ~= nil then - FreezeEntityPosition(entityData.spawned, data.freeze) - end - -- Add other updatable properties as needed - end +-- -- If entity is currently spawned, apply updates +-- if entityData.spawned and DoesEntityExist(entityData.spawned) then +-- if data.coords then +-- SetEntityCoords(entityData.spawned, entityData.coords.x, entityData.coords.y, entityData.coords.z, false, false, false, true) +-- end +-- if data.rotation then +-- if entityData.entityType == 'object' then +-- SetEntityRotation(entityData.spawned, entityData.rotation.x, entityData.rotation.y, entityData.rotation.z, 2, true) +-- else -- Ped/Vehicle heading +-- SetEntityHeading(entityData.spawned, type(entityData.rotation) == 'number' and entityData.rotation or entityData.rotation.z) +-- end +-- end +-- if data.freeze ~= nil then +-- FreezeEntityPosition(entityData.spawned, data.freeze) +-- end +-- -- Add other updatable properties as needed +-- end - -- Update Point registration if coords or distance changed - if needsPointUpdate then - Point.Remove(id) - Point.Register( - entityData.id, - entityData.coords, - entityData.spawnDistance or 50.0, - SpawnEntity, - RemoveEntity, - nil, - entityData - ) - end +-- -- Update Point registration if coords or distance changed +-- if needsPointUpdate then +-- Point.Remove(id) +-- Point.Register( +-- entityData.id, +-- entityData.coords, +-- entityData.spawnDistance or 50.0, +-- entityData, +-- SpawnEntity, +-- RemoveEntity, +-- OnUpdateEntity +-- ) +-- end - if entityData.OnUpdate and type(entityData.OnUpdate) == 'function' then - entityData.OnUpdate(entityData, data) - end -end +-- if entityData.OnUpdate and type(entityData.OnUpdate) == 'function' then +-- entityData.OnUpdate(entityData, data) +-- end +-- end function ClientEntity.Get(id) return Entities[id] @@ -228,6 +277,11 @@ RegisterNetEvent("community_bridge:client:UpdateEntity", function(id, data) ClientEntity.Update(id, data) end) +AddEventHandler('onResourceStart', function(resourceName) + if resourceName ~= GetCurrentResourceName() then return end + Behaviors.Setup() +end) + -- Resource Stop Cleanup AddEventHandler('onResourceStop', function(resourceName) if resourceName == GetCurrentResourceName() then diff --git a/lib/particles/client/particles.lua b/lib/particles/client/particles.lua index d425163..a5be4dc 100644 --- a/lib/particles/client/particles.lua +++ b/lib/particles/client/particles.lua @@ -1,7 +1,7 @@ Particles = {} Particle = {} ---@diagnostic disable: duplicate-set-field -local Ids = Ids or Require("lib/utility/shared/ids.lua") +Ids = Ids or Require("lib/utility/shared/ids.lua") local point = Require("lib/points/client/points.lua") ---Loads a ptfx asset into memory. @@ -28,21 +28,58 @@ end --- @param looped boolean --- @param loopLength number|nil --- @return number|nil ptfxHandle -- The handle of the particle effect, or nil if it failed to create. -function Particle.Play(dict, ptfx, pos, rot, scale, color, looped, loopLength) +function Particle.Play(dict, ptfx, pos, rot, scale, color, looped, removeAfter) LoadPtfxAsset(dict) UseParticleFxAssetNextCall(dict) SetParticleFxNonLoopedColour(color.x, color.y, color.z) local particle = nil + removeAfter = removeAfter or 5000 if looped then particle = StartParticleFxLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) - CreateThread(function() - if loopLength then - Wait(loopLength) - Particle.Remove(particle) + local strParticle = tostring(particle) + Particles[strParticle] = particle + Wait(10) + if particle == 0 or not DoesParticleFxLoopedExist(particle) then + particle = StartParticleFxNonLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + if not particle and particle == 0 then + print(string.format("[Particle] Failed to start particle fx: %s from dict: %s", ptfx, dict)) + return nil end - end) - else - particle = StartParticleFxNonLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + local strParticle = tostring(particle) + Particles[strParticle] = particle + CreateThread(function() + while Particles[strParticle] do + Wait(removeAfter) + if not Particles[strParticle] then break end + RemoveParticleFx(particle, false) + particle = StartParticleFxNonLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + Particles[strParticle] = particle + end + end) + return strParticle + else + if not removeAfter or removeAfter <= 0 then return particle end + CreateThread(function() + while Particles[strParticle] do + Wait(removeAfter) + if not Particles[strParticle] then break end + StopParticleFxLooped(particle, false) + UseParticleFxAssetNextCall(dict) + LoadPtfxAsset(dict) + particle = StartParticleFxLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + Particles[strParticle] = particle + end + end) + return strParticle + end + else + particle = StartParticleFxLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + Wait(10) + if not DoesParticleFxLoopedExist(particle) then + particle = StartParticleFxNonLoopedAtCoord(ptfx, pos.x, pos.y, pos.z, rot.x, rot.y, rot.z, scale, false, false, false, false) + end + Wait(removeAfter) + Particle.Stop(particle) end return particle @@ -53,66 +90,7 @@ function Particle.Stop(particle) StopParticleFxLooped(particle, false) RemoveParticleFx(particle, false) RemoveNamedPtfxAsset(particle) -end - -function Particle.Create(data) - assert(data, "Particle data is nil") - assert(data.dict, "Invalid particle data. Must contain string dict.") - assert(data.ptfx, "Invalid particle data. Must contain string ptfx.") - - local _id = data.id or Ids.CreateUniqueId(Particles) - data = { - id = _id, - dict = data.dict, - ptfx = data.ptfx, - position = data.position or vector3(0.0, 0.0, 0.0), - rotation = data.rotation or vector3(0, 0, 0), - size = data.size or 1.0, - color = data.color or vector3(255, 255, 255), - looped = data.looped or false, - loopLength = data.loopLength or nil, - spawned = false, - } - Particles[_id] = data - - point.Register( -- checking if players in range - _id, - data.position, - data.drawDistance or 50.0, - data, - function(_) - if not Particles[_id] then return point.Remove(_id) end - local particleData = Particles[_id] - if particleData.spawned then return end - particleData.spawned = Particle.Play( - particleData.dict, - particleData.ptfx, - particleData.position, - particleData.rotation, - particleData.size, - particleData.color, - particleData.looped, - particleData.loopLength - ) - end, - function(markerData) - if not Particles[_id] then return end - local particleData = Particles[_id] - if not particleData.spawned then return end - Particle.Stop(particleData.spawned) - particleData.spawned = nil - end - ) - return _id -end - -function Particle.Remove(id) - if not id then return end - local particle = Particles[id] - if not particle then return end - Particle.Stop(particle.spawned) - Particles[id] = nil - point.Remove(id) + Particles[tostring(particle)] = nil end diff --git a/lib/points/client/points.lua b/lib/points/client/points.lua index cbd9319..97e7ceb 100644 --- a/lib/points/client/points.lua +++ b/lib/points/client/points.lua @@ -75,6 +75,9 @@ function Point.StartLoop() point.args = point?.onExit(point, point.args) or point.args end end + if point.inside and point.onUpdate then + point.onUpdate(point, point.args) + end end end Wait(1000) @@ -82,11 +85,11 @@ function Point.StartLoop() end) end -function Point.Register(id, target, distance, args, _onEnter, _onExit) +function Point.Register(id, target, distance, args, _onEnter, _onExit, _onUpdate) local isEntity = type(target) == "number" local coords = isEntity and GetEntityCoords(target) or target Grid.Generate() - local self = {} + local self = args or {} self.id = id self.target = target -- Store entity ID or Vector3 self.isEntity = isEntity @@ -94,8 +97,8 @@ function Point.Register(id, target, distance, args, _onEnter, _onExit) self.distance = distance self.onEnter = _onEnter or function() end self.onExit = _onExit or function() end + self.onUpdate = _onUpdate or function() end self.inside = false -- Track if player is inside - self.args = args or {} local grid = Grid.GetCellByCoords(coords) grid[id] = self Point.All[id] = self diff --git a/modules/target/qb-target/client.lua b/modules/target/qb-target/client.lua index 6fd49d2..c1a4b63 100644 --- a/modules/target/qb-target/client.lua +++ b/modules/target/qb-target/client.lua @@ -84,7 +84,7 @@ end ---This will add target options to all specified models. This is useful for when you want to add target options to all models of a specific type. ---@param options table -Target.AddGlobalPed = function(options, distance) +Target.AddGlobalPed = function(options) options = Target.FixOptions(options) qb_target:AddGlobalPed({ options = options, @@ -100,7 +100,7 @@ end ---This will add taget options to all vehicles. ---@param options table -Target.AddGlobalVehicle = function(options, distance) +Target.AddGlobalVehicle = function(options) options = Target.FixOptions(options) qb_target:AddGlobalVehicle({ options = options, @@ -136,7 +136,7 @@ end ---This will generate targets on non networked entites with the passed options. ---@param entities number | table ---@param options table -Target.AddLocalEntity = function(entities, options, distance) +Target.AddLocalEntity = function(entities, options) options = Target.FixOptions(options) qb_target:AddTargetEntity(entities, { options = options, @@ -174,7 +174,7 @@ end ---@param size table ---@param heading number ---@param options table -Target.AddBoxZone = function(name, coords, size, heading, options, debug, distance) +Target.AddBoxZone = function(name, coords, size, heading, options, debug) options = Target.FixOptions(options) if not next(options) then return end qb_target:AddBoxZone(name, coords, size.x, size.y, { @@ -195,7 +195,7 @@ end ---@param coords table ---@param radius number ---@param options table -Target.AddSphereZone = function(name, coords, radius, options, debug, distance) +Target.AddSphereZone = function(name, coords, radius, options, debug) options = Target.FixOptions(options) qb_target:AddCircleZone(name, coords, radius, { name = name, diff --git a/modules/zones/oxlib/client.lua b/modules/zones/oxlib/client.lua index 26f67ca..f181615 100644 --- a/modules/zones/oxlib/client.lua +++ b/modules/zones/oxlib/client.lua @@ -1,3 +1,25 @@ +--- ox_lib compatibility wrapper for zone creation and management. +--- Provides a small API around lib.zones (box, sphere, poly) to create/destroy +--- and lookup zones with automatic id generation and resource ownership. +--- +--- Example: +--- local id = cZones.Create("box", { coords = vec3(0,0,0), size = vec3(2,2,2), onEnter = function(z) ... end }) +--- cZones.Destroy(id) +--- +---@module cZones +---@class ZoneData +---@field id string Unique id for the zone (generated) +---@field invoking string Resource that created the zone +---@field coords vector3? Center coordinates (box/sphere) +---@field points vector2[]? Array of points for poly zones +---@field radius number? Radius for sphere zones +---@field size table? Size table or vec3 for box zones +---@field zone any Internal zone handle returned by lib.zones +---@field debug boolean? Debug flag passed to lib.zones +---@field onEnter fun(data:ZoneData)? Callback invoked on enter (receives ZoneData) +---@field onExit fun(data:ZoneData)? Callback invoked on exit (receives ZoneData) +---@alias ZoneType "box"|"sphere"|"poly" + ---@diagnostic disable: duplicate-set-field local resourceName = "ox_lib" if GetResourceState(resourceName) == 'missing' then return end @@ -6,6 +28,12 @@ Ids = Ids or Require('lib/utility/shared/ids.lua') cZones = {} --conflict with ox cZones.All = {} + +--- Create a zone of the specified type. +--- Supported types: "box", "sphere", "poly" +---@param type ZoneType +---@param data ZoneData +---@return string|nil id Returns the generated zone id on success, or nil on failure function cZones.Create(type, data) assert(type, "Requires zone type ('box', 'sphere', or 'poly')") assert(data, "Requires data table") @@ -93,6 +121,9 @@ function cZones.Create(type, data) return nil end +--- Destroy a zone by id. +---@param id string +---@return boolean success True if destroyed, false otherwise function cZones.Destroy(id) if not id then return false end local zone = cZones.All[id].zone @@ -102,6 +133,9 @@ function cZones.Destroy(id) return true end +--- Destroy all zones created by a specific resource. +---@param resource string Name of the invoking resource +---@return boolean success True if operation completed (no guarantee zones existed) function cZones.DestroyByResource(resource) if not resource then return false end for id, zone in pairs(cZones.All or {}) do @@ -112,11 +146,16 @@ function cZones.DestroyByResource(resource) return true end +--- Retrieve zone data by id. +---@param id string +---@return ZoneData|nil function cZones.Get(id) if not id then return nil end return cZones.All[id] end +--- Event handler: clean up zones when a resource stops. +--- This is registered to the "onResourceStop" event and delegates to DestroyByResource. RegisterNetEvent("onResourceStop", function(resource) cZones.DestroyByResource(resource) end)