Filfre: A Windows Interactive Fiction Interpreter



Introduction
The File Menu
The Edit Menu
The Options Menu
The Windows Menu
The Help Menu
Some More Convenience Features
A Beginner's Guide to Playing Interactive Fiction by Federick Ramsberg
Change Log
Distribution and Licensing
Thank Yous
Feedback


Introduction

Filfre is a program for playing interactive fiction stories, also known as text adventures. These stories are available in a variety of different formats. Filfre supports the most long-lived and common of these, the Z-Machine, as well as a newer virtual machine called Glulx that is a successor of sorts to the Z-Machine. 

The Z-Machine format was invented by a pioneering computer game company called Infocom in about 1980, and used by them for 35 or classic games. Following Infocom’s demise in 1990, members of the free interactive fiction community reverse-engineered the format to allow interpreters like this one, and then developed a brand new development language called Inform to allow new Z-Machine games to be written. Today there are literally hundreds of Z-Machine stories available for free, many of strikingly high quality.

Glulx was created by Andrew Plotkin in the late 1990s as a response to the greatest weaknesses of the Z-Machine, namely its restrictions on the allowable size of the stories it plays and its lack of support for modern, high-quality graphics and sound. 
 
Filfre supports versions 3, 4, 5, and 8 Z-Machine story files, either as standalone files or compiled into the Blorb IF packaging format. This encompasses the vast majority of all Z-Machine stories ever released. Support for graphical games, known as version 6, is not provided, due to certain features of this interpreter that are incompatible with that format. As of this writing, only five finished games in that format exist, however, and there is no reason to expect more in the future, as the newer Glulx format’s much superior multimedia support makes it the preferred format for stories using these features. Other available interpreters can be used to play version 6 Z-Machine stories, should you desire to do so.

Filfre supports the latest (as of this writing) version of the Glulx virtual machine, 3.1.2. Games created for earlier versions of Glulx are completely backward compatible with the latest version.

Filfre should run on most installations of Windows from Windows 95 on, but only Windows 2000 and beyond are “officially supported.” Certain features may behave oddly on Windows 9X installations, and Unicode support will be spotty at best.

Older, slower machines might run newer works of IF, particularly those produced with Inform 7, somewhat sluggishly, and may choke entirely on some multimedia-intensive Glulx stories.
 
Back to Table of Contents

The File Menu

Restart Story
Restart the currently loaded story from the beginning.

Open Story (CTRL+N)
Load and begin playing a new Z-Machine or Glulx story.

Restore Game (CTRL+O)
Load a saved position and begin playing from there. This saved game must of course belong to the currently loaded story. This menu option is the same as entering RESTORE at the command prompt.

Save Game (CTRL+S)
Save your position in the current story so that you can return to it later. There is no limit to the amount of saves you can keep for any given story. This menu option is the same as entering SAVE at the command prompt.

Transcript
Begin creating a text file containing all text output by the game to the main window, and all commands entered by you. The end result is a history of your session. If the text file you choose to write to already exists, Filfre will give you the option of overwriting that file completely or of appending its text to the end of the file. When scripting is in progress, a check mark will appear next to this menu option. Choose it again to halt the transcript. This menu option is the same as entering SCRIPT at the command prompt.

Recently Loaded Story Files
For your convenience, Filfre stores the four most recently loaded stories as entries in the file menus. Simply select one to automatically load that story.

Exit (CTRL+Q)
Close Filfre.

Back to Table of Contents

The Edit Menu

Undo (CTRL+Z)
Undo the last turn of the current game. This menu option is only available if the loaded story allows it. Choosing this menu option is the same as entering UNDO at the command prompt.

Copy (CTRL+C)
Copy the currently selected text from the main window into the Clipboard. From there, it can be pasted into any word processor or text editor.

Paste (CTRL+V)
Paste the current contents of the Clipboard into the Filfre command prompt. You can also make a word from Filfre’s main window appear at the command prompt by simply double-clicking it.

Select All (CTRL+A)
Select the complete contents of Filre’s current scrollback buffer. You can then use Copy to copy it to the clipboard for pasting into the word processor or text editor of your choice.

Find (CTRL+F)
Search for text within Filfre’s history buffer.

 Back to Table of Contents

The Options Menu

Fonts
Choose the fonts Filfre uses for various purposes. The Text Font appears in the main window. The Status Font is used for the status bar that appears at the top of the screen in most stories. Other Fonts are used in the additional, “meta-data” windows that Filfre can optionally display. Under certain rare circumstances, Filfre may override your font choices if they are not suitable for the story you are playing. Infocom’s Beyond Zork, for example, displays properly only with a very limited subset of Status Fonts. 

Colors
Choose your preferred background colors for Filfre’s various windows. Individual stories may override your choice of colors, if you choose to allow this.  Two colors are used on the status line, of which the first is much more commonly seen. Note that your color choices can be overridden by stories that use custom colors if the option “Allow Story-Defined Colors” is enabled. See below for more information.

Margins
Set Filre’s left and right margins, in pixels.

Timer
Filfre can optionally display a timer for your current session. This timer automatically resets if the current story is restarted from the menu, or if a new story is loaded. Restarting by typing RESTART at the command prompt does not affect the timer. You may also pause or reset the timer manually from this menu. (Clicking the timer display on the status bar will also pause or restart the timer.)

Show Warning Prompts
If this option is checked, Filfre will warn you and give you a chance to cancel any action which could potentially be destructive to your current game. Otherwise, Filfre will assume you know what you are doing at all times.

Show More Prompts
If this option is checked, Filfre will pause output any time more than one full screen of text appears between inputs to allow you the opportunity to read that text before it scrolls off the screen. Even if this option is not checked, you can of course read long chunks of text by scrolling the window back somewhat.

Display Frontispiece (if available)
Some recent story files are packaged in the so-called “Blorb” format, containing bibliographic information as well as a “back cover blurb” and possibly even “cover art.” When this menu is checked, Filfre will automatically display this information in a separate window when you begin to play one of these stories.

Back to Table of Contents

The Windows Menu

Verbs
Display a list of all verbs allowed by the current story. Click on any verb in the list to have it appear at the command prompt. You can customize the appearance of this list. All verbs listed in Filfre’s verbs1.ini file that are present in the current story will appear first. All verbs listed in Filfre’s verbs2.ini file that are present in the current story will appear next. All other verbs in the current story will follow. Synonyms for already listed verbs are not included.

Helper Words
Display a list of commonly used prepositions. Click on any word in the list to have it appear at the command prompt. You can customize this list by editing the file helpers.ini to contain the words you would like to see here.

Compass
Display a navigation compass. Click on a direction to have your character attempt to move that way.
 
Back to Table of Contents

The Help Menu

Help Topics
Display this file.

About this Story
If the currently loaded story was distributed with a frontispiece containing bibliographic data and other “cover art,” this menu will be accessible, and can be used to display this information at any time. This is the same display that will appear automatically at the beginning of a story if the “Display Frontispiece (if available)” menu item under “Options” is selected.

About
Display some information about the version of Filfre currently running.
 
Back to Table of Contents

Some More Convenience Features

Filfre incorporates a number of other features that will hopefully make playing IF easier for those who prefer the mouse to the keyboard. In addition to making use of the verb, preposition, and compass direction shortcut menus, you can also:

•    Double click on any word in a story’s text to have it automatically input into the command line, just as if you had typed it.
•    Paste text from the Windows clipboard into the command line.
•    Access a history of your previous 100 inputs by pressing the up and down arrow keys.
•    You can also access the history using TAB completion. Press the TAB key on a partially completed command line to retrieve the most recent command (if any) that matches what you have typed so far.
•    If you have a three-button mouse, the middle button will function as the enter key

Back to Table of Contents

A Beginner’s Guide to Playing Interactive Fiction by Fredrik Ramsberg

The material below is excerpted from Fredrik Ramsberg’s “A Beginner’s Guide to Playing Interactive Fiction.”  The full text is available at http://IFGuide.ramsberg.net.

The Game Starts

When you start a game, you will first see an introduction, usually consisting of one or a few screenfuls of text, giving you some background on who you are, where you are, and perhaps even what your objectives in the game are. Whenever the game has printed a screenful of text, it will wait until you press ENTER or some other key, so that you get a chance to read everything before it scrolls off the top of the screen.

How to Interact

When the introduction is over, you will get a prompt, usually “>”, but it may be a little different from game to game. The prompt means that the game is now waiting for you to tell it what you want to do. You do this by typing in imperative commands, as if you were commanding someone. Let’s say the introduction told you that you are in a kitchen, and that you can see a closed glass jar standing on the kitchen counter. Commands you could try at this point include TAKE THE JAR, or OPEN THE JAR, or perhaps EXAMINE THE JAR (Throughout this document, things that are written in capital letters with an italic font are complete commands that can be typed into an IF game. They don’t have to be typed in capital letters when entered into a game). If you want to, you can skip the articles: TAKE JAR will work just at well as TAKE THE JAR. If there are several different jars you could mean, the game may ask you which one you mean. Just type one or more words that uniquely identifies one of the items. For instance, if the game says “Which one do you mean, the blue glass jar or the green glass jar?”, you might reply BLUE to take the blue one. You can also choose to ignore the question altogether, just typing a new command.

Movement

To go to another location, most games expect you to type in which direction you want to go. You can type GO SOUTH, but just SOUTH will also do the trick, as will S (which is the commonly accepted abbreviation for SOUTH). Other directions and their abbreviations are NORTH (N), EAST (E), WEST (W), NORTHEAST (NE), SOUTHEAST (SE), NORTHWEST (NW), SOUTHWEST (SW), UP (U), DOWN (D), IN and OUT. If you are aboard a ship of some kind you may also be able to use FORE, AFT, STARBOARD and PORT.

Other ways to move around may include commands like ENTER CAR, GO CAR, SIT ON MOTORCYCLE, GET ON BIKE, CLIMB ONTO SHIP, JUMP ONTO PLATFORM, DIVE INTO LAKE, BOARD SHIP, EXIT CAR, EXIT, LEAVE, GET OUT. Exactly which commands are recognized vary from game to game as well as from situation to situation in those games. When interacting with IF games, always try to express yourself as simply as possible. If you have tried several ways of expressing yourself and the game refuses to understand what you want to do, you are most probably on the wrong track; it’s time to try something completely different.

Common Verbs

As you know by now, you can use the verb TAKE to pick up items in the game. Of course, you can also use DROP to drop items. Most modern games actually recognize a hundred different verbs or more. With some of the most used verbs, you can also use multiple items, like this: TAKE GREEN BALL AND SCREWDRIVER or DROP ALL or PUT ALL BUT HAMMER IN BAG. You’ll find that ALL is often a very useful word, although it only works with certain verbs, most notably TAKE and DROP. Here are some of most important verbs, with examples:

LOOK or L -- L or LOOK AT BOB or LOOK IN JAR or LOOK UNDER BED
TAKE    -- TAKE KNIFE
DROP -- DROP KNIFE
EXAMINE or X -- EXAMINE KNIFE or X KNIFE
SEARCH -- SEARCH DESK
INVENTORY or I -- I
OPEN    -- OPEN DRAWER
CLOSE -- CLOSE DRAWER
LOCK -- LOCK DOOR WITH RUSTY KEY
UNLOCK -- UNLOCK DOOR WITH RUSTY KEY
ASK -- ASK JOHN ABOUT POLICE OFFICER
TELL -- TELL JOHN ABOUT MURDER
SAY -- SAY HELLO TO JOHN
GIVE -- GIVE RABBIT TO BOB
SHOW -- SHOW KNIFE TO POLICE OFFICER
WAIT or Z -- Z
AGAIN or G -- G

Other verbs you will need from time to time include ATTACK, BUY, COVER, DRINK, EAT, FILL, JUMP, KISS, KNOCK, LISTEN, MOVE, PULL, PUSH, REMOVE, READ, SIT, SLEEP, STAND, THROW, TIE, TOUCH, TURN, TYPE, UNTIE, WEAR. There are lots more. Hopefully they will seem natural to you when you need them.

How Time Works

Almost all IF games count time in turns, rather than hours and minutes. Every time you type something and press ENTER, one turn passes. This also means that until you press ENTER, no time passes. You could think of a turn as being something like a minute, but how long it actually is depends on what you do during that turn. If you want time to pass, but don’t want to perform any actions, just type WAIT or Z. This will prove useful while waiting for someone to arrive or something to get ready in the oven etc (in the game world, not in the real world!).

There are games that use real-time instead of turn-based play, but they are few and far between, and they will tell you about their real-time system at the beginning of the game.

Talking to People

The most useful ways of talking to people usually involve the verbs ASK and TELL. When using them, try to pin down the best keyword for what you are interested in, rather than longer constructs. For example, TELL BOB ABOUT HOW I SAW SHEILA GIVE A STRANGE AMULET TO ANOTHER WOMAN is not likely to yield any useful results, but TELL BOB ABOUT AMULET or perhaps TELL BOB ABOUT SHEILA may indeed be useful. In other words, you tell the game the subject you want to talk about or ask about, not exactly what to say. The game will try to make reasonable assumptions on what you want to say regarding the subject.

Also note that many games are quite primitive when it comes to modelling people. The author has to put in an enormous amount of work to make people in the game behave realistically and respond well to conversation. In general, don’t expect too much from people in the game, but there are of course games that shine in this area too. You’ll also see that some authors prefer menu-based conversation, to facilitate interaction.

To tell someone else to do something, type the name of the person, a comma, and then a command. Example: BOB, BREAK THE JAR. Just like in real life, most people won’t automatically do something just because you tell them to. If you think Bob knows what to do with the jar, you can also try GIVE JAR TO BOB or SHOW JAR TO BOB.

Special Verbs

All games recognize some verbs that don’t do anything in the game world, but tells the game something about how you want it to behave, or some special task you want it to peform. These verbs include:

UNDO     -- Takes back the last move you made.
QUIT or Q -- Ends the current game.
RESTART -- Starts the game over from the beginning.
SAVE -- Saves your current position to a file on disk.
RESTORE -- Loads a previously saved game position.
HELP or ABOUT -- Shows some information about the game and its author, in some cases even hints to some of the puzzles.
VERBOSE -- Tells the game you want a long description of every room you enter, even if you’ve been there before.
BRIEF -- Tells the game you want a long description the first time you enter a room, and a short description when you come back. This is the default mode.
SUPERBRIEF -- Tells the game you always want short descriptions of all rooms.

Getting Stuck and Unstuck

While playing IF, you will get stuck. This is part of the deal—where there are puzzles, there will also be stuckness. If you grow tired of being stuck in the same spot for too long, you can either type HELP in the game to see if there are any hints available, or you can ask other players for hints. A good place to ask for hints is the newsgroup rec.games.int-fiction. That’s also one of the best places to meet other IF players, discuss games you’ve played, get tips on games you should play and more.

Oh, one last thing about playing interactive fiction. Make a map as you play. You are very likely to need it.
 
Back to Table of Contents

Change Log

Version 0.90 (May, 2005)

•    Initial public release.

Version 0.91 (May, 2005)

•    Corrected a nasty bug that was causing stack overflow errors on certain Infocom story files.

Version 0.92 (June, 2005)

•    Added option to set margins.

•    DLL hell had led to Filfre being completely broken on Windows 98 and earlier. Fixed this by explicitly forcing Filfre to load RichEdit 2.0. Many thanks to Robert Dunn for information and code.

•    Added a little frame around the status window to make things look a bit prettier.

•    If Filfre was closed with the Compass window open, it would crash when next started up. The only way to correct this was to delete its registry entries. Fixed this.

•    Changed behavior of the compass so that clicking on a direction leads to the player immediately attempting to proceed in that direction. It is no longer necessary to press RETURN first.

•    Allowed Filfre’s main window to be made much smaller. Note that using too small a window may lead to a messed-up display in Infocom games and early Inform games that do not properly model their display on the player’s chosen window size.

•    Fixed Filfre’s wonky handling of the MORE prompt. This should now consistently work correctly, and the ugly and distracting “jumping” effect when dealing with large text dumps has been eliminated.

•    Modified Filfre’s handling of color to make it more logical and consistent. In games that tell Filfre they will use color, Filfre’s status line colors are now based on the player’s choice of text window background and font color. The player’s chosen status line colors are only used for stories that do not use color, or in all circumstances if the “Allow Story-Defined Colors” options is unchecked.

•    Fixed Filfre’s handling of Unicode. Assuming appropriate fonts are chosen, Filfre now properly supports the full Unicode character set. Input is possible of any valid Latin-1 Unicode character. These changes should make it possible to play non-English language games with Filfre.

•    Added story info for the following: All Things Devours, Blue Chairs, Earth and Sky, The Fire Tower, Goose Egg Badger, Mingsheng, Sting of the Wasp, and Whom the Telling Changed.

Version 0.94 (July, 2006)

•    Retired the Inventory and Objects in Area menus as interesting ideas that just weren’t worth the trouble. Double-clicking on words in the story’s text is almost as convenient anyway.

•    Added support for Inform 7’s Zblorbed story files, including display of frontispiece information.

•    Added a Select All option to facilitate easy copying and pasting of the entire scrollback buffer into a text editor.

•    Yet more work on Unicode support. At this point, I believe I am basically there on Windows 2000/XP systems, although I live in dread of someone telling me otherwise. Older Windows systems are not so complete in their Unicode support, but Filfre tries to step down gracefully.

•    A whole host of minor and major bug fixes, from random crashes to corrupted displays. Thanks to everyone who offered feedback on this stuff.

Version 0.97 (July, 2007)

•    Completely rewrote everything from the ground up to correct several annoyances that I couldn't deal with any other way.

•    Added full support for the Glulx virtual machine, including full graphics and sound support.

•    Added an option to allow the player to turn off MORE prompting.

•    Retired the Recording function from the File menu, as this can be done from the command line and this infrequently-used option just seems like added clutter.

Version 0.98 (January, 2008)

•    Increased the number of output windows allowed under Glulx from 20 to 25.

•    Fixed some problems with Filfre’s external file handling that were playing particular havoc with Inform 7 games that attempted to write out and restore tables.

•    Fixed some problems with Unicode support under Glulx.

•    Fixed a bug that would sometimes cause Glulx windows to not clear when requested to by a game.

•    When it sets up file associations, Filfre will now properly associate “.gblorb” files with itself.

•    Added a “Please Wait” message that appears during extended virtual machine processing to let the user know that the game is in fact doing something. Otherwise known as the Inform 7 Alert.

•    Fixed Ogg Vorbis music support under Glulx so that it now, well, works.

Version 0.981 (July, 2008)

•    Fixed a problem with Filfre’s Glulx random number generator that was causing it to return numbers slightly out of the range requested by games.

•    Fixed a bug that was causing Filfre to crash when trying to play certain sounds in Sherlock: Riddle of the Crown Jewels.

•    Fixed a veritable smorgasbord of bugs and glitches relating to Filfre’s color settings. It should now be possible to set colors and keep them set.

Version 0.985 (September, 2009)

•    Added Inform 7 Glulx acceleration functions and brought Filfre up to compliance with Glulx specification 3.1.1.

•    Fixed many small deviances from the Glulx VM standard. Test suites all now function correctly.

•    Resizing or closing the interpreter while a MORE prompt is up no longer leads to a potential crash.

•    Added command line TAB completion.

•    Z-Machine games now allow multiple UNDOs just like Glulx games.

•    Typing too long of a command line no longer leads to a potential crash.

•    Filfre should now work much better for impatient folks who start typing a command before the previous is finished processing.

•    One can now just click in the status bar to pause or restart the timer and to change from overwrite to insert mode and vice versa.

•    Pressing a CTRL-arrow key combination no longer leads to all sorts of interface strangeness.

•    Fixed bug whereby a "Please Wait..." prompt and snoozing cursor would sometimes get "stuck."

•    Fixed bug whereby a MORE prompt could get "stuck."

•    The frontispiece display now deals (slightly) more gracefully with very long author fields like that of Alabaster.

Version 0.986 (October, 2009)

•    Fixed tiny but nasty bug with one of the accelerated Glulx functions that led to a crash in at least one game.

Version 0.987 (November, 2009)

•    Filfre was misreporting that it could handle the FyreVM output system when in fact it cannot. Fixed this.

Version 0.988 (April, 2010)

•    Filfre was attempting to update file associations in a way that is no longer allowed for non-administrators running Windows Vista and Windows 7. This was causing a nasty crash for said users. Fixed this so that Filfre now conforms to the way that Microsoft wants us to do things.

•    Changed the help system to this nifty HTML file, rather than continue to rely on the archaic old Windows Help system that doesn't even come installed with Windows Vista and Windows 7.

Version 1.00 (March, 2011)
Version 1.01 (August 13, 2011)
Version 1.1 (January 10, 2013)
Version 1.1.1 (January 24, 2013)

  
Back to Table of Contents

Distribution and Licensing

Filfre was written from scratch by me, Jimmy Maher, with many starts and stops over a period of several years, and then rewritten from the ground up over a year beginning in mid-2006. Graham Nelson’s Z-Machine Standards Document was an invaluable help throughout the process, as was Andrew Plotkin's documentation of his Glulx virtual machine and GLK input/output standard.

Filfre’s source code is available from the Interactive Fiction Archive. Please note, however, that it was written using Borland’s C++ Builder development environment, and is heavily dependent upon Borland’s VCL libraries that accompany that product. Thus the source may be of limited use to you if you are not a Borland user. Also, the source is currently a mess of somewhat disorganized, generally uncommented code. 

You are free to use and give away Filfre as you see fit, and you are welcome to improve it or to incorporate parts of it into projects of your own. However, I do maintain copyright on the code that I have written. You are not allowed to remove my name from the program, and you must credit me should you incorporate any of my code into your own projects. You are not, under any circumstances, allowed to charge money for Filfre, nor are you allowed to distribute it with any commercial product without my express permission. In short, do not try to use Filfre in a money-making venture, and be sure to give credit where it is due, and you will be fine.
 
Back to Table of Contents

Thank Yous

•    To Infocom, for basically creating our modern notion of “literary” interactive fiction as well as the Z-Machine.
   
•    To everyone involved in reverse-engineering the Z-Machine following Infocom’s demise and creating the first free interpreters, then going on to make the creation of new Z-Machine games possible through the programming language Inform. Paul David Doherty and Graham Nelson only begin the list of names without whom Filfre, and possibly interactive fiction as we know it today, would not exist.
   
•    To Graham Nelson (again), for his thorough documentation of the Z-Machine format, documentation that became my Bible throughout my work on Filfre.

•    To Andrew Plotkin for his Glulx virtual machine and the GLK input-output standard it uses, and his careful documentation of both.
   
•    To Mark Howell for Ztools. These story-file analysis tools were invaluable in testing Filfre and confirming that it was doing what it was supposed to be doing.
   
•    To Robert Dunn, for his invaluable work with the arcane world of Microsoft’s various RichEdit libraries and their interaction with Borland’s VCL. I lifted his RichEdit 2.0 library into Filfre almost verbatum.
   
•    To Gustavo Daud for creating the DelphiPNG library. Since C++ Builder (and Delphi) lack out of the box support for PNG, this library saved me a huge amount of time and effort by allowing me to avoid rolling my own.

•    To Ian Luck's BASS sound system, which plays all of the sound formats supported by Glulx effortlessly, and saved me the uncounted hours I would have needed to spend implementing all of this myself.
   
•    To everyone who tried out earlier versions of Filfre and emailed or posted on the newsgroups with bug reports and suggestions.
   
•    To everyone in the modern interactive fiction community. I don’t know of any other place on the Internet so full of intelligent, creative, and helpful folks. To me, this community represents everything the Internet should and can be.
 
Back to Table of Contents

Feedback

I initially created Filfre for myself, both because no Z-Machine interpreter had the features I desired and as a way of honing my sadly atrophied programming chops. Now that it is basically done, though, I hope others will find it to be of interest as well.

I would love to hear from you, whether it be to suggest new features, to offer your thoughts on Filfre’s design choices, or to report the inevitable bugs that doubtlessly still exist. I can currently be reached at maher@filfre.net.

Thank you for trying out Filfre, and most of all thank you for helping to keep text adventures alive. Happy adventuring!

Jimmy Maher
April, 2010

Back to Table of Contents