mirror of https://github.com/stella-emu/stella.git
3709 lines
134 KiB
HTML
3709 lines
134 KiB
HTML
<html>
|
|
<head>
|
|
<title>Stella - A multi-platform Atari 2600 VCS emulator</title>
|
|
<meta name="AppleTitle" content="docs">
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<center><b><font size="7">Stella</font></b></center>
|
|
<br><br>
|
|
<center><h2><b>A multi-platform Atari 2600 VCS emulator</b></h2></center>
|
|
|
|
<center><h4><b>Release 3.5.5</b></h4></center>
|
|
<br><br>
|
|
|
|
<center><h2><b>User's Guide</b></h2></center>
|
|
<br><br>
|
|
|
|
<ol>
|
|
<li><a href="#History">A Brief History of the Atari 2600</a></li>
|
|
<li><a href="#Introduction">Introduction</a><br>
|
|
<ul><li><a href="#Features">Features</a></li></ul>
|
|
</li>
|
|
<li><a href="#QuickStart">Getting Started</a><br>
|
|
<ul>
|
|
<li><a href="#Requirements">Requirements</a></li>
|
|
<li><a href="#Installation">Installation</a></li>
|
|
<li><a href="#Games">Locating Game Images (aka, ROMs)</a></li>
|
|
<li><a href="#Playing">Playing a Game</a></li>
|
|
<li><a href="#Keyboard">Keyboard Layout</a></li>
|
|
<li><a href="#ControlMap">Controller Map</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#Advanced">Advanced Configuration</a><br>
|
|
<ul>
|
|
<li><a href="#CommandLine">Using the Command Line</a></li>
|
|
<li><a href="#Options">Changing Options</a></li>
|
|
<li><a href="#Remapping">Event Remapping / Input Devices</a></li>
|
|
<li><a href="#ROMInfo">ROM Launcher</a></li>
|
|
<li><a href="#ROMAudit">ROM Audit Mode</a></li>
|
|
<li><a href="#Adaptor">Stelladaptor/2600-daptor Support</a></li>
|
|
<li><a href="#AtariVox">AtariVox/SaveKey Support</a></li>
|
|
<li><a href="#Debugger">Developer Options/Integrated Debugger</a></li>
|
|
<li><a href="#Settings">Settings File</a></li>
|
|
<li><a href="#Cheats">Cheatcode Manager</a></li>
|
|
<li><a href="#Logs">Viewing the System Log</a></li>
|
|
<li><a href="#Properties">Game Properties</a></li>
|
|
<li><a href="#Palette">Palette Support</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#Acknowledgments">Acknowledgments</a></li>
|
|
<li><a href="#License">License and Disclaimer</a></li>
|
|
</ol>
|
|
|
|
<br><br><br>
|
|
|
|
<center><b>February 1999 - February 2012</b></center>
|
|
<center><b>The Stella Team</b></center>
|
|
<center><b><a href="http://stella.sourceforge.net">Stella Homepage</a></b></center>
|
|
|
|
<br><br><br>
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="History">A Brief History of the Atari 2600</a></h1>
|
|
<hr>
|
|
|
|
<p><a><img src="graphics/console.png" ALIGN=RIGHT></a>
|
|
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.
|
|
</p>
|
|
|
|
<p><a><img src="graphics/chucky_cheese.png" ALIGN=LEFT></a>
|
|
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.
|
|
</p>
|
|
|
|
<p><a><img src="graphics/space_invaders.png" ALIGN=RIGHT></a>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
<p><a><img src="graphics/pacman.png" ALIGN=LEFT></a>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p><a><img src="graphics/jr_pacman.png" ALIGN=RIGHT></a>
|
|
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!
|
|
<p><a><img src="graphics/secret_quest.png" ALIGN=LEFT></a>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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!
|
|
</p>
|
|
|
|
<p><i>Alexander Bilstein<br>February 1999</i></p>
|
|
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="Introduction">Introduction</a></h1>
|
|
<hr>
|
|
|
|
<p>
|
|
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).
|
|
</p>
|
|
|
|
<p>
|
|
</h1>
|
|
<h2><b><a name="Features">Features</a></b></h2>
|
|
|
|
<ul>
|
|
<li>High speed emulation using optimized C++ code</li>
|
|
<li>Supports high quality sound emulation using code derived from Ron Fries'
|
|
TIA Sound Emulation library, including stereo sound support</li>
|
|
<li>Emulates the Atari 2600 Joystick Controllers using your computer's keyboard,
|
|
joysticks or mouse</li>
|
|
<li>Emulates the Atari 2600 Keyboard Controllers using your computer's keyboard</li>
|
|
<li>Emulates the Atari 2600 Paddle Controllers using your computer's mouse, keyboard
|
|
or joysticks</li>
|
|
<li>Emulates the Atari 2600 Driving Controllers using your computer's keyboard,
|
|
joysticks or mouse</li>
|
|
<li>Emulates the CBS BoosterGrip Controller using your computer's keyboard,
|
|
joysticks or mouse</li>
|
|
<li>Emulates the Sega Genesis Controller using your computer's keyboard,
|
|
joysticks or mouse</li>
|
|
<li>Emulates CX-22 / CX-80 style trackballs and Amiga Mouse using your
|
|
computer's mouse</li>
|
|
<li>Support for real Atari 2600 controllers using the
|
|
<a href="http://www.stelladaptor.com">Stelladaptor</a> and
|
|
<a href="http://2600-daptor.com">2600-adaptor</a></li>
|
|
<li>Support for the speech portion of a real
|
|
<a href="http://www.richard.hutchinson.dsl.pipex.com/new_page_5.htm">
|
|
AtariVox</a> device connected to your PC using a USB adaptor</li>
|
|
<li>Supports EEPROM emulation for <a href="http://www.richard.hutchinson.dsl.pipex.com/new_page_5.htm">
|
|
AtariVox</a> and <a href="http://www.vectrex.biz/MemCard.htm">SaveKey</a> controllers</li>
|
|
<li>Supports all known bankswitching schemes (let us know if there's one we missed)</li>
|
|
<li>Supports DPC+ bankswitching scheme from the Harmony cart, including partial emulation of the ARM processor</li>
|
|
<li>Supports cartridge autodetection for almost all bankswitching schemes</li>
|
|
<li>Supports Supercharger single-load and multi-load games</li>
|
|
<li>Supports ROMs stored in ZIP and GZIP format, as well as the usual A26/BIN/ROM formats</li>
|
|
<li>Supports property file for setting the properties associated with games</li>
|
|
<li>Supports the NTSC, PAL and SECAM television standards in 50Hz and 60Hz mode</li>
|
|
<li>Supports autodetection of display format for 50Hz vs. 60Hz modes</li>
|
|
<li>Supports several "undocumented features" of the TIA graphics chip used by
|
|
some games</li>
|
|
<li>TIA emulation supports full collision checking, with ability to disable
|
|
both TIA sprites and collisions for each object separately</li>
|
|
<li>Built-in extensive debugger, including the Distella disassembler</li>
|
|
<!-- FIXME
|
|
<li>Emulation of CRT TV systems with OpenGL shaders, including texturing,
|
|
colour bleed, RF noise, and phosphor burn-off</li>
|
|
-->
|
|
<li>Built-in ROM database with information compiled by RomHunter</li>
|
|
</ul>
|
|
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="QuickStart">Getting Started</a></h1>
|
|
<hr>
|
|
|
|
<h2><b><a name="Requirements">1. Requirements</a></b></h2>
|
|
|
|
<blockquote>
|
|
<p>The following sections outline the basic system requirements for running
|
|
Stella under various operating systems.</p>
|
|
|
|
<p>
|
|
<h3><b><u>General</u> (required for all versions of Stella)</b></h3>
|
|
<ul>
|
|
<li>Enough RAM for the OS + 64MB RAM for the emulation; 128MB+ highly recommended</li>
|
|
<li>15/16 bit color minimum; 24/32 bit color graphics card highly recommended</li>
|
|
<li>SDL version 1.2.10 or greater, latest version highly recommended</li>
|
|
<!-- FIXME
|
|
<li>CRT emulation effects require OpenGL 2.0 with GLSL (GL shading language) support</li>
|
|
-->
|
|
<li>Joysticks or gamepads are highly recommended</li>
|
|
<li>Mouse or <a href="http://www.stelladaptor.com">Stelladaptor</a> /
|
|
<a href="http://2600-daptor.com">2600-adaptor</a> with real paddles required for paddle emulation</li>
|
|
<li>Some ROM images (See <a href="http://www.atariage.com">AtariAge</a> for more information)</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Linux/UNIX</u></b></h3>
|
|
<p>The Linux version of Stella is designed to work on a Linux Workstation with
|
|
the following:</p>
|
|
<ul>
|
|
<li>Pentium class machine required; OpenGL accelerated video card highly
|
|
recommended</li>
|
|
<li>Linux Kernel 2.4.x, Linux Kernel 2.6.x/3.x is highly recommended</li>
|
|
<li>i386 or x86_64 class machine, with 32 or 64-bit distribution</li>
|
|
<li>Other architectures (MIPS, PPC, PPC64, etc) have been confirmed to work,
|
|
but aren't as well tested as i386/x86_64</li>
|
|
<li>GNU C++ compiler version 4.x and the make utility are required for compiling
|
|
the Stella source code</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Macintosh</u></b></h3>
|
|
|
|
<p>The Mac version of Stella is designed to work on an Apple Macintosh with
|
|
the following:</p>
|
|
<ul>
|
|
<li>MacOSX 10.4 (Tiger) or above</li>
|
|
<li>PPC G4 or Intel processor, 500MHz or above</li>
|
|
<li>OpenGL capable video card; software rendering mode is still available,
|
|
but as of MacOSX 10.4 is substandard (and untested) compared to OpenGL</li>
|
|
<li>Xcode 3.2 is required to compile the Stella source code (SDL 1.2.14 also
|
|
required to compile the 64-bit version)</li>
|
|
<li>The 64-bit version requires at minimum Snow Leopard (10.6) and Intel CPU/architecture</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Windows</u></b></h3>
|
|
|
|
<p>The Windows version of Stella is designed to work on Windows 98/2000/XP/Vista/7
|
|
with the following:</p>
|
|
|
|
<ul>
|
|
<li>Pentium class machine required; OpenGL accelerated video card highly
|
|
recommended</li>
|
|
<li>64-bit port has been tested on Windows Vista/7 only; it may work on
|
|
WinXP64 as well, but isn't a priority</li>
|
|
<li>Visual C++ 2005 is required to compile the Stella source code for Windows 98 and 2000</li>
|
|
<li>Visual C++ 2010 is required to compile the Stella source code for Windows XP and above</li>
|
|
<li>It may be possible to compile using MinGW, but this hasn't been extensively tested since Stella version 3.0</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Other</u></b></h3>
|
|
|
|
<p>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 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.</p>
|
|
</blockquote>
|
|
|
|
|
|
<h2><b><a name="Installation">2. Installation</a></b></h2>
|
|
|
|
<blockquote>
|
|
<p>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.</p>
|
|
|
|
<p>
|
|
<h3><b><u>Linux/UNIX</u></b></h3>
|
|
<ul>
|
|
<li><b>Binary DEB</b> (stella-<i>release</i>-1_arch.deb)
|
|
<ol>
|
|
<li>Install the binary DEB with the following command:
|
|
<pre> dpkg -i stella-<i>release</i>-1_arch.deb</pre></li>
|
|
</ol>
|
|
</li>
|
|
<li><b>Binary RPM</b> (stella-<i>release</i>-1.arch.rpm)
|
|
<ol>
|
|
<li>Install the binary RPM with the following command:
|
|
<pre> rpm -Uvh stella-<i>release</i>-1.arch.rpm</pre></li>
|
|
</ol>
|
|
</li>
|
|
<li><b>Compressed tarball : building from source code</b> (stella-<i>release</i>-src.tar.gz)
|
|
<ul>
|
|
<li>Debian-based distributions:
|
|
<ol>
|
|
<li>Extract files from the distribution:
|
|
<pre> tar zxvf stella-release-src.tar.gz</pre></li>
|
|
<li>Change directories to the stella-<i>release</i> directory</li>
|
|
<li>Build the executable with the following command:
|
|
<pre> dpkg-buildpackage</pre></li>
|
|
<li>Install the executable as indicated in the previous section</li>
|
|
</ol>
|
|
</li>
|
|
<li>RPM-based distributions:
|
|
<ol>
|
|
<li>Extract files from the distribution:
|
|
<pre> tar zxvf stella-release-src.tar.gz</pre></li>
|
|
<li>Change directories to the stella-<i>release</i>/src/unix directory</li>
|
|
<li>Build the executable with the following command:
|
|
<pre> rpmbuild -ba stella.spec</pre></li>
|
|
<li>Install the executable as indicated in the previous section</li>
|
|
</ol>
|
|
</li>
|
|
<li>Generic build:
|
|
<ol>
|
|
<li>Extract files from the distribution:
|
|
<pre> tar zxvf stella-release-src.tar.gz</pre></li>
|
|
<li>Change directories to the stella-<i>release</i> directory</li>
|
|
<li>Configure the build with the following command:
|
|
<pre> ./configure (--help for list of options)</pre></li>
|
|
<li>Build the executable with the following command:
|
|
<pre> make</pre></li>
|
|
<li>Install the executable with the following command:
|
|
<pre> make install</pre></li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Macintosh</u></b></h3>
|
|
<ul>
|
|
<li><b>Binary DMG file</b> (Stella-<i>release</i>-macosx.dmg)
|
|
<ol>
|
|
<li>Double-click the disk image, open the 'Stella' folder, then copy the
|
|
<b>Stella.app</b> package to your 'Applications' folder.</li>
|
|
</ol>
|
|
</li>
|
|
<li><b>Compressed tarball : building from source code</b> (stella-<i>release</i>-src.tar.gz)
|
|
<ol>
|
|
<li>Extract files from the distribution using an archiving program that supports
|
|
gzipped tar files</li>
|
|
<li>Open the <b>stella-<i>release</i>/src/macosx/stella.xcodeproj</b>
|
|
file using Xcode 3.2</li>
|
|
<li>Make sure you have the SDL runtime library/framework installed in src/macosx (located at
|
|
<a href="http://www.libsdl.org/download-1.2.php">libsdl.org</a>)</li>
|
|
<li>Build the 'Stella' project (making sure to select 'Deployment' mode)</li>
|
|
<li>For installation:
|
|
<ul>
|
|
<li>Run the script <b>Create_build.sh</b>, located in the src/macosx directory.
|
|
This will create a DMG installation archive on your desktop.</li>
|
|
<b>OR</b>
|
|
<li>Copy the <b>Stella.app</b> package to your 'Applications' folder.</li>
|
|
</ul>
|
|
<li>For compiling the Intel/Snow Leopard version, open the <b>stella-<i>release</i>/src/macosx/stella_intel.xcodeproj</b> file instead, and continue from
|
|
step 2 above.</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<h3><b><u>Windows</u></b></h3>
|
|
<ul>
|
|
<li><b>Binary EXE installer</b> (stella-<i>release</i>-<i>arch</i>.exe)
|
|
<ol>
|
|
<li>Double-click on the installer and follow the onscreen instructions</li>
|
|
</ol>
|
|
</li>
|
|
<li><b>Binary ZIP file</b> (stella-<i>release</i>-windows.zip)
|
|
<ol>
|
|
<li>Unzip the binary ZIP file using <b>Winzip</b> or <b>Total Commander</b></li>
|
|
<li>Copy the contents of either 32-bit or 64-bit directory somewhere on your system</li>
|
|
</ol>
|
|
</li>
|
|
<li><b>Compressed tarball : building from source code</b> (stella-<i>release</i>-src.tar.gz)
|
|
<ol>
|
|
<li>Make sure you have library and header files installed for SDL for
|
|
the correct architecture (32-bit, 64-bit or both), and that Visual Studio
|
|
is properly configured to find them</li>
|
|
<li>Extract files from the distribution using <b>Winzip</b>,
|
|
<b>Total Commander</b>, or some other archiving program that supports
|
|
gzipped tar files</li>
|
|
<li>For Windows XP and above: open the <b>stella-<i>release</i>/src/win32/Stella.sln</b>
|
|
file using Visual C++ 2010</li>
|
|
<li>For Windows 98/2000: open the <b>stella-<i>release</i>/src/win32/Stella_vs2005.sln</b>
|
|
file using Visual C++ 2005</li>
|
|
<li>Build the 'Stella' solution, making sure to correctly select either 'Win32'
|
|
or 'x64' mode (depending on the version of Windows you have installed)</li>
|
|
<li>For installation:
|
|
<ul>
|
|
<li>Double-click on <b>Create_builds.bat</b> to generate ZIP and EXE files;
|
|
you must have the 'flip' and 'zip' applications installed on your system,
|
|
as well as the InnoSetup application. This will generate the EXE and ZIP
|
|
files, which can be installed as explained above</li>
|
|
<b>OR</b>
|
|
<li>Manually copy the <b>Stella.exe</b> and <b>SDL.dll</b> files somewhere
|
|
on your system (they may be located in the 'Release' or 'x64\Release'
|
|
directories)</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Games">3. Locating Game Images (aka, ROMs)</a></b></h2>
|
|
|
|
<blockquote>
|
|
<p>
|
|
<h3><b><u>Cartridges</u></b></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<p><ul>
|
|
<li>Search around the internet and find ROM images to download (websites such
|
|
as <a href="http://atariage.com">AtariAge</a> and
|
|
<a href="http://www.atarimania.com/rom_collection_archive_atari_2600_roms.html">
|
|
AtariMania/RomHunter</a> may be useful)</li>
|
|
|
|
<li>You can purchase the Atari 2600 Action Packs by Activision and use
|
|
their ROM images</li>
|
|
|
|
<li>If you're handy with a soldering iron then you can design and build a
|
|
device that plugs into the printer port of a PC and read the data from the
|
|
cartridge</li>
|
|
</ul>
|
|
|
|
<p><b>WARNING:</b> It is illegal to use ROM images of games that you do not
|
|
actually own since these games are still copyrighted.</p>
|
|
|
|
<p>
|
|
<h3><b><u>Supercharger Cassettes</u></b></h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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:
|
|
|
|
<pre> % cat survivl0.bin survivl6.bin survivl7.bin > survivl.bin</pre>
|
|
|
|
or to create it under DOS you would:
|
|
|
|
<pre> % copy /b survivl0.bin+survivl6.bin+survivl7.bin survivl.bin</pre>
|
|
|
|
<p>Once you have the multi-load ROM image file, survivl.bin in this case, you
|
|
can play the game using it.</p>
|
|
|
|
<p>
|
|
<h3><b><u>Supported File formats</u></b></h3>
|
|
|
|
<p>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).</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Playing">4. Playing a Game</a></b></h2>
|
|
|
|
<blockquote>
|
|
<p>Once Stella is installed and you have some ROM images you're almost ready to
|
|
start playing.</p>
|
|
|
|
<p>
|
|
<h3><b><u>Integrated GUI</u></b></h3>
|
|
|
|
<p>Stella contains an integrated GUI for all ports. Commandline support is also
|
|
available for those who want to use it.</p>
|
|
|
|
<p>If you start Stella and do not specify a ROM image, it will start in
|
|
'ROM Launcher' mode:<br><br>
|
|
<img src="graphics/launcher.png"></p>
|
|
|
|
<p>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:</p>
|
|
<p><img src="graphics/select_romdir.png">
|
|
<img src="graphics/rom_browser.png"></p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>At this point, you may want to set the locations for snapshots and other
|
|
external paths. This is described in more detail in
|
|
<b>Advanced Configuration - <a href="#ConfigPaths">Config Paths</a></b>.
|
|
These settings are optional, and can be left at the defaults if you won't be using
|
|
snapshots in the ROM launcher.</p>
|
|
|
|
<p>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
|
|
<b>Getting Started - <a href="#Keyboard">Keyboard Layout</a></b>
|
|
for more information. To exit a game and re-enter the ROM launcher, press the 'Escape'
|
|
key.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>
|
|
<h3><b><u>Command Menu</u></b></h3>
|
|
|
|
<p>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
|
|
<b>Getting Started - <a href="#Keyboard">Keyboard Layout</a></b>).
|
|
However, another alternative is available. Pressing the '\' key toggles
|
|
a command menu dialog as follows:</p>
|
|
<p><img src="graphics/commandmenu.png"></p>
|
|
|
|
<p>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).</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Keyboard">5. Keyboard Layout</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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
|
|
<b>Advanced Configuration - <a href="#Remapping">Event Remapping</a></b>).
|
|
The tables below show the default settings.</p>
|
|
|
|
<p><b>Console Controls (can be remapped)</b></p>
|
|
|
|
<table BORDER=2 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key (Standard)</th>
|
|
<th>Key (MacOSX)</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Exit emulator</td>
|
|
<td>Control + q</td>
|
|
<td>Cmd + q</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Exit game mode/enter launcher mode</td>
|
|
<td>Escape</td>
|
|
<td>Escape</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Enter/exit options mode</td>
|
|
<td>Tab</td>
|
|
<td>Tab</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Enter/exit command mode</td>
|
|
<td>Backslash (\)</td>
|
|
<td>Backslash (\)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Enter/exit debugger</td>
|
|
<td>Backquote (`)</td>
|
|
<td>Backquote (`)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Select Game</td>
|
|
<td>F1</td>
|
|
<td>F1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Reset Game</td>
|
|
<td>F2</td>
|
|
<td>F2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Color TV</td>
|
|
<td>F3</td>
|
|
<td>F3</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Black/White TV</td>
|
|
<td>F4</td>
|
|
<td>F4</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Left Player Difficulty B</td>
|
|
<td>F5</td>
|
|
<td>F5</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Left Player Difficulty A</td>
|
|
<td>F6</td>
|
|
<td>F6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Right Player Difficulty B</td>
|
|
<td>F7</td>
|
|
<td>F7</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Right Player Difficulty A</td>
|
|
<td>F8</td>
|
|
<td>F8</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Save state to current slot</td>
|
|
<td>F9</td>
|
|
<td>F9</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Change current state slot</td>
|
|
<td>F10</td>
|
|
<td>F10</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Load state from current slot</td>
|
|
<td>F11</td>
|
|
<td>F11</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Save PNG snapshot</td>
|
|
<td>F12</td>
|
|
<td>F12</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pause/resume emulation</td>
|
|
<td>Pause</td>
|
|
<td> </td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<p><b>Joystick / BoosterGrip Controller (can be remapped)</b></p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Left Joystick (Joy0)</th>
|
|
<th>Right Joystick (Joy1)</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Up</td>
|
|
<td>Up arrow</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Down</td>
|
|
<td>Down arrow</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Left</td>
|
|
<td>Left arrow</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Right</td>
|
|
<td>Right arrow</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Fire Button</td>
|
|
<td>Space</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Trigger Button</td>
|
|
<td>4</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Booster Button</td>
|
|
<td>5</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Up</td>
|
|
<td>Y</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Down</td>
|
|
<td>H</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Left</td>
|
|
<td>G</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Joystick Right</td>
|
|
<td>J</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Fire Button</td>
|
|
<td>F</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Trigger Button</td>
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Booster Button</td>
|
|
<td>7</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Paddle Controller digital emulation (can be remapped independently of joystick controller)</b></p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Left Paddles</th>
|
|
<th>Right Paddles</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 0 decrease</td>
|
|
<td>Same as 'Joy0 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 0 increase</td>
|
|
<td>Same as 'Joy0 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 0 Fire</td>
|
|
<td>Same as 'Joy0 Fire'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 1 decrease</td>
|
|
<td>Same as 'Joy0 Up'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 1 increase</td>
|
|
<td>Same as 'Joy0 Down'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 1 Fire</td>
|
|
<td>Same as 'Joy0 Booster'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 2 decrease</td>
|
|
<td>Same as 'Joy1 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 2 increase</td>
|
|
<td>Same as 'Joy1 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 2 Fire</td>
|
|
<td>Same as 'Joy1 Fire'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 3 decrease</td>
|
|
<td>Same as 'Joy1 Up'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 3 increase</td>
|
|
<td>Same as 'Joy1 Down'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Paddle 3 Fire</td>
|
|
<td>Same as 'Joy1 Booster'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Driving Controller (cannot be remapped, always associated with joystick controller)</b></p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Left Driving</th>
|
|
<th>Right Driving</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Left Direction</td>
|
|
<td>Same as 'Joy0 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Right Direction</td>
|
|
<td>Same as 'Joy0 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Fire Button</td>
|
|
<td>Same as 'Joy0 Fire'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Left Direction</td>
|
|
<td>Same as 'Joy1 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Right Direction</td>
|
|
<td>Same as 'Joy1 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Fire Button</td>
|
|
<td>Same as 'Joy1 Fire'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Sega Genesis Controller (cannot be remapped, always associated with joystick and booster-grip controllers)</b></p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Left Pad</th>
|
|
<th>Right Pad</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Up</td>
|
|
<td>Same as 'Joy0 Up'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Down</td>
|
|
<td>Same as 'Joy0 Down'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Left</td>
|
|
<td>Same as 'Joy0 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Right</td>
|
|
<td>Same as 'Joy0 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Button 'B'</td>
|
|
<td>Same as 'Joy0 Fire'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Button 'C'</td>
|
|
<td>Same as 'Joy0 Booster'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Up</td>
|
|
<td>Same as 'Joy1 Up'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Down</td>
|
|
<td>Same as 'Joy1 Down'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Left</td>
|
|
<td>Same as 'Joy1 Left'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Pad Right</td>
|
|
<td>Same as 'Joy1 Right'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Button 'B'</td>
|
|
<td>Same as 'Joy1 Fire'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Button 'C'</td>
|
|
<td>Same as 'Joy1 Booster'</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Keypad Controller (can be remapped)</b></p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Left Keypad</th>
|
|
<th>Right Keypad</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Pad Button</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>2</td>
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>3</td>
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>4</td>
|
|
<td>Q</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>5</td>
|
|
<td>W</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>6</td>
|
|
<td>E</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>7</td>
|
|
<td>A</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>8</td>
|
|
<td>S</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>9</td>
|
|
<td>D</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>.</td>
|
|
<td>Z</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>0</td>
|
|
<td>X</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>#</td>
|
|
<td>C</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
|
|
<td>
|
|
<table BORDER=1 cellpadding=5>
|
|
<tr>
|
|
<th>Pad Button</th>
|
|
<th>Key</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>1</td>
|
|
<td>8</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>2</td>
|
|
<td>9</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>3</td>
|
|
<td>0</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>4</td>
|
|
<td>I</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>5</td>
|
|
<td>O</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>6</td>
|
|
<td>P</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>7</td>
|
|
<td>K</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>8</td>
|
|
<td>L</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>9</td>
|
|
<td>;</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>.</td>
|
|
<td>,</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>0</td>
|
|
<td>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>#</td>
|
|
<td>/</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<a name="DeveloperKeys"></a>
|
|
<p><b>Developer Keys in TIA mode (cannot be remapped)</b></p>
|
|
|
|
<table BORDER=2 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key (Standard)</th>
|
|
<th>Key (MacOSX)</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Set "Display.YStart" to next <i>larger</i> value</td>
|
|
<td>Alt + PageUp</td>
|
|
<td>Cmd + PageUp</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Set "Display.YStart" to next <i>smaller</i> value</td>
|
|
<td>Alt + PageDown</td>
|
|
<td>Cmd + PageDown</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Set "Display.Height" to next <i>larger</i> value</td>
|
|
<td>Control + PageUp</td>
|
|
<td>Control + PageUp</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Set "Display.Height" to next <i>smaller</i> value</td>
|
|
<td>Control + PageDown</td>
|
|
<td>Control + PageDown</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle frame stats (scanline count/fps/bs type/etc)</td>
|
|
<td>Alt + l</td>
|
|
<td>Cmd + l</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Player0 object</td>
|
|
<td>Alt + z</td>
|
|
<td>Cmd + z</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Player1 object</td>
|
|
<td>Alt + x</td>
|
|
<td>Cmd + x</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Missile0 object</td>
|
|
<td>Alt + c</td>
|
|
<td>Cmd + c</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Missile1 object</td>
|
|
<td>Alt + v</td>
|
|
<td>Cmd + v</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Ball object</td>
|
|
<td>Alt + b</td>
|
|
<td>Cmd + b</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Playfield object</td>
|
|
<td>Alt + n</td>
|
|
<td>Cmd + n</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Player0 collisions</td>
|
|
<td>Shift-Alt + z</td>
|
|
<td>Shift-Cmd + z</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Player1 collisions</td>
|
|
<td>Shift-Alt + x</td>
|
|
<td>Shift-Cmd + x</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Missile0 collisions</td>
|
|
<td>Shift-Alt + c</td>
|
|
<td>Shift-Cmd + c</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Missile1 collisions</td>
|
|
<td>Shift-Alt + v</td>
|
|
<td>Shift-Cmd + v</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Ball collisions</td>
|
|
<td>Shift-Alt + b</td>
|
|
<td>Shift-Cmd + b</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA Playfield collisions</td>
|
|
<td>Shift-Alt + n</td>
|
|
<td>Shift-Cmd + n</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA HMOVE blanks</td>
|
|
<td>Alt + m</td>
|
|
<td>Cmd + m</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle TIA 'Fixed Debug Colors' mode</td>
|
|
<td>Alt + Comma</td>
|
|
<td>Cmd + Comma</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turn all TIA objects off</td>
|
|
<td>Alt + .</td>
|
|
<td>Cmd + .</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turn all TIA objects on</td>
|
|
<td>Alt + /</td>
|
|
<td>Cmd + /</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turn all TIA collisions off</td>
|
|
<td>Shift-Alt + .</td>
|
|
<td>Shift-Cmd + .</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Turn all TIA collisions on</td>
|
|
<td>Shift-Alt + /</td>
|
|
<td>Shift-Cmd + /</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Other Keys (cannot be remapped, except those marked with '*')</b></p>
|
|
|
|
<table BORDER=2 cellpadding=5>
|
|
<tr>
|
|
<th>Function</th>
|
|
<th>Key (Standard)</th>
|
|
<th>Key (MacOSX)</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Switch to next <i>larger</i> zoom level</td>
|
|
<td>Alt + =</td>
|
|
<td>Cmd + =</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Switch to next <i>smaller</i> zoom level</td>
|
|
<td>Alt + -</td>
|
|
<td>Cmd + -</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle fullscreen/windowed mode</td>
|
|
<td>Alt + Enter</td>
|
|
<td>Cmd + Enter</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Decrease volume (*)</td>
|
|
<td>Alt + [</td>
|
|
<td>Cmd + [</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Increase volume (*)</td>
|
|
<td>Alt + ]</td>
|
|
<td>Cmd + ]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle display palette (<i>NTSC/PAL/SECAM</i>)</td>
|
|
<td>Control + f</td>
|
|
<td>Control + f</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Save current properties to a new properties file</td>
|
|
<td>Control + s</td>
|
|
<td>Control + s</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Switch mouse between controller emulation modes</td>
|
|
<td>Control + 0</td>
|
|
<td>Control + 0</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Reload current ROM (singlecart ROM, TIA mode)<br>
|
|
Load next game in ROM (multicart ROM, TIA mode)</td>
|
|
<td>Control + r</td>
|
|
<td>Control + r</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Reload ROM listing (ROM launcher mode)</td>
|
|
<td>Control + r</td>
|
|
<td>Control + r</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Emulate 'frying' effect (TIA mode) (*)</td>
|
|
<td>Backspace</td>
|
|
<td>Backspace</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Go to parent directory (UI mode) (*)</td>
|
|
<td>Backspace</td>
|
|
<td>Backspace</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle 'phosphor' effect</td>
|
|
<td>Alt + p</td>
|
|
<td>Cmd + p</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle palette</td>
|
|
<td>Control + p</td>
|
|
<td>Control + p</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Toggle PAL color-loss effect</td>
|
|
<td>Control + l</td>
|
|
<td>Control + l</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>Save continuous PNG snapshots</td>
|
|
<td>Alt + s</td>
|
|
<td>Cmd + s</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>UI keys in Text Editing areas (cannot be remapped)</b></p>
|
|
|
|
<table BORDER=2 cellpadding=5>
|
|
<tr><th>Key</th><th>Editor Function</th></tr>
|
|
<tr><td>Home</td><td>Move cursor to beginning of line</td></tr>
|
|
<tr><td>End</td><td>Move cursor to end of line</td></tr>
|
|
<tr><td>Delete</td><td>Remove character to right of cursor</td></tr>
|
|
<tr><td>Backspace</td><td>Remove character to left of cursor</td></tr>
|
|
<tr><td>Control-a</td><td>Same function as 'Home'</td></tr>
|
|
<tr><td>Control-e</td><td>Same function as 'End'</td></tr>
|
|
<tr><td>Control-d</td><td>Same function as 'Delete'</td></tr>
|
|
<tr><td>Control-k</td><td>Remove all characters from cursor to end of line</td></tr>
|
|
<tr><td>Control-u</td><td>Remove all characters from cursor to beginning of line</td></tr>
|
|
<tr><td>Control-w</td><td>Remove entire word to left of cursor</td></tr>
|
|
<tr><td>Control-Left</td><td>Move cursor to beginning of word to the left</td></tr>
|
|
<tr><td>Control-Right</td><td>Move cursor to beginning of word to the right</td></tr>
|
|
<tr><td>Control-c</td><td>Copy entire line to clipboard (not complete)</td></tr>
|
|
<tr><td>Control-v</td><td>Paste clipboard contents (not complete)</td></tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="ControlMap">6. Controller Map</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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 <b>(+ extra)</b> 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.</p>
|
|
|
|
<table BORDER=2 cellpadding=5>
|
|
<tr>
|
|
<th> </th>
|
|
<th colspan="5">Computer</th>
|
|
</tr>
|
|
<tr>
|
|
<th>Virtual<br>Controller</th>
|
|
<th>Keyboard</th>
|
|
<th>Joystick</th>
|
|
<th>Mouse<br>(auto mode)</th>
|
|
<th>Mouse<br>(specific axis)</th>
|
|
<th>Stelladaptor/<br>2600-daptor</th>
|
|
</tr>
|
|
<tr>
|
|
<th> Joystick</th>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✕</td>
|
|
<td> ✓</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Paddles</th>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Booster</th>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓ (+ extra)</td>
|
|
<td> ✕</td>
|
|
<td> ✓ (+ extra)</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Genesis</th>
|
|
<td> ✓</td>
|
|
<td> ✓ (+ extra)</td>
|
|
<td> ✓</td>
|
|
<td> ✕</td>
|
|
<td> ✕</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Keyboard</th>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✕</td>
|
|
<td> ✕</td>
|
|
<td> ✕</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Driving</th>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✓</td>
|
|
<td> ✕</td>
|
|
<td> ✓</td>
|
|
</tr>
|
|
<tr>
|
|
<th> Trackball/mouse</th>
|
|
<td> ✕</td>
|
|
<td> ✕</td>
|
|
<td> ✓</td>
|
|
<td> ✓ (axis ignored)</td>
|
|
<td> ✕</td>
|
|
</tr>
|
|
<tr>
|
|
<th> AtariVox</th>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
</tr>
|
|
<tr>
|
|
<th> SaveKey</th>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
<td> N/A</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="Advanced">Advanced Configuration</a></h1>
|
|
<hr>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2><b><a name="CommandLine">1. Using the Command Line</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>In addition to the built in ROM launcher, Stella can also be used from the
|
|
commandline (assuming your operating system has a commandline).</p>
|
|
|
|
<p>To run Stella from the commandline, use the following format:</p>
|
|
|
|
<pre> stella [options ...] ROM_FILENAME</pre>
|
|
|
|
<p><b>Options</b> ('0' or 'false' indicates false, '1' or 'true' indicates true,
|
|
others are self-explanatory):</p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-video <soft|gl></pre></td>
|
|
<td>Use software or OpenGL rendering mode.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_lib <filename></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_filter <nearest|linear></pre></td>
|
|
<td>OpenGL mode only. Use GL_NEAREST or GL_LINEAR filtering.
|
|
GL_NEAREST results in a scaled, pixelated image, while
|
|
GL_LINEAR introduces blurring.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_aspectn <number><br>-gl_aspectp <number></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_fsmax <1|0></pre></td>
|
|
<td>OpenGL mode only. Stretch TIA image while in fullscreen mode.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_vbo <1|0></pre></td>
|
|
<td>OpenGL mode only. Use the Vertex Buffer Object extension, if available. This is enabled by default.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gl_vsync <1|0></pre></td>
|
|
<td>OpenGL mode only. Synchronize screen updates to the vertical blank
|
|
period. This can result in smoother updates, and eliminate tearing.</td>
|
|
</tr>
|
|
|
|
<!-- FIXME
|
|
<tr>
|
|
<td><pre>-tv_tex <off|normal|stag></pre></td>
|
|
<td>OpenGL 2.0 mode only. Enable TV texturing. The GL_TEXTURE_RECTANGLE
|
|
extension must be disabled for this to work correctly.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tv_bleed <off|low|medium|high></pre></td>
|
|
<td>OpenGL 2.0 mode only. Enable TV colour bleed emulation. A fast
|
|
video card with at least 128MB RAM is required to use 'high'.
|
|
The GL_TEXTURE_RECTANGLE extension must be disabled for this to
|
|
work correctly.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tv_noise <off|low|medium|high></pre></td>
|
|
<td>OpenGL 2.0 mode only. Enable TV radio frequency noise emulation.
|
|
A fast video card with at least 128MB RAM is required to use 'high'.
|
|
The GL_TEXTURE_RECTANGLE extension must be disabled for this to
|
|
work correctly.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tv_phos <1|0></pre></td>
|
|
<td>OpenGL 2.0 mode only. Enable phosphor effect of TV image. This
|
|
is in addition to the currently emulated software phosphor
|
|
effect. The GL_TEXTURE_RECTANGLE extension must be disabled
|
|
for this to work correctly.</td>
|
|
</tr>
|
|
-->
|
|
<tr>
|
|
<td><pre>-tia_filter <filter></pre></td>
|
|
<td>Use the specified filter while in TIA/emulation mode. Currently,
|
|
this can be zoomZx, where Z={2..10}.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-fullscreen <1|0|-1></pre></td>
|
|
<td>Play the game in fullscreen mode (1 or 0), or completely disable
|
|
fullscreen mode (-1).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-fullres <auto|WxH></pre></td>
|
|
<td>Use the given resolution in fullscreen mode. If 'auto', let Stella decide
|
|
which resolution to use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-center <1|0></pre></td>
|
|
<td>Centers game window (if possible).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-palette <standard|z26|user></pre></td>
|
|
<td>Set the palette to either normal Stella, the one used in the z26
|
|
emulator, or a user-defined palette.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-colorloss <1|0></pre></td>
|
|
<td>Enable/disable the PAL color-loss effect.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-framerate <number></pre></td>
|
|
<td>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).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-timing <sleep|busy></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-uimessages <1|0></pre></td>
|
|
<td>Enable or disable display of message in the UI. Note that messages
|
|
indicating serious errors override this setting, and are always
|
|
shown.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-sound <1|0></pre></td>
|
|
<td>Enable or disable sound generation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-fragsize <number></pre></td>
|
|
<td>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).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-freq <number></pre></td>
|
|
<td>Set sound sample output frequency (0 - 48000).
|
|
Default is 31400. Do not change unless you experience sound
|
|
issues.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tiafreq <number></pre></td>
|
|
<td>Set sound sample generation frequency (0 - 48000).
|
|
Default is 31400. Do not change unless you experience sound
|
|
issues.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-volume <number></pre></td>
|
|
<td>Set the volume (0 - 100).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-clipvol <1|0></pre></td>
|
|
<td>Enable volume clipping (eliminates popping). Do not change
|
|
unless you experience sound issues.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-cheat <code></pre></td>
|
|
<td>Use the specified cheatcode (see Cheat section for description).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-loglevel <0|1|2></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-logtoconsole <1|0></pre></td>
|
|
<td>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'.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-joydeadzone <number></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-joyallow4 <1|0></pre></td>
|
|
<td>Allow all 4 directions on a joystick to be pressed
|
|
simultaneously. Bumper Bash ignores this setting,
|
|
and always allows all 4 directions.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-grabmouse <1|0></pre></td>
|
|
<td>Keeps the mouse in the game window in emulation mode.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-mcontrol <never|auto|rom></pre></td>
|
|
<td>Disable mouse input entirely, enable using the mouse axes for various controllers automatically (paddle, driving, etc),
|
|
or use the settings specified by the current ROM.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-dsense <number></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-msense <number></pre></td>
|
|
<td>Sensitivity for emulation of paddles when using a mouse.
|
|
Valid range of values is from 1 to 15, with larger numbers causing
|
|
faster movement.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-sa1 <left|right></pre></td>
|
|
<td>Stelladaptor/2600-daptor 1 emulates specified joystick port.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-sa2 <left|right></pre></td>
|
|
<td>Stelladaptor/2600-daptor 2 emulates specified joystick port.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ctrlcombo <1|0></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-autoslot <1|0></pre></td>
|
|
<td>Automatically switch to the next available save state slot after
|
|
saving a ROM state file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-stats <1|0></pre></td>
|
|
<td>Overlay console info on the TIA image during emulation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-fastscbios <1|0></pre></td>
|
|
<td>Disable Supercharger BIOS progress loading bars.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-snapdir <path></pre></td>
|
|
<td>The directory to save snapshot files to.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-sssingle <1|0></pre></td>
|
|
<td>Generate single snapshot instead of many, overwriting
|
|
any previous snapshots.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ss1x <1|0></pre></td>
|
|
<td>Ignore any scaling applied to the TIA image, and save
|
|
snapshot in unscaled (1x) mode.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ssinterval <number></pre></td>
|
|
<td>Set the interval in seconds between taking snapshots in continuous snapshot mode (currently, 1 - 10).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-rominfo <rom></pre></td>
|
|
<td>Display detailed information about the given ROM, and then exit
|
|
Stella.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-listrominfo</pre></td>
|
|
<td>Prints relevant contents of the Stella ROM database, one ROM per line,
|
|
and then exit Stella. This can be used for external frontends.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-uselauncher <1|0></pre></td>
|
|
<td>Use the built-in ROM launcher. If disabled, launching Stella will
|
|
simply print a help message, and exiting a ROM will completely
|
|
exit the program.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-launcherres <WxH></pre></td>
|
|
<td>Set the size of the ROM launcher.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-launcherfont <small|medium|large></pre></td>
|
|
<td>Set the size of the font in the ROM launcher.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-launcherexts <allfiles|allroms|LIST></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-romviewer <0|1|2></pre></td>
|
|
<td>Hide ROM info viewer in ROM launcher mode (0), or use the
|
|
given zoom level (1 or 2).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-uipalette <1|2></pre></td>
|
|
<td>Used the specified palette for UI elements. This isn't yet
|
|
complete.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-listdelay <delay></pre></td>
|
|
<td>Set the amount of time to wait between treating successive
|
|
keypresses as a single word in list widgets (value can range
|
|
from 300-1000).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-mwheel <lines></pre></td>
|
|
<td>Set the number of lines a mousewheel will scroll in the UI.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-romdir <dir></pre></td>
|
|
<td>Set the directory where the ROM launcher will start.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-statedir <dir></pre></td>
|
|
<td>Set the directory in which to access state files.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-cheatfile <file></pre></td>
|
|
<td>Set the full pathname of the cheatfile database.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-palettefile <file></pre></td>
|
|
<td>Set the full pathname of the user-defined palette file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-propsfile <file></pre></td>
|
|
<td>Set the full pathname of the ROM properties file.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-eepromdir <dir></pre></td>
|
|
<td>Set the directory in which to access EEPROM files.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-cfgdir <dir></pre></td>
|
|
<td>Set the directory in which to access Distella config files.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-avoxport <name></pre></td>
|
|
<td>Set the name of the serial port where an AtariVox is connected.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-maxres <WxH></pre></td>
|
|
<td>Useful for developers, this sets the maximum size of window that
|
|
can be created, allowing to simulate testing on 'smaller' systems.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-help</pre></td>
|
|
<td>Prints a help message describing these options, and then
|
|
exit Stella.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<a name="DeveloperCommandLine"></a>
|
|
<p>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 <b>not</b> case sensitive.</p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Argument</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-resolvedata <never|always|auto></pre></td>
|
|
<td>Try to differentiate between code vs. data sections in the
|
|
disassembler. See the Debugger section for more information.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-gfxformat <2|16></pre></td>
|
|
<td>Sets the base to use for displaying GFX sections in the disassembler.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-showaddr <1|0></pre></td>
|
|
<td>Shows/hides opcode addresses in the disassembler.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-debuggerres <WxH></pre></td>
|
|
<td>Set the size of the debugger window.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-break <address></pre></td>
|
|
<td>Set a breakpoint at specified address.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-debug</pre></td>
|
|
<td>Immediately jump to debugger mode when starting Stella.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-holdreset</pre></td>
|
|
<td>Start the emulator with the Game Reset switch held down.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-holdselect</pre></td>
|
|
<td>Start the emulator with the Game Select switch held down.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-holdbutton0</pre></td>
|
|
<td>Start the emulator with the left joystick button held down.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tiadriven <1|0></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ramrandom <1|0></pre></td>
|
|
<td>On reset, either randomize all RAM content, or zero it out instead.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-bs <type></pre></td>
|
|
<td>Set "Cartridge.Type" property. See the <i>Game Properties</i> section
|
|
for valid types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-type <type></pre></td>
|
|
<td>Same as using -bs.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-channels <Mono|Stereo></pre></td>
|
|
<td>Set "Cartridge.Sound" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ld <A|B></pre></td>
|
|
<td>Set "Console.LeftDifficulty" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-rd <A|B></pre></td>
|
|
<td>Set "Console.RightDifficulty" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-tv <Color|BW></pre></td>
|
|
<td>Set "Console.TelevisionType" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-sp <Yes|No></pre></td>
|
|
<td>Set "Console.SwapPorts" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-lc <type></pre></td>
|
|
<td>Set "Controller.Left" property. See the <i>Game Properties</i>
|
|
section for valid types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-rc <type></pre></td>
|
|
<td>Set "Controller.Right" property. See the <i>Game Properties</i>
|
|
section for valid types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-bc <type></pre></td>
|
|
<td>Sets both "Controller.Left" and "Controller.Right" properties.
|
|
See the <i>Game Properties</i> section for valid types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-cp <Yes|No></pre></td>
|
|
<td>Set "Controller.SwapPaddles" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ma <Auto|XY></pre></td>
|
|
<td>Set "Controller.MouseAxis" property.
|
|
See the <i>Game Properties</i> section for valid types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-format <format></pre></td>
|
|
<td>Set "Display.Format" property. See the <i>Game Properties</i> section
|
|
for valid formats.</td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ystart <number></pre></td>
|
|
<td>Set "Display.YStart" property (0 - 64).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-height <number></pre></td>
|
|
<td>Set "Display.Height" property (210 - 256).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-pp <Yes|No></pre></td>
|
|
<td>Set "Display.Phosphor" property.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-ppblend <number></pre></td>
|
|
<td>Set "Display.PPBlend" property, used for phosphor effect (0-100).
|
|
Default is 77.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><pre>-thumb.trapfatal <true|false></pre></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Options">2. Changing Options</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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
|
|
<b>Options</b> button, or in-game by pressing the 'Tab' key.</p>
|
|
|
|
<p><b>Options Menu</b> dialog:<br><br>
|
|
<img src="graphics/options.png">
|
|
<br><br>
|
|
<p><b>Video Settings</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_video.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Renderer (*)</td><td>use specified rendering mode (requires restart)</td><td>-video</td></tr>
|
|
<tr><td>TIA Filter</td><td>filter for emulation mode </td><td>-tia_filter</td></tr>
|
|
<tr><td>TIA Palette</td><td>palette for emulation mode</td><td>-palette</td></tr>
|
|
<tr><td>Fullscrn Res</td><td>resolution for fullscreen mode</td><td>-fullres</td></tr>
|
|
<tr><td>Timing (*)</td><td>how to wait between frames (requires restart)</td><td>-timing</td></tr>
|
|
<tr><td>GL Filter</td><td>OpenGL filter mode</td><td>-gl_filter</td></tr>
|
|
<tr><td>GL Aspect (N)</td><td>OpenGL width of TIA image in NTSC mode</td><td>-gl_aspectn</td></tr>
|
|
<tr><td>GL Aspect (P)</td><td>OpenGL width of TIA image in PAL mode</td><td>-gl_aspectp</td></tr>
|
|
<tr><td>Framerate</td><td>frames per second in emulation mode</td><td>-framerate</td></tr>
|
|
<tr><td>Fullscreen mode</td><td>self-explanatory</td><td>-fullscreen</td></tr>
|
|
<tr><td>GL FS Stretch</td><td>stretch fullscreen OpenGL in emulation mode</td><td>-gl_fsmax</td></tr>
|
|
<tr><td>GL VBO</td><td>enable OpenGL Vertex Buffer Objects</td><td>-gl_vbo</td></tr>
|
|
<tr><td>GL VSync</td><td>enable OpenGL vertical synchronization</td><td>-gl_vsync</td></tr>
|
|
<tr><td>PAL color-loss</td><td>use PAL color-loss effect</td><td>-colorloss</td></tr>
|
|
<tr><td>Fast SC/AR BIOS</td><td>Skip progress loading bars for SuperCharger ROMs</td><td>-fastscbios</td></tr>
|
|
<tr><td>Show UI messages</td><td>overlay UI messages onscreen</td><td>-uimessages</td></tr>
|
|
<tr><td>Center window</td><td>attempt to center application window</td><td>-center</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<!-- FIXME
|
|
<p><b>Video Settings</b> dialog (TV Effects):</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_video_tv.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>TV Color Texture</td><td>emulate TV pixel texturing</td><td>-tv_tex</td></tr>
|
|
<tr><td>TV Color Bleed</td><td>emulate TV color bleed</td><td>-tv_bleed</td></tr>
|
|
<tr><td>TV Image Noise</td><td>emulate TV RF image noise</td><td>-tv_noise</td></tr>
|
|
<tr><td>TV Phosphor Burn-off</td><td>emulate TV phosphor mixing</td><td>-tv_phos</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
-->
|
|
<p><b>Audio Settings</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_audio.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Volume</td><td>self-explanatory</td><td>-volume</td></tr>
|
|
<tr><td>Sample size (*)</td><td>set size of audio buffers</td><td>-fragsize</td></tr>
|
|
<tr><td>Output freq (*)</td><td>change sound output frequency (advanced)</td><td>-freq</td></tr>
|
|
<tr><td>TIA freq</td><td>change TIA output frequency (advanced)</td><td>-tiafreq</td></tr>
|
|
<tr><td>Clip volume</td><td>Eliminate popping in sound generation (advanced)</td><td>-clipvol</td></tr>
|
|
<tr><td>Enable sound</td><td>self-explanatory</td><td>-sound</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<p><b>Input Settings</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_input.png"></td>
|
|
<td> </td>
|
|
<td valign="top"><br>This dialog is described in further detail in
|
|
<b>Advanced Configuration - <a href="#Remapping">Event Remapping</a></b>.</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<p><b>UI Settings</b> dialog (3 tabs):</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_ui.png"></td>
|
|
<td> </td>
|
|
<td valign="top"><br>This tab is described in further detail in
|
|
<b>Advanced Configuration - <a href="#ROMInfo">ROM Launcher</a></b>.</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_debugger.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Debugger Width/Height</td><td>self-explanatory (requires restart)</td><td>-debuggerres</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_misc.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Interface Palette</td><td>palette to use for UI elements</td><td>-uipalette</td></tr>
|
|
<tr><td>List quick delay</td><td>time to wait between keypresses in listwidget</td><td>-listdelay</td></tr>
|
|
<tr><td>Mouse wheel scroll</td><td>number of lines mouse scroll will move in listwidget</td><td>-mscroll</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<a name="ConfigPaths"></a>
|
|
<p><b>Config Paths</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/launcher_options_files.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Rom path</td><td>specifies location of ROM files</td><td>-romdir</td></tr>
|
|
<tr><td>Snapshot path</td><td>specifies where to load/save snapshots</td><td>-snapdir</td></tr>
|
|
<tr><td>Cheat file</td><td>specifies location of cheatfile database</td><td>-cheatfile</td></tr>
|
|
<tr><td>Palette file</td><td>specifies location of user palette</td><td>-palettefile</td></tr>
|
|
<tr><td>Properties file </td><td>specifies location of external stella.pro database</td><td>-propsfile</td></tr>
|
|
<tr><td>State path</td><td>specifies location of state files</td><td>-statedir</td></tr>
|
|
<tr><td>EEPROM path</td><td>specifies location of EEPROM files</td><td>-eepromdir</td></tr>
|
|
<tr><td>Overwrite snapshots</td><td>whether to overwrite old snapshots</td><td>-sssingle</td></tr>
|
|
<tr><td>Snapshot in 1x mode</td><td>save snapshot in 1x mode, without filtering</td><td>-ss1x</td></tr>
|
|
<tr><td>Continuous snapshot interval</td><td>interval (in seconds) between snapshot</td><td>-ssinterval</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p><b>Audit ROMs</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/romaudit.png"></td>
|
|
<td> </td>
|
|
<td valign="top"><br>This dialog is described in further detail in
|
|
<b>Advanced Configuration - <a href="#ROMAudit">ROM Audit Mode</a></b>.</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<p><b>Game Properties</b> dialog:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/options_gameinfo.png"></td>
|
|
<td> </td>
|
|
<td valign="top"><br>This dialog allows you to change all ROM properties
|
|
as described in <b>Advanced Configuration - <a href="#Properties">Game Properties</a></b>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Remapping">3. Event Remapping / Input Devices</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>Almost every event in Stella can be remapped to another key on the keyboard or
|
|
to buttons on up to eight joysticks/gamepads (see <b>Getting Started -
|
|
<a href="#Keyboard">Keyboard Layout</a></b> for those events which can/cannot be
|
|
remapped).</p>
|
|
|
|
<p>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.
|
|
|
|
<p>To remap an event:
|
|
<ol>
|
|
<li>Enter <b>Options menu</b> and click the <b>Input Settings</b> button.</li>
|
|
<li>If you wish to remap emulation events, click the 'Emul. Events' tab.
|
|
Otherwise, click the 'UI Events' tab for user interface events.</li>
|
|
<li>Select event you want to remap and click the 'Map' button.</li>
|
|
<li>Press a key or a joystick button, and that key/button will be bound
|
|
to the selected event. If nothing seems to happen, either Stella
|
|
can't see the input device, or the selected event doesn't support being
|
|
remapped to the input device.</li>
|
|
<li>Cancel a remap in progress by clicking 'Cancel', erase a mapping by
|
|
clicking 'Erase', or reset to default mapping by clicking 'Reset'</li>
|
|
<li>Reset to default <b>all</b> mappings by clicking 'Defaults'.</li>
|
|
</ol>
|
|
|
|
<p>The following screenshots illustrate the event remapping process:<br><br>
|
|
<img src="graphics/eventmapping.png">
|
|
<img src="graphics/eventmapping_remap.png">
|
|
|
|
<p>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:</p>
|
|
<img src="graphics/eventmapping_combo.png">
|
|
<p>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.</p>
|
|
|
|
</p>
|
|
|
|
<p>Device and port settings can be configured under the 'Devices & Ports' tab, shown below:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/eventmapping_devsports.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>Brief description</th><th>For more information,<br>see <a href="#CommandLine">CommandLine</a></th></tr>
|
|
<tr><td>Stelladaptor X is</td><td>Specifies which virtual port each Stelladaptor/2600-daptor uses (See <b>Advanced Configuration - <a href="#Adaptor">Stelladaptor/2600-daptor Support</a></b>)</td><td>-sa1 & -sa2</td></tr>
|
|
<tr><td>AVox serial port</td><td>Described in further detail in <b>Advanced Configuration - <a href="#AtariVox">AtariVox/SaveKey Support</a></b> </td><td>-avoxport</td></tr>
|
|
<tr><td>Joy deadzone size</td><td>Deadzone area for axes on joysticks/gamepads</td><td>-joydeadzone</td></tr>
|
|
<tr><td>Digital paddle sensitivity</td><td>Sensitvity used when emulating a paddle using a digital device</td><td>-dsense</td></tr>
|
|
<tr><td>Mouse paddle sensitivity</td><td>Sensitivity used when emulating a paddle using a mouse</td><td>-msense</td></tr>
|
|
<tr><td>Allow all 4 ...</td><td>Allow all 4 joystick directions to be pressed simultaneously</td><td>-joyallow4</td></tr>
|
|
<tr><td>Grab mouse ...</td><td>Keep mouse in window in emulation mode</td><td>-grabmouse</td></tr>
|
|
<tr><td>Use mouse as ...</td><td>Mouse axes are either automatically or specifically mapped to certain actions</td><td>-mcontrol</td></tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="ROMInfo">4. ROM Launcher</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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
|
|
<b>UI Settings => Launcher</b> dialog, as shown below:</p>
|
|
<img src="graphics/launcher_options.png">
|
|
<p>Most of the options are self-explanatory, except for the 'ROM Info
|
|
viewer', which is described below.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>Currently, there are several restrictions for this feature:</p>
|
|
<ol>
|
|
<li>The ROM info viewer can be shown in 1x or 2x mode only.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
</ol>
|
|
|
|
<p>The following snapshots illustrate the various font sizes and rom info
|
|
zoom levels:</p>
|
|
|
|
<p>ROM info viewer in 1x mode, UI sized 800x480, small launcher font:</p>
|
|
<img src="graphics/rominfo_1x_small.png">
|
|
|
|
<p>ROM info viewer in 1x mode, UI sized 1000x760, medium launcher font:</p>
|
|
<img src="graphics/rominfo_1x_large.png">
|
|
|
|
<p>ROM info viewer in 2x mode, UI sized 1400x900, large launcher font:</p>
|
|
<img src="graphics/rominfo_2x_small.png">
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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:</p>
|
|
|
|
<p><ol>
|
|
<li><p><b>Override properties</b>: Selecting this option shows a dialog whereby
|
|
ROM properties can be temporarily overriden. Selecting options from this
|
|
dialog will cause all ROMs launched after that to use those properties
|
|
you specify. Clicking <b>Default</b> will disable its functionality,
|
|
and use ROM properties as defined by the ROM itself. The dialog is as
|
|
follows (See <b>Advanced Configuration - <a href="#Properties">Game Properties</a></b>
|
|
for more information concerning ROM properties):</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/launcher_override.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>For more information,<br>see Commandline</th></tr>
|
|
<tr><td>Bankswitch type</td><td>-bs</td></tr>
|
|
<tr><td>Left Difficulty</td><td>-ld</td></tr>
|
|
<tr><td>Right Difficulty</td><td>-rd</td></tr>
|
|
<tr><td>TV Type</td><td>-tv</td></tr>
|
|
<tr><td>Hold Select down</td><td>-holdselect</td></tr>
|
|
<tr><td>Hold Reset down</td><td>-holdreset</td></tr>
|
|
<tr><td>Hold Button 0 down</td><td>-holdbutton0</td></tr>
|
|
</table>
|
|
<p></p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</li>
|
|
|
|
<li><p><b>Filter listing</b>: Selecting this option shows a dialog whereby
|
|
one can filter the types of files shown in the listing. The dialog is as
|
|
follows:</p>
|
|
<p><img src="graphics/launcher_filter.png"></p>
|
|
<p>Currently, the choices are as follows:</p>
|
|
<p><ul>
|
|
<li><b>All files</b> - self explanatory, show all files in the ROM
|
|
listing. This is the default, and emulates the behaviour of
|
|
all previous versions of Stella.</li>
|
|
<li><b>All roms</b> - show only files with a valid ROM extension.
|
|
Currently, this means extensions .a26, .bin, .rom, .gz, .zip.</li>
|
|
<li><b>ROMs ending with</b> - show only files with a ROM extension
|
|
as selected from the checkboxes.</li>
|
|
</ul></p>
|
|
</li>
|
|
|
|
<li><b>Reload listing</b>: Selecting this performs a reload of the
|
|
current listing. It is an alternative to pressing the Control-r
|
|
key combo.</li>
|
|
</ol></p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="ROMAudit">5. ROM Audit Mode</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>This feature is accessible from <b>Options => Audit ROMs</b>, and is only
|
|
available while in ROM launcher mode. The dialog box for this feature
|
|
is as follows:</p>
|
|
<img src="graphics/romaudit.png">
|
|
|
|
<p>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.</p>
|
|
|
|
<p>There are several items to take note of:</p>
|
|
<ul>
|
|
<li><b>THIS OPERATION CANNOT BE UNDONE</b>. 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.</li>
|
|
<li>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.</li>
|
|
<li>If a valid ROM doesn't have a properties entry, it will be
|
|
ignored.</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Adaptor">6. Stelladaptor/2600-daptor Support</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>Stella supports real Atari 2600 joysticks, paddles and driving controllers
|
|
using the <a href="http://www.stelladaptor.com">Stelladaptor</a> and
|
|
<a href="http://2600-daptor.com">2600-adaptor</a> devices.</p>
|
|
|
|
<p>Stella can use up to <b>two</b> 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.</p>
|
|
|
|
<p>The detection and configuration is as follows:
|
|
|
|
<ul>
|
|
<li>The first device found will act as the <b>left game port</b>
|
|
on a real Atari. Depending on the device, Stella will detect it as
|
|
either the left joystick, paddles 0 & 1, or the left driving controller.</li>
|
|
|
|
<li>The second device found will act as the <b>right game port</b>
|
|
on a real Atari. Depending on the device, Stella will detect it as
|
|
either the right joystick, paddles 2 & 3, or the right driving controller.</li>
|
|
|
|
<li>Any other devices will be ignored.</li>
|
|
|
|
<li>The assignment ordering of Stelladaptor/2600-daptor to port can be redefined with
|
|
'sa1' and 'sa2' (see description in 'Starting a Game').</li>
|
|
</ul>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="AtariVox">7. AtariVox/SaveKey Support</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>Stella supports a real AtariVox device for the speech/SpeakJet portion
|
|
of the controller. You will need a real AtariVox device, located
|
|
<a href="http://www.richard.hutchinson.dsl.pipex.com/new_page_5.htm">here</a>,
|
|
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
|
|
<b>Advanced Configuration - <a href="#Remapping">Input Devices</a></b>.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The location of the EEPROM files are configurable through the
|
|
'<i>-eepromdir</i>' commandline argument and within the application itself
|
|
(see <b>Advanced Configuration - <a href="#ConfigPaths">Config Paths</a></b>).
|
|
If the path for these files hasn't been set, the default location will depend on the
|
|
version of Stella, as follows:</p>
|
|
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>Linux/Unix</b></td>
|
|
<td><i>~/.stella/atarivox_eeprom.dat<br>
|
|
~/.stella/savekey_eeprom.dat</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Macintosh</b></td>
|
|
<td><i>~/Library/Application Support/Stella/atarivox_eeprom.dat<br>
|
|
~/Library/Application Support/Stella/savekey_eeprom.dat</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Windows</b></td>
|
|
<td><i>%APPDATA%\Stella\atarivox_eeprom.dat<br>
|
|
%APPDATA%\Stella\savekey_eeprom.dat</i>
|
|
<b>OR</b><br>
|
|
<i>_BASEDIR_\atarivox_eeprom.dat<br>
|
|
_BASEDIR_\savekey_eeprom.dat<br></i>
|
|
(if a file named 'basedir.txt' exists in the application
|
|
directory containing the full pathname for _BASEDIR_)
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>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.</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Debugger">8. Developer Options/Integrated Debugger</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>Many options are available for ROM developers, which are described in
|
|
different sections of this manual, as follows:</p>
|
|
|
|
<p><ul>
|
|
<li>Developer key-combo shortcuts, used to change TIA state dynamically
|
|
(ie, while the emulation is still running). See <b>Keyboard Layout -
|
|
<a href="#DeveloperKeys">Developer Keys in TIA mode</a></b> for more information.</li>
|
|
|
|
<li>Commandline options influencing emulation state. See <b>Using the Command Line -
|
|
<a href="#DeveloperCommandLine">Developer Commands</a></b> for more information.</li>
|
|
|
|
<li>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:
|
|
<p><img src="graphics/developer_stats.png"></p>
|
|
<p>The two lines of output describe the following:
|
|
<ol>
|
|
<li>Number of scanlines in current frame, associated framerate, and
|
|
resulting display format. Note that the framerate shown is the
|
|
<i>internal</i>, 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'.</li>
|
|
<li>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).</li>
|
|
</li>
|
|
</ol></p></li>
|
|
</ul></p>
|
|
|
|
<p>Finally, Stella contains an extensive, built-in debugger. Have a look at
|
|
<a href="debugger.html">this page</a> for integrated debugger documentation.</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Settings">9. Settings File</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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: <b>command = value</b>, where <i>command</i> is the same as that
|
|
specified on the command line (without the '-' character), and <i>value</i>
|
|
is dependent on the command.</p>
|
|
|
|
<p>For example, the following table illustrates how command line and settings entries
|
|
are similar:</p>
|
|
|
|
<table BORDER=2>
|
|
<tr>
|
|
<th>Command Line</th>
|
|
<th>Settings File</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-video gl</td>
|
|
<td>video = gl</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-volume 75</td>
|
|
<td>volume = 75</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>-center 1</td>
|
|
<td>center = 1 (or center = true)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The settings file has a special name/location depending on which version of Stella
|
|
you use, which is currently not configurable:</p>
|
|
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>Linux/Unix</b></td>
|
|
<td><i>$HOME/.stella/stellarc</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Macintosh</b></td>
|
|
<td>Not applicable; settings are saved in <i>~/Library/Preferences/net.sourceforge.Stella.plist</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Windows</b></td>
|
|
<td><i>%APPDATA%\Stella\stella.ini</i>
|
|
<b>OR</b><br>
|
|
<i>_BASEDIR_\stella.ini</i>
|
|
(if a file named 'basedir.txt' exists in the application
|
|
directory containing the full pathname for _BASEDIR_)
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Cheats">10. Cheatcode Manager</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>To add/remove/edit a cheat code, enter the 'Cheat Code' dialog:<br><br>
|
|
<img src="graphics/cheat.png">
|
|
|
|
<p>Currently, there are three types of cheatcodes available, all of which
|
|
must be entered in hexidecimal format:
|
|
<ul>
|
|
<li><p>Per-frame RAM cheats:<br>
|
|
Evaluated each frame, and apply to RAM only. Format as follows:
|
|
<pre>
|
|
4-digit code: c041
|
|
c0 = address
|
|
41 = data
|
|
</pre>
|
|
</li>
|
|
|
|
<li>Cheetah codes, which are explained in detail on
|
|
<a href="http://members.cox.net/rcolbert/">Bob Colbert's web page</a>,
|
|
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:
|
|
<pre>
|
|
6-digit (cheetah) code: aaaddc
|
|
aaa = address - $f000
|
|
dd = data
|
|
c = count - 1
|
|
</pre>
|
|
</li>
|
|
|
|
<li>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:
|
|
<pre>
|
|
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 - 1
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>There's also the concept of <i>one shot</i> codes. These codes work
|
|
exactly the same as above, except they aren't saved. They are evaluated
|
|
once and immediately discarded.
|
|
|
|
<p>Here are a few cheat codes we've found:</p>
|
|
<pre>
|
|
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 lives
|
|
</pre>
|
|
|
|
<p>The name of the cheat database file is configurable through the
|
|
'<i>-cheatfile</i>' commandline argument and within the application itself
|
|
(see <b>Advanced Configuration - <a href="#ConfigPaths">Config Paths</a></b>). If the
|
|
path for this file hasn't been set, the default filename will depend on the
|
|
version of Stella, as follows:</p>
|
|
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>Linux/Unix</b></td>
|
|
<td><i>$HOME/.stella/stella.cht</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Macintosh</b></td>
|
|
<td><i>~/Library/Application Support/Stella/stella.cht</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Windows</b></td>
|
|
<td><i>%APPDATA%\Stella\stella.cht</i>
|
|
<b>OR</b><br>
|
|
<i>_BASEDIR_\stella.cht</i>
|
|
(if a file named 'basedir.txt' exists in the application
|
|
directory containing the full pathname for _BASEDIR_)
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>Stella will require a restart for changes to this file to take effect.</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Logs">11. Viewing the System Log</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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:</p>
|
|
<table border="5" cellpadding="2" frame="box" rules="none">
|
|
<tr>
|
|
<td><img src="graphics/logs.png"></td>
|
|
<td> </td>
|
|
<td valign="top">
|
|
<table border="1" cellpadding="4">
|
|
<tr><th>Item</th><th>For more information,<br>see Commandline</th></tr>
|
|
<tr><td>Log level</td><td>-loglevel</td></tr>
|
|
<tr><td>Print to console</td><td>-logtoconsole</td></tr>
|
|
</table>
|
|
<p></p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>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.</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Properties">12. Game Properties</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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 <b>stella.pro</b> 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.</p>
|
|
|
|
<p>
|
|
<h2><b>Property File</b></h2>
|
|
|
|
<p>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:</p>
|
|
|
|
<p>
|
|
<pre>
|
|
; Comments
|
|
"Cartridge.MD5" "Value"
|
|
"Property" "Value"
|
|
""
|
|
|
|
; Comments
|
|
"Cartridge.MD5" "Value"
|
|
"Property" "Value"
|
|
""
|
|
|
|
. . .
|
|
|
|
; Comments
|
|
"Cartridge.MD5" "Value"
|
|
"Property" "Value"
|
|
""</pre>
|
|
|
|
<p>Every block in the property file must have a unique value for the
|
|
<i>Cartridge.MD5</i> property.</p>
|
|
|
|
<p>
|
|
<h2><b>Properties</b></h2>
|
|
|
|
<p>Each block in a property file consists of a set of properties for a single
|
|
game. Stella supports the properties described below:</p>
|
|
|
|
<table CELLSPACING="10">
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.MD5:</i></td>
|
|
<td>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.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Manufacturer:</i></td>
|
|
<td>Indicates the game's manufacturer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.ModelNo:</i></td>
|
|
<td>Indicates the manufacturer's model number for the game.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Name:</i></td>
|
|
<td>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).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Note:</i></td>
|
|
<td>Contains any special notes about playing the game.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Rarity:</i></td>
|
|
<td>Indicates how rare a cartridge is, based on the scale described on AtariAge.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Sound:</i></td>
|
|
<td>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 <b>Mono</b> or <b>Stereo</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Cartridge.Type:</i></td>
|
|
<td>Indicates the bank-switching type for the game.
|
|
The value of this property must be either <b>Auto-detect</b> 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:
|
|
<table cellpadding="2" border="1">
|
|
<tr><th> Type </th><th>Description</th></tr>
|
|
<tr><td>0840 </td><td>8K ECONObanking </td></tr>
|
|
<tr><td>2IN1 ¹</td><td>4-32K Multicart (2 games) </td></tr>
|
|
<tr><td>4IN1 ¹</td><td>8-32K Multicart (4 games) </td></tr>
|
|
<tr><td>8IN1 ¹</td><td>16-64K Multicart (8 games) </td></tr>
|
|
<tr><td>16IN1 ¹</td><td>32-128K Multicart (16 games) </td></tr>
|
|
<tr><td>32IN1 ¹</td><td>64-128K Multicart (32 games) </td></tr>
|
|
<tr><td>2K </td><td>64-2048 byte Atari </td></tr>
|
|
<tr><td>3E </td><td>32K Tigervision </td></tr>
|
|
<tr><td>3F </td><td>512K Tigervision </td></tr>
|
|
<tr><td>4A50 </td><td>64K 4A50 + ram </td></tr>
|
|
<tr><td>4K </td><td>4K Atari </td></tr>
|
|
<tr><td>AR </td><td>Supercharger </td></tr>
|
|
<tr><td>CV </td><td>Commavid extra ram </td></tr>
|
|
<tr><td>DPC </td><td>Pitfall II </td></tr>
|
|
<tr><td>DPC+</td><td>Enhanced DPC </td></tr>
|
|
<tr><td>E0 </td><td>8K Parker Bros </td></tr>
|
|
<tr><td>E7 </td><td>16K M-network </td></tr>
|
|
<tr><td>EF </td><td>64K Homestar Runner </td></tr>
|
|
<tr><td>EFSC </td><td>64K Homestar Runner + ram</td></tr>
|
|
<tr><td>F0 </td><td>Dynacom Megaboy </td></tr>
|
|
<tr><td>F4 </td><td>32K Atari </td></tr>
|
|
<tr><td>F4SC </td><td>32K Atari + ram </td></tr>
|
|
<tr><td>F6 </td><td>16K Atari </td></tr>
|
|
<tr><td>F6SC </td><td>16K Atari + ram </td></tr>
|
|
<tr><td>F8 </td><td>8K Atari </td></tr>
|
|
<tr><td>F8SC </td><td>8K Atari + ram </td></tr>
|
|
<tr><td>FA </td><td>CBS RAM Plus </td></tr>
|
|
<tr><td>FA2 </td><td>CBS RAM Plus 24K </td></tr>
|
|
<tr><td>FE </td><td>8K Decathlon </td></tr>
|
|
<tr><td>MC ¹²</td><td>C. Wilkson Megacart </td></tr>
|
|
<tr><td>SB </td><td>128-256k SUPERbanking </td></tr>
|
|
<tr><td>UA </td><td>8K UA Ltd. </td></tr>
|
|
<tr><td>X07 ¹</td><td>64K AtariAge </td></tr>
|
|
</table></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Console.LeftDifficulty:</i></td>
|
|
<td>Indicates the default difficulty setting for the left
|
|
player. The value must be <b>A</b> or <b>B</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Console.RightDifficulty:</i></td>
|
|
<td>Indicates the default difficulty setting for the
|
|
right player. The value must be <b>A</b> or <b>B</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Console.TelevisionType:</i></td>
|
|
<td>Indicates the default television setting for the
|
|
game. The value must be <b>Color</b> or <b>BW</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Console.SwapPorts:</i></td>
|
|
<td>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 <b>Yes</b> or <b>No</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Controller.Left:</i><br><i>Controller.Right:</i></td>
|
|
<td>Indicates what type of controller the left and right player
|
|
uses. The value must be one of the following types:
|
|
<table cellpadding="2" border="1">
|
|
<tr><th> Type </th><th>Description</th></tr>
|
|
<tr><td>Joystick </td><td>Atari's famous black joystick that was originally included with the system.</td></tr>
|
|
<tr><td>BoosterGrip </td><td>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.</td></tr>
|
|
<tr><td>Paddles </td><td>Standard paddle controllers for use with games such as Breakout and Warlords. One pair of controller per connector (allows for 4-player Warlords).</td></tr>
|
|
<tr><td>Paddles_IAxis </td><td>Same as Paddles, except the axes are inverted.</td></tr>
|
|
<tr><td>Paddles_IDir </td><td>Same as Paddles, except the direction of movement is inverted.</td></tr>
|
|
<tr><td>Paddles_IAxDr </td><td>Same as Paddles, except both the axes and direction of movement is inverted.</td></tr>
|
|
<tr><td>Driving </td><td>Looks like a paddle, but allows 360' movement. Only one unit per connector, unlike paddles which were sold in pairs.</td></tr>
|
|
<tr><td>Keyboard </td><td>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.</td></tr>
|
|
<tr><td>Trackball22 </td><td>Standard Atari 2600 CX-22 trackball controller.</td></tr>
|
|
<tr><td>Trackball80 </td><td>Atari ST CX-80 trackball controller.</td></tr>
|
|
<tr><td>AmigaMouse</td><td>Commodore Amiga computer mouse.</td></tr>
|
|
<tr><td><a href="http://www.richard.hutchinson.dsl.pipex.com/new_page_5.htm">
|
|
AtariVox</a></td><td>A SpeakJet based unlimited-vocabulary speech / sound synthesizer with 32K EEPROM.</td></tr>
|
|
<tr><td><a href="http://www.vectrex.biz/MemCard.htm">SaveKey</a></td><td>A 32K EEPROM for saving high scores, etc (the EEPROM portion of an AtariVox).</td></tr>
|
|
<tr><td>Genesis </td><td>Sega Genesis controller, which can be used similar to a BoosterGrip, giving an extra button.</td></tr>
|
|
</table></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Controller.SwapPaddles:</i></td>
|
|
<td>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 <b>Yes</b> or <b>No</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Controller.MouseAxis:</i></td>
|
|
<td>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 <b>Auto</b> or <b>XY</b>, as follows:
|
|
<table cellpadding="2" border="1">
|
|
<tr><th> Id </th><th>Controller</th></tr>
|
|
<tr><td>0 </td><td>Paddle 0</td></tr>
|
|
<tr><td>1 </td><td>Paddle 1</td></tr>
|
|
<tr><td>2 </td><td>Paddle 2</td></tr>
|
|
<tr><td>3 </td><td>Paddle 3</td></tr>
|
|
<tr><td>4 </td><td>Driving 0</td></tr>
|
|
<tr><td>5 </td><td>Driving 1</td></tr>
|
|
</table></td>
|
|
</tr>
|
|
|
|
<!--
|
|
In the latter case, XY indicates
|
|
how to use the X/Y axis (ie, 02 is paddle0/paddle2).
|
|
-->
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Display.Format:</i></td>
|
|
<td>Indicates the television format the game was designed for. The value
|
|
must be <b>Auto-detect</b>, <b>NTSC</b>, <b>PAL</b>, <b>SECAM</b>, <b>NTSC50</b>,
|
|
<b>PAL60</b> or <b>SECAM60</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Display.YStart:</i></td>
|
|
<td>Indicates the scan-line to start displaying at.
|
|
The value must be <i>n</i> such that 0 <= <i>n</i> <= 64.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Display.Height:</i></td>
|
|
<td>Indicates the number of scan-lines to display.
|
|
The value must be <i>n</i> such that 210 <= <i>n</i> <= 256.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Display.Phosphor:</i></td>
|
|
<td>Indicates whether the phosphor effect should be emulated or not.
|
|
The value must be <b>Yes</b> or <b>No</b>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN="TOP"><i>Display.PPBlend:</i></td>
|
|
<td>Indicates the amount of blending which will occur while using the
|
|
phosphor effect. The value must be <i>n</i> such that 0 <= <i>n</i>
|
|
<= 100. The default value is 77.</td>
|
|
</tr>
|
|
</table>
|
|
<!--
|
|
<p><b>Note:</b> Items marked as '*' are deprecated, and will probably be
|
|
removed in a future release.</p>
|
|
-->
|
|
<p>The name of the properties file is configurable through the
|
|
'<i>-propsfile</i>' commandline argument and within the application itself
|
|
(see <b>Advanced Configuration - <a href="#ConfigPaths">Config Paths</a></b>). If the
|
|
path for this file hasn't been set, the default filename will depend on the
|
|
version of Stella, as follows:</p>
|
|
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>Linux/Unix</b></td>
|
|
<td><i>$HOME/.stella/stella.pro</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Macintosh</b></td>
|
|
<td><i>~/Library/Application Support/Stella/stella.pro</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Windows</b></td>
|
|
<td><i>%APPDATA%\Stella\stella.pro</i>
|
|
<b>OR</b><br>
|
|
<i>_BASEDIR_\stella.pro</i>
|
|
(if a file named 'basedir.txt' exists in the application
|
|
directory containing the full pathname for _BASEDIR_)
|
|
</td>
|
|
|
|
</tr>
|
|
</table>
|
|
<p>Stella will require a restart for changes to this file to take effect.</p>
|
|
</blockquote>
|
|
|
|
<h2><b><a name="Palette">13. Palette Support</a></b></h2>
|
|
<blockquote>
|
|
|
|
<p>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:</p>
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>standard</b></td>
|
|
<td>The default palette from Stella 1.4 onwards.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>z26</b></td>
|
|
<td>The palette from the z26 emulator.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>user</b></td>
|
|
<td>An external palette file, supplied by the user.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>A user-defined palette has certain restrictions, further described as follows:
|
|
<ul>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>The PAL colour-loss effect is calculated within Stella. You do not
|
|
need to specify those colours in the palette file.
|
|
</ul>
|
|
|
|
<p>The name of the palette file is configurable through the
|
|
'<i>-palettefile</i>' commandline argument and within the application itself
|
|
(see <b>Advanced Configuration - <a href="#ConfigPaths">Config Paths</a></b>). If the
|
|
path for this file hasn't been set, the default filename will depend on the
|
|
version of Stella, as follows:</p>
|
|
|
|
<p><table cellpadding="5" border="1">
|
|
<tr>
|
|
<td><b>Linux/Unix</b></td>
|
|
<td><i>$HOME/.stella/stella.pal</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Macintosh</b></td>
|
|
<td><i>~/Library/Application Support/Stella/stella.pal</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Windows</b></td>
|
|
<td><i>%APPDATA%\Stella\stella.pal</i>
|
|
<b>OR</b><br>
|
|
<i>_BASEDIR_\stella.pal</i>
|
|
(if a file named 'basedir.txt' exists in the application
|
|
directory containing the full pathname for _BASEDIR_)
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>Note that to actually use the external palette, the palette file must
|
|
exist and be valid, <b>and</b> the palette option should be set to <i>user</i>
|
|
(in <b>Video Settings</b> dialog). The current ROM will have to be reloaded
|
|
for changes to this file to take effect.</p>
|
|
</blockquote>
|
|
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="Acknowledgments">Acknowledgments</a></h1>
|
|
<hr>
|
|
|
|
<p>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 <a href="http://stella.sf.net/credits.php">Credits List</a>.
|
|
If I've missed someone, please let us know.</p>
|
|
|
|
|
|
<!-- ///////////////////////////////////////////////////////////////////////// -->
|
|
<br><br>
|
|
<p><h1>
|
|
<a name="License">License and Disclaimer</a></h1>
|
|
<hr>
|
|
|
|
<p>
|
|
<H2>GNU GENERAL PUBLIC LICENSE</h2>
|
|
<P>
|
|
Version 2, June 1991
|
|
|
|
</P>
|
|
|
|
<PRE>
|
|
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.
|
|
</PRE>
|
|
|
|
|
|
|
|
<H2>Preamble</H2>
|
|
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
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.
|
|
|
|
</P>
|
|
<P>
|
|
The precise terms and conditions for copying, distribution and
|
|
modification follow.
|
|
|
|
</P>
|
|
|
|
|
|
<H2>TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</H2>
|
|
|
|
|
|
<P>
|
|
|
|
<STRONG>0.</STRONG>
|
|
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".
|
|
<P>
|
|
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>1.</STRONG>
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<STRONG>2.</STRONG>
|
|
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:
|
|
<P>
|
|
|
|
<UL>
|
|
|
|
<LI><STRONG>a)</STRONG>
|
|
You must cause the modified files to carry prominent notices
|
|
stating that you changed the files and the date of any change.
|
|
|
|
<P>
|
|
<LI><STRONG>b)</STRONG>
|
|
You must cause any work that you distribute or publish, that in
|
|
whole or in part contains or is derived from the Program or any
|
|
part thereof, to be licensed as a whole at no charge to all third
|
|
parties under the terms of this License.
|
|
|
|
<P>
|
|
<LI><STRONG>c)</STRONG>
|
|
If the modified program normally reads commands interactively
|
|
when run, you must cause it, when started running for such
|
|
interactive use in the most ordinary way, to print or display an
|
|
announcement including an appropriate copyright notice and a
|
|
notice that there is no warranty (or else, saying that you provide
|
|
a warranty) and that users may redistribute the program under
|
|
these conditions, and telling the user how to view a copy of this
|
|
License. (Exception: if the Program itself is interactive but
|
|
does not normally print such an announcement, your work based on
|
|
the Program is not required to print an announcement.)
|
|
</UL>
|
|
|
|
These requirements apply to the modified work as a whole. If
|
|
identifiable sections of that work are not derived from the Program,
|
|
and can be reasonably considered independent and separate works in
|
|
themselves, then this License, and its terms, do not apply to those
|
|
sections when you distribute them as separate works. But when you
|
|
distribute the same sections as part of a whole which is a work based
|
|
on the Program, the distribution of the whole must be on the terms of
|
|
this License, whose permissions for other licensees extend to the
|
|
entire whole, and thus to each and every part regardless of who wrote it.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>3.</STRONG>
|
|
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:
|
|
|
|
|
|
<!-- we use this doubled UL to get the sub-sections indented, -->
|
|
<!-- while making the bullets as unobvious as possible. -->
|
|
<UL>
|
|
|
|
<LI><STRONG>a)</STRONG>
|
|
Accompany it with the complete corresponding machine-readable
|
|
source code, which must be distributed under the terms of Sections
|
|
1 and 2 above on a medium customarily used for software interchange; or,
|
|
|
|
<P>
|
|
<LI><STRONG>b)</STRONG>
|
|
Accompany it with a written offer, valid for at least three
|
|
years, to give any third party, for a charge no more than your
|
|
cost of physically performing source distribution, a complete
|
|
machine-readable copy of the corresponding source code, to be
|
|
distributed under the terms of Sections 1 and 2 above on a medium
|
|
customarily used for software interchange; or,
|
|
|
|
<P>
|
|
<LI><STRONG>c)</STRONG>
|
|
Accompany it with the information you received as to the offer
|
|
to distribute corresponding source code. (This alternative is
|
|
allowed only for noncommercial distribution and only if you
|
|
received the program in object code or executable form with such
|
|
an offer, in accord with Subsection b above.)
|
|
</UL>
|
|
|
|
The source code for a work means the preferred form of the work for
|
|
making modifications to it. For an executable work, complete source
|
|
code means all the source code for all modules it contains, plus any
|
|
associated interface definition files, plus the scripts used to
|
|
control compilation and installation of the executable. However, as a
|
|
special exception, the source code distributed need not include
|
|
anything that is normally distributed (in either source or binary
|
|
form) with the major components (compiler, kernel, and so on) of the
|
|
operating system on which the executable runs, unless that component
|
|
itself accompanies the executable.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<STRONG>4.</STRONG>
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>5.</STRONG>
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>6.</STRONG>
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>7.</STRONG>
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
This section is intended to make thoroughly clear what is believed to
|
|
be a consequence of the rest of this License.
|
|
|
|
<P>
|
|
|
|
<STRONG>8.</STRONG>
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>9.</STRONG>
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
|
|
<P>
|
|
|
|
|
|
<STRONG>10.</STRONG>
|
|
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.
|
|
|
|
|
|
|
|
<P><STRONG>NO WARRANTY</STRONG></P>
|
|
|
|
<P>
|
|
|
|
<STRONG>11.</STRONG>
|
|
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.
|
|
|
|
<P>
|
|
|
|
<STRONG>12.</STRONG>
|
|
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.
|
|
|
|
</body>
|
|
</html>
|