About

Colleen, the official port for Android of the Atari800 emulator is up on the android play store. Scan this QR code to get it (or search for 'Atari800' in the market):

Manual

The first thing the emulator requires are the images of the ROM chips used in the original machines. The different Atari machines used distinct ROM chips. They are essential (as in the emulator won't work without them) but have nevertheless been dumped and are available on the internet. For example, you can find the Atari XL ROMs as a legal download inside the XFormer package available at the Atari800 project site -- check out the ROM files link. The standard names for each type of ROM are:

atariosa.rom - OS/A,
atariosb.rom - OS/B,
atarixl.rom - XL, and
ataribas.rom - XL Basic

The emulator does not require all of them to work. For example you can only have the 2 XL images and the emulator will work just fine for any XL-class machine. You just won't be able to switch to older machines. Note also that these are the exact file names which the emulator will look for when trying to boot the intended machine.

To get the emulator working, you need to copy the ROM images to a directory on the device, typically /sdcard/atari800. When the emulator starts it will ask you to point to the directory containing the ROMs. Use the file selector to navigate to the directory (/sdcard/atari800 in the previous example) and hit the Select directory button. You can at a later time add to this directory any missing ROMs; they will be detected automatically. Also if you decide to relocate this directory at a later time, you can use the Atari ROM Path option in the emulator preferences to point to another directory.

Showing the menu

Colleen supports all Android devices with Android version 1.6 and up. In Android, the mechanism of obtaining a menu for an application, Colleen in this instance, varies. In pre-Honeycomb (3.0) devices, a hardware menu key is provided for bringing up the menu. Press this key Within Colleen to get to the menu. In post Honeycomb devices this is fuzzy. In Colleen, for these devices, an action bar is provided. The action bar is hidden. To bring it up, tap near the top of the screen; emulation will pause and the menu will be shown. This scheme though does not preclude the hardware menu key.

TL;DR: To show the menu: If you've got a menu key on your device, use it. If you're running on 3.0+, also tap the top of the screen.

Playing Planetary Defense 2012

Planetary Defense is an arcade game by Charles Bachand and Tom Hudson published in the A.N.A.L.O.G. Computing magazine on March 1984. Tom has got around to enhancing Planetary Defense especially for Colleen to add two new features:

• A specially crafted interface to benefit from the touchscreen
• An online high score table

Objective: Protect your planet from the alien space bombs. As your defense satellite orbits your planet, tap the screen to send charge particle projectiles flying the enemy's way.

Planetary Defense 2012 is included in this release of Colleen. To play, go into the preferences screen (menu button or action bar) and choose "Play Planetary Defence 2012" from the "Extras" section. Press OPTION on the starting screen to select the touchscreen control scheme. Tap top-left and bottom-down, as directed to calibrate the touchscreen controls. When your game ends, you will be asked to enter a name for the high score table (you may skip this by just pressing Return). Upon entering a name and pressing Return, Colleen will ask you if you want to go online and submit the high score. Pressing 'Yes' on this dialog will launch the default browser, which will submit your score and allow you to browse the rankings. Hit 'Back' to go back to Colleen. Note that Colleen automatically enables the 'Touchscreen Mode' preference when playing Planetary Defense 2012. You need to manually go uncheck this option if you intend to, f.ex., boot another game and use the joystick. Otherwise, this preference is cleared each time Colleen is restarted.

Opening a disk image

Once the emulator is up and running, hit the Menu button and use the Open option to bring up the file selector. Navigate to the required folder on touch an item to auto boot it. The emulator supports the following file formats: atr, atz, xfd, dcm, xfz, xex, cas, rom, bin, car, a8s, com, exe. These are the extensions of the filenames supported and range from compressed/uncompressed disk images to cartridges and cassettes.

Many games come in several disk images. To insert a disk image in the drive and not have the machine reboot, simply long press on the item. A menu will show up displaying the currently mounted images on drives D1: to D4:. Touch the drive where you want to mount the image to. Touch Unmount All to unmount images from all drives. There is also a handy shortcut to inserting disk images while the emulator is running: Bring up the emulator menu and touch the Next Side option. Currently this only support images with appropriate filenames using a specific pattern. As an example, if the currently running image's filename in drive D1: is "My Game (s1).atr", hitting the Next Side option will have the emulator try to mount "My Game (s2).atr". The key pattern which is searched is of the form "s<number>". Moreover, supposing that a disk images has 4 sides and currently the fourth side is mounted, the some option will mount the first image (i.e. the images wrap around).

Save state load/save

The emulator supports saving the entire contents of the ROM+RAM to a state file. This can be loaded later; emulation will resume where it left off. Saved states can be used as means f.ex. saving a game and reloading it later. To save the current emulator state, you must first provide a path where the state file will be saved. To do this, touch the Save State Path option in the preferences. The file selector will pop up. Touch Select directory to set the required path. This is required only the first time you need to use the state save facilities. To actually save the emulator state, touch the Save Current State option in the preferences. A dialog will pop up where you can enter a name for this state. The .a8s extension will be appended to the name you type, and this file will be saved at the path you've set. To subsequently load this save state, use the normal Open option in the emulator menu. navigate to your state save path and open the required .a8s file.

Input

Joystick
Central to the oldskool fun is the emulation of the joystick input methods of the Atari. The emulator features several ways to generate joystick input. The on-screen joystick is probably the easiest. The screen is divided horizontally into the joystick side and the fire button side. Touching the joystick side will result in joystick action and respectively for the fire button side. Normally, the left portion of the screen is mapped to the joystick side and the right portion to the fire button side, but this allocation can be inverted by ticking the Right-Handed Joystick option in the emulator Preferences. The percentage of the screen area allocated to either side is also configurable via the Joystick Screen Split option in the Preferences. The Search button of the device also serves as a fire button substitute. This allows single touch devices (pre Eclair) to still use the on screen joystick. The fire button, as well as all joystick input, can further be remapped to other keys through the Keyboard joystick preference.

The joystick area is marked by a transparent rectangle. Touches registered within the joystick area (joystick deflections) will cause input to the joystick in port 0. A dead band area is also observed, the size of which is configurable at the Joystick Deadband preference. A dead band of 30% for instance means that joystick deflections within a 30% margin around the center will not register at all. The joystick area can also be dragged around by keeping pressed the joystick touch and dragging outside the joystick area. This comes in handy when there is too much action on screen to keep an eye on where your finger is positioned. This feature can be turned off however (why? :-)) via the Anchor Joystick preference. The joystick area can be repositioned in another way as well: When the joystick is idle (no touches) a touch outside the joystick area but within the joystick side of the screen will recenter the joystick area around the touch point. The Joystick Grace Area preference allows a leniency to this rule: it extends (virtually, not shown) the joystick area by some amount. Any touches within this virtual area will result in joystick movement and small drag-through repositioning, rather than a full joystick area repositioning centered around the touch point. The joystick area's visibility, size and transparency strength can all be tweaked in the emulator preferences.

The hardware keyboard can also serve as a joystick input for joystick port 0. The option Keyboard Joystick must be enabled in the preferences. The sub-menu Configure Keyboard in the preferences can be used to remap the keys used to perform the joystick actions. There are two kinds of actions: fixed and remappable. Fixed actions are those whose input can be changed but their effect cannot be changed. Fixed actions are: Up, Down, Left, Right and Fire. Remappable actions are those that the input (what you press) is configurable but also their effect (what gets done) is configurable too. There are up to three generic mappable actions, divided by the fixed actions by their own heading in the keyboard configuration screen. Remappable actions can be used to input keycodes, for example, when using a controller (when I press the X button, I want the spacebar to be pressed). To change the mapping for an action, touch the action and a dialog will pop up, waiting for input. At this time, you can press the key to assign the action or touch Cancel to abandon the mapping. If the action is fixed, as soon as a key is sensed the dialog is dismissed and the new mapping is registered. If the action is a generic mappable one, a second dialog will show up which allows you to enter the key you want to be pressed. Some keys are reserved for the system and cannot be mapped at this time, including: the shift keys, volume up/down, the menu, search back and home keys, power, call and end call keys. Pressing these while mapping will result in no action (as if nothing was pressed).

The Wii Controller is another way to provide joystick input to the emulator. You first need to download the 'Wiimote controller' app from the android market. Set it up according to the instructions, then fire up Atari800. To use it, the Keyboard Joystick option must be checked in the emulator preferences, as the Wiimote controller acts as a keyboard. Use the Configure Keyboard option in the preferences to remap Wii remote buttons to joystick actions, using the procedure outlined in the previous paragraph. The Wii classic controller can also be used for input.

A short note with respect to the Xperia Play devices: The square, triangle, the X and both left and right triggers are supported. As such, they can be properly configured within the Configure Keyboard preference. The circle key cannot be mapped to anything as, for compatibility reasons, it is always mapped to the Back key (which exits the emulator).

Paddle
Some games support and/or are better with a paddle controller. Paddle emulation is provided by interpreting the x axis of the touch/mouse input as the amount of paddle deflection. To switch on paddle emulation check the Paddle mode option in the preferences. The joystick area will be replaced by a slim rectangle as a visual reminder of the horizontal space which will be used for paddle emulation. Drag from left to right to provide paddle input (and don't forget to toggle paddle mode off in the preferences to go back to joystick input :-).

Keyboard
The device's hardware keyboard is used for keyboard input in the emulator. If the Keyboard Joystick option has been selected in the preferences, then the respective keys are muted; their inputs serve as joystick inputs. The directional pad (DPAD) keys emit the atari arrow keycodes ('Control' + '-', '=', '+', '*'). DPAD Center sends the Break key code. The tilde key ('~') is mapped to the Escape key. The backquote ('`') is mapped to the capslock key. The left-curly-bracket ('{') is mapped to the Atari key. The left shift of the keyboard is used as the atari's shift key, while the right shift is used as atari's control key.

External keyboards can also be used. Android seems to rotate the external keyboard's arrow keys in the same fashion as the built-in DPAD keys. And although this rotation makes sense for the built in arrows, it wreaks havoc with the external keyboard. To address this, use the Derotate Arrow Keys preference. Set this to either Left or Right to manually derotate the keyboard's arrow keys.

For keyboard-less devices, a virtual keyboard is provided. To show it, touch the Keyboard option in the emulator's menu. To hide it, press the Back key on the device.

Breakdown by function

Menu

Open

Shows the file selector. Back to cancel. Touch to mount and boot. Long press to mount only. Use the keyboard to filter filenames.

Next side

Attempt to mount the next side in a disk set. A filename pattern is matched, as described above.

Keyboard

Show the virtual keyboard. Back to hide it. Keyboard won't show if the device has a hardware keyboard, or at least if it is exposed (slided out).

Preferences

Show the preferences screen for the emulator.

Quit

Quits the emulator. Make a good habit of quitting the emulator cleanly, either by this option or pressing the back key twice. It gives the emulator a chance to clean up any temporary files.

Graphics

NTSC TV Mode

When checked, NTSC mode is enabled; when unchecked PAL mode is enabled. NTSC mode requires mode CPU power for emulation.

Aspect

Scale the screen while maintaining correct aspect. None is no aspect enforced (fill whole screen), portrait & landscape means only scale aspect corrected for the respective orientation (the other just fills the screen) and both means always perform aspect correct scaling (in either orientation). Special Note: For devices without keyboard, you might find handy to set this preference to 'Portrait': The soft-keyboard should fit in the bottom part of the screen, not obstructing the playfield (BASIC, text adventures etc.)

Bilinear Scaling

Use bilinear filtering when scaling the atari screen. Some like it, I don't. Also should be slower (in principle) when bilinear scaling is on.

Artifacting

Set artifacting on/off and colors.

Frameskip

How frequently the atari screen is repainted to the device. If you're getting less optimal atari speeds, set this to higher values. Set to auto to have the emulator adjust the frameskip value in real time to maintain 100% of Atari speed.

Accurate Collisions

Disable this to gain more emulation speed. Also, games may be broken by this.

Crop Horizontally, Vertically

Use this to get rid of the borders around the atari screen. Sane values are 320x200.

Emulation

Machine Type

Select emulated machine type and size of RAM. You must have the required ROM images, as described above, or the machine won't boot. Forces a cold reset if changed.

Atari ROM Path

Brings up the file selector to choose the directory where the ROM images reside (see above).

State Save Path

Brings up the file selector to choose the directory where the state save files will reside (see above).

Save Current State

Saves the current emulator state with a filename you provide to the path defined by the previous option. Use the normal Open menu option to load your saved states. (Option is disabled by default until a state save path has been set)

Disable BASIC

When checked, this is like holding down the option atari key when booting.

Show Atari Speed, Drive Access, Sector Access

These toggle on off indicators. The atari speed indicator shows how fast the emulated machine runs. If this is significantly lower than 100% consider increasing the frameskip, disabling collisions, disabling the high quality sound, lowering the sound mixing frequency and so on.

Allow Web Browser

By checking this option the B: device gets generated in the emulated machine, to be used when the emulated program wants web access (i.e. Planetary Defence 2012). Uncheck this to ignore browser requests.

Input

Keyboard Joystick

If checked, the keys defined in the next option will control the joystick. This also has to be checked for the Wii controller to work.

Configure Keyboard

Shows a separate preference screen where the joystick keys can be remapped. Select the action you need to reassign then press a key on the device or the Wii controller to change the mapping. Don't forget to use the Wiimote controller application first for the Wii controller.

Derotate Arrow Keys

Use this option to fix the arrow keys on external keyboards, when switching from portrait to landscape and vice versa.

Joystick Visible

Toggle visibility of the joystick overlays. The on-screen joystick still works, you just don't see it.

Joystick Opacity

Set the transparency level of the joystick overlays. Higher is less transparent.

Joystick Area Size

Set the size of the on-screen joystick. Depends on the thumb, really.

Right-Handed Joystick

Swap the areas the emulator assigns to joystick and fire button. Normally (unchecked) a portion of the screen (defined by the joystick screen split preference below) on the left hand side is allocated to the joystick. The rest is allocated to the fire button. This preference inverts these areas, allocating the percentage defined by screen split on the right hand side while the rest is allocated to the fire button.

Anchor Joystick

Stop the joystick area slide-around action. This pins the joystick area to the current position.

Joystick Screen Split

Define the percentage of screen allocated to the joystick. 50% means down the middle. It is implied that any touch event in the joystick side is a joystick event and vice versa for the fire button. The allocation is inverted if the right-handed joystick option is checked.

Joystick Deadband

Percentage of the joystick area around its center within which no joystick input will be generated. Increase if the joystick seems too sensitive.

Joystick Grace Area

Virtually extends the joystick area by set amount to prevent joystick recenters for closeby touches.

Paddle Mode

When checked, paddle input will be provided instead of joystick.

Touchscreen Mode

A special control scheme crafted for Planetary Defense 2012. When this is check, all other on-screen joystick/paddle input modes are disabled.

Sound

Sound

Switch sound off to gain performance.

Mix Rate

Lower the mix rate to increase emulator performance. Does not make that much of an impact to lower this.

Sound Buffer Size

Lower size is lower latency. Lower size though could lead to clicks in sound audible during emulation (and not during pausing/unpausing, entering the menu preferences, etc. These are normal). Higher size means higher latency which is not desirable but gets rid of sound clicks in less powerful devices.

16bit Sound

Using 16bit sound with high quality sound disabled (below) makes no difference, apart from straining the cpu more. Note: Android documentation recommends using 16bit sound, as it is more compatible.

High Quality Sound

When enabled, high quality low pass filtering is used for POKEY emulation. Apart from increased cpu load (not too much though) this also leads to a delay of a few seconds when the emulator starts up, while the filter coefficients are calculated.

Force Legacy Playback

On devices with android version greater than 2.3, the native OpenSL ES audio driver will be used for accurate sound playback. Setting this option will override this automatic selection and force sound playback through the legacy android audio (use for potential compatibility issues).

Extras

Planetary Defense 2012

Autoboot the machine with the built-in Planetary Defense 2012 image. Also, auto-enable the 'Touchscreen Mode' preference above. Yes. Do it!

Changelogs

3.0
Changes for version 3.0:

* Native Open SL ES sound for perfect playback for > 2.3 devices.
* Fix for no sound for NTSC machines under certain circumstances.
* Various other bugfixes.
* Upgrade to atari800 core v. 3.1.0.

2.0
Changes for version 2.0:

* Free game included: Planetary Defense 2012. Find it in the Preferences.
* UI overhaul for Honeycomb+ devices
* When aspect correction is portrait, make room for the soft keyboard
* Bugfix: Crashes while loading ROMs
* Bugfix: Won't load OSB ROMs
* Bugfix: Crashes in keyboard-joystick remapping
* Warning: State saves from previous version are incompatible (sorry)
* Numerous bug fixes and improvements

Thank you for your continued support and bug/feature reports

1.4
Changes for version 1.4:

* Android port renamed to Colleen
* Implemented paddle emulation
* Allow file selector to roam outside the directory provided by the OS (allows for weird mount points on some devices)
* Support for saving and loading the emulator state
* Various small bug fixes and improvements

1.3
Changes for version 1.3:

* New NTSC/PAL preference
* New keyboard action mapping preferences
* Added support for Xperia Play fire buttons
* DPAD-CENTER now mapped to Break key
* Atari800 core version 2.2.1
* Several bug fixes and improvements

Thank you for your continued support and bug/feature reports :-)

1.2
Changes for version 1.2:

* New disk management menu (long press in the file selector)
* New screen cropping preferences
* New arrow key derotation preference for external keyboards
* DPAD-CENTER and tilde (~) now map to Escape key
* Atari800 core version 2.2.0
* Fix rare sound-related crashes
* Various fixes and improvements

Thanks to the bug/feature reporters!

1.1a

This version is a quick fix for a regression to the Anchor Joystick preference, introduced in v1.1.

1.1

* Fix a crash when sound was switched off
* Added support for .com and .exe files
* Added the auto frameskip option
* Added the new Joystick Grace Area preference
Thanks to the bug/feature reporters!