Grid9 Documentation

Basic Description

Grid9 is an esoteric interpreted language implemented in Rust based on a 3×3 grid of cells — nine cells total — where each cell holds a zero or a one.

You interact with these cells by setting them (s), flipping them (f), or setting all cells to a value (a). Every output-able character in the language has its own unique combination of cells. Why nine cells and not eight, the size of a byte? There's no strict reason — but the ninth cell is useful for variable storage, holding a zero or one that can sway your logic.

Scripts begin with all nine cells set to zero. Uppercase ASCII letters, whitespace, parentheses, periods, and commas are removed before execution. Write comments using uppercase words: digits and lowercase letters remain part of the program. For example, use FOUR rather than 4 in a comment.

Sets<cell><value>

The set command sets a cell to a value.

The syntax is s followed by the cell id and then the value you want to set it to. Cell ids range from 0 to 8. Values are 0, 1, or r for a random bit.

For example, to set cell 0 to 1 you would run the code below.

s01

Flipf<cell>

The flip command flips a cell to the opposite value.

The syntax is f followed by the cell id you'd like to flip (0–8). Unlike set, flip toggles the value regardless of what it currently is.

For example, to flip cell 2 you would run the code below.

f2

Set-alla<value>

The set-all command sets every cell to a single value at once.

The syntax is a followed by 0 or 1. With ar, each cell receives a random bit independently.

For example, to give all cells the value 1 you would run the code below.

a1

Printp

The print command prints the grid's glyph character to the console.

Every output-able character has a combination on the grid called a “glyph.” Print converts the current glyph into the single character it represents. If the queue contains anything, print outputs the queue instead of the current glyph and then clears it. Each print adds a newline. A pattern with no defined glyph causes an interpreter error. The syntax is p.

For example, the character “a” is represented by 000000010. Flip cell 7 (cell ids start at 0) and print, and it outputs “a,” as shown below.

f7 p

Queueqs / qc

The queue command prints multiple glyphs or characters together.

The syntax is qs to add a glyph to the queue and qc to clear the queue entirely.

Say you want to print two “r” letters side by side. Build the glyph for “r,” save it to the queue, build it again, save it, then print — giving you “rr,” as shown below.

f4 f7 f8 qs a0 f4 f7 f8 qs p

Ifi<cell>=/!<value> … }

The if command checks whether a cell is a zero or a one.

The syntax is i followed by the cell id, then = (equal) or ! (not equal), then the value you're testing for. Close an if statement with }. Combine comparisons with & (AND) or | (OR), such as i1=1|2=1 or i1=1&2=0. Write the initial i only once; AND binds more tightly than OR. Comparison values are literal bits.

For example, to test cell 2 for zero and, if true, print the letter c, run the code below.

i2=0 f6 p }

Whilew<cell>=/!<value> … ]

The while command loops as long as its condition is met.

The syntax mirrors if: w followed by the cell id, then = or !, then the value you're testing for. Close a while statement with ].

The condition is checked before each iteration. Compound comparisons use the same syntax as if, such as w0=0&1!1. For example, this loop alternates between c and a space while cell 2 remains zero.

w2=0 f6 p ]

Exite

The exit command breaks out of the innermost enclosing while loop, even from inside an if block. It must be used inside a while loop.

The syntax is simply e.

For example, to loop while cell 5 is zero, print the letter c, then break out of the loop, run the code below.

w5=0 f6 p e ]

Givegg

The give command lets users supply a glyph pattern as input to the script.

The syntax is gg. Enter exactly nine binary digits on one line, such as 000000010.

For example, a simple glyph-to-character converter takes input and prints the character as output. The code for that is shown below.

gg p

Save and Loadgs<id> / gl<id>

Save and load commands store and recall glyph patterns to other grids for use later.

The syntax is gs plus an id from 0–8 to save, and gl plus an id from 0–8 to load. All nine saved grids start at zero; load restores all nine cells.

ar s00 p gs0 ar s00 p gl0 p

Maskgm<id>

The mask command combines a saved grid with the current grid using bitwise OR: a saved one sets the corresponding cell to one, and a saved zero leaves it unchanged.

The syntax is gm plus an id from 0–8 to mask.

ar gs0 ar gm0

Xorgx<id>/c

The xor command xors the current grid, or a saved grid, against it.

The syntax is gx plus an id from 0–8, or c to XOR against the current grid. A cell becomes one when the two corresponding bits differ. gxc clears the current grid.

f6 f2 f0 f7 gxc

Backb<n>

The back command jumps by character positions in the preprocessed code.

The syntax is b followed by a nonnegative integer. At character index k, bN resumes at k - N + 1, including the final character advance. Subtracting past index zero causes an error; b0 has no effect. Count after comments and whitespace are removed and preprocessing optimizations are applied.

For example, b23 subtracts 23 from the character index before the final advance.

b23

Delayd<seconds>

The delay command waits between instructions in your code.

The syntax is d followed by the number of seconds to wait before continuing. This value can be any nonnegative integer; d0 has no effect.

For example, to flip a value, wait 14 whole seconds, then print it, run the code below.

f6 d14 p

Terminatet

The terminate command ends the program.

The syntax is simply t.

For example, to terminate the program when a condition is met, use the code below. The f7p at the end never runs: by default all cells are 0, so the condition is true and the program terminates first.

i0=0 t } f7 p

Tomlconfig.toml

Grid9 can be configured with a TOML file alongside its script, using the same base name: script.toml configures script.g9. Current Grid9 uses snake_case keys split across a [metadata] table and a [config] table.

The structure is shown below. Any value you leave out falls back to its default; the rest take the values you define. Malformed TOML or incorrect value types stop script loading. Unknown keys are ignored without warnings.

[metadata]
author        = "unknown"
description   = "empty"
version       = "0.1.0"
min_grid9_ver = "2026.1.0"
show_metadata = false

[config]
advanced_preprocess = true
dont_cache     = false
echo_grid_mod  = false
no_log         = false
verbosity      = 1

These options change how Grid9 interacts with your code. For instance, advanced_preprocess removes simple empty if blocks and complete zero-valued Back commands such as b0, and echo_grid_mod prints the grid after every instruction that modifies a cell, which is useful while debugging. dont_cache disables reading and writing preprocessed cache entries. Empty while loops and nonzero Back arguments such as b010 are preserved. no_log suppresses informational interpreter logging; runtime errors still report a diagnostic on stderr and exit with status 1. CLI and preprocessing messages currently do not consistently honor it. verbosity controls selected informational messages: zero hides them, one enables cache messages, and two also enables preprocessing and interpreter start messages.