stella-3.9.3/ 0000755 0001750 0000144 00000000000 12267274567 012421 5 ustar stephen users stella-3.9.3/config.sub 0000644 0001750 0000144 00000075777 11205247262 014407 0 ustar stephen users #! /bin/sh
# Configuration validation subroutine script.
# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
# 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
timestamp='2005-07-08'
# This file is (in principle) common to ALL GNU software.
# The presence of a machine in this file suggests that SOME GNU software
# can handle that machine. It does not imply ALL GNU software can.
#
# This file is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA
# 02110-1301, USA.
#
# As a special exception to the GNU General Public License, if you
# distribute this file as part of a program that contains a
# configuration script generated by Autoconf, you may include it under
# the same distribution terms that you use for the rest of that program.
# Please send patches to
By 1981, the video game industry was basically a horse race between the 2600
and the Intellivision. While the Intellivision was technologically superior in
some respects, the 2600 continued to lead in sales. Atari released the home
version of Asteroids, which was a huge success. Inspired by the success of
Activision, another software development group called Imagic was formed. They
would not release any games until 1982 however. Another company, Games by Apollo,
was formed in Texas and released several games that year.
Coleco entered the market in 1982 with the release of the graphically
superior Colecovision. To combat this new system, Atari produced the 5200,
a technologically comparable system. The 2600 dropped $100 in price in order
to remain competitive. Then a company called Arcadia released a peripheral
called the Supercharger which played games in an audio cassette medium. This
allowed for multiple loads and expanded the 2600's capabilities.
Ever since the inception of Activision, Atari had been fighting to keep third
parties from producing cartridges which they felt were stealing profits from
them. Finally the issue was settled when Atari agreed to allow third party
manufacturing in exchange for a royalty. Suddenly software companies began
popping up all over, and 1982 saw releases from companies like Venturevision,
Spectravision, Telesys, CBS, 20th Century Fox, US Games, M Network, Tigervision,
Data Age, Imagic and Coleco. There was even a company that released a line of
X-Rated games for the 2600 called Mystique. The year was financially successful
for Atari, however there seemed to be a glut of software. Although there were
many quality titles still produced, there was an increasing number of rushed
games as manufacturers attempted to cash in on the craze.
More companies jumped on the band wagon in 1983. Zimag, Ultravision, Amiga,
and others were also producing games and peripherals. It seemed as if there was
just too much product to meet the demand, and as it turned out there was. By
the end of the year, companies began folding. US Games, Data Age, Games by
Apollo, Telesys and others all closed their doors from poor sales. A video
game crash was occurring, and all companies were taking it on the chin.
1984 was a much more subdued year for the Atari 2600, and the price of the
system had now dropped to $40-$50. Many were saying that the video game
industry was dead. However, Atari surprised everyone by announcing the release
of the 7800, and also promising more 2600 games with improved graphics and
sound. Unfortunately, neither of these things happened in 1984 because Atari
sold their home video game division to Jack Tramiel who believed that home
computers would replace video game systems. No further mention of the 2600 or
7800 was made that year, and it appeared that they might be dead.
1985 was another very quiet year for Atari and video games in general, and only
a few games were released for the 2600. Activision produced Cosmic Commuter and
Ghostbusters, but with little fanfare or marketing, these games did not sell
well. However, because of the huge game library and cheap price, Atari still
sold over a million 2600 consoles in 1985.
There were very few plans for home video game systems by any company in 1986,
since the market appeared to be dead. Then, to most people's surprise, Nintendo
brought the NES to America and it was a smash hit, proving that video games
still had a place in the US. Atari decided that maybe it would be a good idea
to release the 7800 units it had in storage, and produce some more 2600 games.
The 7800 was released with only 3 games initially available, although it was
compatible with the 2600 library. They also redesigned the 2600 as the 2600 Jr.,
a machine with the same abilities, but a new look and marketing campaign. It
was sold for less than $50.
Today, the 2600 still has a large number of fans who remember the countless
games played over the years, and the years to come. There are even games being
produced by hobbyists, some of them quite professionally, being released on
newly burnt cartridges with labels and manuals. And the recent trend in
retrogaming has brought many more video game fans to rediscover the 2600, and
it continues to live on 22 years after its release!
Alexander Bilstein
Stella is a freely distributed multi-platform Atari 2600 VCS emulator; originally
developed for Linux by Bradford W. Mott, it is now maintained by Stephen Anthony.
Stella allows you to enjoy all of
your favorite 2600 games once again by emulating the 2600's hardware with
software. Stella is written in C++, which allows it to be ported to other
operating systems and architectures. Since its original release Stella has
been ported to AcornOS, AmigaOS, DOS, FreeBSD, Linux, MacOS, OpenStep, OS/2,
Unix, and Windows, as well as consoles such as Sega Dreamcast, GP2X, Nintendo
DS and Playstation Portable (among others).
The following sections outline the basic system requirements for running
Stella under various operating systems.
The Linux version of Stella is designed to work on a Linux Workstation with
the following:
The Mac version of Stella is designed to work on an Apple Macintosh with
the following:
The Windows version of Stella is designed to work on Windows XP/Vista/7
with the following:
Stella is extremely portable, and in its lifetime has been ported to almost every
platform where the SDL library exists. It is 32/64-bit and endian clean in Linux/Unix, MacOSX
and Windows. The Stella Team is interested in hearing about any problems you may
encounter with diverse operating systems and CPU types. Stella is distributed in both source and binary form. In general, you should always
download and install the appropriate binary version. Compiling from source is only
recommended for developers, or if the binary version doesn't work for some reason.
Once you have a Stella distribution you should follow the instructions for your
operating system given below.
Most games for the Atari 2600 came on cartridges. A cartridge usually
consists of a single Read Only Memory (ROM) chip which contains the data and
code for the game. Plugging a cartridge into the Atari 2600 allows the 2600's
microprocessor to access the program stored on the cartridge. In a similar way you must "plug" a copy of a cartridge into Stella when you
want to play it. Having a ROM image / BIN file, of the cartridge allows you to
do this. A ROM image is a file, which contains the actual data and code read
from the cartridge. There are several ways to obtain a ROM image of a
cartridge: WARNING: It is illegal to use ROM images of games that you do not
actually own since these games are still copyrighted.
Supercharger games were not stored on cartridges instead they were stored
on cassette tapes. The Supercharger, which plugged into the Atari 2600's
cartridge slot, loaded games into its 6K of Random Access Memory (RAM) using a
standard audio cassette player. The Supercharger also supported multi-loading,
which allowed games to be broken into several segments and loaded at different
times. This was useful for large games which had distinct parts such as role
playing games. Most of the available Supercharger ROM images are stored in 8448 bytes files.
However, ROM images of multi-load games are sometimes stored in a set of 8448
byte files. The names of these files have a two character sequence number in
them which indicates what load they are. The sequence starts with zero, skips
a few numbers and then increments by one. Stella supports multi-load games, however, the set of ROM images must be
combined into a single ROM image file. For example to create a multi-load ROM
image file for Survival Island you would do the following under Unix:
Once you have the multi-load ROM image file, survivl.bin in this case, you
can play the game using it.
Stella supports ROMs ending with extensions .a26, .bin, .rom, .gz, and .zip.
For the last two compressed formats (GZIP and ZIP, respectively), Stella will
automatically decompress the archive, and use the first ROM image it finds in
it (ie, the first one ending in a valid extension). Once Stella is installed and you have some ROM images you're almost ready to
start playing.
Stella contains an integrated GUI for all ports. Commandline support is also
available for those who want to use it. If you start Stella and do not specify a ROM image, it will start in
'ROM Launcher' mode: If this is your first time starting Stella, you will be asked to select the
default ROM directory to use. This is where you have all your ROMs,
collected as described in the previous section. Several dialogs will be shown, similar
to the following: The browser should be self-explanatory. The 'Go Up' button moves to the parent
folder (if it exists), and the 'Base Dir' button moves to the base directory where,
by default, all Stella-related files are stored. Double-clicking an item will
enter that directory. Click 'Choose' to select the location, or 'Cancel' to exit
the browser. Note that if you don't select a ROM directory now, you will be prompted
again the next time Stella is started. At this point, you may want to set the locations for snapshots and other
external paths. This is described in more detail in
Advanced Configuration - Snapshot Settings and
Advanced Configuration - Config Paths.
These settings are optional, and can be left at the defaults if you won't be using
snapshots in the ROM launcher. Once you've correctly set the default ROM directory, you can start emulation by
selecting a ROM and pressing 'Enter' or clicking 'Select', or double-clicking a ROM.
Note that some games require you to 'Reset' the console before you start playing. In this
case, you need to hit the virtual reset switch, which by default is the F2 key.
Also, some games may require that you press the joystick fire button to begin,
which by default is the Left Control or Space key(s). If a game uses a
more complex controller, see
Getting Started - Keyboard Layout
for more information. To exit a game and re-enter the ROM launcher, press the 'Escape'
key. Using the 'Search' textbox in the upper-right of the ROM launcher, the
listing can be narrowed down, showing only the ROMs that match the pattern
you enter.
While playing a game, normally one would use the keyboard shortcuts for controlling the
'virtual' switches in Stella (ie, the commands associated with the
function keys as described in
Getting Started - Keyboard Layout).
However, another alternative is available. Pressing the '\' key toggles
a command menu dialog as follows: This dialog contains a set of buttons that represent the same functionality
as the function keys. You may find this useful if you cannot remember all
the function key events, or you wish to use Stella without a keyboard (ie,
in a standalone gaming system). The Atari 2600 console controls and controllers are mapped to the computer's
keyboard as shown in the following tables. However, most of these events can be
remapped to other keys on your keyboard or buttons on your joystick (see
Advanced Configuration - Event Remapping).
The tables below show the default settings. Console Controls (can be remapped) Joystick / BoosterGrip Controller (can be remapped) Paddle Controller digital emulation (can be remapped independently of joystick controller) Driving Controller (cannot be remapped, always associated with joystick controller) Sega Genesis Controller (cannot be remapped, always associated with joystick and booster-grip controllers) Keypad Controller (can be remapped) CompuMate Controller (cannot be remapped) TV effects (only active in TIA mode when using OpenGL rendering) Developer Keys in TIA mode (cannot be remapped) Other Keys (cannot be remapped, except those marked with '*') UI keys in Text Editing areas (cannot be remapped) Some Atari (virtual) controllers are simulated with more than one computer controller, and
there are several special cases where controllers are active in certain modes only, as the table
below shows. Items marked as (+ extra) indicate that the computer controller may not have
enough buttons/axes/etc to fully emulate the device, so extra functionality must be mapped to other
controllers. The default options in Stella are meant to cater to as many situations as
possible. As such, you may never need to change many of its options. However,
Stella is very configurable, and if you want to change its behaviour in some way,
there's likely a configuration option to do so. The remainder of this (lengthy)
section details every configurable option. In addition to the built in ROM launcher, Stella can also be used from the
commandline (assuming your operating system has a commandline). To run Stella from the commandline, use the following format: Options ('0' or 'false' indicates false, '1' or 'true' indicates true,
others are self-explanatory): The following are useful to developers. Only use them if you know what
you're doing! Note that in all cases, the values supplied to the arguments
are not case sensitive. All settings can be changed within the integrated Options UI while Stella is
running (unless otherwise noted; some settings require an application restart).
The Options menu can be accessed from the ROM launcher by clicking the
Options button, or in-game by pressing the 'Tab' key. Options Menu dialog: Video Settings dialog: Video Settings dialog (TV Effects): Audio Settings dialog: Input Settings dialog: UI Settings dialog (3 tabs): Snapshot Settings dialog: Config Paths dialog: Audit ROMs dialog: Game Properties dialog: Almost every event in Stella can be remapped to another key on the keyboard or
to buttons on up to eight joysticks/gamepads (see Getting Started -
Keyboard Layout for those events which can/cannot be
remapped). Note that there are currently two separate event modes in Stella; emulation
mode and user-interface (UI) mode. Each mode has separate mappings, so (for example)
while in emulation mode, the left arrow could mean 'joystick 0 left', while in UI
mode it could mean 'move cursor left'. Emulation mode occurs whenever you're
actually playing a game. UI mode occurs whenever a user interface is present
(ROM launcher, debugger, settings menu, etc). Because of these different modes,
there are two separate mapping areas.
To remap an event:
The following screenshots illustrate the event remapping process: There is also a 'Combo' button in the 'Emulation Events' tab, accessible
when a Combo event has been selected from the list of events on the left.
Clicking 'Combo' will show a dialog similar to the following: In this dialog, you can assign various events to the selected combo event.
Note that this simply assigns multiple events to the combo; you still need
to map the combo event itself to some action, as described in the 'remap an
event' section above.
A multi-platform Atari 2600 VCS emulator
Release 3.9.3
User's Guide
A Brief History of the Atari 2600
In the early 1970's, video arcade games gained commercial success for the
first time. The American public was introduced to Pong, Tank, and other
interactive video games which populated amusement parks, bars, and arcades.
The games were successful enough to create interest for home versions, so in
1975 Atari released Home Pong and it was a smash hit. Other companies such as
Magnavox and Coleco followed suit and released their own dedicated console
games. Then in 1976, Fairchild Camera and Instrument introduced the Channel F
system, the first cartridge based home video game system. The industry
recognized that cartridge systems were the future of video gaming, and began
development in that direction. In January 1977, RCA released the Studio II,
another cartridge based system, although it only projected in black and white
and seemed to be focused on educational titles. Then, in October 1977, Atari
released the Atari VCS (Video Computer System) with an initial offering of nine
games. This system, later renamed the Atari 2600, took the industry by storm
and dominated the marketplace for years to come.
Because of oversupply, the Christmas season of 1977 was very rough on the
video game industry, and the Atari 2600 was the only system that managed to
emerge unscathed. Atari enjoyed strong sales in 1978 and a fantastic holiday
season, as Atari released more games such as Outlaw, Spacewar, and Breakout.
Internally however, Atari was at odds. Nolan Bushnell, the inventor of pong and
founder of Atari, wound up leaving the company and purchased Pizza Time Theater,
which later became the successful Chuck E. Cheese! In 1979 Atari continued
their trend and released 12 more games which met with continued success.
However, Atari was now facing some stiffer competition from the Mattel
Intellivision and the Magnavox Odyssey2.
Atari needed a mega-hit in 1980 in order to squash the competition, and they
found it in the home version of a game from Japan called Space Invaders. It was
so popular that people were buying the Atari 2600 just so they could play Space
Invaders at home. Following that, Atari released Adventure, which was the first
video game to contain an Easter Egg - placing an object in a certain area
revealed the programmer's name, Warren Robinett. 1980 was important for another
reason - the creation of the first ever third party software producer, Activision.
The company was formed by four Atari employees who were unsatisfied with the
working conditions at the company. They released four games initially: Dragster,
Fishing Derby, Checkers and Boxing. The games were very well received by the
public, and revealed that the Atari 2600 was capable of better games than
Atari themselves had been producing. Atari tried to prevent Activision from
selling games, but they failed and Activision grossed $70 million that year.
Atari released Pac-Man and E.T. that year, two incredibly hyped games which
were critical flops.
Although Pac-Man sold many copies, it was considered to be a poor
translation of the arcade hit. However, there were many fantastic games
produced for the 2600 during this period, and it was still selling strong.
Video games were once again selling phenomenally in 1987. Atari released
several new titles, including Jr. Pac-Man, and also licensed a number of games
from other companies such as Donkey Kong and Q*Bert. These new titles sold for
$10-$15. Interestingly, a number of titles began appearing again from third
part companies such as Epyx, Froggo, and Exus. It seemed that the 2600 was not
dead yet!
In 1988, Atari rehired Nolan Bushnell and announced a number of new
titles, including Secret Quest, a game written by Mr. Bushnell himself. Atari
continued to manufacture these games even until 1989. However, it was apparent
that the 2600, after its introduction over a decade ago, was finally at the end
of its run. Although it was still produced and marketed outside of the US, the
Atari 2600 finished its run in America. No other console has had such a long
history or sold as many systems in the U.S.
February 1999
Introduction
Features
Getting Started
1. Requirements
General (required for all versions of Stella)
Linux/UNIX
Macintosh
Windows
Other
2. Installation
Linux/UNIX
dpkg -i stella-release-1_arch.deb
rpm -Uvh stella-release-1.arch.rpm
Macintosh
Windows
3. Locating Game Images (aka, ROMs)
Cartridges
Supercharger Cassettes
% cat survivl0.bin survivl6.bin survivl7.bin > survivl.bin
or to create it under DOS you would:
% copy /b survivl0.bin+survivl6.bin+survivl7.bin survivl.bin
Supported File formats
4. Playing a Game
Integrated GUI
Command Menu
5. Keyboard Layout
Function
Key (Standard)
Key (MacOSX)
Exit emulator
Control + q
Cmd + q
Exit game mode/enter launcher mode
Escape
Escape
Enter/exit options mode
Tab
Tab
Enter/exit command mode
Backslash (\)
Backslash (\)
Enter/exit debugger
Backquote (`)
Backquote (`)
Select Game
F1
F1
Reset Game
F2
F2
Color TV
F3
F3
Black/White TV
F4
F4
Left Player Difficulty A
F5
F5
Left Player Difficulty B
F6
F6
Right Player Difficulty A
F7
F7
Right Player Difficulty B
F8
F8
Save state to current slot
F9
F9
Change current state slot
F10
F10
Load state from current slot
F11
F11
Save PNG snapshot
F12
F12
Pause/resume emulation
Pause
Left Joystick (Joy0)
Right Joystick (Joy1)
Function
Key
Joystick Up
Up arrow
Joystick Down
Down arrow
Joystick Left
Left arrow
Joystick Right
Right arrow
Fire Button
Space
Trigger Button
4
Booster Button
5
Function
Key
Joystick Up
Y
Joystick Down
H
Joystick Left
G
Joystick Right
J
Fire Button
F
Trigger Button
6
Booster Button
7
Left Paddles
Right Paddles
Function
Key
Paddle 0 decrease
Same as 'Joy0 Left'
Paddle 0 increase
Same as 'Joy0 Right'
Paddle 0 Fire
Same as 'Joy0 Fire'
Paddle 1 decrease
Same as 'Joy0 Up'
Paddle 1 increase
Same as 'Joy0 Down'
Paddle 1 Fire
Same as 'Joy0 Booster'
Function
Key
Paddle 2 decrease
Same as 'Joy1 Left'
Paddle 2 increase
Same as 'Joy1 Right'
Paddle 2 Fire
Same as 'Joy1 Fire'
Paddle 3 decrease
Same as 'Joy1 Up'
Paddle 3 increase
Same as 'Joy1 Down'
Paddle 3 Fire
Same as 'Joy1 Booster'
Left Driving
Right Driving
Function
Key
Left Direction
Same as 'Joy0 Left'
Right Direction
Same as 'Joy0 Right'
Fire Button
Same as 'Joy0 Fire'
Function
Key
Left Direction
Same as 'Joy1 Left'
Right Direction
Same as 'Joy1 Right'
Fire Button
Same as 'Joy1 Fire'
Left Pad
Right Pad
Function
Key
Pad Up
Same as 'Joy0 Up'
Pad Down
Same as 'Joy0 Down'
Pad Left
Same as 'Joy0 Left'
Pad Right
Same as 'Joy0 Right'
Button 'B'
Same as 'Joy0 Fire'
Button 'C'
Same as 'Joy0 Booster'
Function
Key
Pad Up
Same as 'Joy1 Up'
Pad Down
Same as 'Joy1 Down'
Pad Left
Same as 'Joy1 Left'
Pad Right
Same as 'Joy1 Right'
Button 'B'
Same as 'Joy1 Fire'
Button 'C'
Same as 'Joy1 Booster'
Left Keypad
Right Keypad
Pad Button
Key
1
1
2
2
3
3
4
Q
5
W
6
E
7
A
8
S
9
D
.
Z
0
X
#
C
Pad Button
Key
1
8
2
9
3
0
4
I
5
O
6
P
7
K
8
L
9
;
.
,
0
.
#
/
CompuMate Key 0 - 9 0 - 9 A - Z A - Z Comma Comma Period Period Func Control (left or right) Shift Shift (left or right) Enter Return/Enter Space Space Func-Space Backspace + + or Shift-1 - - or Shift-2 * Shift-3 / / or Shift-4 = = or Shift-5 ? ? (Shift-/) or Shift-6 $ Shift-7 [ [ or Shift-8 ] ] or Shift-9 " " (Shift-') or Shift-0
Function
Key (Standard)
Key (MacOSX)
Disable TV effects
Alt + 1
Cmd + 1
Select 'Composite' preset
Alt + 2
Cmd + 2
Select 'S-video' preset
Alt + 3
Cmd + 3
Select 'RGB' preset
Alt + 4
Cmd + 4
Select 'Badly adjusted' preset
Alt + 5
Cmd + 5
Select 'Custom' preset
Alt + 6
Cmd + 6
Decrease scanline intensity
Shift-Alt + 7
Shift-Cmd + 7
Increase scanline intensity
Alt + 7
Cmd + 7
Disable scanline interpolation
Shift-Alt + 8
Shift-Cmd + 8
Enable scanline interpolation
Alt + 8
Cmd + 8
Select previous 'Custom' mode attribute (*)
Shift-Alt + 9
Shift-Cmd + 9
Select next 'Custom' mode attribute (*)
Alt + 9
Cmd + 9
Decrease 'Custom' selected attribute value (*)
Shift-Alt + 0
Shift-Cmd + 0
Increase 'Custom' selected attribute value (*)
Alt + 0
Cmd + 0
Function
Key (Standard)
Key (MacOSX)
Set "Display.YStart" to next larger value
Alt + PageUp
Cmd + PageUp
Set "Display.YStart" to next smaller value
Alt + PageDown
Cmd + PageDown
Set "Display.Height" to next larger value
Control + PageUp
Control + PageUp
Set "Display.Height" to next smaller value
Control + PageDown
Control + PageDown
Toggle frame stats (scanline count/fps/bs type/etc)
Alt + l
Cmd + l
Toggle TIA Player0 object
Alt + z
Cmd + z
Toggle TIA Player1 object
Alt + x
Cmd + x
Toggle TIA Missile0 object
Alt + c
Cmd + c
Toggle TIA Missile1 object
Alt + v
Cmd + v
Toggle TIA Ball object
Alt + b
Cmd + b
Toggle TIA Playfield object
Alt + n
Cmd + n
Toggle TIA Player0 collisions
Shift-Alt + z
Shift-Cmd + z
Toggle TIA Player1 collisions
Shift-Alt + x
Shift-Cmd + x
Toggle TIA Missile0 collisions
Shift-Alt + c
Shift-Cmd + c
Toggle TIA Missile1 collisions
Shift-Alt + v
Shift-Cmd + v
Toggle TIA Ball collisions
Shift-Alt + b
Shift-Cmd + b
Toggle TIA Playfield collisions
Shift-Alt + n
Shift-Cmd + n
Toggle TIA HMOVE blanks
Alt + m
Cmd + m
Toggle TIA 'Fixed Debug Colors' mode
Alt + Comma
Cmd + Comma
Toggle all TIA objects
Alt + .
Cmd + .
Toggle all TIA collisions
Shift-Alt + .
Shift-Cmd + .
Function
Key (Standard)
Key (MacOSX)
Switch to next larger zoom level
Alt + =
Cmd + =
Switch to next smaller zoom level
Alt + -
Cmd + -
Toggle fullscreen/windowed mode
Alt + Enter
Cmd + Enter
Decrease volume (*)
Alt + [
Cmd + [
Increase volume (*)
Alt + ]
Cmd + ]
Toggle console type in increasing order (NTSC/PAL/SECAM, etc))
Control + f
Control + f
Toggle console type in decreasing order (NTSC/PAL/SECAM, etc))
Shift-Control + f
Shift-Control + f
Save current properties to a new properties file
Control + s
Control + s
Switch mouse between controller emulation modes
Control + 0
Control + 0
Swap Stelladaptor/2600-daptor port ordering
Control + 1
Control + 1
Reload current ROM (singlecart ROM, TIA mode)
Load next game in ROM (multicart ROM, TIA mode)Control + r
Control + r
Reload ROM listing (ROM launcher mode)
Control + r
Control + r
Emulate 'frying' effect (TIA mode) (*)
Backspace
Backspace
Go to parent directory (UI mode) (*)
Backspace
Backspace
Toggle 'phosphor' effect
Alt + p
Cmd + p
Toggle palette
Control + p
Control + p
Toggle PAL color-loss effect
Control + l
Control + l
Save continuous PNG snapshots
Alt + s
Cmd + s
Key Editor Function Home Move cursor to beginning of line End Move cursor to end of line Delete Remove character to right of cursor Backspace Remove character to left of cursor Control-a Same function as 'Home' Control-e Same function as 'End' Control-d Same function as 'Delete' Control-k Remove all characters from cursor to end of line Control-u Remove all characters from cursor to beginning of line Control-w Remove entire word to left of cursor Control-Left Move cursor to beginning of word to the left Control-Right Move cursor to beginning of word to the right Control-c Copy entire line to clipboard (not complete) Control-v Paste clipboard contents (not complete) 6. Controller Map
Computer
Virtual
ControllerKeyboard
Joystick
Mouse
(auto mode)Mouse
(specific axis)Stelladaptor/
2600-daptor
Joystick
✓
✓
✓
✕
✓
Paddles
✓
✓
✓
✓
✓
Booster
✓
✓
✓ (+ extra)
✕
✓ (+ extra)
Genesis
✓
✓ (+ extra)
✓
✕
✕
Keyboard
✓
✓ (+ extra)
✕
✕
✓ (2600-daptor II)
Driving
✓
✓
✓
✕
✓
Trackball/mouse
✕
✕
✓
✓ (axis ignored)
✕
CompuMate
✓
✕
✕
✕
✕
Mindlink
✕
✕
✓
✓ (axis ignored)
✕
AtariVox
N/A
N/A
N/A
N/A
N/A
SaveKey
N/A
N/A
N/A
N/A
N/A
Advanced Configuration
1. Using the Command Line
stella [options ...] ROM_FILENAME
Argument
Description
-video <soft|gl>
Use software or OpenGL rendering mode.
-gl_lib <filename>
OpenGL mode only. Specify the OpenGL library to use (only use
this if you know what you're doing). For MacOSX, this should
probably be left blank.
-gl_inter <1|0>
OpenGL mode only. Use interpolation for the TIA image (results in
blending/smoothing of the image).
-gl_aspectn <number>
-gl_aspectp <number>OpenGL mode only. Specify the amount (as a percentage) to scale the
TIA image width in NTSC and PAL mode. Since many video modes do not
use square pixels, you can reduce width until the pixels appear square.
Allowable values are 80 - 120; I find 85 - 90 gives the most authentic
look for NTSC, and 105 - 110 for PAL.
-gl_fsscale <1|0>
OpenGL mode only. Stretch TIA image completely while in fullscreen mode
(vs. an integral stretch which won't necessarily completely fill the screen).
-gl_vbo <1|0>
OpenGL mode only. Use the Vertex Buffer Object extension, if available.
This is enabled by default.
-gl_vsync <1|0>
OpenGL mode only. Synchronize screen updates to the vertical blank
period. This can result in smoother updates, and eliminate tearing.
-tv_filter <1 - 6>
OpenGL mode only. Blargg TV effects, 0 is disabled, next numbers in
sequence represent presets for 'composite', 's-video', 'RGB', 'bad adjust',
and 'custom' modes.
-tv_scanlines <0 - 100>
OpenGL mode only. Blargg TV effects scanline intensity, where 0
means completely off.
-tv_scaninter <1|0>
OpenGL mode only. Blargg TV effects scanline interpolation, resulting
in blending/smoothing of the scanlines.
-tv_contrast <number>
OpenGL mode only. Blargg TV effects 'contrast'
(only available in custom mode, range -1.0 to 1.0).
-tv_brightness <number>
OpenGL mode only. Blargg TV effects 'brightness'
(only available in custom mode, range -1.0 to 1.0).
-tv_hue <number>
OpenGL mode only. Blargg TV effects 'hue'
(only available in custom mode, range -1.0 to 1.0).
-tv_saturation <number>
OpenGL mode only. Blargg TV effects 'saturation'
(only available in custom mode, range -1.0 to 1.0).
-tv_gamma <number>
OpenGL mode only. Blargg TV effects 'gamma'
(only available in custom mode, range -1.0 to 1.0).
-tv_sharpness <number>
OpenGL mode only. Blargg TV effects 'sharpness'
(only available in custom mode, range -1.0 to 1.0).
-tv_resolution <number>
OpenGL mode only. Blargg TV effects 'resolution'
(only available in custom mode, range -1.0 to 1.0).
-tv_artifacts <number>
OpenGL mode only. Blargg TV effects 'artifacts'
(only available in custom mode, range -1.0 to 1.0).
-tv_fringing <number>
OpenGL mode only. Blargg TV effects 'fringing'
(only available in custom mode, range -1.0 to 1.0).
-tv_bleed <number>
OpenGL mode only. Blargg TV effects 'bleed'
(only available in custom mode, range -1.0 to 1.0).
-tia_filter <filter>
Use the specified filter while in TIA/emulation mode. Currently,
this can be zoomZx, where Z={2..10}.
-fullscreen <1|0|-1>
Play the game in fullscreen mode (1 or 0), or completely disable
fullscreen mode (-1).
-fullres <auto|WxH>
Use the given resolution in fullscreen mode. If 'auto', let Stella decide
which resolution to use.
-center <1|0>
Centers game window (if possible).
-palette <standard|z26|user>
Set the palette to either normal Stella, the one used in the z26
emulator, or a user-defined palette.
-colorloss <1|0>
Enable/disable the PAL color-loss effect.
-framerate <number>
Display the given number of frames per second. Normally, Stella
will determine framerate based on number of scanlines.
Setting this to 0 automatically enables auto-frame
calculation (ie, framerate based on scanlines).
-timing <sleep|busy>
Determines type of wait to perform between processing frames.
Sleep will release the CPU as much as possible, and is the
preferred method on laptops (and other low-powered devices)
and when using GL VSync. Busy will emulate z26 busy-wait
behaviour, and use all possible CPU time, but may eliminate
graphical 'tearing' in software mode.
-uimessages <1|0>
Enable or disable display of message in the UI. Note that messages
indicating serious errors override this setting, and are always
shown.
-sound <1|0>
Enable or disable sound generation.
-fragsize <number>
Specify the sound fragment size to use. Linux/Mac seems to work
with 512, Windows may need 2048 (but newer versions work with
512 as well).
-freq <number>
Set sound sample output frequency (11025,22050,31400,44100,48000)
Default is 31400. Do not change unless you experience sound
issues.
-volume <number>
Set the volume (0 - 100).
-cheat <code>
Use the specified cheatcode (see Cheat section for description).
-loglevel <0|1|2>
Indicates level of logging to perform while the application is running. Zero completely disables logging (except for serious errors), while the remaining numbers show increasingly more detail.
-logtoconsole <1|0>
Indicates that logged output should be printed to the console/commandline as it's being collected. An internal log will still be kept, and the amount of logging is still controlled by 'loglevel'.
-joydeadzone <number>
Sets the joystick axis deadzone area for joysticks/gamepads.
All values within the deadzone are treated as zero-axis values,
while only those values outside are registered as valid input.
Accepts a number from 0 - 29, and uses the formula
3200 + number * 1000. So the possible deadzone values
range from 3200 to 32200.
-joyallow4 <1|0>
Allow all 4 directions on a joystick to be pressed
simultaneously. Bumper Bash ignores this setting,
and always allows all 4 directions.
-grabmouse <1|0>
Keeps the mouse in the game window in emulation mode.
-usemouse <always|analog|never>
Use mouse as a controller as specified by ROM properties in specific case.
Always and never are self-explanatory, analog means only for analog-type devices
(paddles, trackball, etc).
-dsense <number>
Sensitivity for emulation of paddles when using a digital device
(ie, joystick digital axis or button, keyboard key, etc).
Valid range of values is from 1 to 10, with larger numbers causing
faster movement.
-msense <number>
Sensitivity for emulation of paddles when using a mouse.
Valid range of values is from 1 to 15, with larger numbers causing
faster movement.
-saport <lr|rl>
Determines how to enumerate the Stelladaptor/2600-daptor devices in the
order they are found: 'lr' means first is left port, second is right port,
'rl' means the opposite.
-ctrlcombo <1|0>
Use control-x key combos. This is normally enabled, since the
Quit command is tied to 'Control-q'. However, there are times when
a 2-player game is using either the 'f' or 'r' keys for movement,
and pressing Control (for Fire) will perform an unwanted action
associated with Control-r or Control-f.
-autoslot <1|0>
Automatically switch to the next available save state slot after
saving a ROM state file.
-stats <1|0>
Overlay console info on the TIA image during emulation.
-fastscbios <1|0>
Disable Supercharger BIOS progress loading bars.
-snapsavedir <path>
The directory to save snapshot files to.
-snaploaddir <path>
The directory to load snapshot files from.
-snapname <int|rom>
When saving snapshots, use either the internal database name or
the actual ROM filename.
-sssingle <1|0>
Generate single snapshot instead of many, overwriting
any previous snapshots.
-ss1x <1|0>
Ignore any scaling applied to the TIA image, and save
snapshot in unscaled (1x) mode.
-ssinterval <number>
Set the interval in seconds between taking snapshots in continuous snapshot mode (currently, 1 - 10).
-rominfo <rom>
Display detailed information about the given ROM, and then exit
Stella.
-listrominfo
Prints relevant contents of the Stella ROM database, one ROM per line,
and then exit Stella. This can be used for external frontends.
-exitlauncher <1|0>
Always exit to ROM launcher when exiting a ROM (normally, an exit to
launcher only happens when started with the launcher).
-launcherres <WxH>
Set the size of the ROM launcher.
-launcherfont <small|medium|large>
Set the size of the font in the ROM launcher.
-launcherexts <allfiles|allroms|LIST>
Specifies which files to show in the ROM launcher
('allfiles' is self-explanatory, 'allroms' is all files
with valid rom extensions (currently: a26, bin, rom,
gz, zip), 'LIST' is a ':' separated list of valid rom extensions.
-romviewer <0|1|2>
Hide ROM info viewer in ROM launcher mode (0), or use the
given zoom level (1 or 2).
-uipalette <1|2>
Used the specified palette for UI elements. This isn't yet
complete.
-listdelay <delay>
Set the amount of time to wait between treating successive
keypresses as a single word in list widgets (value can range
from 300-1000).
-mwheel <lines>
Set the number of lines a mousewheel will scroll in the UI.
-romdir <dir>
Set the directory where the ROM launcher will start.
-statedir <dir>
Set the directory in which to access state files.
-cheatfile <file>
Set the full pathname of the cheatfile database.
-palettefile <file>
Set the full pathname of the user-defined palette file.
-propsfile <file>
Set the full pathname of the ROM properties file.
-nvramdir <dir>
Set the directory in which to access non-volatile (flash/EEPROM) files.
-cfgdir <dir>
Set the directory in which to access Distella config files.
-avoxport <name>
Set the name of the serial port where an AtariVox is connected.
-maxres <WxH>
Useful for developers, this sets the maximum size of window that
can be created, allowing to simulate testing on 'smaller' systems.
-help
Prints a help message describing these options, and then
exit Stella.
Argument
Description
-dis.resolve <1|0>
Try to differentiate between code vs. data sections in the
disassembler. See the Debugger section for more information.
-dis.gfxformat <2|16>
Sets the base to use for displaying GFX sections in the disassembler.
-dis.showaddr <1|0>
Shows/hides opcode addresses in the disassembler.
-dis.relocate <1|0>
Relocate calls out of address range in the disassembler.
-dbg.res <WxH>
Set the size of the debugger window.
-dbg.fontstyle <0|1|2|3>
How to use bold fonts in the debugger window. '0' means all normal font,
'1' is bold labels only, '2' is bold non-labels only, '3' is all bold font.
-break <address>
Set a breakpoint at specified address.
-debug
Immediately jump to debugger mode when starting Stella.
-holdjoy0 <U,D,L,R,F>
Start the emulator with the left joystick direction/button held down
(ie, use 'UF' for up and fire).
-holdjoy1 <U,D,L,R,F>
Start the emulator with the right joystick direction/button held down
(ie, use 'UF' for up and fire).
-holdselect
Start the emulator with the Game Select switch held down.
-holdreset
Start the emulator with the Game Reset switch held down.
-tiadriven <1|0>
Set unused TIA pins to be randomly driven high or low on a read/peek.
If disabled, use the last databus value for those pins instead.
-ramrandom <1|0>
On reset, either randomize all RAM content, or zero it out instead.
-bs <type>
Set "Cartridge.Type" property. See the Game Properties section
for valid types.
-type <type>
Same as using -bs.
-channels <Mono|Stereo>
Set "Cartridge.Sound" property.
-ld <A|B>
Set "Console.LeftDifficulty" property.
-rd <A|B>
Set "Console.RightDifficulty" property.
-tv <Color|BW>
Set "Console.TelevisionType" property.
-sp <Yes|No>
Set "Console.SwapPorts" property.
-lc <type>
Set "Controller.Left" property. See the Game Properties
section for valid types.
-rc <type>
Set "Controller.Right" property. See the Game Properties
section for valid types.
-bc <type>
Sets both "Controller.Left" and "Controller.Right" properties.
See the Game Properties section for valid types.
-cp <Yes|No>
Set "Controller.SwapPaddles" property.
-ma <Auto|XY>
Set "Controller.MouseAxis" property.
See the Game Properties section for valid types.
-format <format>
Set "Display.Format" property. See the Game Properties section
for valid formats.
-ystart <number>
Set "Display.YStart" property (0 - 64).
-height <number>
Set "Display.Height" property (210 - 256).
-pp <Yes|No>
Set "Display.Phosphor" property.
-ppblend <number>
Set "Display.PPBlend" property, used for phosphor effect (0-100).
Default is 77.
-thumb.trapfatal <true|false>
The default of true allows the Thumb ARM emulation to
throw an exception and enter the debugger on fatal errors. When disabled, such
fatal errors are simply logged, and emulation continues. Do not use this
unless you know exactly what you're doing, as it changes the behaviour as compared
to real hardware.
2. Changing Options
Item Brief description For more information,
see CommandLineRenderer (*) use specified rendering mode (requires restart) -video TIA Filter filter for emulation mode -tia_filter TIA Palette palette for emulation mode -palette Fullscrn Res resolution for fullscreen mode -fullres Timing (*) how to wait between frames (requires restart) -timing GL Filter OpenGL filter mode -gl_filter GL Aspect (N) OpenGL width of TIA image in NTSC mode -gl_aspectn GL Aspect (P) OpenGL width of TIA image in PAL mode -gl_aspectp Framerate frames per second in emulation mode -framerate Fullscreen mode self-explanatory -fullscreen GL FS Stretch stretch fullscreen OpenGL in emulation mode -gl_fsmax GL VBO enable OpenGL Vertex Buffer Objects -gl_vbo GL VSync enable OpenGL vertical synchronization -gl_vsync PAL color-loss use PAL color-loss effect -colorloss Fast SC/AR BIOS skip progress loading bars for SuperCharger ROMs -fastscbios Show UI messages overlay UI messages onscreen -uimessages Center window attempt to center application window -center
Item Brief description For more information,
see CommandLineTV Mode disable TV effects, or select TV preset -tv_filter Scanline Intensity sets scanline black-level intensity -tv_scanlines Scanline Interpolation smooth/blend scanlines into image -tv_scaninter Adjustable sliders set specific attribute in 'Custom' mode -tv_contrast, tv_hue, etc. Clone Composite copy 'Composite' attributes to 'Custom' sliders Clone S-Video copy 'S-Video' attributes to 'Custom' sliders Clone RGB copy 'RGB' attributes to 'Custom' sliders Clone Bad Adjust copy 'Bad Adjust' attributes to 'Custom' sliders Revert revert attribute sliders to saved 'Custom' settings
Item Brief description For more information,
see CommandLineVolume self-explanatory -volume Sample size (*) set size of audio buffers -fragsize Frequency (*) change sound output frequency -freq Enable sound self-explanatory -sound
This dialog is described in further detail in
Advanced Configuration - Event Remapping.
This tab is described in further detail in
Advanced Configuration - ROM Launcher.
Item Brief description For more information,
see CommandLineDebugger Width/Height self-explanatory (requires ROM reload) -dbg.res Set window size for ... self-explanatory presets (requires ROM reload) N/A Font Style self-explanatory (requires ROM reload) -dbg.fontstyle
Item Brief description For more information,
see CommandLineInterface Palette palette to use for UI elements -uipalette List quick delay time to wait between keypresses in listwidget -listdelay Mouse wheel scroll number of lines mouse scroll will move in listwidget -mscroll
Item Brief description For more information,
see CommandLineSave path specifies where to save snapshots -snapsavedir Load path specifies where to load snapshots -snaploaddir Save snapshots according to specifies how to name saved snapshots -snapname Continuous snapshot interval interval (in seconds) between snapshot -ssinterval Overwrite existing files whether to overwrite old snapshots -sssingle Disable image filtering (1x mode) save snapshot in 1x mode, without filtering -ss1x
Item Brief description For more information,
see CommandLineRom path specifies location of ROM files -romdir Cheat file specifies location of cheatfile database -cheatfile Palette file specifies location of user palette -palettefile Properties file specifies location of external stella.pro database -propsfile State path specifies location of state files -statedir NVRAM path specifies location of NVRAM (flash/EEPROM) files -nvramdir
This dialog is described in further detail in
Advanced Configuration - ROM Audit Mode.
This dialog allows you to change all ROM properties
as described in Advanced Configuration - Game Properties.
3. Event Remapping / Input Devices
Device and port settings can be configured under the 'Devices & Ports' tab, shown below:
![]() |
|
Several options are configurable in the ROM launcher. The size of the launcher and fonts, as well as the 'ROM info viewer' can be changed in UI Settings => Launcher dialog, as shown below:
![]()
Most of the options are self-explanatory, except for the 'ROM Info viewer', which is described below.
Stella supports viewing snapshots and ROM properties of the currently selected ROM in the ROM launcher. Support is automatic, as long as your snapshot directory contains snapshots in the appropriate format. An archive of updated snapshots will be available on the Stella webpage. This archive may be updated periodically as new ROMs are found, and also for each new release of Stella. Note that the snapshots can be any size generated by Stella; they will be resized accordingly.
Currently, there are several restrictions for this feature:
- The ROM info viewer can be shown in 1x or 2x mode only.
- To view snapshots in 1x mode, the ROM launcher window must be sized at least 640x480. If the launcher isn't large enough, the functionality will be disabled.
- To view snapshots in 2x mode, the ROM launcher window must be sized at least 1000x760. If the launcher isn't large enough, an attempt will be made to use 1x mode.
The following snapshots illustrate the various font sizes and rom info zoom levels:
ROM info viewer in 1x mode, UI sized 800x480, small launcher font:
![]()
ROM info viewer in 1x mode, UI sized 1000x760, medium launcher font:
![]()
ROM info viewer in 2x mode, UI sized 1400x900, large launcher font:
![]()
The text box in the upper right corner can be used to narrow down the results in the ROM listing. When this box is empty, all files are shown (subject to the restrictions from the filtering option, explained below). Typing characters here will show only those files that match that pattern. For example, typing 'Activision' will show only files that contain the word 'Activision' in their name. This is very useful for quickly finding a group of related ROMs. Note that the search is not case sensitive, so you don't need to worry about capital or lower-case letters.
The ROM launcher also contains a context menu, selected by clicking the right mouse button anywhere in the current window. This context menu contains the following items:
Power-on options: Selecting this option shows a dialog whereby ROM properties can be temporarily overridden, and joystick/console buttons can be temporarily held down. Selecting options from this dialog will cause all ROMs launched after that to use those properties you specify. Clicking Defaults will disable its functionality, and use ROM properties as defined by the ROM itself. The dialog is as follows (See Advanced Configuration - Game Properties for more information concerning ROM properties):
Item For more information,
see CommandlineBankswitch type -bs Left Difficulty -ld Right Difficulty -rd TV Type -tv Startup Mode -debug Left joy items -holdjoy0 Right joy items -holdjoy1 Console: Select -holdselect Console: Reset -holdreset Filter listing: Selecting this option shows a dialog whereby one can filter the types of files shown in the listing. The dialog is as follows:
Currently, the choices are as follows:
- All files - self explanatory, show all files in the ROM listing. This is the default, and emulates the behaviour of all previous versions of Stella.
- All roms - show only files with a valid ROM extension. Currently, this means extensions .a26, .bin, .rom, .gz, .zip.
- ROMs ending with - show only files with a ROM extension as selected from the checkboxes.
- Reload listing: Selecting this performs a reload of the current listing. It is an alternative to pressing the Control-r key combo.
Stella has the ability to rename all your ROMs according to the name specified in the properties database. This is useful if you've downloaded ROMs in DOS 8.3 naming format, and wish the filenames to be more descriptive, or the current filenames are too large to see in the launcher.
This feature is accessible from Options => Audit ROMs, and is only available while in ROM launcher mode. The dialog box for this feature is as follows:
![]()
Simply select the ROM path with the 'Audit path' button, and click the 'Audit' button. The ROMs will then be renamed according to their internal properties. When the operation is complete, the number of ROMs that were renamed (as well as ones that weren't) will be shown.
There are several items to take note of:
- THIS OPERATION CANNOT BE UNDONE. I cannot stress this enough; if you aren't completely sure you want to rename your ROMs, don't use this function. There is no undo feature, and one won't be added.
- Only filenames that Stella considers to be valid ROMs will be considered. Currently, this means files that end in '.a26', '.bin', '.rom', '.gz' and '.zip'. Files which don't have these extensions will be ignored.
- If a valid ROM doesn't have a properties entry, it will be ignored.
Stella supports real Atari 2600 joysticks, paddles and driving controllers using the Stelladaptor and 2600-adaptor devices.
Stella can use up to two adaptors; any extra ones are ignored. Stelladaptor devices will be automatically detected and configured. Stelladaptor devices must be plugged in before starting the application; actual controllers can be plugged/unplugged while the emulator is running, although you will need to restart the game currently being emulated.
The detection and configuration is as follows:
- The first device found will act as the left game port on a real Atari. Depending on the device, Stella will detect it as either the left joystick, paddles 0 & 1, the left driving controller, left keypad, etc.
- The second device found will act as the right game port on a real Atari. Depending on the device, Stella will detect it as either the right joystick, paddles 2 & 3, the right driving controller, right keypad, etc.
- Any other devices will be ignored.
- The assignment ordering of Stelladaptor/2600-daptor to port can be redefined with 'saport' (see description in 'Starting a Game') and dynamically with the 'Control-1' key combo.
Stella supports a real AtariVox device for the speech/SpeakJet portion of the controller. You will need a real AtariVox device, located here, as well as some means of connecting it to your computer (some sort of serial port/USB adaptor). There should be drivers for your serial convertor, which allow your particular operating system to 'see' the device (configuring this is outside the scope of this document). Once your operating system properly detects the AtariVox, you will need to tell Stella which serial port it is connected to. This is done by using the '-avoxport' commandline argument, or by setting it in the UI under the 'Devices & Ports' tab in Advanced Configuration - Input Devices.
Note that you must use the entire name of the port as specified by your operating system. For example, in Windows this would be COM1, COM2, etc; Linux and MacOSX tend to use names similar to '/dev/xxxxxx'. For now, only Linux/UNIX, MacOSX, and Windows are supported.
Support for the EEPROM portion of the AtariVox and SaveKey is currently emulated. That is, a file will be created on your computer simulating the EEPROM; the actual EEPROM hardware itself will not be accessed or modified. This is very useful in the testing stages of creating a new game, since writing to a real EEPROM many times will eventually wear it out.
The location of the EEPROM files are configurable through the '-nvramdir' commandline argument and within the application itself (see Advanced Configuration - Config Paths). If the path for these files hasn't been set, the default location will depend on the version of Stella, as follows:
Linux/Unix ~/.stella/nvram/atarivox_eeprom.dat
~/.stella/nvram/savekey_eeprom.datMacintosh ~/Library/Application Support/Stella/nvram/atarivox_eeprom.dat
~/Library/Application Support/Stella/nvram/savekey_eeprom.datWindows %APPDATA%\Stella\nvram\atarivox_eeprom.dat
%APPDATA%\Stella\nvram\savekey_eeprom.dat OR
_BASEDIR_\nvram\atarivox_eeprom.dat
_BASEDIR_\nvram\savekey_eeprom.dat
(if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_)Note that these EEPROM files will be created when necessary, and initialized as a real EEPROM would be (containing all $FF). The files can be manually deleted, which is very useful in testing cases where a ROM is accessing the EEPROM for the first time.
Many options are available for ROM developers, which are described in different sections of this manual, as follows:
- Developer key-combo shortcuts, used to change TIA state dynamically (ie, while the emulation is still running). See Keyboard Layout - Developer Keys in TIA mode for more information.
- Commandline options influencing emulation state. See Using the Command Line - Developer Commands for more information.
- Viewing TIA/console information overlaid on the TIA image. This option can be enabled from the commandline or using the Alt-L key combo, and is extremely useful for viewing the current scanline count and associated frames per second, bankswitch and display formats, etc. The following shows an example of this information:
The two lines of output describe the following:
- Number of scanlines in current frame, associated framerate, and resulting display format. Note that the framerate shown is the internal, virtual framerate (it's calculated from the number of scanlines). If the '*' character is present, it means the display format was auto-detected as shown. For the given example, the format was auto-detected as 'NTSC'.
- Cartridge information. If the '*' character is present, it means the bankswitch format was auto-detected as shown. The item in round brackets indicates ROM size. For the given example, the bankswitch type was auto-detected as 4K, and the file size was 4K (4096 bytes).
Finally, Stella contains an extensive, built-in debugger. Have a look at this page for integrated debugger documentation.
Stella will remember when you change a setting either at the command line or while the emulation is running, and use the settings the next time you start the emulator. The settings are saved in a text file which can be edited outside of Stella. This file can contain your default options, and eliminates the need to specify them on the command line. Any options specified on the command line will override those in the settings file.
The syntax for the settings file is very straightforward. Any line starting with a ';' character is considered a comment and is ignored. Other lines must be of the form: command = value, where command is the same as that specified on the command line (without the '-' character), and value is dependent on the command.
For example, the following table illustrates how command line and settings entries are similar:
Command Line Settings File -video gl video = gl -volume 75 volume = 75 -center 1 center = 1 (or center = true) The settings file has a special name/location depending on which version of Stella you use, which is currently not configurable:
Linux/Unix $HOME/.stella/stellarc Macintosh Not applicable; settings are saved in ~/Library/Preferences/net.sourceforge.Stella.plist Windows %APPDATA%\Stella\stella.ini OR
_BASEDIR_\stella.ini (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_)
Stella contains support for Bob Colbert's Cheetah cheat codes, as well as an extended Stella-specific type of cheat code that works on bankswitched ROMs.
To add/remove/edit a cheat code, enter the 'Cheat Code' dialog:
![]()
Currently, there are three types of cheatcodes available, all of which must be entered in hexidecimal format:
Per-frame RAM cheats:
Evaluated each frame, and apply to RAM only. Format as follows:4-digit code: c041 c0 = address 41 = data- Cheetah codes, which are explained in detail on Bob Colbert's web page, along with a list of codes for various games. Cheetah codes don't support bankswitched ROMs, so they only work for 2K or 4K ROMs. Format as follows:
6-digit (cheetah) code: aaaddc aaa = address - $f000 dd = data c = count - 1- Stella extended cheats are similar to Cheetah codes, except that they can be 7 or 8 digits long, with the extra digits used for the bank number:
7-digit (stella) code: baaaddc b = bank (0 to $f) aaa = address - $f000 dd = data c = count - 1 8-digit (stella) code: bbaaaddc bb = bank (0 to $ff) aaa = address - $f000 dd = data c = count - 1There's also the concept of one shot codes. These codes work exactly the same as above, except they aren't saved. They are evaluated once and immediately discarded.
Here are a few cheat codes we've found:
Pitfall (standard Cheetah codes): 5b0ea1 - infinite lives 723ea1 - infinite time aa5??0 - set starting level, ?? = 01 to ff (d0 is kinda neat) Battlezone (Stella extended codes): 1236ea1 - infinite lives Ms Pac-Man (Stella extended codes): 108fea1 - infinite livesThe name of the cheat database file is configurable through the '-cheatfile' commandline argument and within the application itself (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:
Linux/Unix $HOME/.stella/stella.cht Macintosh ~/Library/Application Support/Stella/stella.cht Windows %APPDATA%\Stella\stella.cht OR
_BASEDIR_\stella.cht (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_)Stella will require a restart for changes to this file to take effect.
Stella maintains a log of its operations when the program first starts up, and while it is running. In older releases, this information was only viewable from the commandline. However, the current release allows you to see this information from within the UI. This can be selected from the main Options menu, where it is labelled "System Logs". Clicking on the button will show a window similar to the following:
Item For more information,
see CommandlineLog level -loglevel Print to console -logtoconsole The log levels are self-explanatory (None, Basic, Verbose). The "Print to console" option emulates the behaviour of older versions of Stella, whereby the logged output is also shown on the commandline from which Stella was launched (if it was launched in that fashion). Finally, the current contents of the system log can be saved to your home directory by clicking the "Save log to disk" button.
Stella uses game properties to specify the "best" emulator settings for a game. As of version 2.2 of Stella, a default database of properties are built-in, but you may modify these through the use of a stella.pro file. This file will contain all properties modified by the user. So this means that when you upgrade Stella, your personal properties settings are preserved.
Property File
A property file consists of some number of blocks. Each block in the file contains the properties for a single game. For example the general format of a property file is:
; Comments "Cartridge.MD5" "Value" "Property" "Value" "" ; Comments "Cartridge.MD5" "Value" "Property" "Value" "" . . . ; Comments "Cartridge.MD5" "Value" "Property" "Value" ""Every block in the property file must have a unique value for the Cartridge.MD5 property.
Properties
Each block in a property file consists of a set of properties for a single game. Stella supports the properties described below:
Cartridge.MD5: Indicates the MD5 checksum of the ROM image as a string of hexadecimal digits. Stella uses this property while attempting to match a game with its block of properties. If the value of the property matches the MD5 checksum of the ROM image then Stella uses that block of properties for the game. You can use the GNU md5sum program, which is included with most Linux distributions, to calculate the MD5 checksum of a ROM image. Cartridge.Manufacturer: Indicates the game's manufacturer. Cartridge.ModelNo: Indicates the manufacturer's model number for the game. Cartridge.Name: Indicates the actual name of the game. When you save snapshots, load/save state files, or use the 'ROM Audit' functionality, this is the name that will be used for the respective file(s). Cartridge.Note: Contains any special notes about playing the game. Cartridge.Rarity: Indicates how rare a cartridge is, based on the scale described on AtariAge. Cartridge.Sound: Indicates if the game should use 1 or 2 channels for sound output. All original Atari 2600 machines supported 1 channel only, but some homebrew games have been written to take advantage of stereo sound. The value must be Mono or Stereo. Cartridge.Type: Indicates the bank-switching type for the game. The value of this property must be either Auto or one of the following (for more information about bank-switching see Kevin Horton's 2600 bankswitching document or the documentation in each cartridges source code file). Types marked as (¹) do not currently have reliable auto-detection, those marked as (²) are not fully supported in the debugger:
Type Description 0840 8K ECONObanking 2IN1 ¹ 4-32K Multicart (2 games) 4IN1 ¹ 8-32K Multicart (4 games) 8IN1 ¹ 16-64K Multicart (8 games) 16IN1 ¹ 32-128K Multicart (16 games) 32IN1 ¹ 64-128K Multicart (32 games) 2K 64-2048 byte Atari 3E 32K Tigervision 3F 512K Tigervision 4A50 64K 4A50 + ram 4K 4K Atari 4KSC CPUWIZ 4K + ram AR Supercharger BF CPUWIZ 256K BFSC CPUWIZ 256K + ram CM ¹ Spectravideo CompuMate CV Commavid extra ram DF CPUWIZ 128K DFSC CPUWIZ 128K + ram DPC Pitfall II DPC+ Enhanced DPC E0 8K Parker Bros E7 16K M-network EF 64K Homestar Runner EFSC 64K Homestar Runner + ram F0 Dynacom Megaboy F4 32K Atari F4SC 32K Atari + ram F6 16K Atari F6SC 16K Atari + ram F8 8K Atari F8SC 8K Atari + ram FA CBS RAM Plus FA2 CBS RAM Plus 24/28K FE 8K Decathlon MC ¹² C. Wilkson Megacart SB 128-256k SUPERbanking UA 8K UA Ltd. X07 ¹ 64K AtariAge Console.LeftDifficulty: Indicates the default difficulty setting for the left player. The value must be A or B. Console.RightDifficulty: Indicates the default difficulty setting for the right player. The value must be A or B. Console.TelevisionType: Indicates the default television setting for the game. The value must be Color or BW. Console.SwapPorts: Indicates that the left and right ports should be swapped internally. This is used for ROMs like 'Raiders' where the Player 0 joystick is plugged into the right joystick port. The value must be Yes or No. Controller.Left:
Controller.Right:Indicates what type of controller the left and right player uses. The value must be one of the following types:
Type Description Joystick Atari's famous black joystick that was originally included with the system. BoosterGrip A controller add-in that plugs directly into the joystick port and provides a pass-through for the joystick. In doing so, it provides the two independent buttons. Paddles Standard paddle controllers for use with games such as Breakout and Warlords. One pair of controller per connector (allows for 4-player Warlords). Paddles_IAxis Same as Paddles, except the axes are inverted. Paddles_IDir Same as Paddles, except the direction of movement is inverted. Paddles_IAxDr Same as Paddles, except both the axes and direction of movement is inverted. Driving Looks like a paddle, but allows 360' movement. Only one unit per connector, unlike paddles which were sold in pairs. Keyboard Also known as the Star Raiders controller, functionally identical to the Kid's Controller and Keyboard Controller. Game included an overlay with commands, for use with Star Raiders. Trackball22 Standard Atari 2600 CX-22 trackball controller. Trackball80 Atari ST CX-80 trackball controller. AmigaMouse Commodore Amiga computer mouse. AtariVox A SpeakJet based unlimited-vocabulary speech / sound synthesizer with 32K EEPROM. SaveKey A 32K EEPROM for saving high scores, etc (the EEPROM portion of an AtariVox). Genesis Sega Genesis controller, which can be used similar to a BoosterGrip, giving an extra button. CompuMate Spectravideo CompuMate (if either left or right is set, CompuMate is used for both). Mindlink Mindlink controller. Controller.SwapPaddles: Indicates that the left and right paddles in a particular port should be swapped. This is used for ROMs like 'Demons to Diamonds' where the default paddle is paddle 1, not paddle 0. Other ROMs such as 'Tac-Scan' default to paddle 3, which can be set using both 'Controller.SwapPaddles' and 'Console.SwapPorts'. The value must be Yes or No. Controller.MouseAxis: Indicates how the mouse should emulate virtual controllers. In 'Auto' mode, the system decides how to best use the mouse. Otherwise, XY indicates how to use the X/Y axis (ie, 02 is paddle0/paddle2). Currently, the mouse X-axis and left button are tied together, as are the Y-axis and right button. The value must be Auto or XY, as follows:
Id Controller 0 Paddle 0 1 Paddle 1 2 Paddle 2 3 Paddle 3 4 Driving 0 5 Driving 1 6 MindLink 0 7 MindLink 1 Display.Format: Indicates the television format the game was designed for. The value must be Auto, NTSC, PAL, SECAM, NTSC50, PAL60 or SECAM60. Display.YStart: Indicates the scan-line to start displaying at. The value must be n such that 0 <= n <= 64. Display.Height: Indicates the number of scan-lines to display. The value must be n such that 210 <= n <= 256. Display.Phosphor: Indicates whether the phosphor effect should be emulated or not. The value must be Yes or No. Display.PPBlend: Indicates the amount of blending which will occur while using the phosphor effect. The value must be n such that 0 <= n <= 100. The default value is 77. The name of the properties file is configurable through the '-propsfile' commandline argument and within the application itself (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:
Linux/Unix $HOME/.stella/stella.pro Macintosh ~/Library/Application Support/Stella/stella.pro Windows %APPDATA%\Stella\stella.pro OR
_BASEDIR_\stella.pro (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_)Stella will require a restart for changes to this file to take effect.
An Atari 2600 palette consists of 128 colours, which are different for the three major television standards (NTSC, PAL, SECAM). Stella supports two built-in palettes and one user-defined palette for each format. These are set using the '-palette' option, and are described as follows:
standard The default palette from Stella 1.4 onwards. z26 The palette from the z26 emulator. user An external palette file, supplied by the user. A user-defined palette has certain restrictions, further described as follows:
- The palette file must be at least 792 bytes long. Colours are stored in 24-bit RGB, with the first byte for red, the second for green, the third for blue, for a total of 3 bytes per colour.
- The first 384 bytes of the file (128 * 3) will be used for the NTSC palette. The next 384 bytes (128 * 3) will be for the PAL palette. The next 24 bytes (8 * 3) will be for the SECAM palette, which consists of eight distinct colours. Any extra data in the file will be ignored.
- The PAL colour-loss effect is calculated within Stella. You do not need to specify those colours in the palette file.
The name of the palette file is configurable through the '-palettefile' commandline argument and within the application itself (see Advanced Configuration - Config Paths). If the path for this file hasn't been set, the default filename will depend on the version of Stella, as follows:
Linux/Unix $HOME/.stella/stella.pal Macintosh ~/Library/Application Support/Stella/stella.pal Windows %APPDATA%\Stella\stella.pal OR
_BASEDIR_\stella.pal (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_)Note that to actually use the external palette, the palette file must exist and be valid, and the palette option should be set to user (in Video Settings dialog). The current ROM will have to be reloaded for changes to this file to take effect.
Bradford W. Mott started developing Stella during the fall of 1995, and Stephen Anthony has maintained the project since around 2004. Over the years, a number of people from around the world have contributed to the project. Some people have provided technical help while others have offered suggestions and praise. The Stella Team is grateful for all the help and support it has received over the years. A (likely incomplete) list of the people who have played a part in bringing Stella to you is available on the main Stella webpage Credits List. If we've missed someone, please let us know.
Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. stella-3.9.3/docs/debugger.html 0000644 0001750 0000144 00000200711 12205116016 015774 0 ustar stephen users
The debugger in Stella may never be complete, as we're constantly adding new features requested by homebrew developers. However, even in its current form it's still quite powerful, and is able to boast at least one feature that no other 2600 debugger has; it's completely cross-platform.
Pressing ` (aka backtick, backquote, grave accent) toggles the debugger on & off. When you exit the debugger, the emulation resumes at the current program counter, and continues until either a breakpoint/trap is hit, or the ` key is pressed again.
The main debugger window will look similar to the following (note that the letters here are for reference in the document below; they aren't actually present in the debugger):
For space reasons, the Prompt, TIA, I/O and Audio displays are split into 4 tabs, only one of which is visible at a time. You can use the mouse or keyboard to select which tab you want to view. Pressing Shift with the left or right arrow keys cycles between tabs from right-to-left and left-to-right, respectively. Pressing Tab cycles between widgets in the current tab (except for in the Prompt area, where 'tab' is used for something else).
You can also enter the debugger at emulator startup by use the 'debug' command on the command line, or alternatively within the ROM launcher in 'Power-on options':
; will enter the debugger before any instructions run stella -debug mygame.bin ; alternatively, you can use 'break' to accomplish the same thing ; $fffc is the 6502/6507 init vector. This command will break and enter the ; debugger before the first 6507 instruction runs, so you can debug the ; startup code: stella -break "*($fffc)" mygame.bin
Using the ` key will always enter the debugger at the end of the frame (scanline 262, for NTSC games). This is because Stella only checks for keystrokes once per frame. Once in the debugger, you can control execution by stepping one instruction, scanline, or frame at a time (or more than one at a time, using commands in the prompt). You can also set breakpoints or traps, which will cause the emulator to enter the debugger when they are triggered, even if it happens in mid-frame.
The debugger tracks changes to the CPU registers and RAM by displaying changed locations or registers with a red background after each step, trace, scanline, or frame advance. This sounds simple, and it is, but it's also amazingly useful.
One clarification about the change tracking: it only tracks when values have changed. If the ROM writes a value into a RAM location that already contained the same value, that's not considered a change (old value was $whatever, new value is the same, so nothing got tracked). This may change in a future version of Stella.
This is a command-line interface, similar to the DOS DEBUG command or Supermon for the C=64.
Editing keys work about like you'd expect them to in Windows, but many Bash-style commands are also supported:
Home | Move cursor to beginning of line |
End | Move cursor to end of line |
Delete | Remove character to right of cursor |
Backspace | Remove character to left of cursor |
Control-a | Same function as 'Home' |
Control-e | Same function as 'End' |
Control-d | Same function as 'Delete' |
Control-k | Remove all characters from cursor to end of line |
Control-u | Remove all characters from cursor to beginning of line |
Control-w | Remove entire word to left of cursor |
Shift-PgUp | Scroll up through previous commands one screen/page |
Shift-PgDown | Scroll down through previous commands one screen/page |
Shift-Up | Scroll up through previous commands one line |
Shift-Down | Scroll down through previous commands one line |
Shift-Home | Scroll to beginning of commands |
Shift-End | Scroll to end of commands |
You can also scroll with the mouse. Copy and paste is not yet supported.
To see the available commands, enter "help". Bash-style tab completion is supported for commands, labels and functions (see below).
For now, there are some functions that only exist in the prompt. We intend to add GUI equivalents for all (or almost all?) of the prompt commands in future releases. People who like command prompts will be able to use the prompt, but people who hate them will have a fully functional debugger without typing (or without typing much, anyway).
While entering a command, label or function, you can type a partial name and press the Tab key to attempt to auto-complete it. If you've ever used "bash", this will be immediately familiar. If not, try it: load up a ROM, go to the debugger, type "print w" (but don't press Enter), then hit Tab. The "w" will change to "WSYNC" (since this is the only built-in label starting with a "w"). If there are multiple possible completions (try with "v" instead of "w"), you'll see a list of them, and your partial name will be completed as far as possible.
Tab completion works on all labels: built-in, loaded from a symbol file, or set during debugging with the "define" command. It also works with built-in functions and those defined with the "function" command, but it doesn't (yet) work on filenames.
Almost every command takes a value: the "a" command takes a byte to stuff into the accumulator, the "break" command takes an address to set/clear a breakpoint at. These values can be as a hex constant ($ff, $1234), or as complex as "the low byte of the 16-bit value located at the address pointed to by the binary number 1010010110100101" (which would be "@<\1010010110100101"). You can also use registers and labels in expressions.
You can use arithmetic and boolean operators in expressions. The syntax is very C-like. The operators supported are:
+ - * / (add, subtract, multiply, divide: 2+2 is 4) % (modulus/remainder: 3%2 is 1) & | ^ ~ (bitwise AND, OR, XOR, NOT: 2&3 is 2) && || ! (logical AND, OR, NOT: 2&&3 is 1, 2||0 is 0) ( ) (parentheses for grouping: (2+2)*3 is 12) * @ (byte and word pointer dereference: *$80 is the byte stored at location $80) [ ] (array-style byte pointer dereference: $80[1] is the byte stored at location ($80+1) or $81) < > (prefix versions: low and high byte. <$abcd is $cd) == < > <= >= != (comparison: equality, less-than, greater-than, less-or-equals, greater-or-equals, not-equals) << >> (bit shifts, left and right: 1<<1 is 2, 2>>1 is 1)
Division by zero is not an error: it results in zero instead.
None of the operators change the values of their operands. There are no variable-assignment or increment/decrement operators. This may change in the future, which is why we used "==" for equality instead of just "=".
The bitwise and logical boolean operators are different in that the bitwise operators operate on all the bits of the operand (just like AND, ORA, EOR in 6502 asm), while the logical operators treat their operands as 0 for false, non-zero for true, and return either 0 or 1. So $1234&$5678 results in $1230, whereas $1234&&$5678 results in 1. This is just like C or C++...
Like some programming languages, the debugger uses prefixed characters to change the meaning of an expression. The prefixes are:
"*"
Dereference a byte pointer. "*a" means "the byte at the address that
the A register points to". If A is 255 (hex $ff), the result will be
the value currently stored in memory location 255. This operator
will be very familiar to you if you're a C or C++ programmer. It's
equivalent to the PEEK() function in most 8-bit BASICs. Also, the
debugger supports array-like byte dereferences: *address can be
written as address[0]. *(address+1) can be written as address[1],
etc.
"@"
Dereference a pointer to a word. This is just like the "*" byte deref,
except it refers to a 16-bit value, occupying 2 locations, in
low-byte-first format (standard for the 6507).
The following are equivalent:
@address *address+$100**(address+1) address[0]+#256*address[1]
(TODO: add (indirect),y and (indirect,x) syntax)
"<"
Take the low byte of a 16-bit value. This has no effect on an 8-bit
value: "a" is equal to "<a". However, "<$1234" equals "$34".
">"
Take the high byte of a 16-bit value. For 8-bit values such as
the Accumulator, this will always result in zero. For 16-bit values,
"<$1234" = "$12".
"#"
Treat the input as a decimal number.
"$"
Treat the input as a hex number.
"\"
Treat the input as a binary number.
These only have meaning when they come before a number, not a label or a register. "\1010" means 10 decimal. So do "$0a" and "#10". "a" by itself is always the Accumulator, no matter what the default base is set to.
If you don't specify any number base prefix, the number is assumed to be in the default base. When you first start Stella, the default base is 16 (hexadecimal). You can change it with the "base" command. If you want to change the default base to decimal permanently, you can put a "base #10" command in your "autoexec.stella" file (see the section on "Startup").
Remember, you can use arbitrarily complex expressions with any command that takes arguments.
A breakpoint is a "hotspot" in your program that causes the emulator to stop emulating and jump into the debugger. You can set as many breakpoints as you like. The command is "break xx" where xx is any expression. If you've created a symbol file, you can use labels.
Example: you've got a label called "kernel". To break there, the command is "break kernel". After you've set the breakpoint, exit the debugger ("quit" or click the Exit button). The emulator will run until it gets to the breakpoint, then it will enter the debugger with the Program Counter pointing to the instruction at the breakpoint.
Breakpoints happen *before* an instruction is executed: the instruction at the breakpoint location will be the "next" instruction.
To remove a breakpoint, you just run the same command you used to set it. In the example, "break kernel" will remove the breakpoint. The "break" command can be thought of as a *toggle*: it turns the breakpoint on & off, like a light switch.
You could also use "clearbreaks" to remove all the breakpoints. Also, there is a "listbreaks" command that will list them all.
A conditional breakpoint causes the emulator to enter the debugger when some arbitrary condition becomes true. "True" means "not zero" here: "2+2" is considered true because it's not zero. "2-2" is false, because it evaluates to zero. This is exactly how things work in C and lots of other languages, but it might take some getting used to if you've never used such a language.
Suppose you want to enter the debugger when the Game Reset switch is pressed. Looking at the Stella Programmers' Guide, we see that this switch is read at bit 0 of SWCHB. This bit will be 0 if the switch is pressed, or 1 otherwise.
To have an expression read the contents of an address, we use the dereference operator "*". Since we're looking at SWCHB, we need "*SWCHB".
We're only wanting to look at bit 0, so let's mask off all the other bits: "*SWCHB&1". The expression now evaluates to bit 0 of SWCHB. We're almost there: this will be 1 (true) if the switch is NOT pressed. We want to break if it IS pressed...
So we invert the sense of the test with a logical NOT operator (which is the "!" operator): !(*SWCHB&1). The parentheses are necessary as we want to apply the ! to the result of the &, not just the first term (the "*SWCHB").
"breakif !(*SWCHB&1)" will do the job for us. However, it's an ugly mess of letters, numbers, and punctuation. We can do a little better:
"breakif { !(*SWCHB & 1 ) }" is a lot more readable, isn't it? If you're going to use readable expressions with spaces in them, enclose the entire expression in curly braces.
Remember that Stella only checks for input once per frame, so a break condition that depends on input (like SWCHB) will always happen at the end of a frame. This is different from how a real 2600 works, but most ROMs only check for input once per frame anyway.
Conditional breaks appear in "listbreaks", numbered starting from zero. You can remove a cond-break with "delbreakif number", where the number comes from "listbreaks".
Any time the debugger is entered due to a trap, breakpoint, or conditional break, the reason will be displayed in the status area near the TIA Zoom display (area H).
There is one annoyance about complex expressions: once we remove the conditional break with "delbreakif" or "clearbreaks", we'd have to retype it (or search backwards with the up-arrow key) if we wanted to use it again.
We can avoid this by defining the expression as a function, then using "breakif function_name":
function gameReset { !(*SWCHB & 1 ) } breakif gameReset
Now we have a meaningful name for the condition, so we can use it again. Not only that: we can use the function as part of a bigger expression. Suppose we've also defined a gameSelect function that evaluates to true if the Game Select switch is pressed. We want to break when the user presses both Select and Reset:
breakif { gameReset && gameSelect }
User-defined functions appear in "listfunctions", which shows the label and expression for each function. Functions can be removed with "delfunction label", where the labels come from "listfunctions".
If you've defined a lot of complex functions, you probably will want to re-use them in future runs of the debugger. You can save all your functions, breakpoints, conditional breaks, and watches with the "save" command. If you name your saved file the same as the ROM filename and place it in the ROM directory, it'll be auto-loaded next time you load the same ROM in Stella. The save file is just a plain text file called "rom_filename.stella", so you can edit it and add new functions, etc.
You can also create a file called "autoexec.stella" which will be loaded when the debugger starts, no matter what ROM you have loaded. The location of this file will depend on the version of Stella, as follows:
Linux/Unix | ~/.stella/autoexec.stella |
Macintosh | ~/Library/Application Support/Stella/autoexec.stella |
Windows | %APPDATA%\Stella\autoexec.stella
OR _BASEDIR_\autoexec.stella (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_) |
Note that these '.stella' script files are only accessed if you enter the debugger at least once during a program run. This means you can create these files, and not worry about slowing down emulation unless you're actively using the debugger.
Stella has some pre-defined functions for use with the "breakif" command. These allow you to break and enter the debugger on various conditions without having to define the conditions yourself.
Built-in functions and pseudo-registers always start with an _ (underscore) character. It is suggested that you don't start labels in your game's source with underscores, if you plan to use them with the Stella debugger.
Function | Definition | Description |
---|---|---|
_joy0left | !(*SWCHA & $40) | Left joystick moved left |
_joy0right | !(*SWCHA & $80) | Left joystick moved right |
_joy0up | !(*SWCHA & $10) | Left joystick moved up |
_joy0down | !(*SWCHA & $20) | Left joystick moved down |
_joy0button | !(*INPT4 & $80) | Left joystick button pressed |
_joy1left | !(*SWCHA & $04) | Right joystick moved left |
_joy1right | !(*SWCHA & $08) | Right joystick moved right |
_joy1up | !(*SWCHA & $01) | Right joystick moved up |
_joy1down | !(*SWCHA & $02) | Right joystick moved down |
_joy1button | !(*INPT5 & $80) | Right joystick button pressed |
_select | !(*SWCHB & $02) | Game Select pressed |
_reset | !(*SWCHB & $01) | Game Reset pressed |
_color | *SWCHB & $08 | Color/BW set to Color |
_bw | !(*SWCHB & $08) | Color/BW set to BW |
_diff0b | !(*SWCHB & $40) | Left difficulty set to B (easy) |
_diff0a | *SWCHB & $40 | Left difficulty set to A (hard) |
_diff1b | !(*SWCHB & $80) | Right difficulty set to B (easy) |
_diff1a | *SWCHB & $80 | Right difficulty set to A (hard) |
Don't worry about memorizing them all: the Prompt "help" command will show you a list of them.
These "registers" are provided for you to use in your conditional breaks. They're not registers in the conventional sense, since they don't exist in a real system. For example, while the debugger keeps track of the number of scanlines in a frame, a real system would not (there is no register that holds 'number of scanlines' on an actual console).
Function | Description |
---|---|
_bank | Currently selected bank |
_rwport | Last address to attempt a read from the cart write port |
_fcount | Number of frames since emulation started |
_cclocks | Color clocks on a scanline |
_scan | Current scanline count |
_vsync | Whether vertical sync is enabled (1 or 0) |
_vblank | Whether vertical blank is enabled (1 or 0) |
_scan always contains the current scanline count. You can use this to break your program in the middle of your kernel. Example:
breakif _scan==#64
This will cause Stella to enter the debugger when the TIA reaches the beginning of the 64th scanline.
_bank always contains the currently selected bank. For 2K or 4K (non-bankswitched) ROMs, it will always contain 0. One useful use is:
breakif { pc==myLabel && _bank==1 }
This is similar to setting a regular breakpoint, but it will only trigger when bank 1 is selected.
A watch is an expression that gets evaluated and printed before every prompt. This is useful for e.g. tracking the contents of a memory location while stepping through code that modifies it.
You can set up to 10 watches (in future the number will be unlimited). Since the expression isn't evaluated until it's used, you can include registers: "watch *y" will show you the contents of the location pointed to by the Y register, even if the Y register changes.
The watches are numbered. The numbers are printed along with the watches, so you can tell which is which. To delete a watch use the "delwatch" command with the watch number (1 to whatever). You can also delete them all with the "clearwatches" command.
Note that there's no real point in watching a label or CPU register without dereferencing it: Labels are constants, and CPU registers are already visible in the CPU Widget
A trap is similar to a breakpoint, except that it catches accesses to a memory address, rather than specific location in the program. They're useful for finding code that modifies TIA registers or memory.
An example: you are debugging a game, and you want to stop the emulation and enter the debugger whenever RESP0 is strobed. You'd use the command "trap RESP0" to set the trap, then exit the debugger. The emulator will run until the next time RESP0 is accessed (either read or write). Once the trap is hit, you can examine the TIA state to see what the actual player 0 position is, in color clocks (or you can in the future when we implement that feature in the TIA dump!)
Unlike breakpoints, traps stop the emulation *after* the instruction that triggered the trap. The reason for this is simple: until the instruction is executed, the emulator can't know it's going to hit a trap. After the trap is hit, the instruction is done executing, and whatever effects it may have had on e.g. the TIA state have already happened... but we don't have a way to run the emulated VCS in reverse, so the best we can do is stop before the next instruction runs.
Traps come in two varieties: read access traps and write access traps. It is possible to set both types of trap on the same address (that's what the plain "trap" command does). To set a read or write only trap, use "trapread" or "trapwrite". To remove a trap, you just attempt to set it again: the commands actually toggle the trap on & off. You can also get rid of all traps at once with the "cleartraps" command.
Use "listtraps" to see all enabled traps.
Type "help" to see this list in the debugger.
a - Set Accumulator to value xx bank - Show # of banks, or switch to bank xx base - Set default base (hex, dec, or bin) break - Set/clear breakpoint at address xx (default=PC) breakif - Set breakpoint on condition xx c - Carry Flag: set (0 or 1), or toggle (no arg) cheat - Use a cheat code (see manual for cheat types) clearbreaks - Clear all breakpoints clearconfig - Clear Distella config directives [bank xx] cleartraps - Clear all traps clearwatches - Clear all watches cls - Clear prompt area of text and erase history code - Mark 'CODE' range in disassembly colortest - Show value xx as TIA color d - Decimal Flag: set (0 or 1), or toggle (no arg) data - Mark 'DATA' range in disassembly define - Define label xx for address yy delbreakif - Delete conditional breakif xx delfunction - Delete function with label xx delwatch - Delete watch xx disasm - Disassemble address xx [yy lines] (default=PC) dump - Dump 128 bytes of memory at address xx exec - Execute script file xx exitrom - Exit emulator, return to ROM launcher frame - Advance emulation by xx frames (default=1) function - Define function name xx for expression yy gfx - Mark 'CFX' range in disassembly help - This cruft jump - Scroll disassembly to address xx listbreaks - List breakpoints listconfig - List Distella config directives [bank xx] listfunctions - List user-defined functions listtraps - List traps loadconfig - Load Distella config file loadstate - Load emulator state xx (0-9) n - Negative Flag: set (0 or 1), or toggle (no arg) pc - Set Program Counter to address xx pgfx - Mark 'PGFX' range in disassembly print - Evaluate/print expression xx in hex/dec/binary ram - Show ZP RAM, or set address xx to yy1 [yy2 ...] reset - Reset 6507 to init vector (excluding TIA/RIOT) rewind - Rewind state to last step/trace/scanline/frame riot - Show RIOT timer/input status rom - Set ROM address xx to yy1 [yy2 ...] row - Mark 'ROW' range in disassembly run - Exit debugger, return to emulator runto - Run until string xx in disassembly runtopc - Run until PC is set to value xx s - Set Stack Pointer to value xx save - Save breaks, watches, traps to file xx saveconfig - Save Distella config file savedis - Save Distella disassembly saverom - Save (possibly patched) ROM saveses - Save console session to file xx savestate - Save emulator state xx (valid args 0-9) scanline - Advance emulation by xx scanlines (default=1) step - Single step CPU [with count xx] tia - Show TIA state (NOT FINISHED YET) trace - Single step CPU over subroutines [with count xx] trap - Trap read/write access to address(es) xx [to yy] trapread - Trap read access to address(es) xx [to yy] trapwrite - Trap write access to address(es) xx [to yy] type - Show disassembly type for address xx [to yy] uhex - Toggle upper/lowercase HEX display undef - Undefine label xx (if defined) v - Overflow Flag: set (0 or 1), or toggle (no arg) watch - Print contents of address xx before every prompt x - Set X Register to value xx y - Set Y Register to value xx z - Zero Flag: set (0 or 1), or toggle (no arg)
When selected, this tab shows detailed status of all the TIA registers (except for audio; use the Audio tab for those).
Most of the values on the TIA tab will be self-explanatory to a 2600 programmer.
Many of the variables inside the TIA can only be written to by the 6502. The debugger lets you get inside the TIA and see the contents of these variables. These include the color registers, player/missile graphics and positions, and the playfield.
You can control almost every aspect of the TIA from here, too: most of the displays are editable. You can even toggle individual bits in the GRP0/1 and playfield registers (remember to double-click).
The group of buttons labelled "Strobes" allows you to write to any of the strobe registers at any time.
The collision registers are displayed in decoded format, in a table. You can see exactly which objects have hit what. These are read-only displays; you can't toggle the bits in the current release of Stella. Of course, you can clear all the collisions with the CXCLR Strobe button.
To the right of each color register, you'll see a small rectangle drawn in the current color. Changing a color register will change the color of this rectangle.
When selected, this tab shows detailed status of the Input, Output, and Timer portion of the RIOT/M6532 chip (the RAM portion is accessed in another part of the debugger).
As with the TIA tab, most of the values here will be self-explanatory to a 2600 programmer, and almost all can be modified. However, the SWCHx registers need further explanation:
SWCHx(W) can be modified; here, the (W) stands for write. Similarly, SWACNT/SWBCNT can be directly modified. However, the results of reading back from the SWCHx register are influenced by SWACNT/SWBCNT, and SWCHx(R) is a read-only display reflecting this result.
This tab lets you view the contents of the TIA audio registers. In the current release of Stella, these are read-only displays. This tab will grow some features in a future release.
In the upper left of the debugger, you'll see the current frame of video as generated by the TIA. If a complete frame hasn't been drawn, the partial contents of the current frame will be displayed up to the current scanline, with the contents of the old frame (in black & white) filling the rest of the display. Note that if 'phosphor mode' has been enabled for a ROM, you will see the effect here as well. That is, no flicker will be shown for 30Hz display, even though a real system would alternate between drawing frames (and hence produce flicker).
You can use the "Scan+1" button, the prompt "scan" command, or the Alt-L key-combo to watch the TIA draw the frame one scanline at a time.
You can also right-click anywhere in this window to show a context menu, as illustrated:
The options are as follows:
To the right of the TIA display (E) there is TIA information, as shown:
The indicators are as follows:
Below the TIA Info (F) is the TIA Zoom area. This allows you to enlarge part of the TIA display, so you can see fine details. Note that unlike the TIA display area, this one does generate frames as the real system would. So, if you've enabled 'phosphor mode' for a ROM, it won't be honoured here (ie, you'll see alternating frames at 30Hz display, just like on a real system).
You can also right-click anywhere in this window to show a context menu, as illustrated:
These options allow you to zoom in on the image for even greater detail. If you click on the output window, you can scroll around using the cursor, PageUp/Dn and Home/End keys. You can also select the zoom position from a context menu in the TIA Display.
Below the TIA Zoom (G), there is a status line that shows the reason the debugger was entered (if a breakpoint/trap was hit), as shown:
The output here will generally be self-explanatory. Due to space concerns, conditional breakpoints will be shown as "CBP: ...", normal breakpoints as "BP: ...", read traps as "RTrap: ..." and write traps as "WTrap: ...". See the "Breakpoints" section for details.
This displays the current CPU state, as shown:
All the registers and flags are displayed, and can be changed by double-clicking on them (to the left). Flags are toggled on double-click. Selected registers here can also be changed by using the "Data Operations" buttons, further described in (J). All items are shown in hex. Any label defined for the current PC value is shown to the right. Decimal and binary equivalents are shown for SP/A/X/Y to the right (first decimal, then binary).
The column to the far right shows the 'source' of contents of the respective registers. For example, consider the command 'LDA ($80),Y'. The operand of the command resolves to some address, which isn't always easy to determine at first glance. The 'Src Addr' area shows the actual resulting operand/address being used with the given opcode.
There's not much else to say about the CPU widget: if you know 6502 assembly, it's pretty self-explanatory. If you don't, well, you should learn :)
These buttons can be used to change values in either CPU Registers (I), or the RIOT RAM (K), depending on which of these widgets is currently active.
Each of these buttons also have a keyboard shortcut (indicated in square brackets). In fact, many of the inputboxes in various parts of the debugger respond to these same keyboard shortcuts. If in doubt, give them a try.
0 [z] - Set the current location/register to zero. Inv [i !] - Invert the current location/register [toggle all its bits]. Neg [n] - Negate the current location/register [twos' complement negative]. ++ [+ =] - Increment the current location/register -- [-] - Decrement the current location/register << [< ,] - Shift the current location/register left. >> [> .] - Shift the current location/register right. Any bits shifted out of the location/register with << or >> are lost (they will NOT end up in the Carry flag).
This is a spreadsheet-like GUI for inspecting and changing the contents of the 2600's RAM. You can view 128 bytes of RAM at a time, starting with the RAM built in to the console (zero-page RAM). If a cartridge contains extended RAM, a scrollbar will be activated, allowing to scroll in sequence through each 128 byte 'bank' of RAM. The address in the upper left corner indicates the offset (in terms of the read port) for the bank currently being displayed.
You can navigate with either the mouse or the keyboard arrow keys. To change a RAM location, either double-click on it or press Enter while it's highlighted. Enter the new value (hex only for now, sorry), then press Enter to make the change. If you change your mind, press Escape and the original value will be restored. The currently selected RAM cell can also be changed by using the Data operations buttons/associated shortcut keys (J).
Note: Many extended RAM schemes involve different addresses for reading versus writing RAM (read port vs. write port). The UI takes care of this for you; although the addresses shown are for the read port, modifying a cell will use the write port. Also, some bankswitching schemes can swap RAM and ROM dynamically during program execution. In these cases, the values shown may not always be for RAM, and may point to ROM instead. In the latter case, the data cannot be modified.
The 'Undo' button in the upper right should be self-explanatory; it will undo the most previous operation to one cell only. The 'Revert' button is more comprehensive. It will undo all operations on all cells since you first made a change.
The UI objects at the bottom refer to the currently selected RAM cell. The 'label' textbox shows the label attached to this RAM location (if any), and the other textboxes show the decimal and binary equivalent value. The remaining buttons to the right are further explained in section (L).
The RAM widget also lets you search memory for values such as lives or remaining energy, but it's also very useful when debugging to determine which memory location holds which quantity.
To search RAM, click 'Search' and enter a byte value into the search editbox (0-255). All matching values will be highlighted in the RAM widget. If 'Search' is clicked and the input is empty, all RAM locations are highlighted.
The 'Compare' button is used to compare the given value using all addresses currently highlighted. This may be an absolute number (such as 2), or a comparitive number (such as -1). Using a '+' or '-' operator means 'search addresses for values that have changed by that amount'.
The 'Reset' button resets the entire operation; it clears the highlighted addresses and allows another search.
The following is an example of inspecting all addresses that have decreased by 1:
This area contains a disassembly of the current bank of ROM. If a symbol file is loaded, the disassembly will have labels. Even without a symbol file, the standard TIA/RIOT labels will still be present.
The disassembly is often quite extensive, and whenever possible tries to automatically differentiate between code, graphics, data and unused bytes. There are actually two levels of disassembly in Stella. First, the emulation core tracks accesses as a game is running, making for very accurate results. This is known as a dynamic analysis. Second, the built-in Distella code does a static analysis, which tentatively fills in sections that the dynamic disassembler missed (usually because the addresses haven't been accessed at runtime yet).
As such, code can be marked in two ways (absolute, when done by the emulation core), and tentative (when done by Distella, and the emulation core hasn't accessed it yet). Such 'tentative' code is marked with the '*' symbol, indicating that it has the potential to be accessed as code sometime during the program run. This gives very useful information, since it can indicate areas toggled by an option in the game (ie, when a player dies, when difficulty level changes, etc). It can also indicate whether blocks of code after a relative jump are in fact code, or simply data.
The "Bank state" is self-explanatory, and shows a summary of the current bank information. For normal bankswitched ROMs, this will be the current bank number, however more advanced schemes will show other types of information here. More detailed information is available in Detailed Bankswitch Information (N).
Each line of disassembly has four fields:
At this point, we should explain the various 'types' that the disassembler can use. These are known as 'directives', and partly correspond to configuration options from the standalone Distella program. They are listed in order of decreasing hierarchy:
CODE | Addresses which have appeared in the program counter, or which tentatively can appear in the program counter. These can be edited in hex. |
GFX | Addresses which contain data stored in the player graphics registers (GRP0/GRP1). These addresses are shown with a bitmap of the graphics, which can be edited in either hex or binary. The bitmap is shown as large blocks. |
PGFX | Addresses which contain data stored in the playfield graphics registers (PF0/PF1/PF2). These addresses are shown with a bitmap of the graphics, which can be edited in either hex or binary. The bitmap is shown as small dashes. |
DATA | Addresses used as an operand for some opcode. These can be edited in hex. |
ROW | Addresses not used as any of the above. These are shown up to 8 per line, and cannot be edited. |
For code sections, the 6502 mnemonic will be UPPERCASE for all standard instructions, or lowercase for "illegal" 6502 instructions (like "dcp"). If automatic resolving of code sections has been disabled for any reason, you'll likely see a lot of illegal opcodes if you scroll to a data table in ROM. This can also occur if the disassembler hasn't yet encountered addresses in the PC. If you step/trace/scanline/frame advance into such an area, the disassembler will make note of it, and disassemble it correctly from that point on.
You can scroll through the disassembly with the mouse or keyboard. To center the display on the current PC, press the Space bar.
Any time the Program Counter changes (due to a Step, Trace, Frame or Scanline advance, or manually setting the PC), the disassembly will scroll to the current PC location.
Even though ROM is supposed to be Read Only Memory, this is an emulator: you can change ROM all you want within the debugger. The hex bytes in the ROM Widget are editable. Double-click on them to edit them. When you're done, press Enter to accept the changes (in which case the cart will be re-disasembled) or Escape to cancel them. Note that only instructions that have been fully disassembled can be edited. In particular, blank lines or 'ROW' directives cannot be edited. Also note that certain ROMs can have sections of address space swapped in and out dynamically. As such, changing the contents of a certain address will change the area pointed to at that time. In particular, modifying an address that points to internal RAM will change the RAM, not the underlying ROM. A future release may graphically differentiate between RAM and ROM areas.
The ROM Disassembly also contains a Settings dialog, accessible by right-clicking anywhere in the listing:
The following options are available:
These limitations will be addressed in a future release of Stella.
This area shows a detailed breakdown of the bankswitching scheme. Since the bankswitch schemes can greatly vary in operation, this tab will be different for each scheme, but its specific functionality should be self-explanatory. An example of both 4K (non-bankswitched) and DPC (Pitfall II) is as follows:
In many cases, quite a bit of the scheme functionality can be modified. Go ahead and try to change something!
There are also buttons on the right that always show up no matter which tab you're looking at. These are always active. They are: Step, Trace, Scan+1, Frame+1 and Exit. The larger button to the left (labeled '<') performs the rewind operation, which will undo the previous Step/Trace/Scan/Frame advance. The rewind buffer is currently 100 levels deep.
When you use these buttons, the prompt doesn't change. This means the status lines with the registers and disassembly will be "stale". You can update them just by re-running the relevant commands in the prompt.
You can also use the Step, Trace, Scan+1, Frame+1 and Rewind buttons from anywhere in the GUI via the keyboard, with Alt-S, Alt-T, Alt-L, Alt-F and Alt-R.
As mentioned in ROM Disassembly (M), Stella supports the following directives: CODE/GFX/PGFX/DATA/ROW. While the debugger will try to automatically mark address space with the appropriate directive, there are times when it will fail. There are several options in this case:
The location of 'configdir' will depend on the version of Stella, as follows:
Linux/Unix | ~/.stella/cfg/ |
Macintosh | ~/Library/Application Support/Stella/cfg/ |
Windows | %APPDATA%\Stella\cfg\
OR _BASEDIR_\cfg\ (if a file named 'basedir.txt' exists in the application directory containing the full pathname for _BASEDIR_) |
Here is a step-by-step guide that shows you how to use the debugger to actually do something useful. No experience with debuggers is necessary, but it helps to know at least a little about 6502 programming.
Since we just want to get rid of the instruction, we can replace it with NOP (no operation). From looking at the disassembly, you can see that "DEC $ba" is a 2-byte long instruction, so we will need two one-byte NOP instructions to replace it. From reading the prompt help (the "help" command), you can see that the "rom" command is what we use to patch ROM.
Unfortunately, Stella doesn't contain an assembler, so we can't just type NOP to put a NOP instruction in the code. We'll have to use the hex opcode instead.
Now crack open your 6502 reference manual and look up the NOP instruction's opcode... OK, OK, I'll just tell you what it is: it's $EA (234 decimal). We need two of them, so the bytes to insert will look like:
$ea $ea
Select the line at address $f236 and enter 'ROM patch' mode. This is done by either double-clicking the line, or pressing enter. Then delete the bytes with backspace key and enter "ea ea". Another way to do this would have been to enter "rom $f236 $ea $ea" in the Prompt widget.
Now, try the same techniques on some other ROM image (try Pac-Man). Some games store (lives+1) or (lives-1) instead of the actual number, so try searching for those if you can't seem to make it work.
If you successfully patch a ROM in the debugger, but the saved version won't work, or looks funny, you might need to add an entry to the stella.pro file, to tell Stella what bankswitch and/or TV type to use. That's outside the scope of this tutorial :)
Of course, the debugger is useful for a lot more than cheating and hacking ROMs. Remember, with great power comes great responsibility, so you have no excuse to avoid writing that game you've been thinking about for so long now :)
stella-3.9.3/docs/graphics/ 0000755 0001750 0000144 00000000000 12267274567 015151 5 ustar stephen users stella-3.9.3/docs/graphics/options_video_tv.png 0000644 0001750 0000144 00000017517 12162610274 021243 0 ustar stephen users ‰PNG IHDR Þ Z °¿< bKGD ÿ ÿ ÿ ½§“ pHYs a a¨?§i tIMEÝ 8&ÚM_ tEXtComment Created with GIMPW ·IDATxÚíݽŽÖHº `3ê`Fâ"&dDBr$$RP_Ñv†6ê„`‘ÈI'AÄHH³ ê‘6õE õÜ'˜cŽ©-Ûe»l—íç‘Z¢¿¯°Ë?]¯ß*Ûu硗ßÞ}üZ Ëzþä^uçêêê›] ˪뺪ªªºhGa `×ÇÝê'» Ö#ðÀŠ.ì‚srCݾ/‚.Ž!3ã½~óÙÞÚ±×/Éš]`/¯ »Ž!ÀÎ2Þ®¬ A€Ì/ ðÀîxœˆ$Ÿ½Š~þåÃËÿ*3ôÙÔuÅ–Ó.ÛµŽ”2 §¼Gk(Ã@²Çmjê<%Î]çÐ~ýòáeõðÙ«êá³W¹¯ÌÇZ€º×Õ6\}ÙÏž‚–†€â2Þ0讕¥ï£}¼JÊŽûÊÄ.îúº´ceÂï»¶=e]€À»yc>¶¡»ç6¦s—ü±%÷g׸tûb/¥LJW|Êr€ãÛÝ]ÍíÆ«Ý…~Mƒ+“²œ®Æ46f›RÆ_tuuÓÇŽå”2sëVÊr oOÎ-ÌlèÞOM·äþJéÊÓݽƅR¸oôŽ€À[l#¾dC™c9²Ûc\0l±]Í ðž®¡œ»œ¾gWÙ§”,yJÅÞ©wÅæjÐ4Œyc®ã±dfšÒý;¦‹¸¯«]W3PUUuçêêê[UõO×¼dI†ÆvÇÜ<63í{Ø Ët–"©Ç¯™Vδ€ûäøÁ>5mq‘]ÍCiÊ÷©Ÿ-QFF@Ã$ ð€À ÌÔ9ÆÛ}Æ~4Çï×_µ3t<2uÝÜx5ÎÇæŽØ}»w¿ú…\ǂ\8y5ýÅ〠¼ ð€À ¼ pàÀûíÙ«ê[ë¥ÿ~÷ûQÿfzG`I³…÷Ž—þÏÖw«9Û«ëºúíßÿv®“Ûøº®xŽwòìD¢|~ûíŸvB¡ž>ý—sX„1^ (9ð÷â,œë€Œ Îx{qÎu` SÿãÃŽn¸/ƪ)3ôYêºæ.'uÙ[ùùçüðû_ýÇ pöŒ÷[+PµƒUøûš ùð€coMÐýë¯ÿ|¸a ν¾%—Æx"ïÖŽtÛÙ®Œw›ž€%-úï—/«‡Ï^UŸ½úþïæó)še´—Õ˜cëI ܱ2CËZ:Ûç¾ÏÚú¾-#Vvh±r{ º?ÿüÿª»1^@Æ;àÂÀЇA7y_0 Ëì!Ó»«c]Öa&Ý•Y‡y( ¯Ñ=¾t¦+󊼥Ž{…Aw€ÙÀK1¥Ë:º{ªcöMx¡Rú¹ìÛÅÒ+hw7e¬%ò½’ØMSÆŠÓ2^û (2ðžeÜëËN·3M Pº/Tºö1^` ‡ysUصœ3Ãngì±ÏçfDZ®Ü)ûL}D(üa}únÀ:Bð•éEÞ)ã^á¸ëZÁ7\_ûû®€ÙUf麷ƒ]×ãEíïûºIÃ2± ×°ÌÐ÷ír{Z]õ7Æ,aöoj@š¸bÿ·kyCëI©ÇÛ4&