gridKit

Square, hex and isometric boards for any multiplayer world: picking, multi-cell pieces, movement range and paths, line of sight and cover, undo, save/load, four turn models and eight swappable highlight looks, behind one interface.

Version 1.0.10 (GK.VERSION; the version in this README, package.yaml and GK.VERSION move together).

Quick start

Grid { shape = "hex" }

That one line, inside content() of a scene's build.luau, gives a working hex board 6 m in front of the default spawn: the cell under the pointer lights up, a click or tap places a token (seats alternate red and blue), and Z (or the on-screen Undo button) takes it away again.

Install and use, step by step

1. Install the gridKit.package asset into /source (search ZeroMind for "gridKit", or zeromind_install guid=<gridKit package guid> at=/source). It needs nothing else: it builds on engine packages every world already has.

2. In scenes/main.scene/build.luau, add this at the very top of the file:

   local Grid = require("gridKit.api").Grid
   

3. Inside function content(), before its end, add:

   Grid { shape = "hex" }
   

4. Press play. Walk up to the board, aim at a cell (the screen centre aims while the mouse steers the camera; a free mouse or a finger points directly) and click or tap. Press Z to undo, G to steer a cell cursor with the arrow keys or a gamepad, Esc to put the cursor away and walk on.

Change one setting to change the board: shape = "square" | "hex_flat" | "hex_pointy" | "iso", highlight = "holo", turns = "action_points", tokenLook = "neon". A running board swaps any of them live (board:setHighlight("pixel")), from any player. Every choice, with tags to pick by, is in the variant catalog.

A tactics board with a starting position:

local GK = require("gridKit.api")

-- inside content():
GK.Grid {
	name = "Skirmish", shape = "square", cols = 8, rows = 8, position = { 0, 0, 10 },
	turns = "action_points", actionPoints = 4, highlight = "holo", theme = "night", tokenLook = "neon",
	placeKind = "",                       -- clicks select and move; nothing new is placed
	label = "Skirmish",                   -- a sign behind the board (text or a translation key)
	pieces = { { kind = "pawn", q = 1, r = 0, seat = 1 }, { kind = "king", q = 6, r = 7, seat = 2 } },
	walls = { { kind = "long_wall", q = 2, r = 3 }, { kind = "crate", q = 5, r = 4 } },
}

Reacting to what happens, in code that runs in play (a scene's entrypoint.luau):

local GK = require("gridKit.api")
local conn

function onLoad()
	conn = GK.on("moved", function(e)
		print(e.piece.kind .. " moved to " .. e.q .. "," .. e.r)
	end)
end

function onUnload()
	if conn then conn.Disconnect() end
end

Guides

Two guides come with the package and open in the Docs panel once gridKit is installed:

• How to make a turn based grid board game: square, hex or isometric boards with movement, line of sight and undo teaches the kit: picking a shape, pointing at cells, the eight looks, multi-cell pieces, move ranges and paths, line of sight and cover, undo, turns and seats, save and load, and the shared multiplayer board.
• How to make a hex grid tactics game, step by step builds a two-sided hex skirmish from an empty world: move ranges and paths, attacks only on enemies a piece can see, undo, turns and a winner.

This README stays the short reference for every option.

What you get

Grid shapes

Highlight looks (highlight)

Pick the look when you make a board, Grid { shape = "hex", highlight = "holo" }, or change it while it runs, board:setHighlight("pulse"). Every name in the second column works too; case, spaces and hyphens do not matter. (style is the same setting under its older name.) An unknown name is an error listing every look and its names; an option Grid does not know is a warning, never silently dropped.

Each look draws every layer in its own colour: hover (gold), selected (orange), move range (blue), path (green), line of sight (white), blocked (red), cursor (magenta), committed plans (violet). On top of any look, three guides read at a glance: a bright outline around the whole move range, a green path ribbon with a dot per step and an arrowhead, and a raised sight beam that turns red and dashed past the wall that blocks it, with a flat red ✕ lying on top of that wall (it never rises above the wall, so it cannot hide anything behind it).

Token looks (tokenLook): classic (lacquered turned pieces with brass collars, stone walls, crates) and neon (smoked glass with glowing seat colours). Board colours (theme): slate, walnut, night, sand.

Piece kinds: pawn, king, disc, domino (2 cells), ell (3 cells), wall (blocks sight, full cover), long_wall (3 cells), crate (half cover). Add your own with GK.definePiece(id, { footprint = { {0,0}, {1,0} }, blocksSight = false, cover = 1, neutral = false }).

Turn models (turns)

Any number of seats (seats = 4). Seats are played hot-seat: whoever acts plays for the seat whose turn it is, unless a player claims a seat with board:claimSeat(n); a claimed seat's actions and end of turn are then taken only from that player, and anyone else is refused with "not_your_seat". Undo stays shared.

Variant catalog

GK.CATALOG lists every choice a board has: the 4 shapes, the 8 highlight looks and the 4 turn models, 16 in all. Each entry is { kind, setting, id, aliases, name, nameKey, tags, description }: setting is the Grid { } option it goes in and id the value to write. Filter it with GK.variants{ kind = "look" | "shape" | "turns", tag = "sci-fi", search = "hex tactics" }; GK.catalog.tags() lists every tag and GK.catalog.describe() prints the whole list.

local GK = require("gridKit.api")
for _, v in GK.variants({ tag = "retro" }) do print(v.setting, v.id) end   -- shape iso, highlight pixel
Grid { shape = "hex", highlight = GK.variants({ tag = "sci-fi" })[1].id }

API

local GK = require("gridKit.api")

GridBoard fields (all settable in Grid { } and live): shape, cols, rows, cellSize, diagonal, style (in Grid { } also highlight, which reads better and takes every alias), turns, seats, actionPoints, tokenLook, theme, label, subtitle, labelHeight, labelSize, labelMaxWidth, labelTilt (degrees the sign and legend lean back; 40-60 reads from above too; in play a sign or legend that comes between a player's camera and them or the board they are at steps out of that player's view until the line is clear), placeKind (what a click on an empty cell places; "" for none), autoPlay (built-in click behaviour; false leaves clicks to your selected handler, and a handler that sets e.handled = true takes over just that click), moveBudget, showReach, showPath, showSight, showcase (keeps a sample range, path and sight line drawn while idle), legend (a colour key for range, path, sight and blocked along the front edge), range. Signs word-wrap to two lines and shrink to fit labelMaxWidth, so neighbouring signs never touch.

Board methods (a cell is q, r or { q = , r = }):

Events

GK.on(name, fn); every handler gets { board, entity, boardId, q?, r?, piece?, seat?, round?, ... }.

Controls

While the cursor is open the player's walking and camera controls stand down; they come back the moment it closes.

Multiplayer

The board's state (pieces, turns, undo history) lives in one synced field written only by the peer that owns the board entity (the room host for a scene board, which claims it when play starts). Every other player's clicks and key presses are sent to that peer, so everyone sees the same tokens appear and disappear and undo is shared. Hover, selection previews, the cell cursor and the HUD stay on each player's own screen. Place boards on synced entities (Grid does); synced = false makes a board only one peer sees.

Known limits

• Seats are hot-seat by default: any player acts for the seat whose turn it is unless seats are claimed with claimSeat.
• Boards lie flat (a board can be moved, turned about its vertical axis and scaled; tilted boards are not picked correctly).
• The decal look stamps flat colour rectangles turned to the cell (no per-shape decal textures), so on hex boards the stamp is a square inside each hex (see #19880 / #10827 for why no textured or emissive decal is used).
• 3D sign text is rasterised at scale 1, since scale 2 clips glyph tops (#19525), and a sign is respawned rather than edited when its text changes (#7781).
• Two engines signed in to the same account collide as one player (#14448), so a two-player check needs two accounts.
• In the browser the engine runs scripts several times slower than on desktop, so a gallery of many boards costs far more of each frame there (#20750).
• The kit and its guides are checked in the desktop app; an agent cannot start a browser engine itself, so the web check is done separately (#20946).
• The pointer's world position is found from screenToRay and the board's plane, since picking a world position from the pointer is not covered in the guides (#8987).
• Mouse and touch events arrive in window pixels while the pointer position and screenToRay use viewport pixels (#21604); gridKit measures the offset each frame, so this only matters if you pick cells yourself.

Versions

• 1.0.10: two guides come with the package, a how-to that teaches the kit and a step-by-step hex grid tactics example (listed under Guides). Three things the example needed and the kit lacked: a selected handler can set e.handled = true to take a click over from the built-in play (and reads the piece the player had selected as e.selectedPiece); act{ op = "remove", id = enemy, by = mine } takes an enemy off as one turn-checked, undoable step; and a seat claimed with claimSeat is now really held, so only its player can act for it or end its turn (before, the claim was recorded but never checked). On the frame of a window resize the screen size can read wrong (#16264), so the status card now skips that frame instead of placing itself against the wrong size. The world moves to the current built-in library. Checked on the current engine: gridKit 1.0.9 installed on its own from ZeroMind into a new empty world, where the README's first example ran exactly as written (a click placed a token on the board at 0, 0, 6 and Z took it away); this release's files laid over that install, where the example guide's code, taken straight from the guide, ran from step 2 to the winner and back with undo; the board entity synced and owned by the room's host; and the test suite (9 tests) twice in a row.
• 1.0.9: the status card on wide screens keeps off every board's title sign from the arrival overview too, where all sixteen boards fill the screen and no corner is free. It now searches the whole screen rather than six corners, treats each sign's plate as something it must not cover and the boards as something to avoid, and when nothing fits at full size it first drops its header and key-hint lines with smaller text, then shows only whose turn it is (and any message). Checked standing at each front-row board, with the camera on the arrival overview and with the camera following the player, at 2560x1440, 2097x1409, 1024x640 and 840x632, in English and Portuguese: in all 64 cases the card covers no sign plate and no board.
• 1.0.8: the status card on wide screens moves off the boards, signs and legends it would cover, to a free top or bottom corner or edge, measured against its own size, so a longer Portuguese line counts too. Checked only with the camera following the player (24 cases at 2560x1440, 2097x1409 and 1024x640, English and Portuguese, nothing covered). From the arrival overview, where no corner is free, the card could still sit on a sign's title (in Portuguese at 2097x1409, and at small windows); 1.0.9 fixes that.
• 1.0.7: the upright-phone HUD is sized in phone points: the UI space is normalised far wider than a phone is in points (664 units across a 390-point phone), so 1.0.6's buttons came out about 33 points tall. They are now about 56 points tall and 64 wide, with the text scaled to match, and the bar's lower edge stays 31% up the screen, clear of the move stick and the jump/sprint buttons.
• 1.0.6: idle boards cost much less: the moving parts of the hologram and pulse looks are baked once into a short loop of frames and only swapped while they play, and glow (which moves through its material) is no longer rebuilt at all. On a phone held upright the HUD buttons are thumb-sized, in one row with a compact status card just above the touch stick and jump/sprint buttons, so the top of the screen (the far boards and their signs) stays clear. Signs, legends, HUD and messages checked in English and Brazilian Portuguese after load, in play and across repeated language switches.
• 1.0.5: signs and legends step out of the way: when one stands between a player's camera and that player, or the board they are walking up to, it is taken out of that player's view (on their screen only) until the line is clear, so walking up to a board behind another row never puts the camera inside a sign; the board a player is at always keeps its own sign. README release history corrected.
• 1.0.4: every look answers to the names a creator would write (holo, sci-fi, soft glow, retro, animated ...), Grid { highlight = ... } picks the look at creation, and Grid warns about options it does not know instead of dropping them; the variant catalog (GK.CATALOG, GK.variants) lists the 16 shapes, looks and turn models with tags; signs and legends follow a language change live; the board you control is the one at your feet (measured from your body, on your own level), and the pointer no longer picks a board hidden behind scenery; labelTilt leans signs back; setHighlight.
• 1.0.3: the red ✕ that marks a wall blocking line of sight now lies flat on top of the wall instead of standing in the air, where it hid the letters of signs behind it.
• 1.0.2: touch picking fixed (a tap's emulated mouse click no longer overrides it, and a cell next to the board's centre line no longer reads as "-0" and refuses moves); range outline, path ribbon and sight beam guides on every look; legend field; signs wrap and fit their width; neon walls darker.
• 1.0.1: first release. Four grid shapes, picking by mouse, screen centre, touch and keyboard/gamepad cursor, multi-cell pieces, movement range and paths, line of sight and cover, undo, save/load, four turn models, eight highlight looks, two token looks, host-authoritative multiplayer, English and Brazilian Portuguese. Translation catalogs also travel inside gridKit.strings, since an asset install leaves a package's plain locales/ folder behind.
• 1.0.0: a pre-release snapshot published from a side branch for the fresh-install check; superseded by 1.0.1 (its translations did not survive an install).

Release history note: 1.0.0, 1.0.1-rc.1 and 1.0.3-rc.1 were published from a side branch called prerelease while proving fresh installs. That branch was removed from this world's working copy, but it still exists on the ZeroMind server: the engine's version control (zm) can publish a branch but has no way to delete one there, so only the world's owner can remove it from the website (#21020), and side-branch pushes claim release versions too (#21038). Nothing has been released from it since 1.0.3-rc.1; from 1.0.4 on every release is made from main, one version per push.