

				Emukon


Emukon is a Sega Master System and Game Gear emulator. It runs on win32 and
needs DirectX7+. It includes a nice GUI, a cool debugger and some video
filters. It runs most games flawlessly if your computer is fast enough
(200MHz+? Well, actually I don't know, my computer is fast enough anyway).
If anybody cares, it's written in C++ and uses DOZE, Marat6502 and ZLib 1.2.1.

 __________
/ Control /
==========
^                Speedup
^ + Shift        Slowdown
Escape           Hide/show GUI

Alt + l          Load ROM
Alt + x          Quit

F5               Load state
F6               Save state
F7               Pick state
F8               Screenshot
F9               Debugger
F11              Debugger: Step into

p                Hard pause
Backspace        Soft reset
Alt + Backspace  Hard reset

The keyboard keys and joypad/joystick buttons for playing can be configured
in the GUI. I recommend to play with joypads or joysticks, as it makes much
more fun than playing with a keyboard. Also, on some keyboards, there are
problems if you press too many keys at the same time. This is especially bad
if two persons play at the same time. But it's not my fault, it happens with
other programs, too.

 _______________________
/ Command line options /
=======================
-debug   Start Emukon with the debugger enabled

 ___________
/ Features /
===========
Accurate emulation
    Emukon is one of the most accurate Game Gear and Master System emulators.

Flicker-free user interface
    Emukon has a nice GUI. It's completly flicker-free, even without double or
    triple buffering. There can only be some tearing if VSync is off or if
    your system is too slow for VSync. It's just somewhat slow, but I'm
    working on optimizations.

Netplay
	Emukon has netplay support using Kaillera.

ZIP support
    You can load ROMs which are compressed in ZIP archives. Emukon scans
    ZIP archives until it finds a ROM file. The other files are just skipped,
    so you can also include other files in the archives.

VGM Logger
    VGM is a great sound logging format. It has support for lots of systems
    and sound chips, including Master System and Game Gear. You can find more
    informations about it on SMS Power: www.smspower.org/music.
    
    Emukon has a VGM logger with some nice trimming options:
    * Wait before sound starts:
        If this is enabled, the VGM logger will be in a wait-state
        until sound starts.
    * Trim loops automatically:
        This will try to trim a loops automatically.
        The loop must be logged more than one time.
        Please be careful with this, as it does not always work perfectly.
    * Trim end automatically:
        This will trim the end automatically, but only if no loop was found.

Movie Logger
    The movie logger can record and play back movies, which only contain the
    players' control data. You can also put little text messages into them.
    This is very useful for fixing bugs if you create your own game.

Video recorder
    The video recorder can record AVI video files. The sound is recorded
    at 44100 Hz, 16 Bit, stereo. While recording, you can't hear any sound,
    because it's rendered to the video. But if you've switched off the sound,
    it is still recorded.

Themes
    You can customize the look of Emukon and save it as .theme file in
    the Emukon\Themes directory. If you make any cool themes, please send
    them to me, so I can include them for others in future releases.

Video filters
    Emukon has some video filters for running games in higher resolutions
    and/or improving image quality. There are also stretching video modes
    for very high resolutions (good if you use a TFT monitor). The image
    is stretched using scaled hardware-blitting if available. If this makes
    the image too blurry for you, try combining it with the double-filter.

Debugger
    Emukon has a debugger with lots of functions. You can create labels,
    variables, breakpoints and comments for easier debugging. You can
    also load NO$GMB symbol files.

 __________
/ Patches /
==========
Patch files can be used to modify the contents of a ROM without modifying
the ROM file itself and for adding labels and other things for debugging.
They're normal text files containing simple commands.

The following commands are available:

ADDR <address>              sets the address for the following writing commands
WB <value>[, <value>, ...]  writes one ore more bytes
WW <value>[, <value>, ...]  writes one ore more words  (in little endian format)
WD <value>[, <value>, ...]  writes one ore more dwords (in little endian format)

Comment <address>, <text>  adds a comment
Label   <address>, <name>  adds a label
VarB    <address>, <name>  adds a byte variable
VarW    <address>, <name>  adds a word variable
VarD    <address>, <name>  adds a dword variable
BP      <address>          adds a break point

The ';'-character can be used to make comments at the end of a line. They are
not visible in the debugger (unlike the comments created by the Comment-command).

Here's an example of a little patch:
--
ADDR $70    ; go to address $70
WB 0, 0     ; write a 0 (NOP) two times
Comment $70, "Two NOPs"
--

At the beginning of a patch, the writing address is reset to 0.

<Load patch> will first delete all existing patch data (variables, breakpoints
and labels) and then reload it. <Add from patch> does the same, except that
the existing patch data isn't deleted. <Save patch> will save all patch data.
It will not destroy any selfmade ';'-comments in the patch file.

To add labels from a NO$GMB symbol file, it must have the name of the
current ROM file + ".sym" (ie. game.gg.sym, and not game.sym).
NO$GMB symbol files can be easily created by the WLA DX linker.

 ________
/ Notes /
========
- The background and window pictures must be in PNG format.
- Numbers in the variables, breakpoints and labels windows can be in
  decimal, hexadecimal ($ at the beginning) and binary (% at the beginning).
- The 'VRAM access wait' in the emulation configuration is only for
  developers who need to know if the VRAM access in their programs has
  correct timing. Writes and reads with incorrect timing are ignored
  and reported in the Messages-window every frame. Unfortunately this
  doens't work correctly sometimes, as some commercial games are reported
  to do incorrectly timed VRAM-accesses, although they work fine on a real
  system. This is probably because of non-perfect CPU/VDP timing. But still,
  if no incorrect accesses are reported, you can be (almost) sure that your
  VRAM-timing is OK.
- You can easily add and remove breakpoints in the debugger and labels window
  with the right mouse button.
- Emukon natively uses 16 bit video mode. You'll need a fast computer
  for 32 bit. Other modes are not supported.
- VSync doesn't work well. I'll later add triple buffering support to fix this.

 ______________________
/ Future enhancements /
======================
- More accurate emulation (new CPU cores, timing fixes, lightgun, BIOS, etc.)
- Support for more systems
- Support for more formats for backgrounds and window pictures
- Triple Buffering
- More video filters
- Better file requester keyboard control
- You tell me

 __________
/ Contact /
==========
The official Emukon homepage is at:
	http://emukon.kontechs.de

Also don't forget to visit the GGT homepage:
	http://www.smspower.org/ggt

My eMail-address is:
	mkon@gmx.de

I understand German and English.
Bug reports and suggestions are very welcome.
There is a form.txt which you can fill out and send to me.

 __________
/ Credits /
==========
I would like to thank the following people:

Zoop/Bock
	for being one of the coolest guys around. He made the legendary MEKA,
	SMS Power and a lot of other cool stuff I can't remember...

Dave
	for DOZE, a great Z80 CPU core, which is used by Emukon.
	He wrote DEGA, a SMS/GG emulator and FinalBurn, an arcade emulator.
	He is also one of the founders of the VGM format.

Charles Mac Donald
	for his famous VDP documentation, which already helped a lot of people.
	He wrote some great SMS and GG demos and he also helped a lot with GGT
	and tested it on real hardware.

Maxim
	for his great work on SMS related stuff.
	He made an excellent PSG documentation, based on his studies with
	a real PSG chip. He's the author of the VGM tool, the VGM plugin for
	WinAMP and the incredibly cool VGM player for the SMS. He even wrote
	some very cool SMS demos and gave me great suggestions for Emukon.

Eric Quinn
	for founding and maintaining the SDSC, which was one of the best
	ideas ever. He made MesaDX, a SMS emulator for developers.

Ville Helin
	for WLA DX, which is by far the best assembler I know.
	He's a very speedy guy. If you suggest a new feature or bug fix for
	WLA DX, you'll usually get it in a day or even less.

Andreas Kai and Robert Konrad
	for their great betatesting and nice ideas.
	They helped me a lot with both Emukon and GGT.
	Robert is the webmaster of Turrican Forever, the best Turrican site ever:
	http://turrican.emucamp.com
	
fx^
	for #smspower on efnet and nice chats.
	http://efnetsmspower.mine.nu

Whitesnake
	for being one of the coolest guys around and for very nice chats.

Tet
	for his cool pictures and graphics, nice chats and support.

John C. a.k.a Bongo
	for very nice suggestions for the debugger.
	He invented the debugger logging feature.

MarcK
	for the SMS picture on the homepage and support.

A few other people who suggested nice features or helped fixing bugs.

Please let me know if I forgot anyone.

 __________
/ Changes /
==========
[V1.05]
        - Renamed eSMS to Emukon
        - -debug command line option
        - right click into label window to add or remove a breakpoint
        - Added File->Reload ROM
        - in windowed video mode, the mouse can now be moved out of the window
        - brighter palette
        - sms soft pause button is now mapped to the gg start button,
          the p-key is always hard-pause, no more alt+p
        - added multiple screenshots options
        - added frameskipping options
        - resizeable file requesters
        - added netplay via Kaillera (still experimental)
        - fixed Code Masters mapper emulation
        - bug fixes
[V1.04]
        - added stretching video modes
        - GUI configuration (theme) can be loaded and saved
        - added seperate background configuration with and without GUI
        - changed the debugger
        - VRAM is viewable in the memory viewer again
        - fixed non-USB joypad/joystick
        - switched to the new ZLib 1.2.1
        - a few little fixes/improvements
[V1.03]
        - SDL isn't used anymore
        - graphics, sound and GUI system changes
        - joypad/joystick buttons now have to be configured
        - added window background picture
        - added 32 bpp and windowed video mode
        - added filerequester keyboard control
        - added NO$GMB symbol file support
        - improved the debugger
        - added debugger label support
        - changed debugger logging
        - added AVI video recorder
        - added sound options
        - added movie logger messaging
        - improved the tiles, tilemap and memory viewers
        - improved the VGM logger, auto loop trimming is much better
        - bug fixes and improvements (again)
[V1.01]
        - Screenshots, VGMs etc. will be saved in subdirectories of the emulator
        - Changed sound output (maybe better, but slower)
        - The Background picture can be in more formats
        - Screenshots are saved in .PNG format
        - added a VGM player (for people who don't want/can't install WinAmp)
        - improved the VGM logger
        - added debugger logging
        - motion blur can be selected for both GUI and fullscreen
        - added gradient colours to the GUI
        - added configurable keyboard input
        - added some mouse wheel support
        - some little bug fixes and improvements
[V1.0]
        - First public release
