*******************************************************************************
*******************************************************************************
*********************     N  U  C  L  E  A  R     Z  X    *********************
*******************************************************************************
*********************   Z  X     S  p  e  c  t  r  u  m   *********************
*********************         E  M  U  L  A  T  O  R      *********************
*********************                v 3.69               *********************
*******************************************************************************
************************************* by Radovan Garabik & Lubomir Salanci ****
*******************************************************************************

Introduction:

This emulator emulates the Sinclair ZX Spectrum 48K on your IBM PC.
I have also written a 128K emulator, but it is still in (stopped) developing 
and has too many bugs, and I'd rather not put this into the public.
There are also some bugs in the 48K emulator, especially in/when emulating
the R register and undocumented instructions, but almost all of the 
games run.
Programs using non-standard loaders are also suported.
Tapes are emulated using .LTP files, acting like virtual tapes.
The emulator also reconizes .TAP and .SNA files, there is no need to
convert them into .LTP and .SNP files.

This emulator is for free, you can give it to anybody you want
(in fact, you are encouraged to do so), provided that you do not 
change or delete anything in this package (you can add a translation
of this file in your local language), and you may also not charge 
anything for this program. 

As I said, this program is for free, but I surely will not object 
if you send me some money :-). (How much do you think is this program
worth? I would say, equivalent of $8 is more than enough).
If you do so, you'll become a registered user and get the newest
version (and you'll always get the new version, when there is one 
released, if you have e-mail), some games I downloaded from 
Spectrum (if you want), and sources. 
It would really encourage me in making new versions.


The other way how to get sources is to ask for them. I do
not charge anything, but the sources are not for free. If you
want them, you can get them if you write me a tender poem about
Sinclair ZX Spectrum [you can write the poem in any language you
want, but preferred languages are (in descending order): English,
ZX Basic, Slovak & Czech, Russian, Esperanto, Polish, and German]. 
And if you do some non-neglidgible improvement with the emulator,
you owe me a copy of that. If you want the sources to be
sent by snailmail, send me enough money to cover postage and a prise of 
one 3.5" diskette (or send me that diskette). No money is necessary,
if you want me to send them via e-mail.

How to contact me:

My address is:  Radovan Garabik
                951 48 Jarok 568
                Slovakia

My e-mail is: garabik@center.fmph.uniba.sk
or:           garabik@teller.dnp.fmph.uniba.sk

I'll answer any questions concerning the emulator sent via e-mail (though
the answer will not be necessarily correct :-)).
Both these e-mail addresses should hopefully work at least until the year 2000.
After that I'll have to look for some other account :-(

Questions concerning VGA graphics, menus or non-standart loading
address to:
salanci@center.fmph.uniba.sk

The version before the latest one can be found at:
 http://www.fmph.uniba.sk/~garabik/zx.html  (then follow the link)
The latest version is reserved for registered users.


Contens of this package:

zx.bat          - simple batch running the emulator
nuclear.exe     - the emulator itself
zx.ovl          - overlay
readme.txt      - this file
zx.rom          - ZX ROM file
transfer.ltp    - tape file, with mrs 64 (assembler & debugger) and
                  ZX program transfering data from Sinclair to IBM PC
zx2pc.pas       - PC program transfering data from Sinclair to IBM PC
nuclear.ltp     - tape file, consisting of a few games
zxcat.exe       - program displaying contents of *.ltp files
sna2snp.exe     - converter converting from *.sna files to *.snp files
tap2ltp.exe     - converter converting TAP files into *.ltp files
ltp2tap.exe     - converter converting *.ltp files into TAP files
snp2z80.exe     - converter converting *.snp files into *.z80 files
                  (written by Philip Kendall)

This program will run fine on a 286 AT (the slowest computer I tried
it on was a 286, 8 MHz, CGA card - with attributes switched off many
games were quite playable). I have reports that it runs successfully 
on 10 MHz XT with reasonable speed, but I have not seen it. 
Supported graphics cards are: CGA, Hercules, VGA. (EGA only
in CGA mode - sorry).

Emulator runs on these platforms:

MSDOS and clones (PCDOS, DRDOS...)
MS Windows 3.1 - runs without any problems, only VGA graphics works only
                 in full screen mode and the sound is distorted
MS Windows 95  - runs without any problems, only VGA graphics works only
                 in full screen mode and the sound is distorted
OS/2           - I have not tested it
DOSEMU under Linux - runs, but you have to switch keyboard into raw mode
                     and the sound is distorted. Some keys (e.g. arrows)
                     sometimes crash the computer. I have not pursuaded the
                     problem further, if there is enough interest, I will
                     look at it.
                     (tested under DOSEMU v66.6)

*******************************************************************************

New features from version 3.68:
 - added Cursor keys feature
 - emulator has now it's name: Nuclear ZX (don't ask me why :-))

*******************************************************************************

A concise description of the Nuclear ZX Emulator:


Function keys:

F1-display keyboard layout

F2-"rewind tape", i.e. the next LOAD will
    read from the beginning of the load-file

F3-unsnap from file

F4-PLAY/STOP: when the program uses a non-standard loader (e.g. WESTBANK
    or HIGHWAY ENCOUNTER), press it after (or even better, before)
    entering LOAD "". (And you should press it again after the program
    has loaded)

F5-debugger. For more info, press F1 while debugging.
   Warning: it is possible to edit the ROM with debugger.

F6-turn sound off/on

F7-save the contents of RAM and registers to the disk (snapshot)
   Backup copy of previous snap file is created.

F8-restore memory and registers previously saved by F7 (unsnap)

These two keys are very handy when playing games. Just set the snap
and unsnap files to be the same, and each time you make some progress
in the game, just press F7. If you get killed, press F8 and you 
go again... And if you accidentaly press F7 when just killed,
there is a backup copy (the same name, but extension .bak) of the
previous snapshot.


F12-ZX RESET


ScrollLock - set slowing ON (see below)

Del (PC keypad) - autofire (Kempston emulation only)

F10-set the emulator's parameters and  other options:

 Tape Screen Options Keypad Printer Sound Quit
*************************************************************************
Tape - tape-emulation options
 Load file - file which emulates the tape (for LOAD) (*.ltp or TAP file format)
             If you want to choose from TAP files, just enter *.tap as filename
 Save file - file which emulates the tape (for SAVE) (*.ltp or TAP)
 Snap file - file, when the snapshot is saved by F7 (*.snp file format)
 Unsnap file  - snapshot file, where memory is loaded from (*.snp or *.sna
                                                             file format)
 Sentimental - when ON, you have the feel of a true
               Sinclair loading (try it). See
               PLAYING/STOPPED (14 lines below)
               for more instructions.
 Snap! - save snapshot on the disk 
         [the same as F7]
 UnSnap! - restore snapshot previously saved by F7
           [the same as F8]
 Dos shell 1 - invoke MSDOS prompt.
            To return to the menu, type EXIT.
 Dos shell 2 - the same as previous command, but
          this one creates a swap file on disk, thus
          leaving you a little more memory for
          your DOS session.
  PLAYING/STOPPED - By setting this option to PLAYING
   you turn the loading emulation to load data
   bit-after-bit. This makes it possible to load
   programs using non-standard loader.
   When loading such a program, first type LOAD "",
   then {call up menu (F10),turn this option to PLAYING,
   escape from menu} or {press F4},
   wait until program loads and then you should turn
   it to STOPPED (or press F4 again) so that the emulator does not
   continue loading bits, which could cause troubles 
   when you want to load another program.
   When Sentimental is ON, you must follow this procedure
   when loading any program.
  Encycled tape - when ON, the tape automatically rewinds
  after reaching the end.
---------------------------------------------------------

Screen - set the screen type. It is better to use a screen
         type without attributes on slow computers (286).

---------------------------------------------------------

Options - different options:
  Slowing delay - set slowing.
            (higher value means slower).
            It is useful when you are running this emulator
            on a fast PC and are not able
            to follow games. Works only when the
            following option is ON:
  Slowing - whether the emulator is slowed or not  (this can 
            be also switched by pressing Scroll lock in emulation mode)
  Beep - ZX - perform BEEP using the original
              ROM-routine.
         PC - perform BEEP using the PC-timer,
              this way produces sound with (almost) exactly
              the same length and frequency as on
              the original Spectrum [but during
              BEEPing the emulator will not react
              to any key (except the RESET switch :))].
  POKE - Replace the address with a given value.
         Particularly suitable when playing games,
         if you know the POKE.
         (this also allows you to change values in the ZX ROM)
  Key interrupt - If it is on, interrupts will be
                  generated each time a key is
                  pressed, therefore a keyboard
                  will react better, but in some
                  games it may cause problems (on slower
                  computers).
                  Turn it on if you want to write texts.
  Interrupt freq - Enter here interrupt frequency.
             Original Sinclairs use interrupt 50 times per
             second (50 Hz).
             On slower computers some games do not work properly
             and then it is better to enter a lower number.
                   (e.g. TRANTOR or ZYNAPS -
                    on a 12 MHz 286 it was necessary
                    to set the frequency less than 8 Hz.,
                    on a 40 MHz 386 nothing was necessary)
  EAR bit - if you want to play games which require ISSUE 2,
            turn it to 1. Otherwise it should not matter.
  BORDER (VGA) - If you turn it ON, BORDER will be emulated.
                 It only works in VGA-video modes.
  ZX RESET - resets the emulator (the same as F12)
  Flushing keyb - when ON, each time you choose some
    DOS-using action (e.g. loading, menu or snapping)
    it releases all the keys (if you hold a key,
    then choose menu and then release the key,
    the emulator would not recognize it and
    it could cause some troubles).
  Refresh - on fast computers it is better to select this
    option, then the screen is periodically
    redisplayed (otherwise the bytes put into the screen
    would be displayed immediately). Useful particularly
    when using programs which write into videoram very often.
    The music will sound somewhat harsh, though.
  Refresh delay - how often the screen will be redisplayed. Set to
                  2 or 1 if your computer is fast enough.
  True R reg - The R-register should be correctly emulated,
               only if this is ON, but it slows down emulation.
               (it does not work quite correctly yet)
  True interrupt - when ON, interrupt is perfomed as close to
                   the original as possible (again, this feature
                   is not fully developed). Use carefully.
               
----------------------------------------------------------------

Keypad - indicates how the numeric keypad will be
         interpreted (what joystick it emulates)
         If you set Cursor keys off, joystick will be emulated
         by cursor keys (fire=ctrl), too, otherwise cursor keys will
         emulate Sinclair cursor keys

----------------------------------------------------------------

Printer - emulate ZX Printer on a printer compatible
          with IBM Graphics Printer or Epson FX 80
  Printer emulation - if on, the printer is emulated.
  Output file - output file
                (PRN=printer)
  Left margin - left margin (in chars)
  Copy - copy screen (without attributes)
  Full copy & attr - copy screen, attributes will be replaced
                     by different patterns.
  Inverse - if 1, printing is inverse (white on black)
---------------------------------------------------------------

Sound - Sound options
  Sound ON/OFF - I think this is clear enough.
  PC Speaker - internal speaker will be used.
  COVOX - COVOX (= Disney Sound Source) will be used.
  COVOX Port - This is the address of the port COVOX is
               connected to. Default it is set to LPT1.
---------------------------------------------------------------

Quit - quits the program.

*************************************************************************

As a parameter of nuclear.exe use the load-file name or unsnap-file name
(i.e. LTP, .TAP, .SNA, or .SNP files can be used)
(e.g. nuclear.exe GAMES1.TAP).
If omitted, ZX.LTP is used.

Other parameters:
nuclear.exe /scr:x  use screen mode No.x
nuclear.exe /snd- start with sound disabled
nuclear.exe /snt+ start in Sentimental mode
nuclear.exe /rom:myrom.rom   use the file "myrom.rom" as ZX ROM (default zx.rom)
                        If the file is longer than 16384 Byte, it will load,
                        but only lower 16KB will be write-protected
nuclear.exe /cov:1   use COVOX rather than internal PC speaker
nuclear.exe /slw:n   set slowing delay to n
nuclear.exe /kpd:n   set joystick emulated by the keypad:
                 1 - Cursor joystick
                 2 - Sinclair #1 joystick
                 3 - Sinclair #2 joystick
                 4 - Kempston joystick
                 5 - Numbers
nuclear.exe /crs+    Cursor keys emulate Sinclair cursor keys
nuclear.exe /crs-    Cursor keys emulate joystick, CTRL emulates fire
nuclear.exe /h  display possible start-up parameters

If running on Hercules or CGA graphics cards, use appropriate start-up
screen mode (e.g. zx /scr:3 for CGA and zx /scr:8 for Hercules)

Program ZXCAT.EXE displays the contens
of load-files.
As a parameter use the load-file name.

*******************************************************************************

How to transfer programs from ZX tapes into *.ltp files


I used a Sinclair ZX Spectrum with parallel ports (it was actually
a clone of Sinclair, but was valid for an original Sinclair with similar
interface, e.g. Interface 1), which had 3 parallel I/O port. I connected
this to a PC's printer port:

           ZX:                         PC:                 meaning:

    port 63 7th bit   <----   LPT1 output (any bit)       ready for data

    port 31 1st bit   ---->   LPT1 input 7th bit (BUSY)   data

    port 31 0th bit   ---->   LPT1 input 5th bit          sending data
                              (OUT OF PAPER)              

    GND               -----   GND                         ground
   

You can use other ports, but you must change the program zx2pc.pas
and its sinclair counterpart accordingly.

Converting software:
PC:  zx2pc.pas
ZX:
  1) choose the tape file "transfer.ltp" e.g. type "zx.bat transfer.ltp" from
     MSDOS command line or choose "Load tape" in menu
  2) type LOAD ""
     mrs 64 will load (very good assembler & debugger indeed)
  3) type edi
  4) type loa
  5) type ln=1

   and you'll see the Sinclair program
   All you have to do is to rewrite it on you original Sinclair into your 
   favourite assembler and compile.
   The starting address is 65531.

   The alternative is to type in the following program:

 10 CLEAR 40000
 20 FOR i=65447 TO 65535
 30 READ a
 40 POKE i,a
 50 RANDOMIZE USR 65531
100 DATA 166,191,55, 63, 237,82, 34, 0,  64, 35, 35, 84, 93, 33, 0,  64
110 DATA 78, 6,  8,  175,211,31, 219,63, 230,128,40, 250,203,17, 23, 55
120 DATA 63, 23, 211,31, 246,1,  211,31, 219,63, 230,128,32, 250,175,211
130 DATA 31, 16, 224,27, 35, 122,179,32, 215,24, 181,0,  0,  62, 130,211
140 DATA 127,175,211,31, 49, 254,255,24, 167
                                                                          
                                                                          


   When run, the program reads the tape 
   played to the Sinclair and after each block of data it transfers this data
   to a PC (this will take only a few seconds). Sometimes it's necessary
   to pause the tape recorder between a long block and the next one, when there 
   is too small a gap. The PC program generates a *.ltp file ready for the 
   emulator.
   Run the PC program first, then run the Sinclair program.

 The three bad things about this are:
 1) This method required a PC and a Sinclair with interface.
 2) It is impossible to transfer programs saved in turbo mode.
 3) It can transfer blocks max. 49062 bytes long [ this problem could be 
    solved by writting a special loader, rewritting part of the screen memory
    when the loading length exceeds free memory (it's quite easy), or by 
    on-line compression when loading - I've seen such a program ! (TFCOPY) ]


*******************************************************************************

Description of *.ltp file:
--------------------------
first block:

  2 bytes - length of the data block without flag-byte and without
            checksum byte
  1 byte - flag byte (00 for header, FF for data) ---
  data                                        |- as at the original ZX tape
  1 byte - checksum                               --- 

next block... 
--------------------------------
As you see, it is almost the same as the TAP format, except for the first two
bytes containing the length, which is 2 bytes shorter. 
Why didn't I use TAP format? Well, I started to write this emulator 
before I ever heard of TAP...

Use the tap2ltp.exe and ltp2tap.exe for converting.


The program for converting *.sna files into *.snp files
is called sna2snp.exe and works reasonably well.
It is a little more difficult the other way, because 
of a bit weird SNA format. 


Description of *.snp file:
0000-bfff   48KB of ZX memory
c000-c001   AF
c002        BORDER colour
c003        reserved
c004-c005   BC
c006-c007   DE
c008-c009   HL
c00a-c00b   PC
c00c-c00d   SP
c00e-c00f   IX
c010-c011   IY
c012        reserved (IFF2 intended, but not implemented)
c013        interrupt: 00-disabled, other-enabled
c014        interrupt mode: 0,1 or 2
c015        R
c016        I
c017-c018   AF'
c019-c01a   BC'
c01b-c01c   DE'
c01d-c01e   HL'

*******************************************************************************
