Chunk

The chunk interface helps you to create your own chunk based systems with high performance.

WARNING

If you are looking for a ready to use "get the nearest point in range" system, please use the PointInRange module.

Example

All Entered

---@type NssLibsChunksApi
local chunks_api = exports.nss_libs:getChunksApi(GetCurrentResourceName())

---@type NssLibsChunkApi
local chunk_api = chunks_api.create()

chunk_api.setModeAllEntered()

local a_on_enter = function(chunk_item_id)
    print('Entered radius A', chunk_item_id)
    -- Do something
end

local a_on_leave = function(chunk_item_id)
    print('Left radius A', chunk_item_id)
    -- Do something
end

local a_x = 0
local a_y = 0
local a_z = 0
local a_radius = 10

chunk_api.add(a_x, a_y, a_z, a_radius, a_on_enter, a_on_leave)

local b_on_enter = function(chunk_item_id)
    print('Entered radius B', chunk_item_id)
    -- Do something
end

local b_on_leave = function(chunk_item_id)
    print('Left radius V', chunk_item_id)
    -- Do something
end

local b_x = 2
local b_y = 2
local b_z = 0
local b_radius = 10

chunk_api.add(b_x, b_y, b_z, b_radius, b_on_enter, b_on_leave)

Only Nearest

---@type NssLibsChunksApi
local chunks_api = exports.nss_libs:getChunksApi(GetCurrentResourceName())

---@type NssLibsChunkApi
local chunk_api = chunks_api.create()

chunk_api.setModeOnlyEnteredNearest()

local a_on_enter = function(chunk_item_id)
    print('Entered radius A', chunk_item_id)
    -- Do something
end

local a_on_leave = function(chunk_item_id)
    print('Left radius A', chunk_item_id)
    -- Do something
end

local a_x = 0
local a_y = 0
local a_z = 0
local a_radius = 10

chunk_api.add(a_x, a_y, a_z, a_radius, a_on_enter, a_on_leave)

local b_on_enter = function(chunk_item_id)
    print('Entered radius B', chunk_item_id)
    -- Do something
end

local b_on_leave = function(chunk_item_id)
    print('Left radius V', chunk_item_id)
    -- Do something
end

local b_x = 2
local b_y = 2
local b_z = 0
local b_radius = 10

chunk_api.add(b_x, b_y, b_z, b_radius, b_on_enter, b_on_leave)

• All Entered: If the player steps into a location the on_enter callback is called. If the player leaves, the on_leave callback is called. If there are more than one location at the same coordinates (or overlapping radius) all callbacks of the related locations are called.
• Only Nearest: Like the above but only the location nearest to the player will be called.

---

Methods (NssLibsChunksApi)

.create()

Creates a chunk grid and returns its API.

TIP

Be careful with grids — the more grids there are, the more performance it will need.

Returns NssLibsChunkApi — The chunk grid API

---

.clear()

Clears all chunk grids of the resource.

Returns NssLibsChunksApi — chainable

---

Methods (NssLibsChunkApi)

.setSize(size_in_meters)

Sets the grid size in meters.

Param	Type	Default	Description
size_in_meters	number	5	The size of the grid in meters

Returns NssLibsChunkApi — chainable

---

.setMonitoringInterval(interval_in_ms)

Sets the monitoring interval in milliseconds.

Param	Type	Default	Description
interval_in_ms	number	1000	The interval in milliseconds. 0 means each frame

Returns NssLibsChunkApi — chainable

---

.setNearMonitoringInterval(interval_in_ms)

A shorter tick while the player stands in a grid cell that holds locations. Off by default; the normal interval applies everywhere else. Cells extend one grid step beyond every location's radius, so "populated cell" already means "within reach plus one cell".

Param	Type	Default	Description
interval_in_ms	number|nil	nil	The interval in milliseconds while close to a location. nil switches it off

Returns NssLibsChunkApi — chainable

---

.setModeAllEntered()

All locations entered by the player will be called. E.g. you have two locations near besides to each other all locations will be called if the player steps into both location radius.

Returns NssLibsChunkApi — chainable

---

.setModeOnlyEnteredNearest()

Only the location nearest to the player will be called. E.g. you have two locations near besides to each other the nearest one will be called if the player steps into both location radius.

Returns NssLibsChunkApi — chainable

---

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

Adds a location to the chunk grid.

Param	Type	Default	Description
x	number	—	The x coordinate of the location
y	number	—	The y coordinate of the location
z	number	—	The z coordinate of the location
radius	number	—	The radius of the location
on_enter_cb	function(location_id)	—	Called when the player enters the location
on_leave_cb	function(location_id)	—	Called when the player leaves the location
height_tolerance	number?	nil	nil: the radius is a 3D sphere, as before. A number: the radius is flat (x/y) and the height difference between the player's centre and the location may be up to this many meters. The prompts linker passes 3.0

Returns NssLibsChunkItemApi — The chunk item API

---

.remove(location_id)

Removes a location from the chunk grid.

Param	Type	Default	Description
location_id	string	—	The location id returned by .add()

Returns NssLibsChunkApi — chainable

---

.reset()

Clears (removes) all locations from the chunk grid.

Returns NssLibsChunkApi — chainable

---

Methods (NssLibsChunkItemApi)

.getId()

Returns the location id.

Returns string — The location id

---

.remove()

Remove the location from the chunk grid.

---

Dev notes

Currently, nothing 😉