PointInRange

Detects when the local player enters or leaves a defined radius around a world position. Wraps the Chunk module for efficient spatial lookup.

DANGER

Do not use this module if your radius is higher than 10m because this results in a massive count of chunks and the more chunks exists the more performance and memory usage is needed. Example: A radius of 100m results in 40x40x40 chunks, so 68000 chunks. This is too much for the PointInRange API. Use the Chunk module instead.

INFO

The monitoring loop runs every 500 ms, and every 250 ms while the player stands in a grid cell that holds points (since 0.37.9).

Reach is flat, height is separate (since 0.37.9)

radius is measured in x/y only, from the player's centre (about a metre above the feet) to the point. The height difference is checked on its own against height_tolerance, default NssLibsPointInRange.DEFAULT_HEIGHT_TOLERANCE (3.0 m). Measured in 3D, a 1.5 m radius around a point at ground level left about 1.1 m of flat reach, and a 0.7 m radius could only be reached when the point had been measured at chest height. Pass a smaller tolerance where floors matter.

---

Example

---@type NssLibsPointInRangeApi
local pir_api = exports.nss_libs:getPointInRangeApi(GetCurrentResourceName())

---@type NssLibsPointInRangeListenerApi
local pir_listener
local radius = 10.0
local x, y, z = 0.0, 0.0, 0.0

local on_enter = function()

    -- Do something when player enters the radius
    print("Entered the location")

    -- Ensure the player can only enter once for all time ;)
    if pir_listener then
        pir_listener.remove()
    end
end

local on_leave = function()

    -- Do something when player leaves the radius
    print("Left the location")
end

-- Ignore the nearest check
pir_listener = pir_api.add(x, y, z, radius, on_enter, on_leave, pir_api.IGNORE_NEAREST_CHECK)

-- Nearest point wins (excluding points that ignore the nearest check)
pir_listener = pir_api.add(x, y, z, radius, on_enter, on_leave)

---

Commands / Objects

exports.nss_libs:getPointInRangeApi(resource_name)

Param	Type	Default	Description
resource_name	string	—	The name of the resource that uses the PointInRange API. Pass GetCurrentResourceName()

Returns NssLibsPointInRangeApi — object scoped to the calling resource

---

NssLibsPointInRangeApi

.add(x, y, z, radius, on_enter_cb, on_leave_cb, ignore_nearest_check?, height_tolerance?)

Registers a new point listener.

Param	Type	Default	Description
x	number	—	World X coordinate of the point center
y	number	—	World Y coordinate of the point center
z	number	—	World Z coordinate of the point center
radius	number	—	Flat (x/y) detection radius in meters. Maximum allowed value is 10.0 meters
on_enter_cb	function	—	Called when the local player enters the radius
on_leave_cb	function	—	Called when the local player leaves the radius
ignore_nearest_check	boolean?	nil	Pass pir_api.IGNORE_NEAREST_CHECK to disable the nearest-point filter
height_tolerance	number?	3.0	Allowed height difference in meters between the player's centre and the point

WARNING

Use the Chunk module for ranges larger than 10.0 meters.

Returns NssLibsPointInRangeListenerApi|nil — the listener object, or nil if radius > 10.0

---

.reset()

Removes all listeners registered by the calling resource. Useful for bulk cleanup without tracking individual listener references.

---

IGNORE_NEAREST_CHECK

Constant (true). Pass as the ignore_nearest_check argument to add() to make a listener trigger independently of other points in the same chunk. By default, when multiple points share a chunk, only the nearest one activates its callbacks (nearest-check). Listeners with IGNORE_NEAREST_CHECK always activate if the player is within their radius, regardless of other nearby listeners.

---

NssLibsPointInRangeListenerApi

Returned by api.add(). Represents a single registered point listener.

.remove()

Unregisters this listener. After calling remove(), the listener's on_enter_cb and on_leave_cb will no longer be invoked.

---

.getId()

Returns string — the internal unique identifier for this listener