Add grid, points, and zones modules, extend table utilities

[core]/esx_lib/imports/grid/shared.lua

@@ -0,0 +1,194 @@
+--[[
+    Based on PolyZone's grid system (https://github.com/mkafrin/PolyZone/blob/master/ComboZone.lua)
+
+    MIT License
+
+    Copyright © 2019-2021 Michael Afrin
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+]]
+
+local mapMinX = -3700
+local mapMinY = -4400
+local mapMaxX = 4500
+local mapMaxY = 8000
+local xDelta = (mapMaxX - mapMinX) / 34
+local yDelta = (mapMaxY - mapMinY) / 50
+local grid = {}
+local lastCell = {}
+local gridCache = {}
+local entrySet = {}
+
+xLib.grid = {}
+
+---@class GridEntry
+---@field coords vector
+---@field length? number
+---@field width? number
+---@field radius? number
+---@field [string] any
+
+---@param point vector
+---@param length number
+---@param width number
+---@return number, number, number, number
+local function getGridDimensions(point, length, width)
+    local minX = (point.x - width - mapMinX) // xDelta
+    local maxX = (point.x + width - mapMinX) // xDelta
+    local minY = (point.y - length - mapMinY) // yDelta
+    local maxY = (point.y + length - mapMinY) // yDelta
+
+    return minX, maxX, minY, maxY
+end
+
+---@param point vector
+---@return number, number
+function xLib.grid.getCellPosition(point)
+    local x = (point.x - mapMinX) // xDelta
+    local y = (point.y - mapMinY) // yDelta
+
+    return x, y
+end
+
+---@param point vector
+---@return GridEntry[]
+function xLib.grid.getCell(point)
+    local x, y = xLib.grid.getCellPosition(point)
+
+    if lastCell.x ~= x or lastCell.y ~= y then
+        lastCell.x = x
+        lastCell.y = y
+        lastCell.cell = grid[y] and grid[y][x] or {}
+    end
+
+    return lastCell.cell
+end
+
+---@param point vector
+---@param filter? fun(entry: GridEntry): boolean
+---@return Array<GridEntry>
+function xLib.grid.getNearbyEntries(point, filter)
+    local minX, maxX, minY, maxY = getGridDimensions(point, xDelta, yDelta)
+
+    if gridCache.filter == filter and
+        gridCache.minX == minX and
+        gridCache.maxX == maxX and
+        gridCache.minY == minY and
+        gridCache.maxY == maxY then
+        return gridCache.entries
+    end
+
+    local entries = xLib.table.array:new()
+    local n = 0
+
+    table.wipe(entrySet)
+
+    for y = minY, maxY do
+        local row = grid[y]
+
+        for x = minX, maxX do
+            local cell = row and row[x]
+
+            if cell then
+                for j = 1, #cell do
+                    local entry = cell[j]
+
+                    if not entrySet[entry] and (not filter or filter(entry)) then
+                        n = n + 1
+                        entrySet[entry] = true
+                        entries[n] = entry
+                    end
+                end
+            end
+        end
+    end
+
+    gridCache.minX = minX
+    gridCache.maxX = maxX
+    gridCache.minY = minY
+    gridCache.maxY = maxY
+    gridCache.entries = entries
+    gridCache.filter = filter
+
+    return entries
+end
+
+---@param entry { coords: vector, length?: number, width?: number, radius?: number, [string]: any }
+function xLib.grid.addEntry(entry)
+    entry.length = entry.length or entry.radius * 2
+    entry.width = entry.width or entry.radius * 2
+    local minX, maxX, minY, maxY = getGridDimensions(entry.coords, entry.length, entry.width)
+
+    for y = minY, maxY do
+        local row = grid[y] or {}
+
+        for x = minX, maxX do
+            local cell = row[x] or {}
+
+            cell[#cell + 1] = entry
+            row[x] = cell
+        end
+
+        grid[y] = row
+
+        table.wipe(gridCache)
+    end
+end
+
+---@param entry table A table that was added to the grid previously.
+function xLib.grid.removeEntry(entry)
+    local minX, maxX, minY, maxY = getGridDimensions(entry.coords, entry.length, entry.width)
+    local success = false
+
+    for y = minY, maxY do
+        local row = grid[y]
+
+        if not row then goto continue end
+
+        for x = minX, maxX do
+            local cell = row[x]
+
+            if cell then
+                for i = 1, #cell do
+                    if cell[i] == entry then
+                        table.remove(cell, i)
+                        success = true
+                        break
+                    end
+                end
+
+                if #cell == 0 then
+                    row[x] = nil
+                end
+            end
+        end
+
+        if not next(row) then
+            grid[y] = nil
+        end
+
+        ::continue::
+    end
+
+    table.wipe(gridCache)
+
+    return success
+end
+
+return xLib.grid

[core]/esx_lib/imports/points/client.lua

@@ -0,0 +1,187 @@
+--!DISCLAIMER
+--[[
+    https://github.com/overextended/ox_lib
+
+    This file is licensed under LGPL-3.0 or higher <https://www.gnu.org/licenses/lgpl-3.0.en.html>
+
+    Copyright © 2025 Linden <https://github.com/thelindat>
+]]
+
+---@class PointProperties
+---@field coords vector3
+---@field distance number
+---@field onEnter? fun(self: CPoint)
+---@field onExit? fun(self: CPoint)
+---@field nearby? fun(self: CPoint)
+---@field [string] any
+
+---@class CPoint : PointProperties
+---@field id number
+---@field currentDistance number
+---@field isClosest? boolean
+---@field remove fun()
+
+---@type table<number, CPoint>
+local points = {}
+---@type CPoint[]
+local nearbyPoints = {}
+local nearbyCount = 0
+---@type CPoint?
+local closestPoint
+local tick
+
+local function removePoint(self)
+    if closestPoint?.id == self.id then
+        closestPoint = nil
+    end
+
+    xLib.grid.removeEntry(self)
+
+    points[self.id] = nil
+end
+
+CreateThread(function()
+    while true do
+        local coords = GetEntityCoords(PlayerPedId())
+        local newPoints = xLib.grid.getNearbyEntries(coords, function(entry) return entry.remove == removePoint end) --[[@as CPoint[] ]]
+        local cellX, cellY = xLib.grid.getCellPosition(coords)
+        closestPoint = nil
+
+        for i = 1, nearbyCount do
+            local point = nearbyPoints[i]
+
+            if point.inside then
+                local distance = #(coords - point.coords)
+
+                if distance > point.radius then
+                    if point.onExit then point:onExit() end
+
+                    point.inside = nil
+                    point.currentDistance = nil
+                end
+            end
+        end
+
+        if nearbyCount ~= 0 then
+            table.wipe(nearbyPoints)
+            nearbyCount = 0
+        end
+
+        for i = 1, #newPoints do
+            local point = newPoints[i]
+            local distance = #(coords - point.coords)
+
+            if distance <= point.radius then
+                point.currentDistance = distance
+
+                if not closestPoint or distance < (closestPoint.currentDistance or point.radius) then
+                    if closestPoint then closestPoint.isClosest = nil end
+
+                    point.isClosest = true
+                    closestPoint = point
+                end
+
+                nearbyCount += 1
+                nearbyPoints[nearbyCount] = point
+
+                if point.onEnter and not point.inside then
+                    point.inside = true
+                    point:onEnter()
+                end
+            elseif point.currentDistance then
+                if point.onExit then point:onExit() end
+
+                point.inside = nil
+                point.currentDistance = nil
+            end
+        end
+
+        if not tick then
+            if nearbyCount ~= 0 then
+                tick = true
+                CreateThread(function()
+                    while tick do
+                        for i = nearbyCount, 1, -1 do
+                            local point = nearbyPoints[i]
+
+                            if point and point.nearby then
+                                point:nearby()
+                            end
+                        end
+                        Wait(0)
+                    end
+                end)
+            end
+        elseif nearbyCount == 0 then
+            tick = false
+        end
+
+        Wait(300)
+    end
+end)
+
+local function toVector(coords)
+    local _type = type(coords)
+
+    if _type ~= 'vector3' then
+        if _type == 'table' or _type == 'vector4' then
+            return vec3(coords[1] or coords.x, coords[2] or coords.y, coords[3] or coords.z)
+        end
+
+        error(("expected type 'vector3' or 'table' (received %s)"):format(_type))
+    end
+
+    return coords
+end
+
+xLib.points = {}
+
+---@return CPoint
+---@overload fun(data: PointProperties): CPoint
+---@overload fun(coords: vector3, distance: number, data?: PointProperties): CPoint
+function xLib.points.new(...)
+    local args = { ... }
+    local id = #points + 1
+    local self
+
+    -- Support sending a single argument containing point data
+    if type(args[1]) == 'table' then
+        self = args[1]
+        self.id = id
+        self.remove = removePoint
+    else
+        -- Backwards compatibility for original implementation (args: coords, distance, data)
+        self = {
+            id = id,
+            coords = args[1],
+            remove = removePoint,
+        }
+    end
+
+    self.coords = toVector(self.coords)
+    self.distance = self.distance or args[2]
+    self.radius = self.distance
+
+    if args[3] then
+        for k, v in pairs(args[3]) do
+            self[k] = v
+        end
+    end
+
+    xLib.grid.addEntry(self)
+    points[id] = self
+
+    return self
+end
+
+function xLib.points.getAllPoints() return points end
+
+function xLib.points.getNearbyPoints() return nearbyPoints end
+
+---@return CPoint?
+function xLib.points.getClosestPoint() return closestPoint end
+
+---@deprecated
+xLib.points.closest = xLib.points.getClosestPoint
+
+return xLib.points