                            ColEm MS-DOS 0.3.1a
              ColecoVision emulator for the MS-DOS platform.
          Core emulator code copyright (C) 1996  Marat Fayzullin
              MS-DOS port copyright (C) 1996  Marcel de Kogel
                                     
                 ColecoVision(tm) is a trademark of Coleco
               MS-DOS(tm) is a trademark of Microsoft Corp.

The latest version of ColEm can always be found at
http://www.freeflight.com/fms/ColEm.
Another Coleco-related archive is located at
ftp://altair.komkon.com/pub/Coleco/

ColEm is a non-profit emulator created for those individuals who were and
still are fans of the Coleco gaming era and who wish to play their
ColecoVision games on today's operating systems. The program was almost
completely written in portable C, and is therefore a bit slow. Please do
not send any mail concerning the speed of ColEm.

No cartridge ROM images are included with ColEm due to the fact that most
of the ColecoVision games are still in copyright by their respective
holders. Also, Marat Fayzullin nor Marcel de Kogel WILL NOT be held
responsible for acts of copyright violation.

Note: ColEm for MS-DOS requires the presence of a DPMI server. If you
don't run the program under a DPMI-hosted environment, put the file
CSDPMI.EXE included in CWSDPMI.ZIP somewhere in your path.

Files included in COLEMDOS.ZIP
------------------------------
COLEMDOS.EXE  The emulator
COLEMDOS.TXT  This file
COLECO.ROM    A dump of the ColecoVision's ROM. This has to be resident
              in the emulator's directory
COL2MID.EXE   A program to convert Coleco soundtrack files to standard
              MIDI files
CMENU14.ZIP   A ColEmDos front end by Andrew Bond
CWSDPMI.ZIP   A DPMI Server required by COLEMDOS.EXE

System requirements
-------------------
A 486DX-33 or better
A VLB- or PCI-based VGA video card
An enhanced keyboard (101 or 102 keys)
MS-DOS version 3.0 or higher
A 486DX2-66 with an adlib compatible sound card and a joystick is
recommended. Make sure your joystick is centred when you start the
emulator.
Note: You may be able to run the emulator with a lesser system by messing
with the parameters a bit. Instructions are in the troubleshooting
section.

List of games not running correctly with the emulator
-----------------------------------------------------
Fathom         Crash after selecting a level
Bump `n Jump
Pitstop        Display gets garbled after playing for a while
Buck Rodgers   Crashes after playing a few levels
Of course, there probably are more

Command line options:
---------------------
-help          Show a help screen describing all available options. Use
               this to get more detailed information
-verbose       Set verbose level
-romfile       Select Coleco ROM dump file
-cpuspeed      Set Z80 cpu speed. Default is 100% for a 3.58MHz CPU
-ifreq         Set interrupt frequency. Most games need 50Hz or 60Hz.
               The default is 50Hz. Select 0 to disable sync
-video         Set video mode
-overscan      Select overscan colour support
-sound         Set sound mode
-soundtrack    Select soundtrack file
-volume        Set initial volume. Only works on SBPro and SB16
               compatible cards
-joystick      Set joystick mode
-mouse         Set mouse mode
-sensitivity   Set mouse/joystick sensitivity
-swapbuttons   Select which buttons to swap
-shots         Set screen shot mode
-expansion     Set expansion module emulation
-calibrate     Force joystick calibration
All command line options can be abbreviated. Use the -help option to get a
list of supported abbreviations.

Keys functions:
---------------
Cursor keys    Joystick movement
Alt            Primary firing button
Ctrl           Secondary firing button
Shift          Third firing button (port 1)
CapsLock/Z     Fourth firing button (port 1)
NumPad -       Third firing button (port 2)
NumPad +       Fourth firing button (port 2)
0-9,-,=        Numpad 1
0-9,Del,Enter  Numpad 2
(right)
F1-F4          Toggle sound channel 1-4 on/off
F5             Toggle sound on/off
F8             Pause & Blank screen
F9             Pause
F11            Decrease volume. Volume control only works on SBPro and
               SB16 compatible cards
F12            Increase volume.
Insert         Switch to joystick mode 1
Home           Switch to joystick mode 2
PageUp         Switch to joystick mode 3
Delete         Swap joystick buttons. Only buttons 1 and 2 are swapped
End            Swap keyboard buttons. Only buttons 1 and 2 are swapped
PageDown       Swap mouse buttons
Space          Take screen shot
Esc            Quit to DOS

About the sound support
-----------------------
The emulator uses the BLASTER environment variable to 'detect' the
presence of a Sound Blaster. Some older Sound Blaster cards are not
supported. Make sure your BLASTER setting is right or you may crash your
system when running the emulator. The syntax of the BLASTER environment
variable is: BLASTER=Aaaa Ii Dd Hh Tt Eeee, where aaa is the port address
(default=220), i is the interrupt used (default=7 or 5, depending on the
model you have), d is the DMA channel used (default=1), h is the high DMA
channel used (SB16/AWE32 only, default=5), t is the model type (4=SB Pro,
5=SB16, 6=AWE32) and eee is the EMU baseport (AWE32 only, default=620).
All other settings are ignored.
If you have a GUS compatible sound card, make sure your ULTRASND
environment variable is set correctly. It's syntax is:
ULTRASND=Port,DMA,Record DMA,IRQ,MIDI IRQ. Only the Port parameter is used
by ColEmDos.

About the joystick modes
------------------------
The emulator reflects both the keyboard and the joystick to both ports 1
and 2. If you're running a game requiring two separate joysticks (e.g.
Smurf Paint&Play Workshop), use -joystick 2 or -joystick 3 or press the
Home or PageUp key during gameplay to switch to mode 2 or 3.

About the mouse support
-----------------------
ColEmDos allows you to emulate a Coleco joystick with a mouse. Mouse
control is poor for most games and can slow the emulation down, so you may
want to turn it off. If you leave it on, mouse movement will be reflected
to both joystick ports.

About the sensitivity settings
------------------------------
You can adjust the joystick and mouse sensitivity by using the -
sensitivity command line option. Useful values are between 150 and 400.
Altering the sensitivity has no effect on joystick control when the
joystick isn't used to emulate an expansion module.

About the screen shots
----------------------
A screen shot taken will have the filename CART.XXX where cart is the name
of the cart loaded (e.g. DKONG), and XXX will the number of screen shots
taken so far (e.g. 002). The screen shots will be in uncompressed windows
bitmap format, 256x192 with 16 colours and will have file sizes of 49.270
bytes.

About the expansion module emulation
------------------------------------
ColEmDos can emulate a roller controller, a driving module expansion and a
super action controller speed roller. If you want to run a game that
requires one of these, you'll have to use the -expansion command line
option. Below is a list of available emulation modes.
-expansion 0   Do not emulate expansion modules
-expansion 1   Emulate a roller controller with the mouse. Use your
               mouse buttons to press one of the first two roller
               controller buttons, use the ctrl and alt keys to press
               one of the second roller controller buttons
-expansion 2   Emulate a roller controller with an analogue joystick.
-expansion 3   Emulate a driving module with an analogue joystick. Move
               your joystick forward to press the accelerator pedal,
               move your joystick to left or to the right to move the
               steering wheel, use the cursor keys or the joystick
               buttons to move the control stick
-expansion 4   Emulate a driving module with a mouse. Press a mouse
               button to press the accelerator pedal, use the cursor
               keys to move the control stick
-expansion 5   Emulate a super controller speed roller on both ports
               with a mouse. The third and fourth firing buttons of the
               super action controllers are always emulated.
-expansion 6   Emulate a speed roller on port 1 with a mouse
-expansion 7   Emulate a speed roller on port 2 with a mouse

About the analogue joystick support
-----------------------------------
When using the -expansion 2 or -expansion 3 options for the first time,
the emulator will ask you to calibrate your joystick. It will then save
the gathered information in the file COLEMDOS.JOY in the emulator's
directory. When you use one of these option again, the emulator will load
the joystick information from this file instead of asking you to calibrate
your joystick again. You can force a re-calibration by either deleting
this file or by using the -calibrate 1 command line option.

Soundtrack file format
----------------------
The soundtrack file format is as follows:
Header:
string         `Coleco Sound File',0x1A
word           Version number (LSB first, currently 1.00)
byte           Interrupt frequency
Data:
0xFF           Single interrupt mark
0xFE <n(byte)> Interrupt mark
0xFD <n(word)> Interrupt mark (LSB first)
0x00-0x7F      Sound register write. High nibble is the register number,
               low nibble is the register value
               Registers 0,2 and 4 are 12 bits wide (lower 8 bits are in
               second byte), all others are 4 bits wide
Example: 13 FF 20 04 56 FD 05 01 45 06
          ^--------------------------- Write 3 to register 1
             ^------------------------ Interrupt
                ^--------------------- Write 004 to register 2
                      ^--------------- Write 6 to register 5
                         ^------------ 261 Interrupts
                                  ^--- Write 506 to register 4

Configuration files
-------------------
The emulator loads two configuration files (if present) before it loads a
cartridge rom: ColEmDos.cfg located in the emulator's directory and
CART.cfg (e.g. DKONG.cfg) located in the cartridge dump's directory. These
are plain text files containing optional command line options. Options can
be separated with spaces, tabs or returns.

History
-------
0.3.1a         Removed printing of debugging messages
0.3.1          Fixed a bug in expansion mode 4 and several bugs in the
               CPU emulation
0.2.7          Fixed a major bug in the SBPro driver, added SB2.0 and
               GUS support, improved SB16 and AWE32 sound, added mouse
               support and some general options, fixed some bugs in the
               emulation code
0.2.6          Added AWE32 support and improved SBPro/SB16 sound, added
               soundtrack logging option
0.2.5          Added super action controller emulation, added volume
               control, added overscan colour control, improved sound
0.2.4          Added roller controller and driving module emulation,
               fixed some bugs
0.2.3          Added OPL3 and Sound Blaster Pro support, added
               configuration file support, set default extension to
               ".rom", changed command line options, added separate
               joystick support
0.2.2          Fixed even more bugs, added screen shot option, increased
               speed
0.2.1          Fixed some more bugs, added automatic sync, better sound
               support and changed some command line options
0.1.2          Fixed a lot of bugs, added the full screen option and
               better sync, increased speed
0.1.1          Initial release

Plans for the future
--------------------
- Fix more bugs
- Add support for the ADAM `super' games (anyone got some detailed info
  ?)

Troubleshooting
---------------
- If a game runs a bit too slow, try using -ifreq 60.
- If the emulator runs all games much too slow, try decreasing cpuspeed
  to 60-70. You may also want to try -ifreq 0.
- If a game runs too fast, decrease cpuspeed to 20-40. You may also want
  to try decreasing ifreq.
- If the emulator crashes before showing the level select screen, try -
  ifreq 0. You'll probably need to increase cpuspeed when doing so.
  Various other problems may be solved by doing this as well, especially
  if you use a slow computer. One user reported he was not able to start
  windows after running the emulator without the -ifreq 0 parameter. You
  may also want to try -sound 1.
- If the emulator just exits to DOS, use -verbose 1 to find out what's
  wrong.
- If a game crashes, try increasing cpuspeed to 120-150. This is known
  to work for Bump&Jump, Pitstop and Buck Rodgers.
- If you want your games to run faster, increase ifreq. If you want them
  to run slower, decrease ifreq.

Credits
- ColEmDos was compiled using DJ Delorie's DJGPP v2.0. DJGPP is a 32 bit
  C compiler for MS-DOS. Source code and binaries of DJGPP are available
  at http://www.delorie.com.
- The SB AWE32 routines are heavily based on `The Unofficial Sound
  Blaster AWE32 Programming Guide' written by Vince Vu a.k.a. Judge
  Dredd. Thanks a million for writing this!
- Martijn Zeedijk tested the GUS routines and helped me fix lots of bugs
- Some parts of the code were taken from Allegro. Allegro is a library
  for DJGPP written by Shawn Hargreaves. Allegro is available at
  ftp://x2ftp.oulu.fi/pub/msdos/programming/djgpp2.

Thanks go to ...
----------------
Coleco
Marat Fayzullin
Martijn Zeedijk
Andrew Bond
Vince Vu
Neal Danner
Shawn Hargreaves
DJ Delorie and all others having contributed to DJGPP
...And all people who helped me with information, bug reports and
encouragement

Please send your comments to Marcel at
m.dekogel@student.utwente.nl.

