@database "Electrostatic Manual"
@$VER: "Electrostatic Manual" 1.2 (10.7.99)
@author "Neil Cafferkey"
@(c) "Neil Cafferkey"

@node "Main" "Electrostatic Manual"

  @{b}@{u}Electrostatic 1.1@{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.
    - OS 3.0 or greater.

@endnode


@node "translating" "Translating Games"

Before you can translate an Atari 2600 game, you must have a directory named
after the game in Electrostatic's drawer. The contents of this drawer must
be in a @{"special format" link "config-format"}.

To translate a game, run "Install Atari 2600 Game" from the Workbench. At
the prompt that appears, enter the name of the game's source drawer (there
is one game included with this package, Okie Dokie).

Next, select the drawer in which to put the translated game, then wait for
it to be translated. This may take several minutes.

@endnode


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

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.

Every game has a Game menu and a Control menu.

@{b}The Game menu:@{ub}

@{u}About:@{uu}

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 inaccurate speed reports.

@{u}Quit:@{uu}

Exits the game.

@{b}The Control menu:@{ub}

@{u}Select:@{uu}

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

@{u}Reset:@{uu}

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

@endnode


@node "compatibility" "Compatibility"

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

  - Sound.
  - Indirect jump instructions.
  - Bank switching.
  - Playfield priority.
  - Any controller besides the first joystick.
  - Mid-line colour changes.
  - Mid-frame collision reading.

@endnode


@node "thanks" "Thanks"

I would like to thank the following people:

  - Bob Colbert, for allowing Okie Dokie to be distributed with emulators.
  - 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.
  - 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". Use it at your own risk.

The Electrostatic package is Copyright © 1999 Neil Cafferkey, 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.

The Electrostatic package is freeware.

@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/PhxAss439.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}V1.2@{ub}

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

@{b}V1.1@{ub}

  - First release.

@endnode