gridplugin
A map of cells that changes while the game runs, held in rows, drawn on render2d.
Putting it in a scene
The scene's sim lists the grid kind from #plugins/grid/grid.sim.ts, and the scene has one { "is": "grid" } actor, chunk 0, whose prefab is exactly as below. The grid spawns every other chunk itself, each value 0, on the first step.
"plugins": ["loader", "scenemanager", "player", "render2d", "grid"],
"world": {
"grid": {
"size": [128, 128],
"chunk": 16,
"layer": "city",
"layers": {
"height": { "bits": 5 },
"zone": { "bits": 4 },
"pollution": { "bits": 8, "scale": 4 }
}
}
},
"actors": [{ "is": "grid" }],
"prefabs": {
"grid": { "k": 0, "cells": {} }
}Properties
Read from world.grid.
.size : [w, h]
The map in cells. Each side is a whole number of chunks.
.chunk : number
How many cells across and down one chunk is. Each chunk is one row, numbered k along the top row of chunks and then down. A changed cell sends only its chunk's string for that layer, a few hundred characters.
.layers : { [name]: { bits, scale } }
The values each cell holds, by name, in order. Every value of a layer is a whole number from 0 to 2bits − 1, with bits from 1 to 30. scale, 1 when left out, is how many cells across and down share one value: a layer of scale 4 holds one value for each 4 × 4 block, for a coarse field such as pollution or land value. A chunk is a whole number of blocks.
.layer : string
The render2d layer the cells are drawn on. It must be a layer that sorts, so each draw is ordered by the depth of its sort point.
The rows
A chunk row is { k, cells }: cells holds one string per layer. A value is written as ⌈bits / 6⌉ characters of A–Z, a–z, 0–9, - and _, six bits each, highest first, and the values lie a row of the chunk's blocks at a time from its top left. A grid kept by the persist addon is found whole and nothing is made again; a layer added to the scene since is given to every chunk at 0.
set("zone", 5, 1, 2) changes one character of chunk 1's string, and only that string is sent.Methods
Rules
From #plugins/grid/grid.sim.ts.
cells( w ) : Cells
The grid's cells, made whole first, so a rule reads the whole map on the first step whichever row runs first. The page reads a packet's the same way with cells({ world, rows }).
| Member | Meaning |
|---|---|
get(layer, x, y) | The value of cell [x, y], x along a row and y down the rows. A cell of a scaled layer reads its block's value. |
set(layer, x, y, v) | Writes the value into its chunk's string, sent to every seat at the step's end. A cell outside the map, a layer the scene does not name, or a value the layer's bits cannot hold throws. |
inside(x, y) | Whether [x, y] is a whole-numbered cell of the map. |
size, chunk, layers | The scene's size and chunk, and the layers' names in order. |
picture( w ) : Pixels
The grid as a picture for the loader's encodePng, with the layers' names, bits and scales as JSON in the PNG text grid. The layers are packed into each pixel's 32 bits in order, each value's lowest bit first from the lowest bit of red, then green, blue and alpha. A layer that would pass the 32nd bit starts the next plane, laid under the first, so the picture is w across and h × planes down.
fill( w, pixels )
Reads a picture, from the loader's pixels, into every chunk. Layers are matched by name: one the picture holds and the scene does not is left out, and one the scene holds and the picture does not is set to 0. A picture with no grid text, such as a height map painted in an image program, is read as holding the scene's own layers in order. A picture of the wrong size, or with a layer of other bits or scale, throws before any cell is written.
On the page
Through plugins.grid.
look( fn, reach = 1 )
Says what each cell is drawn as, from the next frame on. fn(cells, x, y) returns a list of draws for cell [x, y] and may read any cell. When a value changes, every cell within reach cells of it across and down is asked again, so a road's piece can depend on the roads beside it.
| Draw key | Meaning |
|---|---|
sheet | The name of a loader sheet entry. |
frame, clip, frames | One of these: a frame's id; a clip, each frame for the time the sheet gives it; or a list of frame ids. Clips and lists play on the page's clock, so every cell showing one shows the same frame at the same moment. |
fps | Frames a second for a list, or for a clip whose sheet times none of its frames. |
at | The world point [x, y] the frame's anchor stands on. Left out, the cell's corner nearest the viewer, [x + 1, y + 1]. |
lift | Steps of render2d's up above that point, 0 when left out: the cell's height. |
sort, tie | The world point whose depth orders the draw on the layer, at when left out, and the order of draws at one depth, higher over, 0 when left out. |
alpha, tint | As a sprite has them, 1 and 0xffffff when left out. |
A frame of a nearest sheet is drawn on whole pixels. A sheet written while the game runs is drawn again in every cell.
preview( edits | null )
Draws edits, each [layer, x, y, value], over the cells the packets bring, until the next preview. null stops. It shows what a seat would build while it drags, before it asks.
pick( x, y, height?, top? ) : [cx, cy] | undefined
The cell whose top is drawn at canvas point [x, y], in render2d's canvas pixels, or undefined. height(cx, cy) is how many steps up a cell's top is; left out, it is the highest lift of the draws with no at. The point is tried from top, the highest any cell is drawn at when left out, down to 0 in steps of 1/16, so a hill in front hides the cells behind it.
top( x, y ) : number
The height cell [x, y]'s top is drawn at, as pick reads it. 0 for a cell not drawn yet.
cells( ) : Cells | undefined
The grid as drawn, with the preview in it. ahead() is the same without the preview, for a seat planning its next change.