Golly uses a statically embedded Lua interpreter (version 5.4.6) to execute .lua scripts. This lets you extend Golly's capabilities in lots of interesting ways.

 
Example scripts

The Scripts folder supplied with Golly contains a number of example Lua scripts:

To run one of these scripts, tick the Show Files item in the File menu, open the Scripts/Lua folder and then simply click on the script's name. You can also select one of the Run items in the File menu. For a frequently used script you might like to assign a keyboard shortcut to run it (see Preferences > Keyboard).

When Golly starts up it looks for a script called golly-start.lua in the same directory as the Golly application and then in a user-specific data directory (see the getdir command for the likely path on your system). If the script is found then it is automatically executed.

There are a number of ways to abort a running script. Hit the escape key, or click on the stop button in the tool bar, or select the Stop item in the Control menu.

 
Golly's scripting commands

This section describes all the g.* commands that can be used in a script after including this line:

Commands are grouped by function (filing, editing, control, viewing, layers and miscellaneous) or you can search for individual commands alphabetically:

 
FILING COMMANDS

 
EDITING COMMANDS

 
CONTROL COMMANDS

 
VIEWING COMMANDS

 
LAYER COMMANDS

 
MISCELLANEOUS COMMANDS

 
Cell arrays

Some scripting commands manipulate patterns in the form of cell arrays. Golly supports two types of cell arrays: one-state and multi-state. A one-state cell array contains an even number of integers specifying the x,y coordinates for a set of cells, all of which are assumed to be in state 1:

A multi-state cell array contains an odd number of integers specifying the x,y,state values for a set of cells. If the number of cells is even then a padding integer (zero) is added at the end of the array to ensure the total number of integers is odd:

All scripting commands that input cell arrays use the length of the array to determine its type. When writing a script to handle multi-state cell arrays you may need to allow for the padding integer, especially if accessing cells within the array. See tile.lua for example.

Note that all scripting commands return {} if the resulting cell array has no cells. They never return {0}, although this is a perfectly valid multi-state cell array and all commands can input such an array. For example, newarray = g.join(array1,{0}) can be used to convert a non-empty one-state array to multi-state.

One-state cell arrays are normally used in a two-state universe, but they can also be used in a universe with more than two states. A multi-state cell array can be used in a two-state universe, but only if the array's cell states are 0 or 1.

The ordering of cells within either type of array doesn't matter. Also note that positive y values increase downwards in Golly's coordinate system.

 
Rectangle arrays

Some commands manipulate rectangles in the form of arrays. An empty rectangle is indicated by an array with no items; ie. {}. A non-empty rectangle is indicated by an array containing four integers:

The first two items specify the cell at the top left corner of the rectangle. The last two items specify the rectangle's size (in cells). The width and height must be greater than zero.

 
Using the gplus package

The gplus package supplied with Golly provides a high-level interface to many of Golly's built-in scripting commands. The package consists of a set of .lua files stored in the Scripts/Lua/gplus directory. The best way to learn how to use gplus is to look at some of the scripts supplied with Golly:

• See bricklayer.lua for how to use the pattern function to contruct a complicated pattern by combining simpler sub-patterns.
• See invert.lua for how to use the rect function to make it easier to manipulate rectangles.
• See p1100-MWSS-gun.lua for an extended example of an efficient script representation of a large complex pattern. This uses the pattern function to place different phases and orientations of each component object, and the put function to populate the resulting structure with spaceships.
• See shift.lua for how to use the split and validint functions to parse user input.

Here's a summary of the functions available after a script calls local gp = require "gplus" (see init.lua for all the implementation details):

Most of the supplied Lua scripts use gplus, but it isn't compulsory. You might prefer to create your own package for use in the scripts you write. If a script calls require "foo" then Golly will look for foo.lua in the same directory as the script, then it looks for foo/init.lua. If a script calls require "foo.bar" then Golly looks for foo/bar.lua. (If none of those files exist in the script's directory then Golly will look in the supplied Scripts/Lua directory, so scripts can always use the gplus package no matter where they are located.)

 
NewCA.lua

NewCA.lua is a gplus module that can be used by other Lua scripts to explore new cellular automata rules. To implement a new CA you need to create a .lua file that looks something like this:

local g = golly()
require "gplus.NewCA"

SCRIPT_NAME = "MyCA"    -- must match the name of your .lua file
DEFAULT_RULE = "XXX"    -- must be a valid rule in your CA
RULE_HELP = "HTML code describing the rules allowed by your CA."

function ParseRule(newrule)
    -- Parse the given rule string.
    -- If valid then return nil, the canonical rule string,
    -- the width and height of the grid, and the number of states.
    -- If not valid then just return an appropriate error message.

    ... parsing code for your rule syntax ...

    return nil, canonrule, wd, ht, numstates
    -- Note that wd and ht must be from 4 to 4000,
    -- and numstates must be from 2 to 256.
end

function NextPattern(currcells, minx, miny, maxx, maxy)
    -- Create the next pattern using the given parameters:
    -- currcells is a non-empty cell array containing the current pattern.
    -- minx, miny, maxx, maxy are the cell coordinates of the grid edges.
    -- This function must return the new pattern as a cell array.

    local newcells = {}

    ... code to create the next pattern in newcells ...

    -- delete the current pattern and add the new pattern
    g.putcells(currcells, 0, 0, 1, 0, 0, 1, "xor")
    g.putcells(newcells)

    return newcells
    -- Note that currcells and newcells are one-state cell arrays if
    -- g.numstates() == 2, otherwise they are both multi-state.
end

StartNewCA()

It should be possible to implement almost any CA that uses square cells with up to 256 states. NewCA.lua provides a lot of useful functionality:

• The interface is essentially the same as Golly. The only really new feature is a combined menu+tool bar that appears under the edit bar. It has some menus (File, Edit, View) on the left side and various buttons (Start, Reset, etc) on the right side, along with a slider for controlling the step size.
• Full Golly-like editing (cut/copy/paste/select/etc) including unlimited undo/redo. All of Golly's usual cursor modes are supported.
• Patterns can be saved as .rle files. These files can be opened via the File menu's Open Pattern command. You can also open a pattern stored in the clipboard via the Open Clipboard command (or by typing shift-O).
• Users can get help in various ways (type H or click the "?" button) and see documentation about the required rule syntax, the menu commands, a list of all the keyboard shortcuts, etc.
• Your script can run other Lua scripts to do searches, build patterns, etc. In particular, users can specify a script to be run whenever your script starts up. A startup script can do lots of customizations (add/modify keyboard shortcuts, change the color scheme, specify a different DEFAULT_RULE, add aliases for specific rules, etc).

There is of course a price to pay for all this flexibility, and that's speed. Don't expect your CA to run at Golly-like speeds! It won't really be practical to write a CA that supports very large neighborhoods (7x7 is about the limit).

To implement a new CA you'll typically need to write a couple of hundred lines of Lua code to parse the rule strings allowed by your CA and to calculate the next pattern. To help with this task, a couple of example scripts are supplied with Golly:

1D.lua lets you explore some one-dimensional rules. It supports all of Stephen Wolfram's 256 elementary rules (including the odd numbers), as well as totalistic rules with up to 4 states and a maximum range of 4.

The syntax for elementary rules is Wn where n is from 0 to 255. Totalistic rules are strings of the form CcKkRr where c is a code number from 0 to k^((2r+1)k-2r)-1, k is the number of states (2 to 4), and r is the range (1 to 4).

The ParseRule code sets NextPattern to either NextElementary or NextTotalistic, depending on the given rule. This is a useful technique that avoids the code in NextPattern becoming way too big and complicated.

1D.lua always generates from the bottom row of the current pattern. When it reaches the bottom row of the grid, it clears the grid, copies the bottom row to the top of the grid, and continues.

SetColors is redefined to use the same color scheme as in Wolfram's "A New Kind of Science". Note that the SetColors function uses g.setcolor commands to change the grid border and the status bar background to light blue.

1D.lua also redefines the RandomPattern function to create a single row of random cells at the top of the grid.

Margolus.lua lets you explore rules using the Margolus neighborhood. Rule strings are of the form Mn,n,n,... where there must be 16 comma-separated numbers with values from 0 to 15. MCell's syntax (MS,Dn;n;n;...) is also allowed, as are these aliases:

The ParseRule code sets NextPattern to either FastPattern or SlowPattern, depending on the given rule. FastPattern is used if the rule starts with M0, or if it starts with M15 and ends with 0. To avoid ugly strobing effects in the latter case, two alternating rules will be used: one rule for even-numbered generations and another rule for odd-numbered generations (similar to how Golly handles B0 rules).

The above two scripts have a number of features in common:

• Users can hit alt-R (option-R on a Mac) to create a random pattern with a random rule. This makes it easy to search for rules with interesting behavior.
• Both scripts use a toroidal grid with a default size of 500 x 500. For consistency with Golly, all rule strings can have an optional suffix like ":T400,300" or ":T400" to specify a desired grid size. (It's perfectly possible to support other topologies but you'd have to write a lot of messy code.)
• The ParseRule code allows entering an empty string as a quick way to switch to the default rule.
• Letters in a given rule can be entered in lower case, but the canonical version always uses upper case.
• Both scripts define a global aliases table so you can assign mnemonic names to specific rule strings.

It's probably a good idea to support these features in any new CA you might write, but it's not compulsory.

 
Potential problems

1. There are some important points to remember about Lua, especially if converting an existing Python script to Lua:

• Cell arrays and rectangle arrays start with index 1, not 0. This is necessary to be able to use Lua's length operator (#) and standard library functions like table.unpack.
• Lua's true and false are not equivalent to 1 and 0. In particular, "if 0" is true.
• Avoid calls like local x, y, wd, ht = g.getrect(). Only x will get a non-nil value (a rectangle array). You need to do local x, y, wd, ht = table.unpack(g.getrect()).
• When writing a complicated script it's a good idea to add the line require "gplus.strict" near the top. This will catch any undeclared global variables. When the script is working just remove or comment out that line.

More tips can be found at Lua Gotchas.

2. The escape key check to abort a running script is not done by Lua but by each g.* function. This means that very long Lua computations should call an occasional "no-op" like g.doevent("") to allow the script to be aborted in a timely manner.

3. When writing a script that creates a pattern, make sure the script starts with a new call (or, less useful, an open call that loads a pattern, or a save call) otherwise the script might create lots of temporary files or use lots of memory. From Golly's point of view there are two types of scripts:

• A script that calls new or open or save is assumed to be creating some sort of pattern, so when Golly sees these calls it clears any undo history and sets an internal flag that says "don't mark this layer as dirty and don't bother recording any further changes".
• A script that doesn't call new or open or save is assumed to modify the current pattern. Golly must record all the script's changes so that when it finishes you can select "Undo Script Changes" from the Edit menu. Generating changes (due to run or step calls) are stored in temporary files; all other changes are stored in memory.

 
Lua copyright notice

Copyright © 1994–2022 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.