Introduction
A .rule file tells Golly how a cellular automaton works: how a cell’s next state depends on its own state and its neighbours’. Golly’s RuleLoader algorithm reads it, so that anyone can add a rule such as WireWorld, Codd’s automaton or Langton’s loops with a text file and no programming. The file also holds the names of the states, the colours to draw them in and bitmap icons. It is plain text in sections; each starts with a line that begins @.
The rule is written one of two ways. A rule table (@TABLE) lists transitions such as “a cell in state 2 with these neighbours becomes 3”, with variables and symmetries to keep the list short, and the first transition that matches wins. A rule tree (@TREE) is the full answer for every possible neighbourhood, packed as a tree of lookups: it is made by a program and is not meant to be read. A pattern file (RLE, macrocell) names the rule, and Golly looks for the .rule file of that name.
The same text without the sections is also found alone: a .table file holds just the table and a .tree file just the tree, the form some tools convert from.
Sections
A section starts at a line whose first character is @ and runs to the line before the next such line. Golly recognises @TABLE and @TREE only when the line is exactly that, with nothing after it. Text before the first section is not read. The sections can come in any order, except that @RULE is the first line.
| Section | Holds |
|---|---|
@RULE name | The name of the rule and any text about it. The only required section. |
@TABLE | The transition table: n_states, neighborhood, symmetries, variables and transitions. |
@TREE | The rule tree: num_states, num_neighbors, num_nodes and a line for each node. |
@COLORS | The colour of each state, or a gradient. |
@NAMES | A name for each state. |
@ICONS | An icon for each state, as XPM bitmaps or one of Golly’s built-in sets. |
@LICENSE | The licence the rule is shared under, as free text. |
If a file has both a table and a tree, Golly uses the first of them in the file. A file with neither is valid: it adds names, colours or icons to a rule Golly already has (a built-in rule, or a rule file of the same name in the Rules folder).
@RULEName and descriptionfirst line@TABLETransition table or@TREE, a rule treeoptional@NAMESState namesoptional@COLORSState coloursoptional@ICONSIcons in XPMoptional
@RULE
The first line is @RULE, a space and the name of the rule. The name must match the name of the file exactly, without .rule: Golly warns that case-sensitive file systems would otherwise not find it. Use letters and digits; hyphens and underscores are fine, and spaces and colons must not be used (a colon ends a rule name in a pattern file, where :T30,20 follows it). Everything up to the next section is free text: a description, or the program that made a tree.
@TABLE
Blank lines are ignored, and so is everything after a #. The three descriptors come first, neighborhood before symmetries; variables come before the transitions that use them.
| Line | Meaning |
|---|---|
n_states:n | The number of states, from 2 to 256. The states are 0 to n − 1. |
neighborhood:name | vonNeumann, Moore, hexagonal or oneDimensional. |
symmetries:name | none, permute or one the neighbourhood supports (below). Golly’s help adds that other neighbourhoods are emulated by tools that convert them to these. |
var name={s,s,…} | A variable: a set of states. The braces and commas are optional separators, so var a={2,3} and var a=2,3 are the same. A variable may list earlier variables. |
| a transition | The states or variables of the neighbourhood in order, then the new state of the centre cell, separated by commas (spaces or tabs are read as well). When n_states is at most 10, and there are no variables and no commas in the line, the digits are written together: 012345 is 0,1,2,3,4,5. |
The order of the inputs
| Neighbourhood | Inputs | Symmetries |
|---|---|---|
vonNeumann | C, N, E, S, W | none, rotate4, rotate4reflect, reflect_horizontal, permute |
Moore | C, N, NE, E, SE, S, SW, W, NW | none, rotate4, rotate8, rotate4reflect, rotate8reflect, reflect_horizontal, permute |
hexagonal | C, N, E, SE, S, W, NW | none, rotate2, rotate3, rotate6, rotate6reflect, permute |
oneDimensional | C, W, E | none, reflect, permute |
C is the centre cell; the last item of a transition is its new state, C′. A hexagonal grid is the square grid with the neighbours north, east, south-east, south, west and north-west. In a one-dimensional rule each row of the pattern is a separate line of cells.
Variables in a transition
A variable stands for any of its states. A variable that appears more than once among the inputs and output stands for the same state each time (it is bound), so the line is a transition for each of its states. A variable may be the new state only if it is bound, or has just one state. A transition that has no variable names an exact neighbourhood. For example, with var a={2,3}, var b={2,3} and var c={2,3}, the line a,0,b,1,c,b expands to the transitions for b = 2 and b = 3, each with a and c free to be 2 or 3.
Symmetries
Each transition is also applied with its inputs turned or reflected as the symmetry says: rotate4 turns the neighbours by 90 degrees, giving 4 versions (in a Moore neighbourhood the corner and edge neighbours turn together), rotate8 8, rotate4reflect 8, rotate8reflect 16, reflect_horizontal 2, hexagonal rotate2, rotate3, rotate6 and rotate6reflect 2, 3, 6 and 12, one-dimensional reflect 2. permute lets the neighbours (not the centre) come in any order, each distinct order once, so eight neighbours of different states give 40 320 versions.
Running a table
For each cell Golly takes the states of its neighbourhood and looks for the first transition, in file order and for each transition in the order its versions were made, whose inputs all match. Its new state is that transition’s. If no transition matches, the cell keeps its state. A table does not need to list the neighbourhoods where nothing changes. Cells in state 0 with only state 0 round them must stay 0, or the pattern would fill the plane.
Errors Golly gives
Golly stops at the first error and does not load the rule: a missing n_states, neighborhood or symmetries before the first variable or transition, n_states outside 2 to 256, an unknown neighbourhood or symmetry, symmetries before neighborhood, a state number of n_states or more, a transition with too few entries, an output that is not a state or a bound variable, a line over 4000 characters, and a variable with no states.
@TREE
A rule tree is the complete rule: for every combination of states of the neighbourhood, the new state. For n states that is n to the power of 5 (or 9) lookups, which is why it is stored as a tree with equal parts merged. Lines starting # and empty lines are ignored. Three values come first, each on a line of its own as name=value.
| Line | Meaning |
|---|---|
num_states=n | 2 to 256. |
num_neighbors=n | 4 (north, west, east, south, centre) or 8 (northwest, northeast, southwest, southeast, north, west, east, south, centre). Four is a von Neumann neighbourhood and eight a Moore one. |
num_nodes=n | The number of node lines that follow; at least num_neighbors and at most 100 million. |
| a node line | A depth from 1 to num_neighbors + 1, then exactly num_states numbers separated by spaces. At depth 1 the numbers are states; deeper, they are the numbers of earlier nodes one depth up. A node line starts with its depth in the first column. |
Nodes are numbered from 0 in the order they appear, and a node must come before it is used. The last node is the root, with depth num_neighbors + 1. To find the new state, start at the root and take the child numbered by the first neighbour in the order above, from that node the child of the next, and so on; the last step, in a depth 1 node, gives the state. The number of values in all the nodes must be num_nodes × num_states.
Golly’s errors are “Bad basic values”, “Bad line in tree data 1” (the depth), “Bad line in tree data 2” (a character that is not a digit), “Bad state value in tree data”, “Bad node value in tree data”, “Bad node pointer does not point to one level down”, “Bad number of values on tree data line”, “Bad count of values in tree data” and “Bad last node (wrong level)”.
@COLORS
Lines of numbers. Four numbers, state r g b, give a state its colour; anything after is a comment. Six numbers, r1 g1 b1 r2 g2 b2, give the live states (all except 0) a gradient from the first colour to the second. Lines that do not make sense, such as a state or colour value outside 0 to 255, are ignored without a message. Colours of states a rule does not have are ignored too; emulated rules list them.
0 48 48 48 dark gray
1 0 128 255 light blue
0 255 0 255 255 0 live states fade from green to yellow
A state with no line has the default of the algorithm: a gradient for the live states and a dark or white background, as set in Golly’s preferences.
@NAMES
Lines of a state number and a name, as in 1 electron head. Blank lines and lines starting # are ignored, and so are invalid lines and states the rule does not have. Golly shows the names beside the state selector.
@ICONS
Either one of the words circles, diamonds, hexagons or triangles on a line of its own (Golly’s built-in grey icons), or any number of XPM bitmaps. An XPM starts at a line that is just XPM. After it, lines that start with " hold strings; blank lines and lines starting # or / are ignored.
- The header string: four numbers, the width, the height, the number of colours and the characters a pixel takes (1 or 2). The width must be 7, 15 or 31, and the height a multiple of it: the icon count is the height divided by the width. Any other width and Golly skips the whole bitmap.
- One string for each colour: the character or two characters, a space,
c, a space and a colour such as#FFFFFF. - One string for each row of the bitmap, width × characters-a-pixel long.
The strings must number at least 1 + colours + height, or Golly gives an error; extra strings are ignored. The first icon is for state 1, the next for state 2, and so on; if there are fewer icons than live states the last is used for the rest, and extra icons are ignored. Icons are never used for state 0. Sizes that are missing are made by scaling a size that is given: 7 × 7 icons are drawn at scale 1:8, 15 × 15 at 1:16 and 31 × 31 at 1:32.
If every pixel of the icons is a shade of grey the icons are grey: black is transparent (the colour of state 0 shows), white takes the colour of the cell’s state, and greys blend. An icon with any other colour is multi-coloured: only black is replaced.
How Golly finds a rule file
To load rule Foo the RuleLoader looks for Foo.rule in Golly’s temporary folder (where it puts a rule found after a pattern in an RLE file, see the @RULE section of RLE), then in the user’s rules folder, then in the Rules folder Golly comes with. A file with no @TABLE or @TREE found in the user’s folder sends it on to the supplied folder, so a user can change the colours of a supplied rule with a small file. Names, colours and icons are looked up the same way, and if a file lacks them and its name has a hyphen, the file prefix-shared.rule (all the name before the last hyphen) supplies them: Worm-1042015 uses Worm-shared.
An example
Golly’s WireWorld, shortened (the notes in brackets are not in the file). State 3 is a wire, 1 an electron head and 2 its tail; the head moves along the wire. The file has six transitions, which the rotate8 symmetry turns into 48; the last four, left out here, make a wire become a head when one or two heads are beside it.
@RULE WireWorld
@TABLE
n_states:4
neighborhood:Moore
symmetries:rotate8
var a={0,1,2,3}
…
1,a,b,c,d,e,f,g,h,2 (a head becomes a tail)
2,a,b,c,d,e,f,g,h,3 (a tail becomes wire)
@COLORS
0 0 0 0 black
1 0 128 255 light blue
In the explorer
Drop a rule file on the explorer and every section is a node of the tree, and every line of it a child, grouped by what it is. A table shows its descriptors, each variable and each transition decoded (“C 2 N 0 E {2,3} … → 3”), how many transitions each line makes from bound variables and how many the symmetries make in all, in the order Golly tries them. The colours are shown as swatches, the names beside them, the icons as images, and the licence and description as text. Golly’s errors are marked on the line they belong to, with the one it stops at, and the strict reading refuses a file Golly would refuse.
The rule is run too: a rule file holds no pattern, so the picture runs a random soup, a row of cells, one cell or one cell of each state, for as many generations as the Generation option says, in the rule’s own colours. This is Golly’s rule table algorithm and its rule tree algorithm, kept in step with a port of Golly’s source that is run against Golly’s own patterns on its own rule files. The run is on the unbounded plane, or on a torus the size of the soup.
Not described
What this reference leaves out and what the viewer does not do.
Known, not yet covered
- Reference: the part of Golly that applies colours and reads icons (its application code, not the gollybase library) was not read: the colour names an XPM may use, the exact default colours of the RuleLoader and how the grey icons are blended are described from Golly’s help only.
- Reference: the rule table the help calls the “detailed specification” of the table format, and the neighbourhoods Golly emulates with its converter scripts (
RuleTableToTree.pyand the tools inRules/TableGeneratorsandRules/TreeGenerators), are not described. A newer Golly may add neighbourhoods to the four read here. - Viewer: the icons are shown as the file draws them, not blended with the state colours as Golly does. A rule is run only from its own file: a pattern that names a rule file Golly keeps in its Rules folder is not run in the RLE viewer.
- Viewer: the run uses the plane and the plain torus; bounded grids with shifted or twisted edges and a grid unbounded in one direction are not run for table rules.
Other Game of Life pattern formats
- Golly RLE pattern (.rle) – run-length encoded cells with a rule, the usual way to share patterns
- Golly macrocell (.mc) – a universe as a quadtree, for patterns of astronomical size
- MCell pattern (.mcl) – the format of the MCell program
- Plaintext pattern (.cells) – cells drawn as text, a dot for dead and O for alive
Links
Software
- Golly – free Game of Life and cellular automata program that loads rule files (Windows, macOS, Linux)
Developers
- Golly source mirror – the C++ of the RuleLoader:
ruleloaderalgo.cpp,ruletable_algo.cppandruletreealgo.cppingollybase(C++)
Reference
- Golly file formats – Golly’s description of the sections of a rule file