  Introduction
  Keyboard Shortcuts
  Mouse Controls
  Script Commands
  Camera Tracking
  Color Themes
  3D Layers
  Hex Grid
  Notes

Introduction

LifeViewer is a scriptable pattern viewer featuring:

- Rotation and smooth non-integer zoom.
- Color themes with cell history and longevity.
- Automatic hex grid display.
- Pseudo 3D layers and stars.
- Multiple ways to automatically track patterns with the camera as they evolve.

You may find it convenient to bind LifeViewer to a Keyboard action in Golly. This can be done as follows:

1. Open Golly's Preferences dialog with File->Preferences...
2. Click on the Keyboard tab in the dialog
3. In the Key Combination field enter your preferred key combination
4. In the Action drop down select Run Script...
5. Click on the Choose File... button and select "lifeviewer.lua"
6. Click on OK

A Javascript/HTML5 version of LifeViewer is used on the conwaylife.com forums to display posted patterns and also on LifeWiki.

Keyboard Shortcuts

Key combination | Action
--- | ---
Playback controls
Return | Toggle play / pause.
Space | Pause / next generation.
Tab | Pause / next step.
Esc | Close LifeViewer.
R | Reset to generation 0. Reset at generation 0 also resets camera.
Shift R | Toggle hard reset mode.
- | Decrease generation speed.
+ | Increase generation speed.
Shift - | Minimum generation speed.
Shift + | Maximum generation speed.
D | Decrease generations per step.
E | Increase generations per step.
Shift D | Minimum generations per step.
Shift E | Maximum generations per step.
0 | Reset step size and generation speed.
Camera controls
F | Fit pattern to display.
Shift F | Toggle AUTOFIT.
Shift H | Toggle HISTORYFIT mode.
[ | Zoom out.
] | Zoom in.
Shift [ | Halve zoom.
Shift ] | Double zoom.
1 | 1x zoom.
2 | 2x zoom.
4 | 4x zoom.
8 | 8x zoom.
6 | 16x zoom.
3 | 32x zoom.
Shift 1 | Nearest integer zoom.
Shift 2 | -2x zoom.
Shift 4 | -4x zoom.
Shift 8 | -8x zoom.
Shift 6 | -16x zoom.
Left | Pan left.
Right | Pan right.
Up | Pan up.
Down | Pan down.
Shift Left | Pan north west.
Shift Right | Pan south east.
Shift Up | Pan north east.
Shift Down | Pan south west.
< | Rotate left.
> | Rotate right.
Shift < | Rotate left 90 degrees.
Shift > | Rotate right 90 degrees.
5 | Reset angle.
View controls
Q | Increase number of layers.
A | Decrease number of layers.
P | Increase layer depth.
Q | Decrease layer depth.
C | Cycle color theme.
T | Toggle timing display.
Shift T | Toggle extended timing information.
Shift C | Toggle theme / Golly's standard colors.
/ | Toggle hex grid.
S | Toggle stars.
X | Toggle grid lines.
Shift X | Toggle major grid lines.

Mouse Controls

Click and drag with the mouse to pan the view.

The mouse wheel can be used to zoom in or out of the pattern. The zoom will be centered on the mouse pointer.

Script Commands

LifeViewer contains a script language that allows you to control playback of a pattern and how it is viewed through a dynamic camera. You can use the script language to do things like:

- Define how you want a pattern to be displayed when LifeViewer starts.
- Specify whether the pattern should automatically start playing when LifeViewer starts.
- Specify that playback should stop or loop back to the start on reaching a certain generation.
- Have the camera track a pattern as it moves across the universe (good for spaceships).
- Define a set of waypoints and have the camera follow them during playback to highlight interesting parts of your pattern.

Script commands must be embedded in pattern comments which means that you can add them to any pattern file and other pattern readers will happily ignore them. They should be enclosed in [[ and ]]. All commands must be surrounded by whitespace. Multiple script sections are allowed.

The pattern below contains script commands that mean when LifeViewer is started the pattern will be displayed at zoom 9.5 with a camera angle of 30 degrees. The pattern will automatically start running and then stop at generation 100.

    #C [[ ZOOM 9.5 ANGLE 30 ]]
    #C [[ AUTOSTART STOP 100 ]]
    x = 3, y = 3, rule = Life
    ooo$
    bbo$
    bo!

To see this in action:

1. Stop LifeViewer if it is running (click on the Golly window and press Esc).
2. Copy the pattern above to the clipboard.
3. Use File->Open Clipboard in Golly.
4. Run Scripts/Lua/lifeviewer.lua.

There are many script commands available and they are grouped by function in the table below.

Command | Arguments | Action
--- | --- | ---
Script commands
[[ |  | Start script section.
]] |  | End script section.
Playback commands
AUTOSTART |  | Start play automatically.
GPS | <1..60> | Set steps per second.
LOOP | <1..> | Loop at specified generation.
HARDRESET |  | Reset always resets camera.
STEP | <1..50> | Set generations per step.
STOP | <1..> | Stop at specified generation.
Camera commands
ANGLE | <0.0..359.9> | Set camera angle.
AUTOFIT |  | Fit pattern to display.
HISTORYFIT |  | Modify AUTOFIT to use pattern history.
TRACK | X Y | Camera moves at (X, Y) cells/generation.
TRACKBOX | E S W N | Camera tracks bounding box with E, S, W and N edges moving at defined cells/generation.
TRACKLOOP | P X Y | Camera moves at (X, Y) cells/generation and playback loops at generation P.
X | <-4096.0..4096.0> | Set camera pan in X direction.
Y | <-4096.0..4096.0> | Set camera pan in Y direction.
ZOOM or Z | <-16.0..32.0> | Set camera zoom. Negative zooms can also be specified as decimals or fractions: ZOOM -4 = ZOOM 0.25 = ZOOM 1/4.
View commands
DEPTH | <0.0..1.0> | Set layer depth.
EXTENDEDTIMING |  | Show extended timing information when displayed.
GRID |  | Display grid lines.
GRIDMAJOR | <0..16> | Set major grid line interval (0 = off).
HEXDISPLAY |  | Force hex grid display.
LAYERS | <1..10> | Set number of layers.
SQUAREDISPLAY |  | Force square grid display.
STARS |  | Display stars.
SHOWTIMING |  | Show timing information.
THEME | <0..9> | Set color theme.

Camera Tracking

There are several different ways you can have LifeViewer automatically move the camera to track patterns as they evolve.

Method | How it works | Recommendations
--- | --- | ---
AUTOFIT | Glides the camera towards the middle of the current generation bounding box and sets the zoom to fit the bounding box on the display. | Good for arbitrary patterns. Not good for playback at low generations per second.
HISTORYFIT | Modifies AUTOFIT so it includes all previously alive cells in the bounding box. | Good for oscillators.
TRACK X Y | You define X and Y velocities in cells/generation (these can be specified as fractions). Glides the camera towards the middle of the bounding box defined by the initial pattern bounding box offset by (T*X, T*Y) where T is the current generation. | Good for tracking fixed size spaceships including low generations per second playback.
TRACKBOX E S W N | You define the East, South, West and North velocities in cells/generation). Glides the camera towards the middle of the bounding box defined by the initial pattern bounding box whose edges are offset by T*E, T*S, T*W and T*N where T is the current generation. | Good for tracking growing spaceships including low generations per second playback.
TRACKLOOP P X Y | You define P (the loop period) and X and Y velocities in cells/generation. Shorthand for LOOP P TRACK X Y but also works well with GRIDMAJOR. | Good for tracking fixed size spaceships since the LOOP means the pattern never hits the grid edge. Not good for color themes that show history.

Below is an example a using TRACKLOOP to track a glider.

    #C [[ TRACKLOOP 4 1/4 -1/4 ]]
    #C [[ THEME 6 GRID ]]
    #C [[ GPS 8 AUTOSTART ]]
    x = 3, y = 3, rule = Life
    ooo$
    bbo$
    bo!

The TRACKLOOP period is set to 4 since the glider is a period 4 spaceship (i.e. it repeats every 4 generations). The glider takes those 4 generations to move 1 step right and 1 step up. This means it's moving at 1/4 steps per generation in the X direction and -1/4 steps per generation in the Y direction.

THEME 6 is used since it doesn't contain cell history which would be lost every time the pattern loops.

The grid lines are turned on with GRID command.

The playback speed is set to 8 generations per second.

Finally AUTOSTART is used so the pattern begins playback as soon as LifeViewer is started.

To see this in action:

1. Stop LifeViewer if it is running (click on the Golly window and press Esc).
2. Copy the pattern above to the clipboard.
3. Use File->Open Clipboard in Golly.
4. Run Scripts/Lua/lifeviewer.lua.

Color Themes

Color themes are used to provide a visual representation of cell history and longevity. This works automatically on any two state pattern. Each color theme has five different colors that are used for drawing cells.

Name | Description | Default
--- | --- | ---
born | cell just born |
alive | cell alive for at least 63 generations |
died | cell just died |
dead | cell dead for at least 63 generations |
unoccupied | cell never occupied |

New cells are drawn in the born color.

If cells stay alive they fade from the born color to the alive color over the next 63 generations. If cells stay alive after that they remain in the alive color. This provides a visual representation of cell longevity.

Born | Alive
--- | ---

Cells are drawn in the died color when then they die.

If they stay dead they fade from the died color to the dead color over the next 63 generations. If cells stay dead after that they remain in the dead color. This provides a visual representation of cell history.

Died | Dead
--- | ---

Cells that have never been occupied are drawn in the unoccupied color. This is used for showing where cells have never lived.

In the example below you can see a glider leaving a history trail behind it. Top left is a still life block which is in the alive color because it has been alive for at least 63 generations. Bottom right is an oscillator (blinker) which has the center cell in the alive color since it doesn't change, the north and south cells in the born color since they've just been born and the east and west cells in the died color since they both just died.

There are 10 built in color themes which are shown in the table below. A two state pattern will default to using THEME 1 unless you specify an alternative with the THEME script command. You can dynamically cycle between the themes with key C. Shift and C toggles between the current theme and Golly's default colors for the pattern.

Theme | Born | Alive | Died | Dead | Unoccupied
--- | --- | --- | --- | --- | ---
0 |  |  |  |  |
1 |  |  |  |  |
2 |  |  |  |  |
3 |  |  |  |  |
4 |  |  |  |  |
5 |  |  |  |  |
6 |  |  |  |  |
7 |  |  |  |  |
8 |  |  |  |  |
9 |  |  |  |  |

Themes 0 and 6 are good for TRACKLOOP since they have no history.

Theme 8 uses the same color for live cells and cells that died so is used to show a map of where cells have ever lived.

3D Layers

Cell history and longevity can be represented with colors using themes and also with layers. You define the number of layers from 1 (the default) to 10 and also the depth from 0 to 1. The bigger the depth the more distance between the layers and the more the 3D effect is exaggerated.

The number of layers is defined with the LAYERS script command and changed dynamically with keys Q (increase layers) and A (decrease layers).

The layer depth is defined with the DEPTH script command and changed dynamically with keys P (depth up) and L (depth down).

All cells are drawn in the bottom layer (layer 1). As you go up through the layers cells have to be dead for less generations or alive for more generations to be drawn. You will see towers grow up towards you where cells are alive and static (like the block) and cells tumble away from you as cells die (like the trail of the glider).

Hex Grid

Patterns using a hexagonal neighborhood will be automatically displayed using a hex grid.

You can switch between hex and square grids at any time with the / key.

If your pattern uses a custom rule and is not automatically recognized correctly as hex (or square) then you can specify the grid type you want to use by adding the HEXDISPLAY or SQUAREDISPLAY script command to the pattern comments.

Notes

- Hex grid does not support camera rotation. Any rotation will be ignored.
- Grid lines only display at 4x zoom and higher and when the camera angle is 0.
- Decimal values may also be specified as fractions: TRACK -0.5 0.25 = TRACK -1/2 1/4.
- Many of the keyboard shortcuts are the same as Golly's but there are exceptions.
- HISTORYFIT modifies how AUTOFIT works but does not itself switch AUTOFIT on.
- Layers are only displayed when using a color theme. They do not display when viewing a pattern using Golly's standard colors.