Replay - the Classics
=====================
Version: 0.01a

By: Kevin Brisley

Important:
----------
** Do not ask me for ROMs or where you can get them.  You will be ignored.
** This progam is not to be distributed on CDROM without my explicit 
   permission.  I don't appreciate people making money off of my work 
   when I'm not.
** This program must only be redistributed in it's original archive.  It must
   not be distributed with any ROM images included!


Introduction:
-------------

This is the first generally available 'alpha' release of my arcade game
emulator entitled 'Replay'.  It will probably change a lot in the
future but this should give you the general idea.

The thinking behind Replay is that most of the classic arcade games have
numerous similarities.  In these games, you'll find one ore more Z80, 6502
or 6809 CPU, some sort of character based playfield, usually some sprites, 
some memory mapped I/O, etc.  Replay attempts to take advantage of this
fact.  Each game that Replay runs is specified by a resource file.  This
resource file describes the game, where the ROMs go, what the screen 
resolution is, where the video RAM is located, etc.  Replay then reads this
resource file and uses it's generic routines to create the emulation.

My hope is that people will be able to add games to Replay simply by
creating a resource file for it.  Dave Spicer's 'Sparcade' allows new
.RAT files for new games, however the new game must have the same 
hardware as an already supported game.  Replay allows a much more 
extensive specification of the game through it's .KEG files.

Please note that this version of Replay is a preliminary 'alpha' version.
It only supports *one* CPU (the 6502), and only one graphic format.  It is
mainly a test release to see how it works for people.  It runs 'Burgertime'
and it's very unlikely that you'll be able to get any other games going
with it at this time.  

These are the limitations of this version:

1) Only supports 6502.
2) No speed throttling (although it hardly needs it, since I haven't spent
   any time optimizing it yet).
3) *Very* limited graphics support.
4) No sound.

**So please do not send me hate mail saying that it's useless, it'll never
  work, etc., etc.  

Future versions will offer much more support (more CPUs, more graphics 
support, etc.), and hopefully generic emulation isn't a pipe dream.


.KEG Files:
-----------

The .KEG files are specified in a simple 'language' that basically consists
of a bunch of label/value pairs.  If you are familiar with X-resource files
in X-Windows, you'll probably recognize the style of the .KEG files.  However,
the are not true X type resources as there is no pattern matching.  I
probably should have used lex&yacc to create a real specification language,
but this was easier on to implement for a first run at it.

The format for the .KEG files will almost certainly change in the future, so
if you start writing one and have to change it later don't yell at me.

I will create some sort of documentation, detailing how to write a .KEG file
sometime in the future but in the mean time, they're pretty easy to figure
out by just looking at one.


Installation:
-------------
DOS:
1)  Create a directory for replay (e.g. md c:\replay).
2)  Change to the replay directory (.e.g cd c:\replay).
3)  Unzip replay.zip (with -d if you are using pkunzip) 
    (e.g. pkunzip -d c:\temp\replay.zip).
4)  Place the ROMs for the games in the directories under the replay directory.
    (e.g. cd c:\temp\replay\btime ; pkunzip c:\temp\btimerom.zip).

Unix:
1)  Use gzip to uncompress the file (e.g. gzip -d replay.tgz).
2)  Untar the file (e.g. tar xvf replay.tar).
3)  Place the ROMs for the games in the directories under the replay directory.
    (e.g. cd replay/btime ; tar xvf /tmp/btimerom.tar).


Usage:
------
$ replay <options>

where the <options> are:
    -info <file>  : specify an alternate info file (default is ./replay.nfo).
    -vesa         : (DOS only) force the use of 640x480 Vesa mode.
    -nojoy        : (DOS only) disable joystick.
    -altvid       : (DOS only) use the alternate funky tweaked mode with
                    distinctly visible scan lines (yech!).

Sorry about the awful colours and the cheezy UI, I haven't spent a lot
of time on it.

The following keys are used internally by Replay while playing a game:

ESC - Return to game menu.
F1  - Save the game.
F2  - Load the game.


Troubleshooting:
----------------
"It's too fast/slow"
    You can speed it up by increasing the IPeriod value in the .keg file for
    the game or slow it down by decreasing it.

"It doesn't seem to work under Win95"
    Open a full screen DOS window.  Run Replay.  It will probably switch
    back to Win95 and tell you that this should run in MSDOS mode.  It will
    ask if you want to create a shortcut.  Tell it 'No' and then go back
    to the same full screen DOS window and try it again.  It should now run.

"I can't get the joystick to work under Linux"
    That's because there's only joystick support in DOS.

"It doesn't work on my computer"
    Well, I've only tested it on mine where it works.  You'll have to 
    mail me the details.


Burgertime:
-----------
Keys are configurable from the .KEG file but I've assigned the following
initially:

1      - Start 1 player game.
2      - Start 2 player game.
3      - Insert coin into slot 1.
4      - Insert coin into slot 2.
arrows - Chef movement.
space  - Pepper.

- The first game supported by Replay.  
- 2 player mode not working.
- 6502 Decimal mode not implemented, therefore scoring is messed up and no
  high score entering.
- Some sprite glitches that don't affect play.
- Colours aren't original.
- No sound.
- The emulation may occasionaly stop (due to incomplete ROM decryption, see
  below).

- ** The available burgertime ROM archives are missing a ROM.  One of the
     ROMS that contribute to the graphics of the burger pieces is missing.
     From the schematics, I would say that it should be called: AB11.12K.
     In the .KEG file, AB9.15K is duplicated.  What this means is that
     some of the burger pieces are transparent in places where there should
     be colour.  Gameplay is not affected although it would be nice to
     have a complete version.

I took way longer than I had hoped to get this game working, mainly because
the ROMs are encrypted.  Although not encrypted enough to make it immediately
obvious.  After you get going though you start to realize that something
isn't quite right.  Basically, the encrypting involves only the opcodes (not
the data) and only at certain locations in the code.

Here is what I've figured out so far, if anyone can figure the last bit
out, I will be eternally grateful!  Please let me know if you have any
ideas.

Here's the deal...only the opcodes are encrypted and only some of them
are encrypted.  To decrypt an opcode, the following bit shuffle is used
(assuming bits are numbered in the following manner: 7654321):

0 -> 0
1 -> 1
2 -> 3
3 -> 5
4 -> 4
5 -> 6
6 -> 7
7 -> 2

So for example, a PHP opcode ($08, 00001000) would be decrypted to a JSR
$____ opcode ($20, 00100000).

Now the other piece of the puzzle is when to do the decryption.  I have
determined that the only time a decryption occurs is if the address the
opcode appears at an address with bits 2 and 8 set (i.e.
xxxxxxx1xxxxx1xx).  Unfortunately, not all addresses of that form have 
encrypted opcodes on them.  So I need to find out what determines whether
or not an opcode on such an address is encrypted.  I will place a couple
of files on my web site that list all of the addresses of the above 
type that I've found that have encrypted opcodes on them and all of the
addresses that don't.


Contacting the Author:
----------------------
Please feel free to let me know of any bugs you find, or suggestions you
have for improving the emulator.  You can e-mail me and I'm also subscribed
to the MUL8R mailing list.

Name:   Kevin Brisley
e-mail: kevin@isgtec.com
www:    http://www.geocities.com/SiliconValley/Pines/4454


Thank You's
-----------
Sergio Munoz for initially pointing me in the right direction.

Michael M. Morrison for sharing what he knew about Burgertime.

Marat Fayzullin for his portable 6502 emulation package which I referenced
    while writing mine.

Neil Bradley for maintaining the MUL8R mailing list and contributing so
    much to the arcade emulator authors.

Nicola Salmoria whose Mame emulator provided the tweaked VGA modes I use.

Tom Chesser & Paul Thorn for their help on the finer points of schematic 
    reading.
