Macro System

The Macro system is a new and experimental part of Gopher2600. It is likely to change in the future.

Specifying a macro to be run must be done via the command line. For example:

gopher2600 run -macro pitfall_screenshot.macro roms/Pitfall.bin

Language notes taken from the source documentation

The macro language is very simple and does not implement any flow control except basic loops.

DO loopCt [loopName]
    ...
LOOP

The loopName parameter is optional. When a loop is named the current counter value can be referenced as a variable in some contexts (currently, this is the SCREENSHOT instruction only).

Loops can be nested.

The WAIT instruction will pause the execution of the macro for the specified number of frames. If no value is given for this the number of frames defaults to 60.

There are instructions that give basic control over the emulation (only left player joystick control and some panel operations).

LEFT, RIGHT, UP, DOWN, CENTRE, FIRE, NOFIRE, SELECT, RESET

There is also an instruction to initiate a screenshot. The macro system is therefore useful to automate the collation of screenshots in a repeatable manner.

SCREENSHOT [filename suffix]

The filename suffix parameter is optional. Without it the screenshot will be given the default but unique filename.

If the filename suffix parameter is given then the name of the screenshot will be the name of the cartridge plus the suffix. Spaces will be replaced with underscores.

In the context of the screenshot instruction, variables can referenced with the % symbol. For example, if a loop has been given the name "ct", then the following screenshot command could be written:

 SCREENSHOT %ct

Any errors in a macro script will result in a log entry and the termination of the macro execution.

Lines can be commented by prefixing the line with two dashes (--). Leading and trailing white space is ignored.

Example Script

The following script demonstrates a way of taking a screenshot of each room in Pitfall.

gopher2600macro

-- wait 30 frames for ROM initialisation
WAIT 30

-- start game by moving joystick right
RIGHT
CENTER

WAIT 10

-- loop through all 256 screens
DO 256 n
    -- take screenshot using loop counter for filename
    SCREENSHOT %n

    -- position player at right of screen
    POKE $e1 $94

    -- walk right to next screen
    RIGHT
    WAIT 10
    CENTER
LOOP

QUIT