
                                
                                      
                             
                                        
                             
                          E M U L A T O R  
		             Ver 0.04 (BETA 1)


GYRUSS EMULATOR -- BETA RELEASE

Copyright Notices:
    Copyright (C) 1996  Michael Cuddy, Fen's Ende Software
    GYRUSS Emulator Home Page: http://www.fensende.com/Users/mcuddy/gyruss
    
    This program, and this document are Copyright 1996 Michael Cuddy, 
    Fen's Ende software.  This program may be freely redistributed
    only if the entire contents of the archive are kept together.
    
    THIS PROGRAM MAY NOT BE DISTRIBUTED WITH ROM IMAGES FOR GYRUSS, OR
    ANY OTHER GAME (HINT, HINT).  YOU MAY NOT LEGALLY OWN A COPY OF THE 
    GYRUSS ROMS UNLESS YOU OWN A GYRUSS MACHINE.  IF YOU HAVE A COPY OF
    THE GYRUSS ROMS, AND YOU ARE NOT A PROUD OWNER OF A GYRUSS MACHINE,
    YOU DESERVE A SPANKING, AND I'M GOING TO TELL YOUR MOMMY ON YOU! THE
    SOFTWARE CONTAINED IN THE GYRUSS ROMS ARE COPYRIGHT 1983 KONAMI,
    THEY ARE NOT MY PROPERTY, I CAN'T GIVE THEM AWAY.  I WILL IGNORE
    ALL REQUESTS FOR ROMS.
    
    Original Z80 Core is copyright 1995 Marat Fayzulin.
    Original PSG (AY-3-8910) emulation (C) Ville Hallik 1996.
    Synthetic Audio Library (SEAL) is Copyright 1996 Egerter Software
    ModeQ code contributed by Gary Shepherdson
    Custom 6809 crack by Pete Grounds
    
What Have I Got Here?
---------------------
    ** IMPORTANT **
    READ ALL OF THIS FILE, AND ALL OF FAQ.TXT BEFORE SENDING ME EMAIL.
    I AM GETTING SWAMPED WITH EMAIL, AND AM NOT GETTING AS MUCH TIME
    TO WORK ON THE EMULATOR.  I WANT TO KEEP MY FANS IN THE LOOP, SO
    PLEASE GIVE ME TIME TO WORK.  IF YOU ASK A QUESTION COVERED IN THE
    FAQ, YOU WILL NOT RECIEVE AN ANSWER!  SORRY TO BE SO BLUNT, BUT
    I'M GETTING ABOUT 50 MAIL MESSAGES A DAY!
    
    Many have asked, so here it is:
    
    The latest and "greatest" version of the gyruss emulator.   Sprites
    are implemented, if a bit slow.  Sound is implemented, if a bit buggy.
    The colors are passable. (004) The built in color editor has been
    removed from the released version. 
    
    There is much debugging built in (in fact, most of a Z80 monitor), 
    and most of the code is working but not optimized.  The emulator 
    runs in two modes:  text and graphics. In text mode, you get a debug 
    monitor screen, and no automatic vertical blanking interrupt, 
    in graphics mode, the emulator is running in it's full glory. 
    With sound and everything. 
    
    There are less bugs, now.  Let me know if this crashes your 
    machine ... AFTER YOU READ THE FAQ!!!!!!!!
    
    On second thought: let me know, good or bad, what happens.
    
    It should work on any reasonably spiffy pentium (like I said, it's not
    optimized).  I'm targeting a P90 or P100 (before you 486 folks start 
    whining, realize that there's alot going on inside this little box:
    2 CPUs plus 5 programmable sound generators spooling out audio at 
    44KHZ ... besides, a P133 motherboard + CPU is just over
    200.00 now, so upgrade, for chrissakes). 
    
    I've run it under W95 (in a dos box) and it runs just fine.  
    I actually haven't tried it under real "DOS".
    
    There are some known problems with the audio code and AWE32's (I use
    a third party sound library called "SEAL"; if you have problems with
    sound on a SB clone or AWE, try the -b or -B command line options) 
    
    Also, for some reason, the emulator doesn't play happy with some 
    versions of QEMM installed (under DOS or Win95).  You'll have
    to disable QEMM to run it (see the FAQ).
    
Command Line
------------
    
    There are several command line parameters:
    (0.01: now with real argument parsing)
    (0.04: the 'q' flag now works as advertised)
    
	    gy [ -f <gfx-fps> ] [ -a <audio-fps> ] [ -s <srate> ]
	       [ -c <cpu-cycle> ]
	       [ -t ] [ -q ] [ -j ]
	       [ -b ] [ -B ] [ -m ]
	    
    There's a usage message, but it's very terse; so here's a slightly
    more verbose description:
    
       -f <gfx-fps> -- this option sets the number of interrupts 
       	   per second that will be sent to the main CPU.  
	   This relates to the speed of the game. The default 
	   (and correct value) is 60.  Min is 1, max is about 70.  
	   You probably shouldn't need to change this from the default.
	   (unless you're trying to run it on a slow machine -- the
	   symptoms that indicate the need to lower this number are:
	   the emulator 'HALT's for an unknown reason)
       
       -a <audio-fps> -- is the number of times per second (give-or-take) 
           that the audio chips are polled for thier current values 
	   and new sample buffers are generated to be passed to the 
	   sound card.  The default here is also 60.  The minimum is 
	   about 20 (sounds stupid otherwise).  maximum practical 
	   limit is about 120. This does not change the speed at 
	   which sounds play, or thier pitch, it only changes the 
	   accuracy of the simulation of the PSG chips.  The higher 
	   the number the more CPU is needed to calculate the PSG 
	   chips' envelopes. (but they are computed in smaller chunks)
	
	-s <srate> -- this is the data rate that your sound card will chew 
	   through the sample buffers at.  Slower computers should select
	   a lower number.  lowest practical number is 8000, highest is 
	   44100.  (default is 11050 -- should be compatible with
	   most sound cards).
	   
	-c <cpu-cycles> -- the number of cpu cycles executed between 
	   housekeeping tasks (graphics, audio, etc.); there's a bit
	   of overhead associated with entering the CPU emulation
	   code, this parameter helps reduce that overhead so that
	   the emulation cpu can run closer to actual speed.
	   The Default value is 32.  
	   
	-t -- start the emulator in text-mode.  You probably don't 
	   want to do this unless you're me.
	   
	-q -- select old modeQ code.  I've put new tweaked-vga-mode
	   code in this version.  The -q flag selects the old code.
	   
	-b -- cause sound library to pretend your sound card is a 
	   Sound Blaster 16.  This should fix the problems with 
	   AWE-32's
	   
	-B -- cause sound library to pretend your sound card is a
	   "Classic" sound blaster.  Try this if you have a GUS or
	   SB compatible and audio doesn't work right.
	   
	-j -- disable joystick support.  can speed up game on slower
	   systems.
	   
	-m -- force monoaural mode.  can speed up game on slower systems.
	   
Keys and Using the Emulator
---------------------------
	   
    Keys that might be handy:
    
	ESC  - switches to the setup menu
	F12  - take a screen shot (saves in gyNNNN.pcx), won't overwrite
	       existing files
	q    - quit emulator (can also quit from the config menu)
	h    - start / stop the emulation ("pause" will appear
	       above the "credits" line whe stopped, press 'h' to 
	       continue the emulation)
	
    While "playing" (these keys are remappable):
    
	F1   - left coinmech
	F2   - right coinmech
	F3   - service mode (adds a credit)
	F4   - 1P start 
	F5   - 2P start
     2,4,6,8 - (on keypad) move ship
      L-CTRL  - fire 
	
	q    - quit emulator
	Z    - (capital Zed) reset emulator (saves high-scores, and 
	       dipswitch state, too).
       t/T   - increase / decrease music tempo.  the actual tempo can be
               seen on the audio menu in setup mode.  
	
Files, Included and Needed 
--------------------------
    
    The files that are used by the emulator:
    
	    readme.txt -- read this file ... er, wait, I guess you already 
		    are! Congratulations if you read this far before 
		    running the emulator!
		    
	    faq.txt -- If you have any problems, READ THIS FILE!!!!!!
	            Chances are that your problem is covered in here.
		    
	    gy.exe -- this is the main emulator executable
	    
	    gychar.pal -- this is the palette file for the character-graphics
		 if deleted, gy.exe will create a new, ugly, greyscale 
		 palette.
	    
	    gyspr.pal -- sprite palette; same notes as above.
		 
	    gyruss.ram -- session to session persistent state. (dip switches,
		 etc.) This file can be deleted to restore the "factory 
		 default state". (not included in archive)
		 
	    gyruss.hi -- the high-score table. The real gyruss doesn't save
	    	 high scores from game to game (a severe mis-feature!) but
		 the emulator does.  This file can be deleted to clear
		 high-scores. (not included in archive)
		 
	    gyruss.key -- keyboard mappings. don't mess with this file; key
	         bindings are changed from within the program.
	         If you delete it, it will be recreated with default keys.
		 (not included in archive)
		 
	    joy.dat -- joystick calibration information;  if you change 
	         joysticks, you might need to delete this file to get your
		 joystick to calibrate correctly. (not included in archive)
	    	
	    bugrept.txt -- empty bug report; if you find a bug, copy this
	         file, fill it out, and email it to me, please!
		 
	    data\\*.out -- these are audio samples generated by my 8039 
		 simulator. Just in case you haven't downloaded the 
		 audio simulator, yet, these sounds suck.  *SIGH*
		 I'll do better in future releases.
		 
		 
    ROMS: 
	 The emulator will look for roms in data\*.bin. 
	 Roms? did someone say roms ... I don't know where they come 
	 from, I don't know where to get 'em, and I'm not givin' you 
	 mine, assuming I have them. (insert std. disclaimer... ;-)
	 
To Do List
----------
    
    Things that need doing:
    
	 * SPRITES -- these are still slightly bugged (planets, some
	   flicker).  And they are too slow.
	 * PSG's have trouble with some sounds (the player-shooting sound,
	   for example, does not work)
	 * mute button
	 * faster, Faster, FASTer, FASTER!
	   
	   USE THIS PROGRAM AT YOUR OWN RISK (there, is that enough CYA?)
	   
    If this program fails on your machine, please READ THE FAQ!!!
    
    If the FAQ does not answer your questions, fill out the file 
    'bugrept.txt' to the best of your knowledge and email it to 
    me at: mcuddy@fensende.com
    
    The gyruss homepage is:
	http://www.fensende.com/Users/mcuddy/gyruss
	
Availability
------------

    This emulator is freely redistributable.  It is, however, Copyright 
    1996/1997 (C) Michael Cuddy, Fen's Ende Software.
    
    One more time ...
    
    *************************************************************************
    This program may be freely redistributed only if it is NOT accompanied by
    GYRUSS ROMS.  The GYRUSS Roms are Copyright 1983 - 1985 by CENTURI CORP.
    DO NOT ASK ME FOR THE ROMS -- I CANNOT, AND WILL NOT GIVE THEM TO YOU.
    *************************************************************************
    
    If you send me mail asking for the roms, or where they are, your mail
    will be silently dropped.  Sorry.
    
    I plan on eventually making the source code available, but for now
    since the code is in a _constant_ state of flux, I'm not prepared 
    to release it to the whole world.  If you are working on an emulator
    and want the modular-multiple-3910 PSG code or the multiple-cpu patches
    to Marat's Z80 emulator, don't hesitate to ask.
    
    I have put up the PSG code on my web site.  Go to the Gyruss page,
    and there is a link there: http://www.fensende.com/Users/mcuddy/gyruss
    
    I also have the multiple-z80 code up. There's no link.  it's called
    vz80.zip off of the Gyruss directory.
    
    I will _never_ sell this program; however, if feel inspired to send 
    me a gift, old arcade boards, schematics, and manuals are just 
    the right-sort-of-thing ;-)
    
    I'd also like to get the schematics for the game "two tigers"
    (not the fighting game, the Bally sink-the-ships game).  A working board
    for that game would be nice too.
    
Known Working Configurations
----------------------------
    My development machine looks like this:
    
    	* P150 / ASUS (Intel Triton) motherboard, 32M mem, 512K 
	  cache. SoundBlaster 16/MCD, Adaptec SCSI card, DOS box under 
	  Win95.
	  
    On the P150, I run with the compiled-in default settings:
    	fps (-f):	60 	(default)
	srate (-s):	11050 	(default)
	aupdate (-a):	60 	(default)
	cpucycle (-c):	16 	(default)
    The game runs at the right speed, but the music and SFX are not timed
    correctly (still working on that)
	
    If you find better settings, please mail them to me.
    
Special Thanks
--------------

    FIRST AND FOREMOST: to Pete Grounds.  He figured out the encryption 
        method used by the 6809 on the gyruss board was!  The 6809 is 
	responsible for control of all of the sprite generation. 
	Without him, the sprites probably _NEVER_ would have been correct...
	
    Next, to all the other emulator authors, especially  neil@synthcom.com
	for his excellent 'emu'. the (not-just) Atari Vector Graphics 
	emulator. This was the program that inspired me to start down
	the dark side of coding--EMULATORS!
	
    ALSO: thanks to Marat Fayzulin for making his Z80 emulation core
        available.  I've extended this code to allow for multiple Z80's 
	in a single program as well as easy mapping of peripherals to the 
	Z80's memory and I/O busses.
	
    And: Thanks to Gary Shepherdson for the ModeQ code from his Kong 
        Emulator.  This should clear alot of bug-reports from my queue!
    
    ... Thanks to whoever put up the schematics for GYRUSS on the net
    without them none of this would have been possible.
    
Known Problems
--------------

	(0.00) There seems to be a problem with people who have S3 video 
	cards and AWE32's ... the problem seems to be in the seal library.
	using '-a 0' will turn off audio.
	    
	    WORKAROUND: (0.04) If you have an AWE32, you should remove 
	    AWEUTIL.EXE from your AUTOEXEC.BAT (or make a multi-boot 
	    config).  Win95 users should disable the "advanced wave 
	    table synthesis" (or something like that ... I don't have 
	    an AWE32) from the control panel.  This is definately a 
	    bug with SEAL, and I've reported it to them.
	    
	    FIX: use the '-b' option, which forces SEAL to talk to your
	    soundcard as if it was a Sound Blaster-16.  If that doesn't
	    work, use '-B' which will cause your card to be detected as a 
	    "classic" Sound Blaster.
	    
	
	(0.03) I have some new video mode code,  It is the _actual_ 
	code from Gary Shepherdson's Kong Emulator.  If you can run 
	KONG and you can't run GYRUSS, I _REALLY_ want to know about it.
	
	(0.00) Slow machines can sometimes cause "interrupts" to be delivered 
	to the CPU too fast and cause wierd behaviour (usually the 
	emulator halts in a funky state)  Try using '-f 50' (or lower)
	and tell me what happens.
	
	    (0.02) This problem should be lessened (shouldn't happen on
	    any pentium), but is still there.
	    
	    (0.03) The newly revamped graphics system is correct, but slow.
	    Watch out on low-speed pentiums. and, unfortunately, it's 
	    probably going to be unplayable on a 486.
	
	(0.00) The last "player-ship" in the ships-remaining display
	does not erase correctly.  Sometimes parts of it are left behind.
	
	(0.01) The earth 'smears' when the high-score table is up
	    (0.03) this problem is fixed, but some of the planets have "too
	    many parts" (You'll see what I mean when you get there ...)
	
	(0.00) When you run the emulator under win95, it says 
	'you might want to run this under a DOS shell' ... ignore it or 
	change your DOS-box's preferences to ignore it for you.
	
	(0.02) If high-scores get corrupted, delete the gyruss.hi file.
	
	(0.02) 486's are not officially supported, however, the one in my
	office works okay (without audio!).  486's may be supported 
	in the future, when I speed up the sprite routines
	    (0.03) This gets even worse with this release;  next release
	    is the performance release.
	
	(0.02) The Audio tempo setting is a hack.  I need to figure out
	a better way to time this bugger.
	
	(0.01) Sprite drawing is buggered;  sometimes sprites appear
	where they should not. sometimes more than should appear do, and 
	sometimes sprites that should be there are not.  I know about
	all of the sprite problems, you don't need to report them ;-)
	    (0.03) except for the planets, all sprite drawing should
	    be correct now.
	    (0.04) the planet sprites are still messed up; and there
	    is the occasional flicker (for 1 frame of animation) 
	    when all of the sprites on the screen jump from one place 
	    to another.  This error is deterministic, and is a problem 
	    with the way the emulator transfers the sprite control 
	    information to the emulated sprite engine.  I'm working on it...
	
	(0.01) There is no sprite clipping on the sides, sometimes bits
	of the aliens will appear on the opposite side of the screen as 
	they exit (mostly on the left when they exit from the right).
	
	(0.02) Joysticks are still not supported.  There's a menu for
	them, but I haven't put in the code, yet.
	    (0.04) joysticks are supported in the 0.04 release
	
Version History
---------------
    1/31/1997 -- Version 0.04 (BETA 1)
    
	Features Added:
	   * Executable is now bound with PMODE/W.  It should be a 
	     little bit faster than the old version.  Most notably,
	     it should not have problems with sound cards set at IRQ 10
	      
	   * Added a feature to allow overriding of the sound-library's 
	     auto-detect function;  -b will now force the sound-lib to
	     treat your sound card like an SB-16, and -B will force the
	     sound-lib to treat your soundcard like a "classic" sound
	     blaster.  This should help some GUS users, some SB-PRO 
	     users and AWE-32 users.
	     
	   * Revamped command line options; more shared code with TimePilot
	     emulator.
	     
	   * Reduced interrupt load;  used to deliver 1165 interrupts
	     per second; now only 873 per second.  Why so many interrupts?
	     to keep the music plugging at the right rate.  The original
	     gyruss audio cpu spins in a loop watching a clock
	     that runs at about 1500 KHZ, it then watches for a 1->0 
	     transition on that line (effectively dividing the clock
	     frequncy by 2, and then advances it's sound effects / music
	     pointers -- believe me, if I could get away with fewer 
	     interrupts, I would).
	     
	   * Documentation updated;  Version history now in reverse order
	     to make scanning for changes easier.
	     
	   * Emulator output is now saved to 'gyruss.out' once the 
	     emulator is running.  If the emulator crashes,  the output
	     will be here.
	     
	   * Added a small delay (1/2 sec) to allow multi-sync monitors
	     to resync after switching to graphics mode, but before 
	     starting the emulation.
	     
	   * Filled the audio buffers with '0's so as to avoid the annoying
	     speaker pop when starting up.
	     
	   * Removed the color editor;  if you want to map the arrow keys,
	     be my guest (you guys wouldn't believe the number of people
	     who sent in bug reports "when I press the arrow keys the game
	     flickers and slows down") ... *SIGH* I had left it in so that
	     somebody might send me better colors.  I didn't get any.  Oh,
	     well.
	
        Bugs Fixed:
	   * DrawSprites() now correctly updates the screen when the 
	     "sprite hardware" is in the "disabled" state.  (this allows
	     the "test grid" to be seen when the game "boots".
	     
	   * you can now map the arrow keys, 'cause the color editor
	     has been removed.
	     
	   * Graphics mode was being reset wrong when the emulator was
	     reset 'Z'.  This is now fixed.
	     
    1/05/1997 -- Version 0.03
     
        Bugs Fixed:
	   * readme.txt had lots of 1996's where it should have had
	     1997's.
	     
           * Yes, virginia, I _do_ use a custom keyboard handler; I just
	     left out some parenthesis from a macro that I use to 
	     construct the value to be read from the control I/O port
	     and it would stop evaluation of the expression (short-circuit
	     in "C" parlance) when it found the first key pressed)
	     
	   * Changed the video mode code;  It should be more compatible
	     now. If you can't run 003, but you could run 002, use 
	     the '-q' flag to select the old ModeQ code.
	     
	Features Added:
	   * A frequently-asked-questions file (Faq.txt) is now 
	     distributed with the archive.
	     
	   * The sprite system was completely gutted and replaced.
	     it's now almost 100% correct.  The gotcha: it's _really_
	     slow.  Fast enough on my pentium (P150) to maintain 60FPS,
	     but anything less than a P100 and you're probably going
	     to be hurtin'...  I'll fix performance in the next release.
	     
	   * (internal use) added -t flag to start emulator in text mode.
	   
	   * (not a feature, just a note..) When the emulator starts, it
	     doesn't clear the screen and put up the grid anymore (well,
	     it does, it's just that with the new sprite system, it
	     doesn't get updated until sprites are activated.  The
	     interesting bit is that the sprite emulation actually
	     displays garbage sprites just like the real game when booting
	     until the emulation gets to a point where it clears the 
	     sprite control RAM. 
    
    01/02/1997 -- Version 0.02
    
        Bugs Fixed:
	   * "-a 0" did not work as advertised (gave usage message 
	       instead of disabling audio
	       
	New Features:
	   *  Music tempo is changeable from within the program; it
	      should also be more stable.  Find a setting that works 
	      on your computer.  use T/t or the new selection on the 
	      Audio Menu in setup mode.
	      
	   *  Graphic Flicker should be gone for all but the slowest 
	      video cards; drawback: it now uses 128K more memory (sprite
	      buffer and text buffer), advantage: video memory is accessed
	      linearly, in a 64K chunk, 32-bits at a time. so this should
	      make up for the extra memcpy's 
	   
	   *  Joystick menu is there; joysticks are not supported yet.
	   
    01/01/1997 -- Version 0.01a 
        Bugs Fixed:
	   * gy.exe was not compiled as a release version, and 
	     therefore was looking for roms in ..\roms\*.bin
	     
	   * The "too many open files" bug has been squashed; sorry.
	
	New Features:
	   * Sprites!
	   
    01/01/1997 (4:50a PST) -- Version 0.01 -- Happy New Year!
    
        The sprites are (mostly) working.  Colors are okay, but not
	perfect.  The game is _very_ playable.  Released today 'cause
	I wanted to be the first emulator released in '97 (*GRIN*)
	
    12/25/1996 -- Version 0.00 -- Merry Christmas!
    
        I've merged the main CPU code with the audio CPU code;
	speed is not regulated (correctly) and there are 
	no sprites right now,  but the game runs!
	
-E-O-F-
