UNIX CONTROLS

Full keyboard support plus:
Ctrl+[1-4] ........ Insert a virtual disk into drive 1-4.
Ctrl+Shift+[1-4] .. Insert a blank virtual disk (40TSS) into drive 1-4.
Ctrl+A ............ Cycle through artifacted video modes (hi-res only).
Ctrl+B ............ Load CoCo ".bin" binary file.
Ctrl+C ............ Quit emulator.
Ctrl+E ............ Toggle DOS emulation on/off - reset to take effect.
Ctrl+F ............ Toggle normal/full screen mode
Ctrl+H ............ Load ".hex" Intel HEX-record.
Ctrl+I ............ Insert a cartridge.
Ctrl+Shift+I ...... Insert a cartridge, no autorun.
Ctrl+J ............ Cycle through joystick emulation modes (None, Left, Right).
Ctrl+K ............ Toggle between Dragon and CoCo keyboard layout.
Ctrl+L ............ Load a file (see below).
Ctrl+M ............ Toggle between Dragon and CoCo emulation (resets machine).
Ctrl+R ............ Soft reset.
Ctrl+Shift+R ...... Hard reset.
Ctrl+S ............ Save a snapshot.
Ctrl+T ............ Insert ".cas" virtual cassette.
Ctrl+Shift+T ...... Insert virtual cassette and autoload first program.
Ctrl+W ............ Attach a virtual cassette file for writing.
Ctrl+Z ............ Enable keyboard translation mode (see below).

Loading a file with Ctrl+L autodetects the file type by extension, and
acts accordingly:

 * Disk files (".dmk", ".vdk", ".jvc", ".dsk") are inserted into drive 1.
 * Virtual cassettes (".cas") are attached.  If shift is also pressed,
   XRoar will attempt to autodetect their type and insert the appropriate
   load command ("CLOAD" or "CLOADM:EXEC") into the keypress buffer.
 * Hex records (".hex") will be loaded into memory.
 * CoCo binaries (".bin") will be loaded into memory and started from their
   EXEC address.
 * Snapshots (".sna") will continue from when they were saved.
 * Unrecognised filetypes are assumed to be audio files, and if XRoar
   is built with libsndfile, it will attempt to use them for cassette
   input.

Individual key bindings used for loading each type of file in previous
versions of XRoar have been kept for the moment as synonyms for Ctrl+L,
but this is deprecated and may be removed in future.

In translation mode, characters typed on the host keyboard are translated
into the correct keypresses required on the emulated machine to achieve
the same character.

Joysticks can be mapped with the -joy-left and -joy-right options.
The arguments are in the form of three pairs of numbers, each pair being
in the format "<joystick-number>,<index>".  The pairs map the X axis,
Y axis and fire button respectively, and the joystick number is optional
if previously specified.  For example, "-joy-left 0,1:0:0" maps axes 1
and 0 on joystick 0 to the X and Y axis on the left emulated joystick
respectively.  Button 2 of joystick 0 is mapped to the left fire button.

The default joystick mapping has changed from previous versions: to
get the old mapping (suitable for use with a PS2 adapter), run with
"-joy-left 0,3:2:0 -joy-right 0,0:1:1".

If you have no real joysticks, you can use joystick emulation (Ctrl+J)
to simulate a joystick with the cursor keys, with Left Alt as fire.

Attaching a virtual cassette for writing will always truncate that file
to zero bytes even if you don't then write anything, so be careful you
don't overwrite something important.  Tape files used for writing and
those used for reading are maintained separately.  The cassette used
for writing is closed on machine reset, but the read image is kept open.

Many games make use of the fact that NTSC exhibits very bad cross-colour
artifacts in regions of high frequency luminance.  The "-ccr" option can
choose between two cross-colour renderers: "simple", using a four-colour
palette, or "5bit", which consults a 5-bit lookup table (2 bits either
side of the considered pixel).  During operation, pressing Ctrl+A will
cycle between "off" and the two phases a typical NTSC television would
sync to on machine reset.

Some games generate audio by switching the sound select lines rapidly
(instead of writing to the DAC or the single-bit sound output line).
XRoar supports these, but at the cost of far more frequent updates
to the audio, meaning increased CPU usage.  The "-fast-sound" option
disables these additional updates (as a side-effect, this "cleans" the
audio for certain games that use the DAC for both joystick polling and
audio output).


GP32 CONTROLS

The controller can be cycled through four modes by pressing the left
shoulder button.  These modes are:

 * KEYBOARD - D-pad selects a key, B presses a key, hold down right
              shoulder button to press shift.
 * CURSORS  - D-pad map to Dragon cursor keys.  B is shift, A is space,
              right shoulder button is enter.
 * RIGHT JOYSTICK - D-pad controls right joystick motion.  B is fire
              button.  A is space, right shoulder button is enter.
 * LEFT JOYSTICK - D-pad controls left joystick motion, with other
              controls as with right joystick mode.

At any time, pressing select will bring up a menu allowing you to load
a snapshot, toggle DOS emulation, insert a tape or disk, switch between
Dragon & CoCo, switch keymaps and reset the machine.  At present, there
is no way to save a snapshot, but you can generate them with the Unix
version and upload them.

If the tape is accessed (eg, you typed 'CLOADM' or 'CLOAD'), you need
to remember to insert a cassette file (".cas") from the menu.


NINTENDO DS (NDS) CONTROLS

The touch screen interface is currently quite basic, but functional.
Files can be loaded by selecting "Load...", the emulated machine can be
changed in the "Machine configuration" menu, and snapshots can be taken
with "Save snapshot".

In the "Input configuration" menu, each of the DS buttons can be mapped
to an input function - a keypress, a joystick direction or an emulator
configuration command.  By default, the D-pad buttons are mapped to the
right joystick, and 'A' to the right firebutton.  'Y' swaps joysticks
for convenience, and 'Start' swaps the DS screens, allowing you to use
the touch screen as an analogue joystick input.


CASSETTE IMAGES

Tools exist online to generate ".cas" cassette images, but they only
work under DOS (or presumably Windows).  Check the software section of
http://archive.worldofdragon.org/ for details.  That site also includes
quite a few titles that have already been converted for your convenience.
If you wish to play the game 'Buzzard Bait' (an excellent Joust clone),
you'll *have* to download the version there, because the original
required a dongle to be inserted, and obviously I don't emulate that.
Please note that site's usage requirements, and don't abuse the archive.

If libsndfile is detected while building, XRoar will use it to support
cassette loading from audio files.


SNAPSHOTS

Snapshot files are *not* compatible with the traditional ".pak" files
used in other emulators.  I may support them in future, but the file
format looks pretty horrible.  This snapshot format is subject to change,
but a snapshot made in this release may well work fine in later ones.
At the moment, the most reliable way of loading programs is to use
cassette images or virtual disks, but you'll probably want to generate
snapshots for your own convenience.


COPYING

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

See the file 'COPYING.GPL' for the full terms.

Binary distributions only:

Binary distributions of this software may be linked, statically or
otherwise, against the SDL and/or libsndfile libraries.  Both packages
are distributed under the GNU Lesser General Public License, Version 2.1.
Source code for these libraries is made available from their respective
home pages, but also from the XRoar home page (see above for URL).

See the file 'COPYING.LGPL-2.1' for the full terms.

http://www.mega-nerd.com/libsndfile/    - libsndfile home page.
http://www.libsdl.org/                  - SDL home page.
