Introduction
A macrocell file stores a Game of Life universe as a quadtree. The universe is one big square; the square is cut into four quarters, each quarter into four, and so on down to small squares of cells. Every square that looks the same is stored once, and every square with no live cell is the number 0. A pattern that repeats itself a million times costs the lines of one copy and the lines that say where the copies go, so a universe 21000 cells wide with a few thousand different squares is a file of a few thousand lines.
Golly’s HashLife algorithm keeps its universe in memory in just this form, and the macrocell file is that memory written out, which is why Golly uses it for patterns that run-length encoding cannot hold and for backups. The same extension is used by other things, for instance Minecraft; a Life file is told by its first line, [M2].
Lines
Lines end in CR, LF or CR LF. Blank lines are allowed anywhere after the first.
| Line | Meaning |
|---|---|
[M2] (golly 4.2) | The first line: the format identifier [M2] and the name and version of the program that wrote the file. Golly accepts any first line that starts with [. |
#R rule | The rule, up to the first space: B3/S23, WireWorld, w22. Golly always writes it; older files have none. |
#G n | The generation count of the universe, as a whole number of any size. Written only when it is not 0. |
#C text | A comment. Any other line starting with # is also a comment. |
#FRAMES count start increment | A timeline: the number of frames, the generation of the first frame (digits and commas) and the number of generations between frames, a power of two written as a number or as 2^10. |
#FRAME index node | Frame number index (in order from 0) is the node numbered node. The node lines it points at come before it. |
| a leaf line, a node line | The squares of the quadtree, below. |
Leaves
Two-state universes have leaves that are 8 × 8 cells. A leaf line is the picture of the square, rows from the top and cells from the left: . is an empty cell, * a live cell and $ the end of a row. Empty cells at the end of a row are left out and so are empty rows at the end. No space is allowed in the line. A line is recognised as a leaf because it starts with ., * or $. A glider is $$..*$...*$.***$$$$: two empty rows, then ..*, ...*, .***.
Multi-state universes have leaves that are 2 × 2 cells. A leaf line is five numbers separated by single spaces: 1 and then the states of the north-west, north-east, south-west and south-east cells. The older two-state form built from these leaves is read too: the depth 1, 2 and 3 lines whose cells are 0 or 1.
Nodes
A node line is five whole numbers: d nw ne sw se. d is the base-2 logarithm of the size of the square, so a node with d = 5 is 32 × 32 cells. The next four are the numbers of the node of each quarter: north-west, north-east, south-west, south-east. Each must be a square of half the size, that is of depth d − 1. For a two-state universe d is at least 4 (its quarters are 8 × 8 leaves); for several states it is at least 2.
Leaves and nodes are numbered together in the order they appear, from 1. A node may only refer to a number already defined. The number 0 stands for the empty square, of whatever size is needed.
The root, the whole universe, is the last node in the file and has the greatest depth. The coordinates are fixed by one rule: the upper left cell of the south-east quarter of the root is at x = 0, y = 1. So a root of side S covers x from −S/2 to S/2 − 1 and y from 1 − S/2 to S/2, with y growing downwards.
[M2]Header the first line1 line#RRule, generation, comments, timeline0 or more lines$$.*Leaves and nodes children before parents, numbered from 11 line each9 …Root the last node, the largest1 line
Files saved from two-state and from multi-state algorithms are not compatible with each other.
An example
A glider in a universe of 16 × 16 cells. The file is four lines, line endings 0A.
5B 4D 32 5D 20 28 67 6F 6C 6C 79 20 34 2E 32 29 0A [M2] (golly 4.2)
23 52 20 42 33 2F 53 32 33 0A #R B3/S23
24 24 2E 2E 2A 24 2E 2E 2E 2A 24 2E 2A 2A 2A 24 24 24 24 0A $$..*$...*$.***$$$$
34 20 30 20 30 20 30 20 31 0A 4 0 0 0 1
Node 1 is the leaf, node 2 is the root: 16 × 16 cells, with the leaf as its south-east quarter and the other three quarters empty. The root covers x from −8 to 7 and y from −7 to 8; the south-east quarter starts at 0, 1, so the glider’s cells are at 2, 3 and 3, 4 and 1, 5 to 3, 5.
In the explorer
The explorer never expands a universe. It reads the file into one entry for each node (size, children, population and the box round its live cells), then draws a window by walking the tree from the root and skipping every square that is empty or outside the window. It shows the rule, the generation, the size of the root, the number of nodes, the population of the universe (exact, however big), the bounding box and a table of how many nodes there are at each depth. Every byte is in the tree: each line, and for a node line each of its five numbers.
The picture fits the live cells. Three options move it: Zoom (a whole number e: from 0 up one pixel is 2e cells; −1 to −4 draw each cell 2, 4, 8 or 16 pixels wide), Centre x and Centre y (the cell in the middle of the window, a whole number of any size). A universe of 2200 × 2200 cells with three live cells is a three-line file and can be walked to each of them by its coordinates.
A file with a timeline (#FRAMES and a #FRAME line for each saved generation, each naming the node that holds the universe at that time) can be shown a frame at a time: the Frame option takes the number of the frame, from 0, and the facts give its node and its generation (the first generation plus the frame’s number times the increment). Without it the picture is the last node of the file. A frame that names the empty node, node 0, is an empty universe, and a frame node that does not exist yet is a problem (Golly’s “Bad FRAME line”).
Not described
What this reference leaves out and what the viewer does not do.
Known, not yet covered
- Reference: the format is described here from Golly’s documentation (its file formats help) and the source of its readers (
readmacrocellingollybase/hlifealgo.cppandghashbase.cpp). How Golly turns a node’s cells into the next generation (HashLife) is not described. - Reference: the older macrocell version without
[M2]is not described. - Viewer: the universe is shown as it is stored; it is not run. Cells of a multi-state universe are drawn in the viewer’s state colours, not the colours the rule’s own file gives.
Other Game of Life pattern formats
- Game of Life pattern (.lif) – Life 1.05, Life 1.06 and plain grids
- Golly RLE pattern (.rle) – run-length encoded text, the usual way to share a pattern
- MCell pattern (.mcl) – the format of the MCell program
Links
Software
- Golly – free Game of Life and cellular automata program that opens and saves macrocell files (Windows, macOS, Linux)
Reference
- Golly file formats – Golly’s description of macrocell, Extended RLE and rule files
- Macrocell – the LifeWiki page on the format