GBAFrotz v1.15

History

NEW SINCE V1.1

NEW SINCE V1.0

Intro

GBAFrotz is as you may have guess a port of the popular ZCode interpreter "Frotz" to the Gameboy Advance. This allows you to play a large number of text adventures (now more commonly known as Interactive Fiction, or IF for short) compiled to this format. This includes all the classic Infocom games (Zork, Hitchhikers Guide To The Galaxy etc) as well as modern IF and even things that are not IF at all (Arcade games, dictionaries etc).

You may ask yourself how you can play a text-adventure on a platform with no keyboard? Well it's not easy, but I've been experimenting with a few features and I hope you'll give me feedback on them. More below.

Running

Either try it in an emulator (I'm not sure anything but Visualboy Advance SDL handles it) or on the real thing. To add files to the ROM, use the ADDFILES command like so;

ADDFILES.EXE <binfile> <file1> <file2>

Any files ending with ".zcode" will be recognized as story files that can be played (and shown in a menu). Any files ending with ".bmp" that matches a name of a zcode-files will be shown before starting the game, provided that it's a 240x160 8bit bmp that uses no more than 224 colors. Also note that you always need to add a few special files: 

keyb.dat
normal.font
fixed.font
And for games using the graphics-font (font 3) you also need: 
gfx.font
This is the keyboard graphics and the fonts. You can replace the fonts with others, just make sure that normal.font is proportional and fixed.font is monospaced.

For an example, look at the provided MAKEROM.BAT which creates an example rom.

Compability

Pretty good, but problems with newer games using graphcis or relying on at least 80 columns. However, It does play a lot of the newer game, and even games that are larger than the GBA memory, because I added virtual mem support to the zcode interpretor (which was easy because of the clean way it was written!).

The Keyboard

Now to the interesting bit; how to type in words?

The virtual keyboard

Pressing SELECT brings up the virtual keyboard, from which you can type most of the normal characters (and hopefully everyone you need in a text adventure). The basic idea is that you select a key group by combinations of the Left and Right shoulder buttons, and then you enter a specific key in that group by pressing either one of 8 directions on the direction pad, or one of the A & B buttons. This gives you a total of 50 possible keys - 5 combinations of keyboxes and 10 keys in each keybox.

Yes, 5 combinations. No buttons, Left, Right, Left+Right and Right+Left (meaning that when holding both shoulder buttons the order in which you press them is important).

I think the keys are logically mapped and it requires around three key presses for every two letters inserted which is pretty good for a GBA. Using the direction pad can be a bit awkward since it's not really meant for "clicking" but for pressing and holding. Note that the keys are "sticky" so any keys you press will be combined until you release all keys - otherwise it would be very hard to press the diagonals (which are really a comination of two keys).

The Smartkey System

When the keyboard is not showing, all input is handled by the smartkey device. This system lets you connect sequences of keypresses to ascii- values or special functions.

The default bindings should work well for most games but you can change them through commands in the config file.

Default behavour:

Line Editing
Simple line editing should work, Left and Right while outside keyboard mode moves the cursor and lets you edit the text.
History
Just pressing Up or Down from the prompt lets you navigate through earlier entered lines for editing.
General Shortcuts
Works both in virtual keyboard mode and outside:

Start = Enter
Right Shoulder + Start = Backspace
Left Shoulder + Start = Space
Right Shoulder + Select = Complete word

Screen grab
Press L+R together and the cursor will jump up to the screen allowing you to move between words and select one. Just pressing A on a word will insert that into the buffer and exit grabmode. B will do the same but stay. L+R again will cancel the grab.
Dictionaries
L,R,A or B + keys should insert verbs into the commandline. Check below for specifics. This also works while in grabmode.

Config Files

When you select a game to play, Frotz will look for a file in rom with the same name as the game-file except ending with "cfg" instead of "zcode". If that is not found it tries "default.cfg".

Config parameters

All parameters must be on a separate line with no spaces. Colors are ansi-numbers (0-15) but only (0-7) for foreground colors. 
fgcol=<color>
bgcol=<color>
Sets the forground or background color to <color>. Default is bgcol=0, fgcol=7 
fgrev=<color>
bgrev=<color>
Sets the reverse foreground and background colors. Default is fgrev=-1, bgrev=-1 (meaning just use the inverse of fgcol & bgcol). 
font=<fontfile>
fixed=<fontfile>
Set proportional and fixed font. Default is "normal.font" and "fixed.font"

Key bindings

Any line starting with "bind " defines a key-binding;

bind <sequence> <command> [mode]

The sequence is a string of letters, where each letter is either one of the 10 keys or a special flag. A sequence means pushing those buttons in order and keeping them pressed.

Sequence characters and meanings:
U Up
D Down
< Left
> Right
R Right Shoulder
L Left Shoulder
S Start
E Select
* Any keys
! Auto commit
Auto commit means this binding will take effect immidiatly when the last key in the sequence is pressed. Normally it doesn't take effect until all keys are released again.

The '*' symbol can (currently) not be followed by any other keys.

The command can be a number (meaning an ASCII code), a character enclosed in single quotes (meaning that character) or a special command. These are: 

GO_MODE0             Switch to mode 0
GO_MODE1             Switch to mode 1
GO_MODE2             Switch to mode 2
GO_MODE3             Switch to mode 3
HISTORY_UP           Show the previous line in commandline history
HISTORY_DOWN         Show the next line in commandline history
CURSOR_LEFT          Move the edit cursor left
CURSOR_RIGHT         Move the edit cursor right
SHOW_KEYBOARD        Go to virtual keyboard mode
COMPLETE             Complete the current commandline
MARKER_UP            Move the screengrab marker up one line
MARKER_DOWN          Move the screengrab marker down one line
MARKER_WORDLEFT      Move the screengrab marker one word to the left
MARKER_WORDRIGHT     Move the screengrab marker one word to the right
MARKER_INSERTBACK    Insert the current marked word into the commandline
                     and go to the precious mode
MARKER_INSERT        Insert the current marked word into the commandline
GET_DICT0            Insert a word from dictionary 0
GET_DICT1            Insert a word from dictionary 1
GET_DICT2            Insert a word from dictionary 2
GET_DICT3            Insert a word from dictionary 3
The optional third argument is 'mode' and indicates that the binding should only be used in that mode (default is mode 0).

The modes are used to have different bindings for different modes and jump between them. For instance the default bindings used mode 1 for screengrab.

There is a special mode 4 that is only active when frotz is reading a single key instead of a line. The default key bindings bind the cursor keys to cursor movement and history, but in mode 4 they are bound to keycodes 129-132 which is Frotz keycodes for cursor-movement. This makes sure (for instance) the menu in Beyond Zork works.

For default bindings check default.cfg. Note that the provided default.cfg in it's current form is redundant, as that is the default internal settings that would be used even when no config file was found. Also note that if you specify any bind commands in your config, all of the default ones will be removed (so you always have to specify the full set).

Verbs

These are the the four available dictionaries (you will be able to change them in coming versions):

Dictionary 0 (Bound to L+(Directional, A, B) per default)

Dictionary 1 (Bound to R+(Directional, A, B) per default)

Dictionary 2 (Bound to A+(Directional) per default)

Dictionary 3 (Bound to B+(Directional) per default)

  • "load"
  • "score"
  • "save"
  • "wait"
  • "again"
  • "help "
  • "talk to "
  • "exit "

    TODO

    There's a lot that can be done to make it easier to play text adventures on the GBA. Any suggestions on how to improve the virtual keyboard and the shortcut system is appriciated. Ideas I already have include:

    Using dictionary to setup shortcuts (like the inventory or present objects) Smarter history (ie use last lines noun with a new verb) Formatted shortcuts (like "put %s on %s" lets you grab two things from screen)

    CONTACT

    Email: jonas@nightmode.org
    GBAFrotz Homepage

    -- Jonas Minnberg (Sasq / DCS)