Readme section

Controller setup

In the menu: During game (joystick games): During game (paddle games): On first controller: Keypad is mapped to Keyboard: 
 Atari    mapped to  mapped to
 Keypad     left       right
+-+-+-+    +-+-+-+    +-+-+-+
|1|2|3|    |1|2|3|    |8|9|0|
+-+-+-+    +-+-+-+    +-+-+-+
|4|5|6|    |Q|W|E|    |I|O|P|
+-+-+-+    +-+-+-+    +-+-+-+
|7|8|9|    |A|S|D|    |K|L|;|
+-+-+-+    +-+-+-+    +-+-+-+
|*|0|#|    |Z|X|C|    |,|.|/|
+-+-+-+    +-+-+-+    +-+-+-+
Note that all keys are mentioned as on the US keyboard mapping. Other keyboard mappings may vary. For example, on german keyboard use [Ö] instead of [;] and [-] instead of [/].

Format of dcstella.ini

The format is simple:
Key=Value

The available keys are

charset.8x8.file filename of 8x8 pixel charset
charset.8x16.file filename of 8x16 pixel charset
title.image.file filename of title image
title.image.xpos x position of title image
title.image.ypos y position of title image
select.image.file filename of the menu background image
select.image.xpos x position of menu background image
select.image.ypos y position of menu background image
select.menu.xpos x position of the rom selection menu
select.menu.ypos y position of the rom selection menu
select.menu.width width of rom selection menu in characters
select.menu.height height of rom selection menu in characters
select.audio.player name of the module player file (arm binary)
select.audio.start position where to load the module in AICA's mem, depends on program that's playing (s3mplay and dxm need 0x10000, so that's the default)
select.audio.file name of the module file
roms.dir name of the roms directory
roms.list.file name of roms list file
properties.dir name of the properties directory
autorun.file rom file to load and start for single rom mode; this obsoletes nearly every other option except for the charset.8x8.*, title.image.* and profiles.* section
cheat.allowed set this to 'yes' to allow cheating

Position of images:

Position of menu:

This one is the offset from the top left corner in pixel

Size of menu:

This is the size of the menu in characters. If the height is negative the 8x8 charset is used instead of the 8x16 charset.

Format of the title and background images

These have to be in Targa, 24Bit, uncompressed.

Format of Charset:

Short: The format is the same as in the C64/C128, only sorted in ascii (at least in the 8x8 case). Each char is 8 pixels wide and stored in a byte, highest bit left. The first 8/16 bytes are the space character; the second 8/16 bytes are the "!" sign, and so on, till ascii character 127 (see the table for an example of an 8x8 font). That sums it up to 768/1536 bytes per 8/16 lines charset. If the 8x16 charset is omitted the 8x8 is used and doubled in height.
byte no. data remark
0 %00000000 "space" char 1st row
1 %00000000 "space" char 2nd row
2 %00000000 "space" char 3rd row
3 %00000000 "space" char 4th row
4 %00000000 "space" char 5th row
5 %00000000 "space" char 6th row
6 %00000000 "space" char 7th row
7 %00000000 "space" char 8th row
8 %00011000 "!" char 1st row
9 %00011000 "!" char 2nd row
10 %00011000 "!" char 3rd row
11 %00011000 "!" char 4th row
12 %00000000 "!" char 5th row
13 %00000000 "!" char 6th row
14 %00011000 "!" char 7th row
15 %00000000 "!" char 8th row
...
264 %00011000 "A" char 1st row
265 %00111100 "A" char 2nd row
266 %01100110 "A" char 3rd row
267 %01111110 "A" char 4th row
268 %01100110 "A" char 5th row
269 %01100110 "A" char 6th row
270 %01100110 "A" char 7th row
271 %00000000 "A" char 8th row
...
760 %00000000 ascii char #127 1st row
761 %00000000 ascii char #127 2nd row
762 %00000000 ascii char #127 3rd row
763 %00000000 ascii char #127 4th row
764 %00000000 ascii char #127 5th row
765 %00000000 ascii char #127 6th row
766 %00000000 ascii char #127 7th row
767 %00000000 ascii char #127 8th row

The issue of the rom list file

The rom list file has the simple format:
filename <SPACE> description <linefeed>
all nonprintable Characters (ASCII < 32 or ASCII > 127) will be replaced with spaces. If the rom list file is missing (doesn't matter if it's the option or the file itself), the directory will be used.

The swap trick

From DCStella V0.2c on, it's possible to swap the disc containing the emulator with one containing the ROMs: Where to get /dcstella.pro/?
Copy it from the original DCStella CD or from the binary release archive.

Playing music in the ROM selection menu

The idea of playing music while selecting a ROM to play became a big hassle. Here's why:

The cheat monitor

The cheat monitor is activated by pressing the X button on the "Cheatcode" in pause menu. (Note: you need to have cheating enabled in dcstella.ini!)

First of all I need to explain how the whole cheating works: if a cheat code is activated, after every frame is emulated, one byte of the 128 bytes RAM of the Atari will be overwritten with a predefined value. If it's byte where the number of lives is stored, it will be decremented during emulation, but overwritten (or `restored') after the frame is done, so the games ``thinks'' that everything is ok.

But now for an example: here I'm using Phoenix.

Questions left?

This documentation sucks, I know. Tell me what could be done better and what's missing!
Feel free to send me a mail: svolli at svolli dot de.