ColEm
version 5.2

by Marat Fayzullin

New in This Version
Introduction
Buttons
Command Line Options
Frequently Asked Questions
History
Thanks to...

New in This Version

Reorganized built-in configuration menu.
Added built-in menu options for saving printer and MIDI outputs.
Added built-in menu for hardware model and options.
Added built-in menu for Adam disks and tapes.
Fixed built-in menu palette selection.
Added "File | Clear Settings and Quit" option to ColEm-Windows.
Fixed small windows behavior in ColEm-Windows.
Fixed window position behavior in ColEm-Windows.
Saving physical joystick/gamepad selection in ColEm-Windows.
The LoadFile() function will now try loading .STA files.

Introduction

ColEm is a portable emulator of the old ColecoVision videogame console and Coleco Adam personal computer. It should run most ColecoVision games and supports Coleco's SuperAction controllers with spin wheels. You can always get the latest ColEm binaries, source code, and support files from

http://fms.komkon.org/ColEm/

There are versions of ColEm for many platforms. Windows and Unix ports are available for free from the above website. MSDOS, Symbian, Maemo, and Meego ports have been discontinued due to the death of their respective platforms. The Android port can be downloaded from the Google Play:

https://play.google.com/store/apps/details?id=com.fms.colem.deluxe (full version)

https://play.google.com/store/apps/details?id=com.fms.colem (free version)

ColEm is written in portable C and thus can be ported to any sufficiently fast computing platform. The current ColEm source code distribution includes portable core sources and platform-specific sources for Unix, Windows, and MSDOS.

If you would like to port ColEm to another system or make changes in ColEm's code, please, contact me by email or some other means. Be aware that ColEm source code is freely distributable, but it is not public domain and it is not released under GPL. You can not use it for commercial purposes, distribute, or change it on your own, unless you contact me to arrange the conditions of such use and get my permission. Feel free to look at it though.

Buttons

Coleco Adam:
  When using Coleco Adam keyboard, press [CONTROL]+[KEY] to
  access the special function of a [KEY], if it also performs
  a keyboard function.

All versions:
  [ALT]          - Hold to switch to the second controller
  [SPACE]        - FIRE-R button (also: [SHIFT],A,S,D,F,G,H,J,K,L)
  [CONTROL]      - FIRE-L button (also: Z,X,C,V,B,N,M)
  [Q]            - SuperAction PURPLE button (also: E,T,U,O)
  [W]            - SuperAction BLUE button (also: R,Y,I,P)
  [0]-[9]        - Digit buttons
  [-]            - [*] button
  [=]            - [#] button
  [PGUP]         - Fast-forward emulation (also: [F9])
  [ESC]          - Quit emulation (also: [F12])
  [F2]           - Turn soundtrack log on/off
  [F3]           - Toggle FIRE-R autofire on/off
  [F4]           - Toggle FIRE-L autofire on/off
  [F5]           - Invoke configuration menu
  [F6]           - Load emulation state
  [F7]           - Save emulation state
  [F8]           - Replay recorded gameplay
  [F9]           - Fast-forward emulation (also: [PGUP])
  [F11]          - Reset hardware
  [F12]          - Quit emulation (also: [ESC])
  [ALT]+[PGUP]   - Increase audio volume
  [ALT]+[PGDOWN] - Decrease audio volume

With #define DEBUG:
  [F1]           - Go into the built-in debugger

With #define GIFLIB:
  [F10]          - Make a screen snapshot (SNAPxxxx.GIF)

With #define WINDOWS:
  [ALT]+[ENTER]  - Switch between full screen and window modes

Coleco Adam keys:
  [F7]           - UNDO
  [F8]           - WILDCARD
  [PGUP]         - MOVE / COPY
  [PGDOWN]       - STORE / FETCH
  [HOME]         - HOME
  [INSERT]       - INSERT
  [DELETE]       - DELETE
  [END]          - CLEAR
  [PRTSCR]       - PRINT

Command Line Options

Usage: colem [-option1 [-option2...]] [filename]

[filename] = Name of the file to load as a cartridge [CART.ROM]
  This program will transparently uncompress singular GZIPped
  and PKZIPped files.

[-option] =
  -verbose <level>    - Select debugging messages [5]
                          0 - Silent       1 - Startup messages
                          2 - VDP          4 - Illegal Z80 ops
                          8 - EEPROM      16 - Sound
                         32 - Disks       64 - Tapes
                        128 - AdamNet
  -skip <percent>     - Percentage of frames to skip [25]
  -help               - Print this help page
  -home <dirname>     - Set directory with system ROM files [off]
  -pal/-ntsc          - Video system to use [-ntsc]
  -adam/-cv           - Run in Adam/ColecoVision mode [-cv]
  -sgm/-nosgm         - Enable Super Game Module extension [-nosgm]
  -24c08/-24c256      - Enable serial EEPROM emulation [off]
  -sram               - Enable battery-backed SRAM emulation [off]
  -allspr             - Show all sprites [off]
  -autoa/-noautoa     - Autofire/No autofire for FIRE-R button [-noautoa]
  -autob/-noautob     - Autofire/No autofire for FIRE-L button [-noautob]
  -spin1x/-spin1y     - Mouse X/Y position as SuperAction spinner 1 [off]
  -spin2x/-spin2y     - Mouse X/Y position as SuperAction spinner 2 [off]
  -drums/-nodrums     - Hit/Don't hit MIDI drums on noise [-nodrums]
  -logsnd <filename>  - Write soundtrack to a MIDI file [LOG.MID]
  -palette <filename> - Load color palette from given file [ColEm.pal]
  -palette <number>   - Use given color palette [0]
                        0 - Scaled VDP colors   1 - Original VDP colors
                        2 - Faded NTSC colors
  -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
  -nosync             - Do not sync screen updates [-nosync]
  -tv/-lcd/-raster    - Simulate TV scanlines or LCD raster [off]
  -soft/-eagle        - Scale display with 2xSaI or EAGLE [off]
  -epx/-scale2x       - Scale display with EPX or Scale2X [off]
  -cmy/-rgb           - Simulate CMY/RGB pixel raster [off]
  -mono/-sepia        - Simulate monochrome or sepia CRT [off]
  -green/-amber       - Simulate green or amber CRT [off]
  -4x3                - Force 4:3 television screen ratio [off]
  -sound [<quality>]  - Sound emulation quality [22050]
  -nosound            - Don't emulate sound [-nosound]
  -printer <filename> - Redirect Adam printer output to file [stdout]
  -diska <filename>   - Set disk image used for drive A: [none]
  -diskb <filename>   - Set disk image used for drive B: [none]
  -diskc <filename>   - Set disk image used for drive C: [none]
  -diskd <filename>   - Set disk image used for drive D: [none]
  -tapea <filename>   - Set tape image used for drive A: [none]
  -tapeb <filename>   - Set tape image used for drive B: [none]
  -tapec <filename>   - Set tape image used for drive C: [none]
  -taped <filename>   - Set tape image used for drive D: [none]

With #define DEBUG:
  -trap <address>     - Trap execution when PC reaches address [FFFFh]

With #define MSDOS:
  -vsync              - Sync screen updates to VGA VBlanks [-vsync]

With #define UNIX:
  -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
  -scale <factor>     - Scale window by <factor> [2]

With #define MITSHM:
  -shm/-noshm         - Use/don't use MIT SHM extensions for X [-shm]

Frequently Asked Questions

Why is the emulator so slow on my PC?
Your computer may be too slow to run the emulator. On slow machines, try speeding things up by skipping more frames (-skip command line option or "Draw XX% frames" menu option). In ColEm-Windows, make window smaller or switch to the full screen mode with [Alt]+[Enter].
Emulator is too fast on my PC!
If ColEm is too fast on your computer, you can slow it down by syncing it to a timer (-sync in ColEm-Unix), VBlanks (-vsync in ColEm-MSDOS), or by choosing "PAL Video"/"NTSC Video" menu option in ColEm-Windows.
I can't get some ROM images to work with the emulator.
If you can't get ROM image to work, send it to me for analysis.
Is it legal to spread cartridge ROMs?
NO. Nobody seems to care though, mainly because there is no profit to be made from ColecoVision software any longer. Nevertheless, be aware of the fact that by using commercial software you haven't bought you are commencing an act of piracy.
When compiling ColEm-Unix, I get "undefined name" errors.
This usually means that your linker cannot find the necessary libraries (namely, libX11 and libXext) or some additional libraries (like libsocket and libnsl) are required. Find these libraries in your system and modify the Makefile so that the final invocation of the C compiler has -L<path_to_libs> options. If you have no libXext library and the same functionality isn't provided in libX11, try #undefining the MITSHM option.
When starting ColEm-Unix, I get X_ShmAttach error.
You are probably trying to run the emulator on a remote Xterminal while it attempts to use shared memory for interfacing with X. Another reason for this error may be the lack of MITSHM extension support in your Xserver. Use -noshm option to disable the usage of shared memory.
When starting ColEm-Unix, I get X_PutImage error.
Unix/X version of ColEm can currently be compiled for 8bit, 16bit, or 32bit Xterminals. Neither 1bit nor 4bit Xterminals will work with the drivers included into official ColEm distribution.

History

New in ColEm 5.1

Added Coleco Adam state saving, loading, and rewinding.
Added support for more Coleco Adam keys (see documentation).
Disabled loading disks or tapes with no Adam firmware ROMs.
Added support for default palette file named ColEm.pal.
Now able to supply .PAL filename to -palette parameter.
Changing palette in Windows no longer resets emulation.

New in ColEm 5.0

Coleco Adam emulation is now operational, with keyboard, printer, disk, and tape drives. Use -adam command line option or "Hardware | Adam" menu to enable. Requires EOS.ROM and WRITER.ROM files.
Emulator will load .DSK files into disk drive A: and enable Adam mode.
Emulator will load .DDP files into tape drive A: and enable Adam mode.
Printer output can be sent to a file with -printer option.
Adam disk drives can also be loaded with -disk* options.
Adam tape drives can also be loaded with -tape* options.
Windows version has got full support for Adam-specific media images and hardware.
Added "File | Save Printer Output" menu to ColEm-Windows.
Added "Hardware | Disk Drives" menu to ColEm-Windows.
Added "Hardware | Tape Drives" menu to ColEm-Windows.

New in ColEm 4.8

Fixed state saves for games using SRAM.
Fixed wrong SRAM contents being saved.
Fixed SGM AY8910 wave effects.
Now updating sound every 8 scanlines.
Now muting AY8910 channels when Fnum is set to 0.
Enabled AY8910 sound channels in ColEm-Unix.

New in ColEm 4.7

Fixed sprite collision code to take into account early-sync flag.
Fixed scoring in the Carnival bear scene.
Fixed saved state compatibility between 32bit and 64bit architectures.
Fixed several problems with saving and loading TMS9918 states.
Fixed PulseAudio hangup on exit in ColEm-Linux.

New in ColEm 4.6

Made replay save states approximately every 170ms.
Added ability to browse through paused replay.
During replay, press [UP] to pause or resume.
When replay paused, press [LEFT] and [RIGHT] to browse.
Press any other button to continue playing.
Now cancelling replay if any key or button is pressed.
Made WaitJoystick() exit when window closed.

New in ColEm 4.5

Added battery-backed SRAM emulation (Lord Of The Dungeon works).
Added "Hardware | 2kB SRAM" menu option to ColEm-Windows.
Removed -noeeprom command line option, as useless.
Added -sram command line option.
Fixed saved state compatibility between 32bit and 64bit systems.

New in ColEm 4.4

Added ROM page switch specific for carts with EEPROM.
Added 24c08 EEPROM support (Black Onyx saves now).
Added 24c256 EEPROM support (Boxxle works).
Now saving EEPROM state into .SAV files.
Now saving SGM state into .STA files.
Now accepting both AA55h and 55AAh MegaCarts.
SGM games Buckrogers, Subroc, Zaxxon, Dragon's Lair work.
Fixed restoring background screen color from .STA files.
Added EEPROM menu selections to ColEm-Windows.
Added links to CV Addict and AtariAge forums to ColEm-Windows.
Added -24c08, -24c256, and -noeeprom command line options.
Compiled ColEm-Unix with -Wall and eliminated warnings.
Replaced -DNO_WAVE_INTERPOLATION with -DWAVE_INTERPOLATION, off by default.
Removed old LoadSTA() and SaveSTA() code.
Finally deprecated -DNEW_STATES.

New in ColEm 4.3

Added Super Game Module (SGM) emulation.
As part of SGM emulation, added AY8910 PSG chip support.
Added -sgm and -nosgm command line options.
Fixed high-frequency PSG noise (dynamite sounds in HERO).
Added remaining time display during replay.
Stopping replay when menu opens on Windows.
Fixed replay rollover mechanism.
Added shadow underneath the time display.

New in ColEm 4.2

Added multiple monitor support to ColEm-Windows.
Fixed disappearing window in ColEm-Windows.
Fixed best full-screen mode detection in ColEm-Windows.
Fixed window flicker that appeared after recent Win10 updates.
Fixed DirectInput joysticks support in ColEm-Windows.
Fixed directional pads on the XBox gamepads.
Switched ColEm-Linux to using PulseAudio sound.
Updated old PulseAudio driver for 64bit Linux.

New in ColEm 4.1

Added support for DirectInput joysticks to ColEm-Windows.
Moved all input-related options to the "Input" menu in ColEm-Windows.
Fixed crash when changing audio sampling rate in ColEm-Windows.
Added "Draw 65% Frames" option to ColEm-Windows.
Fixed screen updates after changing scaling algorithm in ColEm-Windows.

New in ColEm 4.0

Added MegaCart support for 64kB+ homebrew games.
Fixed SCREEN 0/3 VDP mode selection (Bankrupcy Builder, etc).
Added "Nearest Neighbor" option to disable linear interpolation.
Added "Force 4:3 Screen" option to ColEm-Windows.
Fixed "Hit MIDI Drums" option in VGB-Windows.
Fixed 44kHz sound hiccups when 50Hz sync selected in ColEm-Windows.
Computing effective waveform power when simulating samples via MIDI.
ColEm-Windows will not overwrite last ROM file name with other names.
Added -4x3 command line option to ColEm-Unix.

New in ColEm 3.8

Added Scale2X scaling algorithm.
Added Monochrome, Green, Amber, and Sepia CRT emulation.
Added -scale2x and -raster command line options.
Added -mono, -sepia, -green, and -amber command line options.
EMULib-specific command line options now processed inside EMULib.
Added "Scale2x Algorithm" option on Windows.
Added "LCD Raster" option on Windows.
Renamed "Color Raster" menu to "Color Filter" on Windows.
Deprecated -notv and -nolcd command line options.
Reorganized menus in ColEm-Windows.

New in ColEm 3.7

Fixed sprite collision detection.
Added collision detection even on transparent sprites.
Now setting lower VDPStatus bits to the last tested sprite.

New in ColEm 3.6

Changed VDP VRAM access mechanism according to datasheet.
Added support for *.COL files to ColEm-Windows.
Added "Play Sound When Inactive" option to ColEm-Windows.
Added "Clear File Associations" option to ColEm-Windows.
Added "Debugger" option to ColEm-Windows.
Made color raster effects stronger.

New in ColEm 3.5

Added special effects simulating individual pixel components.
Added EPX and EAGLE scaling algorithms.
Added keypad recording to the instant replay recorder.
Fixed memory corruption bug in the instant replay recorder.
Fixed instant replay not restoring successive states.
Fixed instant replay not recording the first state.
Merged scanline options into "Simulate Scanlines" in ColEm-Windows.
Merged scaling options into "Interpolate Video" in ColEm-Windows.
Added "Apply Color Raster" submenu to ColEm-Windows.
Added "RGB Raster" and "CMY Raster" options to ColEm-Windows.
Added "Clear File Associations" option to ColEm-Windows.
Added -rgb and -cmy command line options.
Added -epx and -eagle command line options.

New in ColEm 3.4

Removed waveform interpolation for more realistic sound.
Switched ColEm-Windows to Direct3D textures-based rendering.
Added "Stretch Full Screen" option to ColEm-Windows.
Added new icon to ColEm-Windows.
Added -lcd and -nolcd command line options.
Switched ColEm-Linux Replay feature to always-on recording.
Now properly setting display update period after restore.
Fixed display updates synchronization in ColEm-Linux.
Fixed compilation warnings in ColEm-Linux.

New in ColEm 3.3

Added accurate SN76489 noise channel emulation.
Added RAM-based cheats with AAAA in 0x6000..0x63FF range.
Added Cheat Hunter tool that lets you search for cheat codes.
Now properly restoring sound parameters.
Disabled console window in ColEm-Windows.
Fixed compilation errors in ColEm-Unix.

New in ColEm 3.2

Added support for Super Game Cartridges with >32kB ROMs.
Added support for cheats in AAAA-DD and AAAA-DDDD formats.
Added RAM-based cheats with AAAA in 0x6000..0x63FF range.
Added Cheat Hunter tool that lets you search for cheat codes.
Gameplay recording now always enabled.

New in ColEm 2.9

Not resetting VDP address latch when reading status (Sir Lancelot).
Implemented 5th sprite fields in the VDP status register.
Switched SN76489 PSG to logarithmic volumes.
Corrected SN76489 PSG base frequency.
Added more realistic "LD R,A" opcode to the Z80 emulation.
Added undocumented opcode 71h to the Z80 emulation.
Added accurate R register emulation.
Added accurate LDIR/LDDR emulation.
Added "replay" function (press [SHIFT]+[F8] to record, [F8] to replay).
Added vertical scanlines effect to ColEm-Windows.
Added LCD-like raster effect to ColEm-Windows.
Started adding Coleco Adam emulation (not yet complete).
ColEm-Android port is now available from Google Play.
Maemo, Meego, Symbian, and MSDOS versions are no longer supported.

New in ColEm 2.6

State save file format (.STA) changed!
Now clearing all RAM to zeros (Heist works).
Now padding smaller ROMs with 0xFFs in LoadROM().
Fixed Reset9918() to reset VDP completely (Boulder Dash and Frogger).
Implemented SCREEN2 table address masking, thanks to Daniel Bienvenu.
Fixed ColEm-Unix to automatically adapt to the screen depth.
Ported ColEm to Maemo5 (aka Fremantle).
Added accelerometer based tilt controls to ColEm-Maemo5.
Added Maemo-specific configuration menu to ColEm-Maemo5.
Added customizable key mappings to ColEm-Maemo5.
Added fast-forwarding with [Ctrl]+[Space] to ColEm-Maemo5.
Fixed on-screen dialpad in ColEm-Maemo.
Multiple other small fixes and additions to ColEm-Maemo.

New in ColEm 2.5

Yet again ported ColEm to Unix using the new EMULib framework. The new ColEm-Unix has been tested to compile and run on Ubuntu Linux but should work on any other Unix. ColEm-Unix source code is included with the core source code distribution.
Ported ColEm to Maemo OS2008 used in N800 and N810 internet tablets from Nokia. ColEm-Maemo has been specifically optimized for the tablets using ARM assembler. It will simulate joypad with the touch screen and automatically open *.cv/*.cv.gz files from the file manager. ColEm-Maemo source code is included with the core source code distribution.
Renamed -zoom/-nozoom to -soft/-nosoft.
Added -scale option to scale window on Unix.
Added -home to set home directory with system ROMs.
Options -tv/-notv, -soft/-nosoft, and the [F8] key now work for both MSDOS and Unix.
ColEm-Symbian display routines rewritten in ARM assembler for speed.
Split ColEm-Symbian configuration menu into four tabs, making "Video" and "Audio" settings separate.
Added "Audio Latency", "Skip Frames", and "Sync Updates" settings to ColEm-Symbian.
Documentation and built-in help changed, many inconsistencies removed.

New in ColEm 2.4

Ported ColEm to smartphones running Symbian/UIQ3 software!
Added new, much better, scanline simulation and video softening effects to ColEm-Windows.
ColEm-Windows full-screen mode now runs in 640x480 resolution.
Added -sync/-nosync option to ColEm-MSDOS to sync screen updates to the timer (use -vsync for VBlanks).
Added -zoom/-nozoom option to ColEm-MSDOS that will zoom ColEm display to fill the whole screen, using image softening algorithm.
ColEm-MSDOS now runs in 640x480x15bpp VESA screen mode when -zoom or -tv options used, otherwise it runs in 320x200x15bpp screen mode.
Added [CONTROL]+[F8] key combination to ColEm-MSDOS to toggle display zoom on/off.
Added new "Fill & Soften" zoom mode to ColEm-Symbian. It is rather slow though.
Fixed possible source of instabilities in the S60 open file dialog in ColEm-Symbian.

New in ColEm 2.3

Added network play option to ColEm-Windows and ColEm-Symbian!
Now resetting R register on ResetZ80() to keep states of both NetPlay players consistent.
Now clearing all RAM on ResetColeco() to keep states of both NetPlay players consistent.
Added new, much better, scanline simulation and video softening effects to ColEm-Windows.
ColEm-Windows full-screen mode now runs in 640x480 resolution.
Added zoom settings to ColEm-Symbian ("None", "Keep Aspect", and "Fill Screen").
Added display orientation settings to ColEm-Symbian ("Landscape", "Portrait", and "Auto").
Finally fixed opendir() problem in EMULib-Symbian. All built-in menu file dialogs work now!
Further extended and optimized Symbian screen rendering routines.
Fixed and optimized TV scanline simulation in ColEm-Symbian, made scanline effect stronger.
Fixed system warnings in when flipping Nokia E70 open/closed.
Fixed possible crash when selecting an initial file in ColEm-Symbian.

New in ColEm 2.2

Changed Z80 NMI handling to comply with the standard.
Added "show all sprites" option (-allspr).
Added error messages to ColEm-Windows and ColEm-Symbian.
Added button and key remapping configuration to ColEm-Symbian.
ColEm-Symbian application menu is now split into three pages.
ColEm-MSDOS is now prebound with DOS32A extender, instead of outdated DOS4GW.

New in ColEm 2.1

Added builtin configuration menu ([F5]).
Added palette selection (-palette) between scaled VDP palette, original VDP palette, and the faded NTSC palette suggested by Richard Drushel.
Now defaulting to the palette from TMS9918 datasheet scaled by 255/224 to get true white color.
Fixed console keyboard input in Windows.
Updated and extended documentation.

New in ColEm 2.0

MSDOS and Windows versions are now based on the new framework.
Started adding Coleco Adam emulation (not finished yet).
Added state saving and loading via .STA files.
Added SuperAction spinner emulation with the mouse.
Added zoomed sprites support in VDP.
Standardized TMS9918 emulation.
Fixed VDP VBlank interrupt bug.
Replaced "updates per VBlank" (-uperiod) with "percentage of skipped frames" parameter (-skip).
Removed -vperiod/-hperiod parameters as deprecated.
Added -pal/-ntsc parameters to switch between TMS9918/TMS9928 and TMS9929 VDPs.
Soundtrack saved into MIDI files.
Documentation rewritten in HTML.
Added speed throttling to ColEm-MSDOS (-vsync).
Keyboard assignments have changed.

New in ColEm 1.0

Standardized Z80 emulation.
Standardized PSG emulation.
Soundtrack saved into .SND files.
Screen refresh done line-by-line.
Sprites are refreshed line-by-line.
Limit on sprites per line introduced.
General cleanup of the source code.
Rewritten documentation.

Thanks to...

Finally, I would like to thank Hans Guijt, Marcel de Kogel, John Stiles, Neal Danner, Alan Steremberg, and all other people who helped me with advice, information, ROM images, and encouragment.

ColEmversion 5.2