• Status Closed
  • Percent Complete
  • Task Type Patches
  • Category Games
  • Assigned To No-one
  • Operating System iPod 5G
  • Severity Low
  • Priority Very Low
  • Reported Version Version 3.3
  • Due in Version Undecided
  • Due Date Undecided
  • Votes
  • Private
Attached to Project: Rockbox
Opened by torne - 2009-06-22
Last edited by torne - 2010-01-17

FS#10370 - New plugin: frotz, a z-machine interpreter

I've started working on porting frotz to Rockbox. The port is not done yet but is able to run a simple test program. Frotz is a Z-Machine interpreter - it plays games in the Z-Machine format such as Zork and the other Infocom text adventures, and more modern interactive fiction.

Actually typing on a player will be difficult (line input is not yet implemented at all so hey) but there are various aids that can be done later to make it a little easier. Once the interpreter is ported I intend to write libraries for Inform to help people produce games more suited to Rockbox player controls, but it should still be able to run standard text adventures if people can put up with the UI :)

Currently it builds (there are many warnings in stubs.c but that is temporary code) and can run gntests.z5 (from the Frotz test suite) which tests a few bits of z-machine spec compliance. The button mappings have been hardcoded to suitable values to control gntests.z5 for now, and have only been mapped for ipodvideo, other platforms are likely to not build because of this. If you want to hack in some different mappings, it's trivial to modify frotz.c to include any half-dozen buttons you like :)

A large plugin buffer is required in any case: currently all buffers used for loading story files and the like are statically allocated and thus frotz.rock needs over 256kb of memory, so it will only work on targets with 512kb+ plugin buffers. This may be addressed later :)

Closed by  torne
2010-01-17 22:43
Reason for closing:  Fixed
Additional comments about closing:   Warning: Undefined array key "typography" in /home/rockbox/flyspray/plugins/dokuwiki/inc/parserutils.php on line 371 Warning: Undefined array key "camelcase" in /home/rockbox/flyspray/plugins/dokuwiki/inc/parserutils.php on line 407

Committed (with further fixes and enhancements) in r24267/24268

torne commented on 2009-06-22 14:21

Oh, forgot to say, this is based on frotz 2.43 if anyone wants to compare it to the original code. The main frotz code is GPL v2+ and the dumbfrotz code is "any use permitted provided copyright notice stays intact", so including it in RB shouldn't be a problem.

I really like the idea of this plugin.
I really love text adventure games, particularly zork. I have been looking for an interpreter for my mobile phone for ages for them, but haven't been able to find one.
Unfortunately I guess as I am a blind rockbox user I can't really make use of this plugin yet because plugins are not voiced, and also there is no true screen reader in the core of rockbox.
Unfortunately that idea got dumped as a gsoc idea for this year which personally I think would have been a lot better than one or two of the ideas that got picked, but still never mind maybe it can be worked on next year if the project applies for gsoc, or maybe someone will decide to have a go for the sake of it.

Regarding your comments about the input of commands being a problem, I don't know how easy this would be to work on, but perhaps you could read the games vocabulary file from the z file and load it into some kind of menu so a user can just select particular words from a menu to form there commands.

Or another idea could be that a user could have some kind of text file on the player listing commonly used words in the game such as take, look and various directions that could be selected from a menu.
That would also speed up inputting of commands. I guess though if you can some how read vocabulary from the game file and put it in a menu that would be the best solution.
I would be very interested in discussing interface issues with you though, and if possible making it accessible to blind rockbox users.

torne commented on 2009-06-24 10:16

Since I am effectively implementing a text console it would be possible for me to interface with a screen reading API rather easily, if someone actually implemented one for Rockbox. I'm willing to take any recommendations people might have about how to make this accessible, though obviously actually finishing the basic port is the priority for now.

The ports of Frotz on the Gameboy Advance and other similar platforms already use things like command lists and picking previously printed words from the screen to type; I will probably implement some of these later.

Reading the game's dictionary is possible in a limited way; Infocom's games use a single dictionary which is pointed to by the game header. Inform games, especially those developed with Inform 7, can use multiple dictionaries and there is no way to find the additional dictionaries beyond reverse engineering the entire game, but the main dictionary usually contains most/all of the words (the others are for use in special contexts only). The problem with this approach is it's a massive cheat: knowing what's in the dictionary is a rather big hint in a lot of games, and usually spoils all the easter eggs (xyzzy and similar magic words). Dictionary words are also truncated to 9 Z-characters (which may be less than 9 actual input characters if the word includes accents or other non-standard symbols), which means displaying longer words would look weird :)

I don't know of any plans to integrate a screen reader into rockbox unfortunately, it was discussed as an idea this year for gsoc but not selected as an idea which i think was a shame, some possible candidates for integration were even talked about but nothing was done.

I realise that reading a games dictionary and allowing words to be picked from a menu would be a problem and possible spoiler, but I guess on the other hand entering words by selecting individual letters from a list would be extremely time consuming and annoying.
I should think that the problem would be if a user had to create a text file with words they wanted to be able to select they wouldn't know half the time what words they should enter into such a file.
Perhaps what you could do would be to make reading the games dictionary optional where it is possible so ask the user if they want to make a list of words to select from a menu at the start before they actually begin playing the game. If they say no, then they can select letters from a list to form there words.

unfortunately I can't help with testing the plugin at the moment even though I would love to because of accessibility issues, but perhaps in the future if a screen reader is ever integrated into rockbox I will be able to help with testing.
As at the moment, there are not many games within rockbox that would be accessible to me apart from the card games, chess and sudoku, and those will not become accessible until another patch is committed that is designed to make plugins accessible.
Though this would be of little help with this plugin because of the vast amount of text being displayed, a screen reader would be required to allow me to make use of it.

torne commented on 2009-06-25 09:43

Ultimately I was intending this to be a platform for games development, rather than just to run existing Z-machine games. I have an interest in developing interactive fiction and rather than invent a new system for it based around the capabilities of Rockbox, I decided to just reuse a time-tested design. Being able to play Zork is a bonus :)

When I get as far as implementing smart input capabilities I will see what I can do about stealing from the game's dictionary. I've played a couple of games in the past using the GBA - one feature that made that far more tolerable was the ability to hit a button to switch to a mode where you can move the cursor around the screen and select any word already printed, and have it typed for you. This covers a pretty large proportion of nouns in most text adventures as it's very common for them to have been printed shortly before you want to refer to them, and a preset menu works pretty well for most cases of verb. Exactly how tolerable the combination of all these features would make it is something I'll have to find out when it's done.

As far as accessibility goes, it's not technically impossible to disassemble a story file and discover the location of all its strings, at which point you could convert them to a voice file and then play it back that way… it would be quite a bit of work, and would only really work for older games: games written with Inform 7, or using more advanced capabilities of Inform 6, generate quite some amount of text at runtime either by printing to internal buffers, assembling it a character at a time, or reprinting bits of user input even if they were not in the dictionary :) Just a thought, not something I would really have time to develop myself I'm afraid…

Unfortunately I don't have the skills needed to disassemble story files, so I guess my best bet is to hope that someone does eventually integrate a screen reader into rockbox.

It sounds sensible to me to reuse a tried and tested system, after all why reinvent the wheel, making a system just for rockbox.

Do you happen to know of any z interpreters for symbian series 60 third edition mobile phones? as I would really like to be able to play games on my mobile when I am out and about, but I have done a lot of googling and haven't been able to come up with anything.

torne commented on 2009-06-26 09:49

I'm afraid I don't know of one, but I'll ask around (I work at Symbian/Nokia *g*).

If you could ask around I would appreciate it.
I know there is an interpreter for second edition phones, unfortunately though it is not accessible with a screen reader,
as unfortunately on mobile phones a big problem is that even if an application exists a lot of the time it is not accessible with the phones screen reader, but still if you do find out about an interpreter for third edition I will give it a go.
Playing games on my mobile would be quite easy for me as I have a nokia e90 which has a proper keyboard, so inputting words would be fairly easy if an interpreter exists. I would be interested in an interpreter for any form of interactive fiction.

Any progress?

torne commented on 2009-07-15 10:35

I have a slightly improved version but it's still not able to run real games and I don't have the code handy here to post an updated patch. I've been busy with real life and with reverse engineering the Gigabeat S bootrom. :)

torne commented on 2009-11-27 01:03

Here's the latest version. Character and line input now works, which means that games may be playable. I am able to play Curses! by Graham Nelson for several commands before I get bored of the incredibly slow keyboard input and quit. It still only has button mappings for ipodvideo but I will probably be switching it to pluginlib actions next. There are a few rendering glitches with inverted text, it looks like, also, but they are minor.

Anyone who wants to test this is encouraged to try it with any .z5 game they feel like; just about anything should work in theory except for z-machine hacks which rely on input timeouts (this is not implemented).

   frotz.diff (246.7 KiB)

I tested this on my Fuze after making a couple changes for the keys. Everything seemed to work fine until I got eaten by a grue. I think this is pretty cool but it would be a big improvement to add some way to quickly insert words from the text or commonly used commands into the starting keyboard string. Text wrapping needs some work. It looks like you get an extra blank line when there's a space where it wants to break lines.

Cool this plugin is still active

torne commented on 2009-11-28 16:50

Text wrapping works fine for me; it's not implemented by my code at all, frotz handles the screen model. Got an example game I can reproduce this with? Not all z-machine games will run correctly on such a narrow screen; some of them assume a higher minimum width than the screen size of many rockbox targets.

Better ways to input text are possible, but not until I've finished porting frotz as-is. It's still missing colour, timed input, control/hotkeys, transcripts, saving, etc

I tried Werner's Quest from I tried Curses and it wrapped OK. Maybe it was just the game.

torne commented on 2009-12-20 22:15

New version. Tidied up a lot, it now grabs the plugin buffer for the story and if that's not enough, steals the audio buffer, so it should work on players with less memory - I have set it to build for all targets with an LCD display. Quitting is now handled properly and doesn't leak filehandles. Key mapping is now done using pluginlib actions' "generic" button mapping; to enter text press the "start" button (play on ipod), to press enter for single key input e.g. "more" prompts, press the "fire" button (select on ipod). This mapping only has four buttons (quit/menu/start/fire) so it should work on every target.

It should be able to load and run any z1 to z8 game, not just z5, now. There are still some display issues with some games, but I'm not sure which are caused by the game not expecting such a narrow display and which may be bugs, I'll investigate some more.

Saving/loading is still not implemented, nor is undo, unicode, or colour. See the STATUS file in the source for a full list.

I'd particularly appreciate someone testing this on a low memory target.

torne commented on 2010-01-02 19:32

Nearly done for a first version. Now supports saving and loading games (also transcript recording and command recording). Also supports timed input so Z-machine hacks will work - the input timeout stops as soon as you press the button to go into the virtual keyboard, as it would be rather unreasonable to expect anyone to type on that keyboard with a time limit :)

The display issues went away for a while but came back; I suspect something is uninitialised or otherwise dodgy causing it to behave differently depending on exact alignment/locations in memory of some variable. Other than that bug the only missing feature for the first version is undo, which needs me to work out some memory allocation scheme. It should probably be turned into an overlay plugin for the benefit of the targets with too small a plugin buffer, though.

torne commented on 2010-01-03 00:21

Apparently the rendering glitches with quote boxes in Curses are a bug in Curses, not my output code. It went away because there are several quotes displayed randomly when the game starts, and some of them are different widths. The ones which are too wide for the narrow display are displayed incorrectly. Nothing we can do about it, the Z-machine spec says that screens should ideally be at least 60 characters wide and 14 lines long, which we can't do with sysfont even on ipodvideo.

torne commented on 2010-01-05 23:43

Add a manual entry, fix file handles leaking when the interpreter crashes, enable command playback, and various code tidyups.

This is now complete for a first version, with the exception that it currently does not compile for targets with a very small plugin buffer such as Archos. It needs to be made into an overlay plugin a la Goban on those targets.

torne commented on 2010-01-08 16:16

Not going to make it an overlay for now because it doesn't build on archos anyway; pluginlib_exit is not supported on SH and I don't know anything about SH to implement longjmp on it. There are some bugs left in timed input handling, though, which cause spurious keypresses, and the [more] prompts are not handled very well with respect to the menu.

torne commented on 2010-01-17 22:42

Bugs mentioned in the above comment have been fixed in the commited version, as well as several failures in the z-machine compliance tests.


Available keyboard shortcuts


Task Details

Task Editing