Gopher 2600 is an emulator for the Atari VCS. It is written in Go and was begun as a project for learning that language.
- Support for joystick, paddle and keyboard hand controllers
- Auto-handling of input type *
- Debugger
- Dear Imgui interface
- Line terminal interface
- CPU and Video stepping
- Breakpoints, traps, watches
- Script recording and playback
- Gameplay session recording and playback
- Regression database
- useful for ensuring continuing code accuracy when changing the emulation code
- ROM patching
- Auto-detection of television specification *
- Setup preferences for individual ROMs
- Television specification
- Setting of panel switches
- Automatic application of ROM patches
The asterisks in the list indicate that these features are experimental. They have performed well during development but there will undoubtedly be cases when the systems fail. To mitigate this, Gopher2600's setup system is available (although, as yet the specifying of input type is not supported).
There is a lot to add to the project but the key ommissions as it currently stands are:
- Not all CPU instructions are implemented. Although adding the missing opcodes when encountered should be straightforward.
- Unimplemented cartridge formats
- F0 Megaboy
- AR Arcadia
- DPC+
- Disassembly of some cartridge formats is known to be inaccurate
- Television display does not handle out-of-spec TV signals as it should
On a 3GHz i3 processor, the emulator (with SDL display) can reach 60fps or thereabouts.
The screenshot below is of ET with the patches from http://www.neocomputer.org/projects/et/ automatically applied. Auto-patching of ROMs is a feature of the emulator
The screenshot below show Keystone Kapers as seen through the debugger.
The two images below show some alternative debugger display. The first picture shows Barnstormer with the "debug colours" turned on. These debug colours are the same as you will see in the Stella emulator. Unlike Stella however, we can also see the off screen areas of the tv image, and in particular, the sprites as they "appear" off screen.
The second screenshot shows Pitfall. The coloured pixels overlayed over the main image indicate when key TIA events have occured. For example, when RESP0 has been triggered, or when HMOVE has been strobed. The most interesting part of this image perhaps, are the grey bars the extend to the right of the image. These bars show WSYNC signal activity. (Note that this overlay feature is not yet available through the default graphical debugger and only through the PLAIN and COLOR term types)
The Stella project (https://stella-emu.github.io/) was used as a reference for video output. I made the decision not to use or even to look at any of Stella's implementation details. The exception to this was a peek at the audio sub-system. Primarily however, Gopher2600's audio implementation references Ron Fries' original TIASound.c file.
Many notes and clues from the AtariAge message boards. Most significantly the following threads proved very useful indeed:
- "Cosmic Ark Star Field Revisited"
- "Properly model NUSIZ during player decode and draw"
- "Requesting help in improving TIA emulation in Stella"
- "3F Bankswitching"
And from and old mailing list:
- "Games that do bad things to HMOVE..." https://www.biglist.com/lists/stella/archives/199804/msg00198.html
These mailing lists and forums have supplied me with many useful test ROMs. I will package these up and distribute them sometime in the future (assuming I can get the required permissions).
Extensive references have been made to Andrew Towers' "Atari 2600 TIA Hardware Notes v1.0"
Cartridge format information was found in Kevin Horton's "Cart Information v6.0" file (sometimes named bankswitch_sizes.txt)
The "Stella Programmer's Guide" by Steve Wright is of course a key document, used frequently throughout development.
The 6507 information was taken from Leventhal's "6502 Assembly Language Programming" and the text file "64doc.txt" v1.0, by John West and Marko Makela.
US Patent Number 4,644,495 was referenced for the implementation of the DPC cartridge format (the format used in Pitfall 2)
The following ROMs were used throughout development and compared with the Stella emulator for accuracy. As far as I can tell the following ROMs work more or less as you would expect:
- Pitfall
- Adventure
- Barnstormer
- Krull
- He-Man
- ET
- Fatal Run
- Cosmic Ark
- Keystone Kapers
- River Raiders
- Tennis
- Wabbit
- Yar's Revenge
- Midnight Madness
- Pitfall 2
- Thrust (v1.2)
- Hack'em (pac man clone)
- Donkey Kong (v1.0)
- Tricade by Trilobit
- Chiphead by KK of Altair
The project has most recently been tested with Go v1.14. It will not work with versions earlier than v1.13 because of language features added in that version (binary literals).
The project uses the Go module system and dependencies will be resolved automatically. Do note however, that you will required the SDL development libraries for the Go SDL module to compile.
Compile with GNU Make
> make build
During development, programmers may find it more useful to use the go command directly
> go run gopher2600.go
Once compiled run the executable with the help flag:
> gopher2600 -help
This will list the available sub-modes. USe the -help flag to get information about a sub-mode. For example:
> gopher2600 debug -help
To run a cartridge, you don't need to specify a sub-mode. For example:
> gopher2600 roms/Pitfall.bin
Although if want to pass flags to the run mode you'll need to specify it.
> gopher2600 run -help
Joystick, paddle and keypad inputs are supported. Currently, only joysticks and paddles for the left player are available however.
The joystick is operated via the cursor keys on the keyboard and the spacebar in place of the fire button.
The paddle is available by operating the mouse. To activate the paddle, click in the play window and waggle the mouse to the extremes three times. Note that once the window has been clicked, the mouse will be captured and the pointer will disappear. To "release" the mouse, click the right-mouse button.
Keypad input is available only when the emulation thinks it is required. When keypad input is expected, neither joystick or paddle controls will work.
- Cursor keys for stick direction
- Space bar for fire
Not yet emulated
- Left mouse button in window to capture mouse (waggle mouse to activate paddle)
- Mouse left/right motion for paddle motion
- Left mouse button for paddle's fire button
- Right mouse button to leave "paddle mode"
Not yet emulated
| VCS | ||
|---|---|---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |
| * | 0 | # |
Using the guide above, we can see the corresponding keys on the PC keyboard for the left and right players.
| left | ||
|---|---|---|
| 1 | 2 | 3 |
| q | w | e |
| a | s | d |
| z | x | c |
| right | ||
|---|---|---|
| 4 | 5 | 6 |
| r | t | y |
| f | g | h |
| v | b | n |
The VCS panel is controlled through the function keys of the keyboard.
- F1 Panel Select
- F2 Panel Reset
- F3 Color Toggle
- F4 Player 0 Pro Toggle
- F5 Player 0 Pro Toggle
To run the debugger use the DEBUG submode
> gopher2600 debug roms/Pitfall.bin
The default debugging mode display a windowed interface. A thorough explanation of the interface is not yet available but it is believed to be self explanatory. Note that the ROM can be interacted with by clicking on the screen image in the TV Screen window. This will "capture" the mouse and allow the emulated VCS to be interacted with in the normal way. Click the right mouse button to release the captured mouse.
In addition to the controller and panel input described above, the following keys are also available during mouse capture:
- F12 (backtick) Toggle screen masking
- F11 Toggle debugging colors
- + Increase screen size
- - Decrease screen size
Not available in the graphical debugger but available in the display for the
PLAIN and COLOR terminal types is this:
- F10 Toggle debugging overlay
The debugging overlay will be added to the graphical debugger in a future version.
As an alternative to GUI interaction the debugger can also be controlled through a terminal. This is available through the terminal window which opens by default on debugger launch. The rest of this section describes
the operation of the terminal in detail.
Help is available with the HELP command. Help on a specific topic is available by specifying a keyword. The list below shows the currently defined keywords. The rest of the section will give a brief run down of debugger features.
[ 0xf000 SEI ] >> help
AUDIO BALL BREAK CARTRIDGE CLEAR
CPU DISASSEMBLY DISPLAY DROP GREP
HELP INSERT LAST LIST MEMMAP
MISSILE ONHALT ONSTEP PANEL PATCH
PEEK PLAYER PLAYFIELD POKE QUANTUM
QUIT RAM RESET RUN SCRIPT
STEP STICK SYMBOL TIA TIMER
TRAP TV WATCH
The debugger allows tab-completion in most situations. For example, pressing W followed by the Tab key on your keyboard, will autocomplete the WATCH command. This works for command arguments too. It does not currently work for filenames, or symbols. Given a choice of completions, the Tab key will cycle through the available options.
Addresses can be specified by decimal or hexadecimal. Hexadecimal addresses can be writted 0x80 or $80. The debugger will echo addresses in the first format. Addresses can also be specified by symbol if one is available. The debugger understands the canonical symbol names used in VCS development. For example, WATCH NUSIZ0 will halt execution whenever address 0x04 (or any of its mirrors) is written to.
Watches are one of the three facilities that will halt execution of the emulator. The other two are TRAP and BREAK. Both of these commands will halt execution when a "target" changes or meets some condition. An example of a target is the Programmer Counter or the Scanline value. See HELP BREAK and HELP TRAP for more information.
Whenever the emulation does halt, the ONHALT command will run. For example, a previous call to ONHALT CPU will cause the CPU command to run whenever the emulation stops. Similarly, the ONSTEP command applies whenever the emulation is stepped forward. By default, the LAST command is run on every step.
The debugger can step forward either, one CPU instruction at a time, or by one video cycle at a time. We can change this mode with the QUANTUM command. We can also conveniently use the STEP command, for example STEP VIDEO, performing the quantum change and stepping forward in one go. The STEP command can also be used to run until the next time a target changes. For example, STEP SCANLINE. Using STEP in this way is often more useful than setting up a TRAP.
Scripts can be recorded and played back with the SCRIPT command. All commands are available when in script recording mode, except RUN and further SCRIPT RECORD command. Playing back a script while recording a new script is possible.
On startup, the debugger will load a configuration script, which consists of debugger commands available at the debugger's command line. A useful startup script would be:
DISPLAY SCALE 3.0
DISPLAY
This opens the debugger with the debugging screen open and ready for use. See the section "Configuration Directories" for more information.
Gopher2600 will look for certain files in a configuration directory. The location
of this directory depends on whether the executable is a release executable (built
with "make release") or a development executable (made with "make build"). For
development executables the configuration directory is named .gopher2600 and is
located in the current working directory.
For release executables, the directory is placed in the user's configuration directory,
the location of which is dependent on the host OS. On modern Linux systems, the location
is .config/gopher2600.
In both instances, the directory, sub-directory and files will be created automatically as required.
Gopher2600 can record all user input and playback for future viewing. This is a very efficient way of recording gameplay and results in far smaller files than a video recording. It also has other uses, not least for the recording of complex tests for the regression database.
To record a gameplay session, use the record flag. Note that we have to specify the run mode for the
flag to be recognised:
> gopher2600 run -record roms/Pitfall.bin
This will result in a recording file in your current working directory, with a name something like:
> recording_Pitfall_20200201_093658
To playback a recording, simply specify the recording file instead of a ROM file:
> gopher2600 recording_Pitfall_20200201_093658
To help with the development process a regression testing system was added. This will prove useful during further development. To quickly add a ROM to the database:
> gopher2600 regress add roms/Pitfall.bin
By default, this adds a "screen digest" of the first 10 frames of the named ROM. We can alter the
number of frames, and also other parameters with regress add mode flags. For example, to run for
100 frames instead of 10:
> gopher2600 regress add -frames 100 roms/Pitfall.bin
The database also supports the adding of playback files. When the test is run, the playback file is run as normal and success measured. To add a playback to the test data, simply specify the playback file instead of a rom:
> gopher2600 regress add recording_Pitfall_20200201_093658
To listing all previously add tests use the "list" sub-mode:
> gopher2600 regress list
> 000 [digest/video] player_switching [AUTO] frames=10 [NUSIZ]
> 001 [digest/video] NUSIZTest [AUTO] frames=10 [NUSIZ]
> 002 [digest/video] testSize2Copies_A [AUTO] frames=10 [NUSIZ]
> 003 [digest/video] testSize2Copies_B [AUTO] frames=10 [NUSIZ]
> 004 [digest/video] player8 [AUTO] frames=10 [NUSIZ]
> 005 [digest/video] player16 [AUTO] frames=10 [NUSIZ]
> 006 [digest/video] player32 [AUTO] frames=10 [NUSIZ]
> 007 [digest/video] barber [AUTO] frames=10 [NUSIZ]
> 008 [digest/video] test1.bas [AUTO] frames=10 [TIMER]
> 009 [digest/video] test2.bas [AUTO] frames=10 [TIMER]
> 010 [playback] playback_player_20200127_172838 [HMOVE/BAD THINGS]
> Total: 11
To run all tests, use the run sub-mode:
> gopher2600 regress run
To run specific tests, list the test numbers (as seen in the list command result) on the command line. For example:
> gopher2600 regress run 1 3 5
Delete tests with the delete sub-mode. For example:
> gopher2600 regress delete 3
The setup system is currently available only to those willing to edit the "database" system by hand.
The database is called setupDB and is located in the project's configuration directory. The format
of the database is described in the setup package. Here is the direct link to the source
level documentation: https://godoc.org/github.com/JetSetIlly/Gopher2600/setup
See the https://github.com/JetSetIlly/Gopher2600-Utils/tree/master/web2600 repository for examples of tools
that use Gopher2600.
In addition to this readme, more information can be found with the command line -help system.
Many modes and sub-modes will accept operational flags. Specifying the -help flag will print
a brief summary of available options.
Help on debugger commands is available with the HELP command at the debugger command line.
More information is available in the Go source files and can be viewed with the
Go documenation system. With godoc installed:
> GOMOD=$(pwd) godoc -http=localhost:1234 -index >/dev/null &
Alternatively, the most current version of the docs available on github can be viewed at https://godoc.org/github.com/JetSetIlly/Gopher2600
Finally, development and maintenance documentation is beginning to be stored in its own Github repository: https://github.com/JetSetIlly/Gopher2600-Dev-Docs
The following projects are used in the gopher2600 project.
- https://github.com/ocornut/imgui
- https://github.com/inkyblackness/imgui-go (occasionally using a fork in the JetSetIlly repository)
- https://github.com/veandco/go-sdl2
- https://github.com/go-gl/gl
- https://github.com/go-audio/audio
- https://github.com/go-audio/wav
- https://github.com/pkg/term