DarkSpecter -- ZX Spectrum Emulator, v0.2.1 RC1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  I'M NOT NATIVE ENGLISH-SPEAKING CREATURE, SO MY ENGLISH IS AWFUL. I KNOW IT.
IF YOU CAN CORRECT THIS DOCUMENT, PLEASE DO IT & SEND ME THE NEW VERSION. I'LL
INCLUDE IT IN THE NEXT DSP RELEASE (WITH THE PROPER CREDITS %-).


-2. dedications
~~~~~~~~~~~~~~~
  DSP is dedicated to Enota.


-1. thanx
~~~~~~~~~
  to my parents for feeding me. %-)
  to Sir Klive Sinclair (of course!) for creating the best 8-bit machine ever.
  to Chris Cowley <ccowley@grok.co.uk> for vbSpec, from which DelphiSpec was
derived.
  to Jari Korhonen <jarit.korhonen@luukku.com> for DelphiSpec from which my
Z80 engine & AY engine was derived.
  to Philip Kendall <pak21-fuse@srcf.ucam.org> for FUSE
<http://fuse-emulator.sourceforge.net/> from which I took the test
package & learned some aspects of Speccy behavior.
  to SMT for UnrealSpeccy from which I took some code %-) (and just for coolest
emu!)
  to Christian Hackbart for Yase2 from which I took some code again %-)
(especially VG-93 emulator. Christian, how it works after all?!)
  to Random for "Russian Spectrum FAQ"
  to Philip Kendall (again) for maintaining the Speccy FAQ (althru i don't use
it while creating this version of DSP %-).
  to Martjin van der Heide for maintaining "The World Of Spectrum" archive
  to FonMax for testing and "add-this-cool-feature-you-asshole!" kicking %-)
  to Nils M. Holm for ArrowLISP
  to all others who keep the emulation scene alive


0. what is it?
~~~~~~~~~~~~~~
  this is ZX Spectrum emulator (isn't it obvious?) for all Speccy-addicted
creatures. this is not the best emu, but I hope to make it at least as good
as FUSE (somewhere in the distant future...) %-)
  you can use DSP in educational purposes (to learn how an emulator can be
created). but you'd better don't ask me any questions, 'cause i don't uderstand
how the code works (yes, i wrote it, but i still can't understand it!).

  i, myself, using DSP to play excellent Speccy games & read old Speccy
e-zines. and, you'll never believe it, but i still writing programs for
Speccy.
  Speccy is the best 8-bit machine of all times and it will never die!


1. features
~~~~~~~~~~~
  * unique control console -- the best feature of DSP! %-)
  * customizable emulation speed
  * full Z80 emulation (including undocumented instructions & flags). i still
    don't know if the timings & flags are ok. at least all programs i've
    tested works ok
  * ZX Spectrum 48K & 128K models, Pentagon 128K, Pentagon 512K
  * VG-93 emulation (works for the most programs) with TR-DOS acceleration
  * sound emulation (should be fixed in the future versions %-)
  * kempston joystick (via keyboard) & kempston mouse (via mouse %-) emulation
  * autofire feature
  * reading Lunter tapes (.tap files)
  * reading TZX tapes v1.10. this feature is not 100% tested, but it should
    work for most loaders
  * tape acceleration (DSP can automatically switch to maxspeed when the tape
    starts and fall back to the previous speed when the tape stops)
  * tape autostarting (DSP can automatically start the tape when ROM tape
    loading routine called)
  * "FastLoader (utm)" -- "instant" tape loader: loads Lunter tapes in no time %-)
  * DSP can pause emulation when the tape stops (so making snapshots of "taped"
    games is very easy!)
  * new snapshot format -- DZS (of course! %-)
  * new memory dump format -- DMB
  * loading .Z80 & .SNA snapshots (48k & 128k)
  * saving .Z80 v3 & .SNA snapshots (48k & 128k)
  * betadisk (TR-DOS) interface
  * loading .TRD (not necessary full-sized), .SCL & hobeta disk images
  * loaded hobetas will be added to the disk image
  * raw files (not hobetas) can be added to the disk image
  * save disk image in .SCL format
  * extract files from disk image (in hobeta format)
  * DSP can automatically add boot to a bootless disk images (and the size of
    the default boot is exactly 1 sector!)
  * boot can be added at any time by the console command
  * contended memory emulation (still doesn't work right %-( )
  * port #FF emulation (SideWize works w/o sprite blinking)
  * loading .scr files & saving screenshots in .scr format

  * zx & pc key bindings can be changed from dsp.script file or from the console
  * a lot of source code in many files

  * built-in debugger
  * built-in ALISP3 language and LISP API to hack games, write hoox, dumperz,
    etc...
  * built-in Z80 assembler which is useful to make small patches "on-the-fly"


2. keys
~~~~~~~
alt+space: call "system menu"
alt+shift+ctrl: show some t-states info

other:
  see *.script,*.s

debugger keys:
  g: "go to" -- hex addr
  z: "go to" -- dec addr
  t: change t-states counter
  f4: rebuild Speccy screen and show it
  f5: show current Speccy screen
  f7: do "single step"
  f8: execute 'till the address of the next instruction is reached.
  space: toggle breakpoint
  c: clear breakpoints
  l: load breakpoints from "dspdef.dbp"
  s: save breakpoints to "dspdef.dbp"
  esc: leave debugger

  Speccy screen is updating even if you tracing the program in the debugger
(so-called "exact mode"). but note that you'll see the results only when the
emulated CRT ray will render the whole screen!


3. todo
~~~~~~~
  * saving to Lunter/TZX tapes (does anybody need this?)
    heh, actually I need this %-) to complete some multipart adventures
  * loading .FDI, .UDI, .TD0 disk images (probably will never be done)
  * better checking of .TRD, .SCL & hobetas
  * full VG-93 emulation (the current is semi-shitty! %-( ) this will open the
    way to support various disk image formats (.FDI, .UDI, .TD0)
  * command timing info in the debugger
  * rewrite Z80 emulation engine from scratch to kill the alien code and
    to do exact timing (also to speed up the whole system). i plan to use
    some sort of "jit compiler" (i believe that JPP uses this kind of
    emulation engine).
    still don't know if it will be better then the current code...
