                            ColEm MS-DOS 0.4.1
              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
CWSDPMI.ZIP   A DPMI Server required by COLEMDOS.EXE
COL2MID.EXE   A program to convert Coleco soundtrack files to standard
              MIDI files
KEYS.EXE      Small utility to alter the key mappings
CMENU19.ZIP   A ColEmDos front end by Andrew Bond
More utilities for use with ColEm MS-DOS can be found on the ColEm MS-DOS
Distribution Site at http://www.komkon.org/~dekogel/colem.html

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.

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
-uperiod          Select number of interrupts per screen update. This
                  option only has effect if it is used in combination
                  with "-ifreq 0"
-video            Set video mode
-overscan         Select overscan colour support
-sound            Set sound mode
-speakerchannels  Set sound channel priority list (Internal speaker
                  only)
                  1-3 = Melodic
                  4   = Noise
                  Most games use channel 3 for their sound effects and
                  channels 1 and 2 for their melodies. Try using "-
                  speakerchannels 3,1,2" if the default list doesn't
                  give the desired sound quality
-reverb           Set reverb send level (SB AWE32 only)
-chorus           Set chorus send level (SB AWE32 only)
-soundquality     Set sound quality (SoundBlaster only)
-soundtrack       Select soundtrack file
-volume           Set initial volume
-joystick         Set joystick mode
-mouse            Set mouse mode
-sensitivity      Set mouse/joystick sensitivity
-swapbuttons      Select which buttons to swap
-calibrate        Force joystick calibration
-keys             Alter key mappings
-shots            Set screen shot mode
-expansion        Set expansion module emulation
All command line options can be abbreviated. Use the -help option to get a
list of supported abbreviations.

Default key mappings:
---------------------
Cursor keys   Joystick movement
Alt           Primary firing button
Ctrl          Secondary firing button
Left Shift    Third firing button (port 1)
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
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 0x100 for 1.00)
byte           Interrupt frequency in hertz
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.4.1   Fixed some bugs in the VDP emulation, slightly improved
        SoundBlaster support
0.3.2   Added PC Speaker support, improved SoundBlaster support, fixed a
        few bugs
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

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 you're using a
  SoundBlaster, try decreasing the soundquality or using Adlib mode
- 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.

