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

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:
-------------

It's been a while but the second publically available version of 'Replay'
is here.  This version has expanded on the original concept with improved
support for multiple processors (Z80, 6502, 6809) as well as more generic
routines.

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 (.KEG) for it.  

There are still some limitations with this version:

1) Speed throttling doesn't work well unless you are running a game directly.
   For this reason, it is turned off by default when running normally and
   turned on by default when running a game directly with the (-game) option.
   This is due to Allegro's screwy timer routines that need to be installed
   to get the mouse going for the menus.  They take over the clock and
   cause havoc with the throttling routines.
2) The Unix versions have no speed throttling.
2) No sound.

Future versions will offer more support.





.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 to implement for a first run at it.

The format for the .KEG files is starting to settle down be may still change 
in the future, so keep that it mind if you attempt to write one.

I still haven't got around to creating a document detailing how to write
a .KEG file (it's been too much fun working on the emulator).  Hopefully
I'll find some time in the near future.  In the mean time, send me e-mail
if you want to know anything, I'd be glad to give you a hand.





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:
    -game <name>  : run the specified game directly, bypassing all menus.
                    valid <name>s can be found in replay.nfo as the 'ID:'
                    field.
    -info <file>  : specify an alternate info file (default is ./replay.nfo).
    -frameskip    : skip this many frames each time around.  If you're
                    desparate for performance, give this a try.
    -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.

Still has the same cheezy UI, sorry 'bout that.

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.
F3  - Reset the game.
F10 - Toggle speed throttling on/off. 





Troubleshooting:
----------------
"It's too fast"
    Try running a game directly with the -game option.  This should give
    you proper speed throttling under DOS only.  Unix users will have to
    live with it.

"It's too slow"
    Try the -frameskip command line option.

"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.

    Running a game directly with the -game option should allow it to run
    in Win95.  It's Allegro's screwy timer routines again that are causing
    this problem.

"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 to test the 6502 emulation.
- 2 player mode now works.
- Scoring and high scores now work.
- Some sprite glitches that don't affect play.
- Colours should be OK.
- No sound.
- The emulation may occasionaly stop (due to incomplete ROM decryption, see
  below).

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.






PacMan:
-------
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.
arrows - PacMan movement.

- The second game supported by Replay to test the Z80 emulation.
- The high-score and credit text is missing.
- Accurate colours.
- No sound.




Super PacMan
------------
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.
arrows - Super PacMan movement.

- The third game supported by Replay to test the 6809 emulation.
- Bad colours.
- Coin-up not working quite correctly.
- After entering a high score, the game stops.  You can reset (F3) to continue
  on.
- No sound.





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 and
    whose generic graphics routines where the inspiration for the generic
    routines in Replay.

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