criticalbeeb 0.1.0
------------------


INTRODUCTION
------------

criticalbeeb is a BBC B Micro emulator.  It is essentially the work of David Gilbert, 
who wrote the original UNIX version, with modifications by various people including 
Mike Wyatt, Richard Gellman and Dave Eggleston.  I took Dave Eggleston's beebem-0.0.11, 
added a menu for the GP2X, fiddled with the rendering code, wrote some key mapping code, 
added some key mappings, and here we are.  I took inspiration (and probably some code) 
from pspbeeb-v1.0.7, which was the PSP port performed by Ludovic Jacomme.

My contact email address is criticalhippo@gmail.com

Acknowledgements for GP2X port: squidge for his mmuhack, ryleh for his minlib, 
Karl Bartel for SFont, Adam Bedore for the menu fonts, Jean-loup Gailly and 
Mark Adler for zlib (when it's actually implemented), Acorn for producing the mighty 
machine in the first place, and finally Dave Moore for running www.stairwaytohell.com.

The licence for the main part of this release may be found in the doc directory,
and others are provided along with the source in the src0.1.0.zip file included.

Note that the main licence states that if changes are made, the new source *must* be 
distributed along with the binary.  Please respect this.


INSTALLATION INSTRUCTIONS
-------------------------

Copy all of the file included with this readme.txt file onto your SD card, 
maintaining the directory structure.

Put your BBC Micro disk images in the criticalbeeb/discs directory.  
They should be unzipped, have the extension .ssd or .dsd, and not be in any 
subdirectory - just in criticalbeeb/discs.

Disks may be tranferred from your originals by following the instructions 
at: http://www.stairwaytohell.com/index2.html.  
Games are also available for download from that site.


LET'S GO
--------

Start criticalbeeb.gpe

You are presented with the main menu.

* Sound options are between On, Off and Accurate.  Accurate sound emulation 
can result in latency (delay between on-screen event and the sound being 
played), but sounds nicer. Off can give a speed boost.

* Frameskip allows you to speed up emulation by not emulating every frame of display.

* Key mapping allows you to select a file that holds mappings between the 
GP2X's buttons and the emulated BBC Micro's keys.  Use joystick left and right to
go through the mappings, and press B when you have the one you want.  It will then
apply the new mappings, and display which buttons are mapped to which keys.

Some mappings for games I like are provided, and further information is given 
about the mapping system below (see "KEY MAPPING").

* State will allow you to load/save the current state of the emulated BBC Micro.  
At version 0.1.0, this is not yet supported.

* Selecting a disk: use the joystick left and right to go through the list of discs 
that are in your criticalbeeb/discs directory.  When the disc you want to play is 
shown, hit B.  The game will load and run.

* Quit will exit back to the GP2X menu.

Whilst the emulation is running, the GP2X's START button will take you back to the 
criticalbeeb main menu, pausing the emulation.  Pressing START again will 
resume the emulation.


KEY MAPPING
-----------

Since the virtual keyboard hasn't been implemented yet, button to key mapping
is currently essential to playing the games.  Inside the criticalbeeb/kbd directory
there are a number of .kbd files.  You can see inside default.kbd that they map
GP2X buttons and joystick directions to key names.  The key names follow the SDL key
naming forms largely, with a few extras to make life easier.

GP2X buttons supported: LEFT, RIGHT, UP, DOWN, A, B, X, Y, SELECT

Emulation keys supported (in the sense that it'll try to do something with them - 
clearly many aren't supported by the BBC Micro anyway): 

BACKSPACE, TAB, CLEAR, RETURN, ESCAPE, SPACE,
EXCLAIM, QUOTEDBL, HASH, PAUSE, DOLLAR, AMPERSAND,
QUOTE, LEFTPAREN, RIGHTPAREN, ASTERISK, PLUS, COMMA,
MINUS, PERIOD, SLASH, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
COLON, SEMICOLON, LESS, EQUALS, GREATER, QUESTION, AT,
LEFTBRACKET, BACKSLASH, RIGHTBRACKET, CARET, UNDERSCORE,
BACKQUOTE, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o,
p, q, r, s, t, u, v, w, x, y, z, DELETE, KP0, KP1, KP2,
KP3, KP4, KP5, KP6, KP7, KP8, KP9, KP_PERIOD, KP_DIVIDE,
KP_MULTIPLY, KP_MINUS, KP_PLUS, KP_ENTER, KP_EQUALS, UP,
DOWN, RIGHT, LEFT, INSERT, HOME, END, PAGEUP, PAGEDOWN,
F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, NUMLOCK, CAPSLOCK,
SCROLLOCK, SHIFT, CTRL, RALT, LALT, MODE, HELP, PRINT,
SYSREQ, BREAK, MENU, POWER, EURO

The supplied key mapping files have been tested to work with the following games:

barbarian.kbd: works for Barbarian
blast.kbd: works for Blast!
bugeyes.kbd: works for Bugeyes and Bugeyes 2
chuckieegg.kbd: works for Chuckie Egg (although you must redefine keys)
default.kbd: works for Snapper, Killer Gorilla, Repton, and probably lots more
exile.kbd: works partially for Exile (not all functions permitted - wait for virtual keyboard)
hobgoblin.kbd: works for Hobgoblin, Hobgoblin 2, Boxer, Scramble, and probably more (uses shift)
ricochet.kbd: works for Ricochet
starshipcmd.kbd: works for Starship Command
thrust.kbd: works for Thrust and Qwak

If you've added some for games you like to play, please mail them to me and I'll add them
to the distribution.

TODO
----

This is an early release of criticalbeeb.  It has a whole range of problems with it, 
but is playable for me, so it's being released in the hope that others might also 
enjoy it.  I welcome constructive criticism and bug reports, but please make sure 
they aren't already noted here:

Sound is poor.
Emulation is slow for some games.
Load/save states aren't implemented yet.
A virtual keyboard isn't implemented yet.
Screen not scaled properly for some games (Snapper loses last few lines, for example).
Filenames for keymaps and discs aren't alpha sorted yet.


VERSION HISTORY
---------------

20061006 - 0.1.0 first public release