Here are the important file formats used by Golly:
Golly prefers to store patterns and pattern fragments in a simple concise textual format we call "Extended RLE" (it's a modified version of the RLE format created by Dave Buckingham). The data is run-length encoded which works well for sparse patterns while still being easy to interpret (either by a machine or by a person). The format permits retention of the most critical data:
Golly uses this format for internal cuts and pastes, which makes it very convenient to move cell configurations to and from text files. For instance, the r-pentomino is represented as
I just drew this pattern in Golly, selected the whole thing, copied it to the clipboard, and then in my editor I did a paste to get the textual version. Similarly, data in this format can be cut from a browser or email window and pasted directly into Golly.
RLE data is indicated by a file whose first non-comment line starts with "x". A comment line is either a blank line or a line beginning with "#". The line starting with "x" gives the dimensions of the pattern and usually the rule, and has the following format:
where width and height are the dimensions of the pattern and rule is the rule to be applied. Whitespace can be inserted at any point in this line except at the beginning or where it would split a token. The dimension data is ignored when Golly loads a pattern, so it need not be accurate, but it is not ignored when Golly pastes a pattern; it is used as the boundary of what to paste, so it may be larger or smaller than the smallest rectangle enclosing all live cells.
Any line that is not blank, or does not start with a "#" or "x " or "x=" is treated as run-length encoded pattern data. The data is ordered a row at a time from top to bottom, and each row is ordered left to right. A "$" represents the end of each row and an optional "!" represents the end of the pattern.
For two-state rules, a "b" represents an off cell, and a "o" represents an on cell. For rules with more than two states, a "." represents a zero state; states 1..24 are represented by "A".."X", states 25..48 by "pA".."pX", states 49..72 by "qA".."qX", and on up to states 241..255 represented by "yA".."yO". The pattern reader is flexible and will permit "b" and "." interchangeably and "o" and "A" interchangeably.
Any data value or row terminator can be immediately preceded with an integer indicating a repetition count. Thus, "3o" and "ooo" both represent a sequence of three on cells, and "5$" means finish the current row and insert four blank rows, and start at the left side of the row after that.
The pattern writer attempts to keep lines about 70 characters long for convenience when sharing patterns or storing them in text files, but the reader will accept much longer lines.
If the File menu's "Save Extended RLE" option is ticked then comment lines with a specific format will be added at the start of the file to convey extra information. These comment lines start with "#CXRLE" and contain keyword/value pairs. The keywords currently supported are "Pos", which denotes the absolute position of the upper left cell (which may be on or off), and "Gen", which denotes the generation count. For instance,
indicates that the upper left corner of the enclosing rectange is at an X coordinate of 0 and a Y coordinate of -1377, and that the pattern stored is at generation 3,480,106,827,776.
All comment lines that are not CXRLE lines, and occur at the top or bottom of the file, are treated as information lines and are displayed when the user clicks the "information" button in Golly's tool bar. Any comment lines interspersed with the pattern data will not be displayed.
The size of an Extended RLE file is frequently proportional to the number of cells it contains, yet Golly supports universes that can contain trillions of cells or more, using hashlife-based algorithms. The storage of these huge universes, for which Extended RLE is not feasible, is done by essentially dumping the in-memory compressed representation of the universe in "Macrocell format". Since little translation need be done between external and internal representation, this format is also used to store backups of universes at certain points in Golly's operation when using one of the hashlife-based algorithms.
The macrocell format has two parts: the header, and the tree. The first portion of the file is the header; this contains the format identifier, the rule, the generation count (if non-zero), and any comments associated with this file. The format identifier is a line that starts with "[M2]" and contains the name and version of the program used to write it:
Following this is any comment lines, which are lines that begin with '#'. If the first two characters of a line are '#R', then the remainder of the line (after intervening whitespace) is the rule for the pattern. If the first two characters are '#G', then the remainder of the line is the current generation count. Any other line starting with a '#' is treated as an ordinary comment line.
Following the header is is a child-first textual representation of a canonicalized quadtree. Each line is either a leaf node, or a non-leaf node. For two-state algorithms, the leaf nodes contain an 8x8 pixel array in a simplified raster format, left-to-right, then top-down, with "." representing an empty cell, "*" representing a live cell, and "$" representing the end of line; empty cells at the end of each row are suppressed. No whitespace is permitted; lines representing leaf nodes for two-state algorithms are recognized because they start with ".", "*", or "$". A sample leaf node containing a glider is:
For algorithms with more than two states, leaf nodes represent a two-by-two square of the universe. They contain five integers separated by single spaces; the first integer is 1, and the next four are the state values for the northwest, northeast, southwest, and southeast values of the square.
Nodes with children are represented by lines with five integers. The first integer is the logarithm base 2 of the size of the square this node representes; for two-state patterns, this must be 4 or larger; for multi-state patterns, this must be 2 or larger. The next four values are the node numbers of the northwest, northeast, southwest, and southeast child nodes. Each of these child nodes must be the appropriate size; that is, a square one fourth the area of the current node.
All nodes, both leaf and non-leaf, are numbered in the order they occur in the file, starting with 1. No node number can point to a node that has yet been defined. The special node number "0" is used to represent all squares that have no live cells.
The total universe represented by a macrocell file is that of the last node in the file (the root node), which also must be the single node with the largest size. By convention, the upper left cell of the southeast child of the root node is at coordinate position (x=0,y=1).
Macrocell files saved from two-state algorithms and from multi-state algorithms are not compatible.
A .rule file contains all the information about a rule: its name, documentation, table/tree data (used by the RuleLoader algorithm), and any color/icon information. The .rule format is textual and consists of one or more sections. Each section starts with a line of the form @XXX... where X is an uppercase letter. If there is more than one section with the same name then only the first one is used. Any unrecognized sections are silently ignored (this will allow us to add new sections in the future without breaking old versions of Golly).
The currently recognized sections are described below. You might like to refer to WireWorld.rule while reading about each section.
This is the only mandatory section. The first line of a .rule file must start with @RULE followed by a space and then the rule name. For example:
The supplied rule name must match exactly the name of the .rule file. This helps Golly to avoid problems that can occur on case-sensitive file systems. When naming a new rule it's best to stick to the following conventions, especially if you'd like to share the .rule file with other Golly users:
After the @RULE line and before the next section (or end of file) you can include any amount of arbitrary text, so this is the place to include a description of the rule or any other documentation. If the .rule file has a @TREE section then this is a good place to put the Python transition function that was used to create the tree data.
This section is optional. If present, it contains a transition table that can be loaded by the RuleLoader algorithm. The contents of this section is identical to the contents of a .table file. A detailed specification of the .table format is available here. This is a simple example:
Empty lines and anything following the hash symbol "#" are ignored. The following descriptors must appear before other content:
After the descriptors comes the variables and transitions. Each variable line should follow the form given in the above example to list the states. Variables should appear before the first transition that uses them. Variables can be used inside later variables.
Transition lines should have states or variables separated by commas. If there are no variables and n_states is less than 11 then the commas can be omitted. Only one transition (or variable) should appear on each line. Inputs are listed in the order C,N,E,S,W,C' for the von Neumann neighborhood, C,N,NE,E,SE,S,SW,W,NW,C' for the Moore neighborhood, C,N,E,SE,S,W,NW,C' for the hexagonal neighborhood, and C,W,E,C' for the oneDimensional neighborhood.
Where the same variable appears more than once in a transition, it stands for the same state each time. For example, the transition in the example above expands to the following: 20212->2, 20213->2, 20312->3, 20313->3, 30212->2, 30213->2, 30312->3, 30313->3, and all 90-degree rotations of those (because of the rotate4 symmetry).
A transition can have a variable as its output (C') if that variable appears more than once in the transition (as in the example above), so that it has a definite value.
Rule tables usually don't specify every possible set of inputs. For those not listed, the central cell remains unchanged.
Transition rules are checked in the order given — the first rule that matches is applied. If you want, you can write rules in the form of general cases and exceptions, as long as the exceptions appear first.
(This form of CA rule table representation was inspired by that in Gianluca Tempesti's PhD thesis: http://lslwww.epfl.ch/pages/embryonics/thesis/AppendixA.html.)
If you have a C/C++ implementation of a transition function, there is a way to automatically produce a rule table. See Rules/TableGenerators/make-ruletable.cpp for instructions.
To share your rule tables with others, you can archive them at the public Rule Table Repository.
This section is optional. If present, it contains a rule tree that can be loaded by the RuleLoader algorithm. (If the .rule file also contains a @TABLE section, RuleLoader will use the first one it finds.) The contents of this section is identical to the contents of a .tree file.
A detailed description of a rule tree is provided below, but most people don't need to know these details because Golly provides a number of tools for creating rule trees. The make-ruletree.py script in Scripts/Python/Rule-Generators can convert a Python transition function (passed via the clipboard) into a rule tree. The script will either create a new .rule file or update the @TREE section in an existing .rule file. Another script, RuleTableToTree.py, does much the same job using a requested .table file as input.
Golly also includes programs that permit you to transform a given transition function in C++, Lua, Python, Perl, or Java into a .tree file (see Rules/TreeGenerators) if the number of states is sufficiently small (approximately 10 states for eight-neighbor rules, and 32 states for four-neighbor rules). The contents of the .tree file can then be copied into the @TREE section of your .rule file.
Essentially, the tree format allows you to add your own rules to Golly without needing to know how to recompile Golly and without dealing with the intricacies of external libraries; it generates relatively compact files, and the data structure is designed for very fast execution.
A rule tree is nothing more than a complete transition table for a rule, expressed in a compressed, canonicalized tree format. For an n state rule, each tree node has n children; each child is either another tree node or a next state value. To look up a function of m variables, each of which is a state value, you start at the root node and select the child node corresponding to the value of the first variable. From that node, you select the child node corresponding to the value of the second variable, and so on. When you finally look up the value of the final variable in the last node, the result value is the actual next state value, rather than another node.
The tree format has fixed the order of variables used for these lookups. For a four-neighbor rule, the order is always north, west, east, south, center; for an eight-neighbor rule, the order is always northwest, northeast, southwest, southeast, north, west, east, south, center.
Without compression, for an n-state rule, there would be a total of 1+n+n^2+n^3+n^4 nodes for a four-neighbor rule, and 1+n+...+n^8 for an eight-neighbor rule; this could quickly get unmanageable. Almost all rules show significant redundancy, with identical rows in the transition table, and identical nodes in the rule tree. To compress this tree, all we do is merge identical nodes, from the bottom up. This can be done explicitly as we construct the tree from a transition function (see Rules/TreeGenerators/RuleTreeGen.java) or symbolically as we evaluate a more expressive format.
The tree format itself is simple, and has similarities to the macrocell format. It is not intended for human authorship or consumption. The tree format has two parts: a header, and the rule tree itself. The header consists of comments (lines starting with a "#") that are ignored, and three required parameter values that must be defined before the first tree node. These values are defined, one per line, starting with the parameter name, then an equals sign, and finally an integer value. The three parameters are num_states, which must be in the range 2..256 inclusive, num_neighbors, which must be 4 or 8, and num_nodes, which must match the number of node lines.
The tree is represented by a sequence of node lines. Each node line consists of exactly num_states+1 integers separated by single spaces. The first integer of each node line is the depth of that node, which must range from 1..num_neighbors+1. The remaining integers for nodes of depth one are state values. The remaining integers for nodes of depth greater than one are node numbers. Nodes are numbered in the order they appear in the file, starting with zero; each node must be defined before its node number is used. The root node, which must be the single node at depth num_neighbors+1, must be the last node defined in the file.
This section is optional and can be used to specify the RGB colors for one or more states using lines with 4 numbers, like these:
Golly silently ignores any states that are invalid for the rule. To specify a color gradient for all live states (all states except 0) you can use a line with 6 numbers, like this:
In both cases, any text after the final number on each line is ignored. Blank lines or lines starting with "#" are also ignored.
Note that a .rule file is loaded after switching to the current algorithm's default color scheme, so you have the choice of completely changing all the default colors, or only changing some of them. Use Preferences > Color to change the default colors for each algorithm.
This section is optional and can be used to override the default icons displayed for this rule (when Golly is in icon mode).
Icon bitmaps can be specified using a simple subset of the XPM format. Here's a small example that describes two 7x7 icons suitable for a 3-state rule (icons are never used for state 0):
Any blank lines or lines starting with "#" or "/" are ignored. A line with XPM by itself indicates the start of a set of icon bitmaps at a particular size. The @ICONS section can contain any number of XPM subsections, and their order is not important. Three different icon sizes are currently supported: 7x7, 15x15 and 31x31 (for displaying at scales 1:8, 1:16 and 1:32 respectively). Any missing icon sizes will be created automatically by scaling a supplied size. Scaled icons can look rather ugly, so if you want good looking icons it's best to supply all three sizes.
After seeing an XPM line, Golly then looks for lines containing strings delimited by double quotes. The first double quote must be at the start of the line (any text after the second double quote is ignored). The first string contains crucial header information in the form of 4 positive integers:
The total number of strings after the XPM line should be 1 + num_colors + height. You'll get an error message if there aren't enough strings. Any extra strings are ignored.
The 1st icon specified is for state 1, the 2nd is for state 2, etc. If the number of icons supplied is fewer than the number of live states then the last icon is automatically duplicated. If there are more icons than required then the extra icons are simply ignored.
Grayscale icons or multi-color icons
Golly recognizes two types of icons: grayscale or multi-color. Grayscale icons only use shades of gray (including black and white), as in the above example. Any black areas will be transparent; ie. those pixels will be replaced by the color for state 0. White pixels will be replaced by the color for the cell's current state. Gray pixels are used to do anti-aliasing; ie. the darker the gray the greater the transparency. Using grayscale icons minimizes the amount of XPM data needed to describe a set of icons, especially if the icons use the same shape for each state (as in WireWorld.rule).
If a set of icons contains at least one color that isn't a shade of gray (including black or white) then the icons are said to be multi-colored. Any black pixels are still converted to the state 0 color, but non-black pixels are displayed without doing any substitutions.
If you want to use multi-colored icons then you'll probably want a @COLORS section as well so that the non-icon colors match the icon colors as closely as possible. For example, if the icon for state 1 consists of red and blue triangles then it would be best to set the color of state 1 to purple in the @COLORS section. This minimizes "color shock" when switching between icon and non-icon display mode.
Instead of specifying icon bitmaps using XPM data, you might prefer to use Golly's built-in grayscale icons by supplying one of the following words on a line by itself:
One way to create XPM icons is to use a painting application that can write .xpm files. Their contents can then be pasted into a .rule file with a small amount of editing.
Another way is to use two Python scripts called icon-importer.py and icon-exporter.py (both can be found in Scripts/Python/Rule-Generators). These scripts allow Golly to be used as an icon editor. Here's how:
Step 1: Switch to the rule whose icons you wish to change or create and then run icon-importer.py. This will create a new layer called "imported icons for rulename" (the name will be used by icon-exporter.py, so don't change it). The script searches for rulename.rule in your rules folder, then in the supplied Rules folder. If found, it extracts any @ICONS data and displays the icon bitmaps in gray boxes. The location of these boxes will be used by icon-exporter.py, so don't move them.
If the @ICONS data is missing icons at a particular size then the script creates them by scaling up or down an existing set of icons. For example, missing 31x31 icons will be created by scaling up the 15x15 icons.
The new layer uses a Generations rule with the maximum number of states (//256) so we can have lots of colors. The initial palette contains a grayscale gradient from white to black, followed by the colors used in the imported icons (if any), followed by three rainbow gradients (bright, pale, dark). You can change these colors by using Layer > Set Layer Colors.
Step 2: Edit the icon bitmaps using Golly's editing capabilities. Golly isn't as powerful as a full-blown painting app, but hopefully it's sufficient for such small images.
Step 3: When you've finshed editing, run icon-exporter.py. This script will extract the icon data and create a suitable @ICONS section in rulename.rule in your rules folder (the script will never create or modify a .rule file in the supplied Rules folder). If rulename.rule already exists in your rules folder then the script replaces any existing @ICONS section (and any @COLORS section if the icons are multi-color) so it won't clobber any other info in the file.
If rulename.rule doesn't exist in your rules folder then it will be created. This file won't have any @TABLE or @TREE section, but that's perfectly valid. It means either the rule is built-in (ie. recognized by a non-RuleLoader algorithm), or else rulename.rule also exists in the supplied Rules folder and so the RuleLoader algorithm will use that file when it can't find any @TABLE or @TREE section in the .rule file in your rules folder.
Finally, icon-exporter.py creates a new layer called "icon test" which uses the original rule and displays a simple pattern containing all live states so you can check what the new icons look like.
There are two situations where Golly needs to look for a .rule file:
1. If the RuleLoader algorithm is asked to switch to a rule called "Foo" then it first looks for Foo.rule in your rules folder. If not found, or if Foo.rule has no @TABLE or @TREE section, it will then look for Foo.rule in the supplied Rules folder. If Foo.rule doesn't exist then it will use the same search procedure to look for Foo.table, then Foo.tree.
2. After switching to a new rule (not necessarily using RuleLoader), Golly needs to look for color and/or icon information specific to that rule. A similar search procedure to the one above is used again, where this time Golly looks for any @COLORS and/or @ICONS sections in Foo.rule. (Unlike the above search, if Foo.rule is found in your rules folder but doesn't have any color/icon info then Golly will not look for Foo.rule in the Rules folder.)
Note that the 2nd search always occurs after clicking OK in the Control menu's Set Rule dialog, even if the current rule wasn't changed. This is a quick way to test changes to a .rule file.
Related rules can share colors and/or icons
If rulename.rule is missing either the @COLORS or @ICONS section, Golly checks to see if rulename contains a hyphen. If it does then it looks for the missing color/icon data in another .rule file called prefix-shared.rule where prefix consists of all the characters before the final hyphen. (As in the above searches, it looks in your rules folder first, then in the supplied Rules folder.) This allows related rules to share a single source of colors and/or icons.
For example, suppose you have a set of related rules in files called Foo-1.rule, Foo-2.rule, etc. If you want all these rules to use the same colors then create a file called Foo-shared.rule:
Note that a shared .rule file should contain a valid @TABLE section with an appropriate value for n_states (the neighborhood setting doesn't really matter, as long as it's legal). This allows the RuleLoader algorithm to load it, which means you can switch to the Foo-shared rule in case you want to add/edit icons using icon-importer.py.
For another good example, see Worm-shared.rule in Golly's Rules folder. It contains the icons shared by all the other Worm-* rules.
How to override a supplied or built-in rule
The search procedure described above makes it easy to override a supplied .rule file, either completely or partially. Note that there is never any need to add or modify files in the supplied Rules folder. For example, if you want to override the colors and icons used in the supplied WireWorld.rule then you can create a file with the same name in your rules folder. Its contents might look like this:
It's also possible to override a built-in rule (ie. a rule recognized by an algorithm other than RuleLoader). A built-in rule name can contain characters not allowed in file names ("/" and "\"), so Golly will substitute those characters with underscores when looking for the corresponding .rule file. For example, if you want to change the colors and/or icons for Life (B3/S23) then you'll need to create a file called B3_S23.rule. This example uses a multi-colored icon to show a blue sphere on a white background:
The easy way to install a new .rule file
Golly provides a quick and easy way to create a new .rule file in the right place. Simply copy the rule contents to the clipboard, then select the Open Clipboard command (in the File menu) or the Paste command (in the Edit menu). If the first line of the clipboard starts with "@RULE rulename" then Golly will save the text as rulename.rule in your rules folder and switch to that rule.
Deprecated files (.table, .tree, .colors, .icons)
Golly still supports the old rule-related files with extensions of .table, .tree, .colors and .icons, but their use is discouraged. To help speed up the transition to .rule files, Golly has a couple of handy features:
1. At the bottom of the Control menu is a new command called Convert Old Rules. This will convert all .table/tree/colors/icons files into corresponding .rule files (but existing .rule files will not be changed). The results are displayed in the help window. If the conversion succeeds you'll be asked if you want to delete the .table/tree/colors/icons files.
2. When Golly opens a .zip file containing .table/tree/colors/icons files it will automatically convert them into .rule files, but only if the zip file has no .rule files. Unlike the Convert Old Rules command, this conversion will overwrite existing .rule files (in case the zip file contents have changed).
Golly can open a standard zip file and process its contents in the following way:
If the zip file is "complex" then Golly builds a temporary HTML file with special unzip links to each included file and shows the result in the help window. A complex zip file is one that contains:
A "simple" zip file contains at most one pattern and at most one script. In this case Golly will load the pattern (if present) and then run the script (if present). For security reasons, if the zip file was downloaded via a get link then Golly will ask if you really want to run the included script. Both the pattern and the script must be at the root level of the zip file; ie. not inside a folder. For an example of such a zip file, open Langtons-ant.zip from the Patterns/WireWorld/ folder. This zip file contains a pattern file and a simple Lua script that sets up a nicer initial view and step size.
A number of pattern collections in the form of zip files can be downloaded from the online archives.