ColEm Documentation

# ColEm
version 2.5

### by Marat Fayzullin

>

# Contents

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

# New in This Version

- 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.

# Introduction

ColEm is a portable emulator of the old ColecoVision videogame console. 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, with Windows, MSDOS, Unix, and Symbian ports being maintained by myself. All these ports are available for free from the above website.

The ColEm-Symbian port works on the 3rd Edition Series60 phones from Nokia and its licensees. You can download it, as well as my other Symbian products, at

http://fms.komkon.org/EmuSymbian/

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 Windows and MSDOS. The ColEm-Unix sources are also available, for a slightly older version of ColEm.

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

    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
      [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

    With #define MSDOS or UNIX:
      [F8]           - Turn scanline simulation on/off
      [CTRL]+[F8]    - Toggle screen softening on/off

# 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
                                            16 - Sound
      -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]
      -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 <number>   - Use given color palette [0]
                            0 - Scaled VDP colors   1 - Original VDP colors
                            2 - Faded NTSC colors
      -sound [<quality>]  - Sound emulation quality [22050]
      -nosound            - Don't emulate sound [-nosound]

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

    With #define UNIX or MSDOS:
      -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
      -nosync             - Do not sync screen updates [-nosync]
      -tv/-notv           - Simulate/Don't simulate scanlines [-notv]
      -soft/-nosoft       - Scale screen up with softening [-nosoft]

    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

1. 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]`.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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 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.

© Copyright by Marat Fayzullin (marat [AT] komkon /DOT/ org)