You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`Gopher2600` is an emulator for the Atari 2600. Whilst the performance is not as efficient as some other emulators it is none-the-less suitable for playing games, on a reasonably modern computer, at the required 60fps. (The development machine for `Gopher2600` has been an i3-3225, dating from around 2012.)
3
+
`Gopher2600` is an emulator for the Atari 2600 written in the Go language. The accuracy of the emulation is very high and the 6507, TIA and RIOT chips are well represented. The key features of the emulator:
4
4
5
-
<imgsrc=".screenshots/crt_official_frogger.png"alt="gopher2600 showing Official Frogger with CRT effects"/>
5
+
*[Support for many of the known cartridge formats](#supported-cartridge-formats)
6
+
*[Gameplay recording and playback](#recording-gameplay)
7
+
* Support for (and auto-detection of) [keypad,paddle and joystick](#hand-controllers)
8
+
* Network access through [PlusROM](#plusrom) emulation
9
+
*[Savekey](#savekey) support
6
10
7
-
The accuracy of the emulation is very high although this is difficult to prove. Certainly, there are no known outstanding issues in the TIA or RIOT.
8
-
9
-
The 6507 emulation is also very accurate although, at the time of writing, not all undocumented opcodes are implemented. That said, the emulation method used for the CPU means adding a missing opcode is trivial.
10
-
11
-
The emulator also comes with a powerful [graphical debugger](#debugger). This is still in active development with many planned additional features but currently it features:
11
+
The graphical [debugger](#debugger) is still in development but the current features include:
12
12
13
13
* CPU and Video stepping
14
-
*[Interactive rewinding](#rewinding)
15
14
* Breakpoints, traps, watches on various CPU, TIA, RIOT targets
16
-
* Interactive TV Screen
17
-
* Specialist windows for specific cartridge types (eg. Supercharger)
15
+
*[Interactive rewinding](#rewinding)
16
+
* Specialist windows for specific cartridge types (eg. supercharger tape)
18
17
* Script recording and playback
19
-
* Line terminal interface for harder to reach parts of the emulation
In addition to the debugger, `Gopher2600` can [record and playback gameplay sessions](#recording-gameplay). This powerful feature efficiently records user input to a text file, suitable for passing along to other people for viewing.
24
-
25
-
The gameplay playback feature is also used in the inbuilt [regression database](#regression-database). This database allow for easy testing of the emulator's integrity and was of invaluable use during development of the emulator. This feature will also be of use perhaps when developing new ROMs for the Atari 2600 - a way of recording the ideal output of the ROM for future comparison.
26
-
27
-
The Atari 2600 comes with a variety of [hand controllers](#hand-controllers) and `Gopher2600` does it's very best to automatically select the correct input device. `Gopher2600` also supports the [SaveKey](#savekey) peripheral.
28
-
29
-
`Gopher2600` supports a variety of cartridge formats including [Supercharger](#supercharger-roms) from MP3 or WAV files. It supports `DPC+` format although there is no support for the ARM as yet. Most other formats are also supported
30
-
31
-
For network access `Gopher2600` supports [PlusROM](#plusrom) functionality.
32
-
33
-
`Gopher2600` is in active development and feature requests are welcomed.
18
+
* Line [terminal](#debugger-terminal) interface for harder to reach parts of the emulation
19
+
*[Regression Database](#regression-database)
34
20
35
21
## Screenshots
36
22
37
-
A variety of screenshots from various points in the emulator's development.
38
-
39
-
<imgsrc=".screenshots/barnstormer.png"height="200"alt="barnstormer"/> <imgsrc=".screenshots/pole_position.png"height="200"alt="pole position"/> <imgsrc=".screenshots/ateam.png"height="200"alt="ateam"/> <imgsrc=".screenshots/he_man_title.png"height="200"alt="he man title screen"/>
40
-
41
-
The following screenshot shows the fabled _ET_ ROM. In this case the ROM has been patched to fix some notorious issues with the original game. Notice, the colour of _ET_ and how he is standing in front of the pit? The patches in question were taken from http://www.neocomputer.org/projects/et/ and automatically applied. Auto-patching of ROMs is a feature of the emulator
42
-
43
-
<imgsrc=".screenshots/et_with_patch.png"height="200"alt="et with patch"/>
44
-
45
-
The next three images show the "TV screen" of the graphical debugger in various states. In the first screenshot, we see _Barnstormer_ with the "debug colours" turned on. This idea was taken from the Stella emulator and indeed, these are the same colours used in that 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.
46
-
47
-
<imgsrc=".screenshots/barnstormer_debug_colours.png"width="400"alt="barnstormer with debug colours"/>
48
-
49
-
The next two screenshots show the `Gopher2600's` overlay feature. An overlay is a way of adding information to the TV screen with the aim of helping the debugging process.
50
-
51
-
The first screenshot shows the `WSYNC` overlay. This overlay shows us graphically the scanlines on which WSYNC has been triggered. In Atari 2600 programming terms, the WSYNC is a way of synchronising the CPU with the TIA. The downside of the WSYNC is that CPU cycles are wasted - something that is not always obvious when looking at the ROM's assembly.
52
-
53
-
The second screenshot shows _Pitfall 2_ and we can see straight away that fewer CPU cycles are wasted, simply by the shorter and less frequent blue bars extending to the right of the screen.
54
-
55
-
<imgsrc=".screenshots/pitfall_overlay.png"width="400"alt="pitfall with overlay"/> <imgsrc=".screenshots/pitfall2_overlay.png"width="400"alt="pitfall with overlay"/>
56
-
57
-
## Resources used
58
-
59
-
The Stella project (https://stella-emu.github.io/) was used as a reference for
60
-
video output. I made the decision not to use or even to look at any of Stella's
61
-
implementation details. The exception to this was a peek at the audio
62
-
sub-system. Primarily however, `Gopher2600's` audio implementation references Ron
63
-
Fries' original TIASound.c file.
64
-
65
-
Many notes and clues from the AtariAge message boards. Most significantly the
66
-
following threads proved very useful indeed:
67
-
68
-
* "Cosmic Ark Star Field Revisited"
69
-
* "Properly model NUSIZ during player decode and draw"
70
-
* "Requesting help in improving TIA emulation in Stella"
71
-
* "3F Bankswitching"
72
-
73
-
And from and old mailing list:
74
-
75
-
* "Games that do bad things to HMOVE..." https://www.biglist.com/lists/stella/archives/199804/msg00198.html
76
-
77
-
These mailing lists and forums have supplied me with many useful test ROMs. I
78
-
will package these up and distribute them sometime in the future (assuming I
79
-
can get the required permissions).
80
-
81
-
Extensive references have been made to Andrew Towers' "Atari 2600 TIA Hardware
82
-
Notes v1.0"
83
-
84
-
Cartridge format information was found in Kevin Horton's "Cart Information
85
-
v6.0" file (sometimes named bankswitch_sizes.txt)
86
-
87
-
The "Stella Programmer's Guide" by Steve Wright is of course a key document,
88
-
used frequently throughout development.
89
-
90
-
The 6507 information was taken from Leventhal's "6502 Assembly Language
91
-
Programming" and the text file "64doc.txt" v1.0, by John West and Marko Makela.
92
-
93
-
US Patent Number 4,644,495 was referenced for the implementation of the DPC cartridge format
94
-
(the format used in Pitfall 2)
95
-
96
-
DPC+ format implemented according to notes provided by Spiceware https://atariage.com/forums/topic/163495-harmony-dpc-programming
97
-
98
-
The "Mostly Inclusive Atari 2600 Mapper / Selected Hardware Document" (dated 03/04/12) by Kevin Horton
99
-
100
-
Supercharger information from the Kevin Horton document above and also the `sctech.txt` document
<imgsrc=".screenshots/games/thrust.png"height="200"alt="thrust"/> <imgsrc=".screenshots/games/pandachase.png"height="200"alt="panda chase"/> <imgsrc=".screenshots/games/mangoesdown.png"height="200"alt="man goes down"/> <imgsrc=".screenshots/games/beast.png"height="200"alt="legacy of the beast"/> <imgsrc=".screenshots/games/chiphead.png"height="200"alt="chiphead"/> <imgsrc=".screenshots/games/genesis.png"height="200"alt="egypt genesis"/>
101
26
102
27
## Compilation
103
28
@@ -124,7 +49,7 @@ directly
124
49
`Gopher2600` makes use of SDL2. The SDL2 go binding used by the project requires a minimum
125
50
SDL2 version of `2.0.10`.
126
51
127
-
## Cross-Compilation
52
+
###Cross-Compilation
128
53
129
54
Native compilation of a Windows executable has not yet been tried. But
130
55
cross-compilation does work via the Makefile:
@@ -158,38 +83,19 @@ Although if want to pass flags to the run mode you'll need to specify it.
158
83
159
84
## Hand Controllers
160
85
161
-
Joystick, paddle and keyboard inputs are supported. Currently, only joysticks and paddles for the left player are available however.
86
+
Joystick, paddle and keypad inputs are supported. Currently, only joysticks and paddles for the left player are available.
162
87
163
-
The joystick is operated via the cursor keys on the keyboard and the spacebar in place of the fire button.
88
+
The joystick is operated via the cursor keys on the keyboard and the spacebar in place of the fire button. Gamepad support will be added in the future.
164
89
165
-
The paddle is available by operating the mouse. To activate the paddle, click
166
-
in the play window and waggle the mouse a few times. Note that once the window
90
+
The paddle is available by operating the mouse. To activate the paddle, double-click
91
+
the play window and waggle the mouse a few times. Note that once the window
167
92
has been double-clicked, the mouse will be captured and the pointer will
168
93
disappear. To "release" the mouse, click the right-mouse button or the escape
169
94
key.
170
95
171
-
#### Joystick (left player)
96
+
###Keypad
172
97
173
-
* Cursor keys for stick direction
174
-
* Space bar for fire
175
-
176
-
#### Joystick (right player)
177
-
178
-
Not yet emulated
179
-
180
-
#### Paddle (left player)
181
-
182
-
* Double-click left mouse button in window to capture mouse (waggle mouse to activate paddle)
183
-
* Mouse left/right motion for paddle motion
184
-
* Left mouse button for paddle's fire button
185
-
186
-
#### Paddle (right player)
187
-
188
-
Not yet emulated
189
-
190
-
#### Keyboard
191
-
192
-
Keyboards for both player 0 and player 1 are supported.
98
+
Keypads for both player 0 and player 1 are supported.
193
99
194
100
||p0|||p1||
195
101
|:-:|:-:|:-:|:-:|:-:|:-:|
@@ -210,27 +116,46 @@ The VCS panel is controlled through the function keys of the keyboard.
210
116
211
117
## Debugger
212
118
213
-
To run the debugger use the DEBUG submode
119
+
To run the debugger use the `DEBUG` submode
214
120
215
121
> gopher2600 debug roms/Pitfall.bin
216
122
217
-
The default debugging mode display a windowed interface. A thorough explanation
218
-
of the interface is not yet available but it is should be self-explanatory.
219
-
Note that the ROM can be "played" by double-clicking on the screen image in
220
-
the `TV Screen` window. This will "capture" the mouse, run the emulation and
221
-
allow the emulated VCS to be interacted with in the normal way. Click the right
222
-
mouse button or the escape key to release the captured mouse.
223
-
224
-
In addition to the controller and panel input described above, the following keys are also available during mouse capture:
225
-
226
-
* F12 (backtick) Toggle screen masking
227
-
* F11 Toggle debugging colours
228
-
* F10 Toggle debugging overlay
229
-
*\+ Increase screen size
230
-
*\- Decrease screen size
231
-
* Escape to leave capture mode
232
-
233
-
When not in capture mode, the Escape key runs/halts the emulation.
Becaus the debugger is still in development, full documentation not yet available. But breifly the features we can see in this screeshot are:
126
+
127
+
The menu-bar across the top of the screen shows the `Debugger`, `VCS` and in this instance a `Cartridge` menu
128
+
129
+
* From `Debugger` menu you can open the preferences windows the terminal and others.
130
+
* The `VCS` menu contains options to open windows that relate to the VCS itself.
131
+
* Many of them are already open but other, less frequently required windows are also available
132
+
* The `Cartridge` menu appears when the loaded cartridge type has additional features. For example:
133
+
* Cartridge memory and or registers
134
+
* In this case, this is the menu for the `Supercharger` format.
135
+
* At the very right of the menu bar we can see the file path for the loaded cartridge
136
+
137
+
Below the menu-bar are the debugging windows. In this screenshot we can see:
138
+
139
+
* The `TV Screen`. This shows the television output from the VCS.
140
+
* The screen is 'interactive' and will show information about the pixel underneath the cursor
141
+
* Clicking the screen will move the VCS emulation to the point where the VCS is outputting that pixel. This is part of the [rewind](#rewinding) system.
142
+
* Also available are a variety of `overlays`. Click the overlay toggle and select which overlay you want to show by selecting with the button to its right (labelled `WSYNC` in the screenshot).
143
+
* The `Audio` window shows the waveform of the recent sound output.
144
+
* The `Control` window allow you to `Run/Halt`, `Step` and also `rewind` through the emulation.
145
+
* The toggle to right of the `Run` button will put the emulation into `video-cycle` mode. This will allow you to step by a single color-clock at a time, rather than a single CPU instruction.
146
+
* The `Timer` window shows the current state of the RIOT Timer.
147
+
* The `CPU` window shows the current state of the 6507.
148
+
* The `Disassembly` window shows the disassembled ROM.
149
+
* If a 'DASM' generated symbol file is available then that will be used.
150
+
* If a symbols file isn't available then the standard symbols will be used. This includes symbols for special cartridge areas that might exists. For example, a hotspot address for switching banks will be indicated with `BANK1`, `BANK2`, etc. instead of the address.
151
+
* If the cartridge does contain more than one bank then the banks will be viewable by selecting the relevant tab. In the screenshot above, the cartridge contains four banks.
152
+
* Add or remove a `PC Breakpoint` by clicking on the disasm entry.
153
+
* The `RAM` window shows the contents of the VCS RAM. Cartidge RAM if available will be show in the `Cartridge RAM` window. Not shown but available through the cartridge menu when appropriate.
154
+
* The highlighted bytes indicate those bytes that have changed since the emulation last halted.
155
+
* The `TIA` window details the six graphical parts of the VCS's graphics chip.
156
+
* The state of the `TIA` can be changed manually but note that the changes will not be retained when the emulation next updates that part of the TIA. This will likely change in future versions of the program.
157
+
158
+
Note that much of the information presented in the windows is editable in-place. For example, the contents of the CPU's PC register can be edited via the window. As in all areas of this project, the user is encouraged to experiement.
0 commit comments