@database "Electrostatic Manual"
@$VER: "Electrostatic Manual" 2.4 (19.9.2001)
@author "Neil Cafferkey"
@(c) "Neil Cafferkey"

Copyright (C) 1999-2001 Neil Cafferkey

This manual is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this manual; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA.


@node "main" "Electrostatic Manual"

  @{b}@{u}Electrostatic 2.4@{uu} - A static binary translator for Atari 2600 games@{ub}


    @{"Introduction" link "intro"}

    @{"System Requirements" link "requirements"}
    @{"Translating Games" link "translating"}
    @{"Running Games" link "running"}
    @{"Compatibility" link "compatibility"}

    @{"PhxAss" link "phxass"}
    @{"JoyRide" link "joyride"}

    @{"Thanks" link "thanks"}
    @{"Contacting the Author" link "author"}
    @{"Legal Information" link "legal"}

    @{"History" link "history"}
@endnode


@node "intro" "Introduction"

Electrostatic is a static binary translator for Atari 2600 games. This means
that, unlike ordinary emulators, it permanently translates the game into an
Amiga program. This gives a great increase in processor emulation speed.

Unfortunately, emulating the Atari 2600's custom hardware takes up far more
time than emulating its CPU, so the benefits of translation are hardly
noticeable. In spite of this, the use of translation rather than
interpretation wasn't pointless, because I developed Electrostatic for a
college project. The main aim of the project was to investigate static
binary translation.

There are currently quite a few limitations on the Atari 2600 programs that
Electrostatic can translate (see @{"Compatibility" link "compatibility"} for details). I hope to
eliminate some of these limitations in the future.

@endnode


@node "requirements" "System Requirements"

The following is needed for the @{u}translator@{uu} to run:

    - About 1 Mb of free memory.

The following are needed for the @{u}translations@{uu} to run:

    - 68020 or better.
    - AGA (or graphics card?).
    - OS 3.0 or greater.
    - About 200kb of free chip RAM.
    - About 1.8Mb of free RAM of any type.

@endnode


@node "translating" "Translating Games"

Before you can translate an Atari 2600 game, you must create a game
description drawer. This is done by running the "Create Description" script,
which creates a drawer within Electrostatic's drawer containing
@{"configuration files" link "config-format"} for the game.

Once the game description exists, you can translate a game by running the
"Translate Game" script from the Workbench. Choose the source drawer
named after the game you want to translate, then select the destination
drawer for the translated game (this must not be the drawer containing the
game's source drawer). After this is done, the translation process begins.
Note that this may take several minutes.

The description for the game Okie Dokie is included in the distribution, so
there is no need to run the "Create Description" script before translating
it.

@endnode


@node "config-format" "Format of Source Game Drawers and Configuration Files"

It is not necessary to read the following information in order to use the
translator. It is really only included because I wrote it for a previous
version of this manual.

Every source game's drawer must include a ROM image of the game and several
description files. There should be three description files: a program file,
a segment file and a bank file.

Each of these description files must begin with a blank line. A field
heading starts in the first column of a line and ends with a colon. On the
next line is the field data, which must be preceded by a tab. Some headings
can be followed by multiple field data items, or none, each on a separate
line.

A program file has the following field headings:

  - Name:             The name of the game. Required.
  - Machine:          The location of the machine file to be used. Should
                          currently always be "machine/atari2600". Required.
  - Segments:         The location of the memory segments included in the
                          game. Multiple.
  - Instructions:     The location of the files describing any custom
                          hardware within the game's cartridge. Multiple.

A segment file has the following field headings:

  - Base Address:   The base address of this memory segment. Required.
  - Length:         The size in bytes of this memory segment. Required.
  - Banks:          The locations of bank files whose address ranges fall
                        inside this segment. Multiple.

A bank file has the following field headings:

  - Memory Type:    An integer representing the memory type of this memory
                        bank. Always 0 for the moment. Required.
  - Base Address:   The base address of this memory bank. Required.
  - Length:         The size in bytes of this memory bank. Required.
  - Data File:      The location of the actual ROM image. Required.
  - Bank Number:    Each bank in a segment must have a number. The first
                        bank's number should be 0. Required.

As an example, here are the @{"program file" link "Okie Dokie/program/MAIN"}, @{"segment file" link "Okie Dokie/segment/MAIN"} and @{"bank file" link "Okie Dokie/bank/MAIN"} for
the game @{"Okie Dokie" link "Okie Dokie/okiedoc/MAIN"}.

@{b}Important:@{ub} 2kb ROM images must be converted to 4kb by concatenating
two copies of the image.

@endnode


@node "running" "Running Games"

The translated games can be run from the Workbench or the Shell. The
following sections explain how to use the translated games.

    @{"Menus" link "menus"}
    @{"Controls" link "controls"}
    @{"Tool Types" link "tooltypes"}

@endnode


@node "menus" "Menus"

Every game has a Game menu and a Control menu.

@{b}Game menu@{ub}

About:

This option tells you how fast the game has been running since this option
was last selected. Very short gaps (eg. two seconds) between calls to this
function will result in slightly inaccurate speed reports.

Quit:

Exits the game.

@{b}Control menu@{ub}

Select:

Emulates the Atari 2600's Select button. Selects game options and ends any
game in progress.

Reset:

Emulates the Atari 2600's Reset button. Starts or restarts the game.

Colour:

If this is deselected, some games will run in black and white.

Easy:

If this is selected, the gameplay of some games will be easier.

@endnode


@node "controls" "Controls"

@{b}Joystick@{ub}

Only the first Atari 2600 joystick is emulated. This is done with an Amiga
joystick connected to the usual port. For joystick input to work, the
JoyRide commodity must be active and the LEFTCONTROLLER Tool Type must not
be set to an alternative controller.

@{b}Paddle Emulation@{ub}

The first Atari 2600 paddle can be emulated through the mouse. The left
mouse button emulates the paddle's fire button. The LEFTCONTROLLER Tool Type
must be set to PADDLES to activate paddle emulation.

@endnode


@node "tooltypes" "Tool Types"

Most game options are set via icon Tool Types. The following Tool Types are
recognised:

    FRAMESKIPRATIO - If this is set to a positive number n, one in every n
        frames will be displayed.

    IDEALFRAMERATE - This is currently only used to report what percentage
        of normal speed the game is running at, but in future versions it
        will be used to limit the game's speed. This value is in frames per
        second.

    STARTLINE - This is the number of the first line of the television
        display to be shown. The first line is 0.

    TVLINES - This is the number of television scan lines to be shown.

    NOSOUND - The presence of this Tool Type causes sound to be disabled in
        the game.

    LEFTCONTROLLER - This sets the type of controller to use with a game.
        Possible values are JOYSTICK (the default) and PADDLES.

    SCREENMODEID - The game's intuition screen will be opened in this screen
        mode. If this Tool Type is not present, a screen mode requester will
        appear. The selected screen mode will be saved for future use unless
        there is a screen mode setting already present, but disabled.

@endnode


@node "compatibility" "Compatibility"

The following features of the Atari 2600 and its games are not yet emulated:

  - Indirect jump instructions.
  - Bank switching.
  - Any controller besides the first joystick and paddle.
  - Mid-frame collision reading.

Below are a list of games that are known to work and a list of games that
are known not to work. Only 2kb and 4kb ROMs are included in these lists,
since ROMs of any other size will definitely fail. Additions and corrections
may be sent to the @{"author" link "author"}.

Also, Ventzislav Tzvetkov has put together a collection of pre-translated
Atari 2600 demos. They are available on Aminet as
"demo/euro/Atari2600Demos.lha".

@{b}Games that do work:@{ub}

Adventure
Basketball
Boing!
Bowling
Carnival
Checkers
Dodge 'Em
Duck Shoot
Exocet
Fantastic Voyage
Fast Eddie
Final Approach
Freeway
Frogger
Hangman
Kaboom
Missile Control
Mission 3000 AD
Mr Postman
Night Driver
Nuts
Okie Dokie
Pacman
Pele's Soccer
Picnic
Pitfall
Skeet Shoot
Skiing
Sky Diver
Snail Against Squirrel
Superman
Tetris26

@{b}Games that don't work:@{ub}

3D Tic-Tac-Toe
Action Force
Adventures of Tron
Air Raid
Air Raiders
Air-Sea Battle
Airlock
Alien
Alien's Return
Amidar
Armor Ambush
Astro War
Atlantis
Breakout
Cakewalk
Choppper Command
Deadly Duck
Death Trap
Defender
Demon Attack
Demons to Diamonds
The Earth Dies Screaming
Eggomania
Enduro
Entombed
Farmyard Fun
Fast Food
Frostbite
Gangster Alley
Guardian
Ice Hockey
Indy 500
Jawbreaker
M*A*S*H
Megamania
Meteor Defence
Mines of Minos
Miniature Golf
Mouse Trap
Night Stalker
Ocean City Defender
Oink!
Outlaw
Panda Chase
Parachute
Reactor
Shuttle Orbiter
Slot Machine
Solar Storm
Space Invaders
Space Robot
Street Racer
Super Breakout
Super-Ferrari
Tac-Scan
Video Checkers
Video Olympics
Warlords

@endnode


@node "thanks" "Thanks"

I would like to thank the following people:

  - Bob Colbert, for allowing Okie Dokie to be distributed with emulators.
  - Ron Fries, for the information in his TIASound package.
  - Brian Koetting, for allowing me to extend JoyRide to use two joysticks
    (not done yet).
  - Bradford Mott, for writing Stella, whose source code was very useful as
    Atari 2600 documentation.
  - Fredrik Olsson, whose MOS6502 emulation code gave me some ideas for
    improving my instruction translations.
  - Matthew Stroup, for porting V2600 to the Amiga, which was useful while
    developing Electrostatic.
  - Ventzislav Tzvetkov, for translating a collection of demos and providing
    some additional game compatibility information.
  - Frank Wille, for allowing me to include GigaPhxAss with Electrostatic.

@endnode


@node "author" "Contacting the Author"

Please send bug reports, suggestions, and any other correspondence to one of
the following addresses.

E-mail: caffer@cs.ucc.ie

Post: Neil Cafferkey,
      30, Upper Kensington,
      Rochestown,
      Cork,
      Ireland.

@endnode


@node "legal" "Legal Information"

This software is provided "as is". You use it at your own risk.

The Electrostatic package is released under the terms of the
@{"GNU General Public Licence" link "GPL/MAIN"}, with the following exceptions. The file
"MOS6507.i" is public domain. JoyRide is Copyright © 1994 Brian Koetting.
GigaPhxAss is copyright © 1994-97 Frank Wille. Okie Dokie is copyright
© 1996 RetroWare. See the individual source files for copyright information
regarding other components.

@endnode


@node "phxass" "PhxAss"

PhxAss is a macro assembler written by Frank Wille. It is used in
Electrostatic's translation process.

The full package is available from Aminet as "dev/asm/PhxAss.lha".

@endnode


@node "joyride" "JoyRide"

JoyRide is a commodity written by Brian Koetting. It allows programs to
share the joystick and only respond to joystick events when the program's
window is active. Every translation produced by Electrostatic uses JoyRide
to handle joystick input.

The full package is available from Aminet as "util/cdity/JoyRide.lha".

@endnode


@node "history" "History"

@{b}V2.4 (September 2001)@{ub}

  - Fixed some silly bugs in the configuration files that made the previous
    release almost useless.
  - Removed some unsuitable screen modes from requester.

@{b}V2.3 (May 2001)@{ub}

  - Source code included.
  - Games run slightly faster.

@{b}V2.2 (October 1999)@{ub}

  - Fixed major bug that caused translation to fail on machines that didn't
    have a PhxAss environment variable.
  - Emulation of first paddle through mouse.
  - Games run a bit faster.
  - New SCREENMODEID Tool Type.
  - Screen mode requester now used instead of the BestModeID function.
  - Games started from Shell now use their icon's Tool Type options.

@{b}V2.1 (September 1999)@{ub}

  - Games generally run much faster than they used to.
  - Fixed a timer bug that caused jumping screens.
  - Implemented mid-line colour changes and variable playfield priority.
  - More forgiving stack emulation.
  - Added colour/black and white switch and difficulty switch.
  - Implemented missile resetting.
  - More accurate frames-per-second reports.
  - Added a frame skipping option.
  - Added sound emulation.
  - Tool Types to select vertical display boundaries.
  - New Installer script to create game description files.
  - Fixed unterminated tag list in translations.

@{b}V1.2 (July 1999)@{ub}

  - Better vertical blanking emulation.
  - Better colours for mouse pointer.
  - Corrected errors in AutoDocs.
  - Miscellaneous bug fixes.

@{b}V1.1 (June 1999)@{ub}

  - First release.

@endnode