A fully typed Luau library for handling grids (2D or 3D) of values.
Add luau-grids in your dependencies:
yarn add luau-gridsOr if you are using npm:
npm install luau-gridsCreate a new 2D grid with a specified size and default cell value.
This class and its type are accessible from the module root:
-- note that the require may differ depending on your Lua environment
local grids = require('@pkg/luau-grids')
local Grid2D = grids.Grid2D
type Grid2D<Cell> = grids.Grid2D<Cell>Grid2D.new<Cell>(
sizeX: number,
sizeY: number,
defaultCell: Cell | (x: number, y: number) -> Cell
) -> Grid2D<Cell>Creates a new 2D grid with the specified dimensions and default cell value.
local grid = Grid2D.new(3, 3, 0) -- 3x3 grid with default value 0The defaultCell value can be an initializer function that gets called for every cell position in the grid that must return a non-nil value.
Grid2D:get(x: number, y: number) -> Cell?Gets the value of the cell at the specified coordinates.
local value = grid:get(1, 1) -- Get value at position (1, 1)Grid2D:set(x: number, y: number, value: Cell) -> CellSets the value of the cell at the specified coordinates and returns the previous value.
grid:set(2, 2, 42) -- Set value 42 at position (2, 2)Grid2D:update(x: number, y: number, fn: (value: Cell) -> Cell?) -> ()Updates the value of the cell at the specified coordinates using the provided function.
-- Increment value at position (1, 1) by 1
grid:update(1, 1, function(value)
return value + 1
end)Grid2D:size() -> (number, number)Returns the size of the 2D grid as a tuple (sizeX, sizeY).
local sizeX, sizeY = grid:size()Create a new 3D grid with a specified size and default cell value.
This class and its type are accessible from the module root:
-- note that the require may differ depending on your Lua environment
local grids = require('@pkg/luau-grids')
local Grid3D = grids.Grid3D
type Grid3D<Cell> = grids.Grid3D<Cell>Grid3D.new<Cell>(
sizeX: number,
sizeY: number,
sizeZ: number,
defaultCell: Cell | (x: number, y: number, z: number) -> Cell
) -> Grid3D<Cell>Creates a new 3D grid with the specified dimensions and default cell value.
local grid = Grid3D.new(3, 3, 3, "empty") -- 3x3x3 grid with default value "empty"The defaultCell value can be an initializer function that gets called for every cell position in the grid that must return a non-nil value.
Grid3D:get(x: number, y: number, z: number) -> Cell?Gets the value of the cell at the specified coordinates.
local value = grid:get(1, 1, 1) -- Get value at position (1, 1, 1)Grid3D:set(x: number, y: number, z: number, value: Cell) -> CellSets the value of the cell at the specified coordinates and returns the previous value.
grid:set(2, 2, 2, "occupied") -- Set value "occupied" at position (2, 2, 2)Grid3D:update(x: number, y: number, z: number, fn: (value: Cell) -> Cell?) -> ()Updates the value of the cell at the specified coordinates using the provided function.
grid:update(1, 1, 1, function(value) return value .. "_updated" end) -- Append "_updated" to value at position (1, 1, 1)Grid3D:size() -> (number, number, number)Returns the size of the 3D grid as a tuple (sizeX, sizeY, sizeZ).
local sizeX, sizeY, sizeZ = grid:size()If you would like to use this library on a Lua environment, where it is currently incompatible, open an issue (or comment on an existing one) to request the appropriate modifications.
The library uses darklua to process its code.
This project is available under the MIT license. See LICENSE.txt for details.