Coming soon!

Inform 7 Interactive Fiction with Vorple

Introduction to Vorple

Vorple is a custom web interpreter and a set of extensions for that adds features to Inform 6 and Inform 7 by letting the Inform story file execute JavaScript commands in the browser where it’s running. Some examples of such features are font styles, tooltips, notifications, and popup modals, but the possibilities are virtually limitless. Take a look at the demo page for some examples.

For a more thorough explanation on how the system works, see chapter Vorple in depth below.

Known issues

The previous versions of Vorple worked only in the Z-machine format, which severely limited the size of the stories that were possible to write, especially with Inform 7. The current release is compatible with Glulx which in practice eliminates all size limitations. The latest version is still a preview, so while it’s stable and works, it hasn’t gone through rigorous testing and may contain unexpected problems.

These are the currently known major issues:

  • No Internet Explorer support — the system should support the latest versions of all major browsers, but the interpreter engine uses a feature that doesn’t work in IE 11.
  • Functionality in mobile devices hasn’t been thoroughly tested, and some features are known to not work on mobile devices, e.g. most of the sound system (although partly because of inherent restrictions in mobile browsers that can’t be fully circumvented.)
  • Some planned features are not ready yet. In Vorple Screen Effects setting font styles for the entire page isn’t implemented, neither is setting colors to an arbitrary value from inside Inform. The transient text feature is removed from the Screen Effects extension and will be included in a future text animation extension. Vorple Modal Windows has only the basic functionality.
  • Displaying text in an element that’s not the main text flow may cause insertion of additional line breaks to the story output in Inform 7. This may happen depending on the location in the Inform code where it’s executed.
  • The prompt is printed twice when the story ends.
  • Opening multiple modal windows in succession with Vorple Modal Windows may cause the modals to act erratically.
  • No status line – the status line extension is “almost there” but doesn’t work well enough to be published.

Also the technical documentation is incomplete. Most functions in the JavaScript API are documented in the code. Technical documentation is necessary only for developers who wish to integrate Inform with their own custom JavaScript code or other JavaScript libraries, so it doesn’t affect “normal” use of the Inform extensions.

The current list of known issues is for the interpreter here and for the extensions here.

Installation and usage

Getting started

First of all, you need Inform 7 which can be downloaded from its web site at inform7.com. From now on we’re assuming you know the basics of Inform, but if that’s not the case, a good place to start is the built-in manual or other available documentation.

(If Inform 7 isn’t to your taste, Vorple is available for Inform 6 as well; documentation here.)

In addition to Inform 7 we need the custom Vorple interpreter and the Vorple extensions. They can be downloaded from the download page. After downloading, you’ll need to install the interpreter and the extensions, and then install a local server so that you can play the stories you create. The instructions are in these two documents:

Inform 7 comes bundled with a previous version of the Vorple interpreter, and the Public Library extension repository hosts old versions of the Vorple extensions. You'll have to make sure your Inform project uses the new version of the interpreter and extensions. See the troubleshooting section of the installation guide if you run into problems.

The extension “Vorple by Juhana Leinonen” contains the basic definitions that are needed for the system to work. It’s required by all other extensions, so it’s the one extension that must be installed. Some extensions depend on each other, so installing all of them is recommended.

Using the extensions

Now that we have the extensions we can start developing. Let’s pick the Vorple Notifications extension which lets us show information on banners outside the actual story text. Start a new project and type the following:

Include Vorple Notifications by Juhana Leinonen.

The functionality of each extension varies, but in addition to including the extension(s) we need, the custom Vorple interpreter must be specified.

Release along with the "Vorple" interpreter.

As per the extension’s documentation we can display banners with a show notification phrase.

The Parade is a room.

 When play begins:
     display a notification reading "Welcome to Vorple!".

The release button

Time to see how it looks like! If we were to now click on the “Go” button the story would be compiled and run inside the Inform IDE. The problem is that the IDE interpreter is of standard Glulx variety which doesn’t support Vorple so we wouldn’t see the notification that way. Instead we have to click on the “Release” button to make the project generate a web page with the custom interpreter.

After Inform has compiled and built the release package, open a web browser and type localhost to the address bar. Remember to install a local server first.

If everything went as planned, we should now see the story start and our welcome message pop up in the top right corner of the web page.

From now on after making changes to the Inform code we can just push the release button, switch to the browser and reload the page.

A story compiled this way doesn't have debugging commands like ACTIONS or SHOWME available. To re-enable them, try the extension Extended Debugging by Erik Temple. Just remember to disable it again when actually releasing the story.

The extensions contain more detailed instructions on how to use them, so for example if you wish to add pictures or sounds to the story, open the Vorple Multimedia extension and read its documentation.

For more basic information, see the documentation for the core Vorple extension.

Compatibility with non-Vorple interpreters

The Glulx story files that use Vorple are compatible with offline interpreters and non-Vorple web interpreters. In most cases the Vorple-specific features just do nothing.

The story file can test whether it’s being run on the Vorple interpreter or not using an if Vorple is supported (or if Vorple is not supported) test:

When play begins:
     if Vorple is supported:
         show notification "Welcome to Vorple!";
     otherwise:
         say "Welcome to a boring old interpreter!"

It’s a good idea to make sure that a text-only version of the story works as intended, for accessibility and archiving purposes.

Vorple in depth

Back in the days when home computers first entered consumer markets there were many competing companies selling computers that weren’t compatible with each other. To maximize the amount of potential customers Infocom had to solve the problem of programming and distributing their games to a wide array of computers with varying specifications and limitations.

The solution was to create a virtual machine that would harmonize the differences between computer systems. The game file would always be the same for each system and there would be a system-specific interpreter program that would translate the game file into instructions the computer understood. This way the game could be programmed and compiled only once and it would work on any system that had an interpreter written for it.

Virtual machine inside operating system

The virtual machine was called Z-machine after Zork, the first game that used it. Decades later Inform 7 still compiles to Z-machine (and Glulx, the contemporary virtual machine that works basically the same way but with many of Z-machine’s limitations removed).

To a modern consumer of interactive fiction the virtual machine model has other benefits in addition to being able to play the stories in a wide selection of devices. The virtual machine is effectively a sandbox that limits what story files are allowed to do. They can’t, for example, delete files from the computer, install malicious software or access your webcam. When you download an interactive fiction story file you can be certain that it isn’t a virus and it can’t do anything harmful.

To an author of interactive fiction the sandbox can sometimes feel rather limiting. We’ve come a long way since the early days of Infocom and the things we now casually do with computers is far more than anyone could have dreamed of 30 years ago. Yet interactive fiction is still confined to streaming text, displaying pictures, playing sounds and performing some limited file operations.

Cue the Internet age. A modern web browser is also a sandbox, but with quite a lot of more capabilities (but still with restrictions in place so that in theory you can visit any web page and be sure that you can’t catch anything malicious).

Virtual machine inside web browser inside operating system

Parchment, the first wide-spread web interpreter, was a small revolution in itself and turned the community focus from downloadable story files to Internet play, but Parchment and other Z-machine and Glulx interpreters are still “only” implementations of existing virtual machines. They restrict the story files to the same sandbox as offline interpreters do.

This is where Vorple comes in. It makes a small addition to the interpreter so that the story files can break free of the sandbox and communicate with the browser that’s running the interpreter.

Vorple creating a bridge between the virtual machine and the browser

With this bridge in place the story file can do pretty much whatever it wants with the user interface and the story text — even story text that has already been printed.

Vorple’s Inform extensions use this feature to interact with the interpreter, the browser and the JavaScript libraries bundled with the Vorple interpreter package. For example, the Vorple Tooltips extension issues commands to the PowerTip library that displays the actual tooltips.

To accomplish this, Vorple uses a virtual filesystem. When targeting Glulx, Inform story files have a limited file read and write capability. The story file writes the JavaScript code to a specifically named file, and the Vorple interpreter captures these file writes and instead executes the JavaScript code.

The story file uses a similar system to decide whether it’s running in a Vorple interpreter. The interpreter provides a special (virtual) file for the Inform story to read. If the file exists and has the correct content, Vorple features can be enabled.

Support

The project’s headquarters are at vorple-if.com where you’ll find all the official materials and downloads. JavaScript developers who want to dig into the innards of the system can find the source code at GitHub.

The best place to look for assistance is the community forum at intfiction.org. Vorple’s author frequents the forum, as do other experienced authors who are happy to answer civilized help requests about authoring with Inform, Vorple or other systems.

Bugs can be reported at the project’s GitHub pages. Issues related to the interpreter should go to the main repository and issues related to the Inform 7 extensions to the I7 extensions repository. If you’re not sure which one to use, post to the extensions repository.

Vorple and all official materials are open source and free for anyone to use for any purpose. (Mandatory footnote: Do still read all the licenses if you want to use it commercially or as a part of a closed system. Some third party libraries, for example, are subject to slightly more restrictive licenses.)