Inform 6 library for Vorple now available

November 17th, 2015

Hugo Labrande has translated the Inform 7 Vorple library into Inform 6. The library uses the same web interpreter and offers the same functionality as the Inform 7 extensions, which means that Vorple’s full capacity is now available for Inform 6 authors.

The Inform 6 library can now be downloaded from the web site.

Vorple 2.5 highlights

April 25th, 2014

It’s been a while, but the next release of Vorple is now just around the corner! The release is scheduled for April 30th, which is also the planned release date for the next version of Inform 7.

Here are the new version’s highlights:

Improved sound support. The underlying audio engine has been replaced by SoundManager 2 which should support a wider range of browsers. There’s support for audio fades, and stopping or changing background music will fade out the previous track instead of stopping it abruptly.

It’s also no longer necessary to provide double copies of audio files (mp3 and ogg versions) to get the best browser compatibility. Only one mp3 file per sound should be enough.

Up-to-date libraries. The supporting UI libraries have been updated to their latest versions, along with Undum and Parchment. Undum has reached version 2 and Parchment supports a wider range of older story files (in case you want to use the Vorple interpreter as a general Z-Machine interpreter).

Better interpreter. Single character input is now supported. Vorple’s soft scrolling to the start of a new turn is more accurate with turns that span longer than one screenful. The Z-code story file can now communicate with the interpreter before Inform 7’s “when play begins” rules in case they need to set up things before anything in the actual story starts. The custom HTML input stream has been replaced by JavaScript functions that can now create nested HTML structures.

Tighter integration with Inform 7. This is mostly thanks to Graham Nelson, who added some crucial new features to Inform and suggested new phrasings that are more in line with the Standard Rules.

Inform now comes bundled with the Vorple 2.5 interpreter, so it can be used out of the box with the “Release along with the “Vorple” interpreter” option. The IDE can download Vorple extensions automatically from the extension repository, which makes any manual installation unnecessary.

Almost all phrases are reworded in extensions, and the extensions are renamed to comply with extension naming guidelines. Practically all projects that wish to migrate from the current version to the upcoming are going to have to change the wording for the Vorple phrases they use. (Fortunately it’s unlikely that such a massive name change is going to happen again in the future.)

Including custom JavaScript and CSS files is now easier. Instead of the interpreter trying to include “vorple.custom.js” and “vorple.custom.css” JavaScript and style files, it’s now possible to add freely named files to the materials folder and use the new release options “Release along with Javascript …” and “Release along with style sheet …” Files added this way will be automatically included in the generated web interpreter.

What about Glulx? Well, there’s still no Glulx support, but after we get this release out the door we’ll start to work on a sustainable way to get the thing playing nicely with Glulx, especially now that Inform is rapidly growing beyond Z-Machine’s capabilities.

Vorple for Inform 7 out now

September 30th, 2012

A long time has passed since the last update, but now we’ve advanced the version and release numbers to 2.4 and Vorple works together with Parchment and Inform 7.

The new release is out now although the web page hasn’t been updated yet. Here are the direct links:

The release includes five extensions: Core, Hyperlinks, Multimedia, Notifications, and Tooltips. Each add features previously unattainable with any major authoring system.

Note that this is essentially an alpha release—as the documentation mentions, there are a lot of known (and unknown) limitations that will be fixed in later releases. It should still be a good taste of what the system is capable of.

Vorple for Parchment: The Inform 7 code

March 10th, 2012

In this post we see how Vorple looks like in Inform 7 code. The I7 source code of the preview can be seen here: source.txt

Basic usage

The goal is and has always been that for an IF author using Vorple should be as easy as using any other Inform feature. The minimum effort is to add the following two lines to any Inform 7 project:

Include Vorple Core by the Vorple Project.
Release along with the "Vorple" interpreter.

Just with this you’d get the default functionality like parser error folding, meta command notifications and layout improvements. For other out-of-the-box features like multimedia you’d add the relevant extension and use the extension-specific phrases to add those features to the story, just like you’d now use Glulx multimedia features or extensions like Glimmr.

For anything more complicated the sky’s the limit: Cook up your own JavaScript module and I7 extension, include it in the project and you can build whatever you want.

Note that the preview story’s code is not as clean as it could be: there are some things that just make sure that the preview works and they will be cleaned up in the future.

The Core extension

As described in the previous post, Vorple uses the proposed 1.2 specification of Z-machine with some custom additions. Inform 7 does not (yet?) support the 1.2 specification directly, so an extension called Vorple Core adds the missing elements using Inform 6 inclusions.

The Core extension also provides phrases that are used to manage the features. Starting from the most basic operations, raw JavaScript code can be inserted with the eval phrase:

When play begins:
    eval "alert( 'Hello world!' );".

HTML content can be added with a couple of phrases, for example:

say element "div" with class "intro";
say "Type ABOUT for more information." inside element "info";
say transient text "This line will be hidden the next turn.";

Since most of Vorple’s JavaScript methods return the desired result’s HTML code, they can be displayed with:

Display Vorple method " 'duck.png' )" in element "bird-image".

The other core features are fallback methods and turn types.

Fallback methods

As mentioned before, the Vorple-enhanced story files fall back to text-only versions on non-Vorple interpreters. You can test whether playing on Vorple with if Vorple is supported: ... Here we override an item’s text description with an image:

The painting is scenery in the living room. The description is "The painting depicts a tea party in a garden."

Instead of examining the painting when Vorple is supported:
    display image "teaparty.png", centered.

Using the “if Vorple is supported” test you can replace any part of the story with alternative content. Usually it’s used as above to provide a text-only substitution of a multimedia feature, so there’s a shortcut for individual phrases:

display Vorple method " '[YouTube id]', { width: 640, height: 346 } )" in a "div" element "television" or fall back to say "You watch the television for a while."

The (phrase) or fall back to (phrase) structure can be used for any phrases. The first phrase will be executed if Vorple is supported, otherwise the latter phrase is used.

Turn types

Output is displayed in the Vorple interpreter differently depending on what type it is: Normal action, parser error or meta (out of world) action. (The two other core output types are “undo” and “dialog”.) The Core extension handles these types automatically, but sometimes you might want to use custom turn types. The phrase to use is mark the current action (type).

Carry out crediting:
    try requesting the story file version;
    say "[bold type]Vorple[roman type] by Juhana Leinonen (MIT license)[line break] ...";
    mark the current action "dialog".

The crediting action is an action out of world, but the carry out rule overrides the default “meta” turn type and uses the “dialog” type instead which makes the output show in a dialog box.

Media extension

The preview uses a minimal media extension that can display pictures positioned in different ways. Here’s a short but complete example of a story’s intro that displays an image and a graphical initial:

"A Tale of Two Cities" by Charles Dickens.

Include Vorple Media by the Vorple Project.

There is a room.

When play begins:
    display image "people.png", centered;
    display image "initial-i.png", floating left or fall back to say "I";
    say "t was the best of times,[line break]it was the worst of times,[line break]it was the age of wisdom,[line break]it was the age of foolishness,[line break]it was the epoch of belief,[line break]it was the epoch of incredulity,[line break]it was the season of Light,[line break]it was the season of Darkness..."

(Notice how the graphical initial is replaced with a plain character “I” in offline versions.)

A picture of the resulting story with a title image and a graphical initial

You can see the example online here.

Vorple for Parchment: How it works

March 1st, 2012

Parchment’s method of displaying (Z-machine) story text is relatively straightforward. There’s a HTML element where all story text is added to as the story progresses.

Program flow with Parchment: Take input, parse command, display output

What Vorple does is that it treats the element where Parchment outputs story text as a buffer. The #parchment container is hidden and a #vorple container takes its role on the screen. Parchment takes user input, processes it, puts the output in the container and triggers a jQuery event Vorple is listening to. Vorple reacts to the event and pulls the buffer’s contents for further processing. Finally it displays the buffer contents in the appropriate place and clears the buffer for the next turn. Thanks to this technique Parchment itself requires very little to no modifications as it’s blissfully unaware of its UI being overridden.

By using the buffer the story text can be displayed wherever needed, not necessarily just in the scrollback. Each turn and each command are wrapped in elements that contain loads of semantical information, including the type of the command that triggered the response (parser error or normal action), the order of the turns, whether or not the command was later undone…

Program flow with Vorple: Parchment output is put into a buffer and moved to the screen through Vorple

The story file tells Vorple of what type the current turn is by calling the vorple.parchment.setTurnType() method at any time during the turn. If the player’s command was invalid, the story file sends vorple.parchment.setTurnType('error') along with the parser error. Now Vorple will add a parserError class to the turn’s container so that it knows to fold it away after the next turn. The author can also extend the feature with additional turn types.

Eval and HTML streams

Z-machine uses two to four streams, depending on the version. Stream 1, for example, is the story text output. Dannii Willis’s Z-machine 1.2 spec adds stream 5, the JavaScript eval stream, which lets the story file give JavaScript instructions to the interpreter. Essentially whatever the interpreter finds coming from stream 5 it evaluates as JavaScript. (Big thanks to Dannii who has also made an implementation of the eval stream in Parchment. Since the feature was ready-made, it cut down Vorple’s development time by months, and makes the story files compatible with other interpreters which I initially thought was not possible or feasible.)

In addition to the JavaScript stream, there has to be a way to add HTML elements inside the story text so that text can be manipulated and styled as necessary. The preview adds stream 6 which accomplishes this, although it’s not an optimal solution by any means: by sending for example string div transient info to stream 6 the interpreter understands the first word as the element’s name and the rest of the string as its classes and closes the tag immediately. The example string would become element <div class="transient info"></div>. Content to the element can be added with the JavaScript stream.

The JavaScript can be any valid JavaScript (at least at this point) or Vorple functions. Authors can also make their own story-specific Vorple modules, as demonstrated with this module used by the preview story’s alarm clock.

As mentioned in the previous post’s comments, the Glk Stylesheets specification determines how things will look like in the future. The Z-machine implementation should match the Glk specification as closely as possible, or at least the Inform syntax should be identical. This also means that Vorple will not support Glulx until Parchment has native support for Glk stylesheets.

Here’s an example of everything that the story file sends to the interpreter when we type X THERMOMETER for the first time in the preview story. Black text is stream 1 (normal story text), red text is stream 5 (JavaScript code), and blue text is stream 6 (HTML elements).

The thermometer shows that the outside temperature is span id795559607242 temperature $(".id795559607242").text("16 degrees Celcius");. Being a highly sophisticated device it also shows the wind speed, span id297333836310 windspeed $(".id297333836310").text("4 m/s");.

div id180186239553 transient info thermo-info $(".id180186239553").text("Type IMPERIAL to switch to imperial units and METRIC to switch back to metric units."); $(".thermo-info").html( $(".thermo-info").html().replace( /(imperial)/, "<a href=\"imperial\" class=\"command\">imperial</a>") ); $(".thermo-info").html( $(".thermo-info").html().replace( /(metric)/, "<a href=\"metric\" class=\"command\">metric</a>") );

Here the units are wrapped inside <span> elements, or more accurately the text is inserted in the created elements. Later the command IMPERIAL can change the content of these elements to match the new units.

In the last paragraph, which is first put into an element that colors and italicizes the text, the commands IMPERIAL and METRIC are made into clickable links. The links are interpreted as commands just as if the player would have typed them in with the keyboard. (The way how the text is turned into links is rather clunky and specific to the preview, mostly because of the HTML stream implementation’s limitations.)

The resulting HTML code (ignoring Parchment’s default markup) is:

The thermometer shows that the outside temperature is <span class="id795559607242 temperature">16 degrees Celcius</span>. Being a highly sophisticated device it also shows the wind speed, <span class="id297333836310 windspeed">4 m/s</span>.

<div class="id180186239553 transient info thermo-info">Type <a href="imperial" class="command">IMPERIAL</a> to switch to imperial units and <a href="imperial" class="command">METRIC</a> to switch back to metric units.</div>

Undum authors might recognize the transient class which is lifted straight from Undum and behaves identically: the text fades out at the start of the next turn.

On screen it looks like this:

An image of text displayed in the interpreter

Backwards compatibility is achieved by the story file checking whether the interpreter supports the new streams. If not, the story can supply alternative text-only content or just not display anything.

Next we’ll take a peek at how all this rather technical stuff looks like in Inform 7 code.

Preview of Vorple for Parchment

February 27th, 2012

Before we go any further, here it is: Vorple using Parchment to run a Z-machine story file created with Inform 7.

Preview of Vorple for Parchment

The preview is a recreation of the proof of concept from almost a year ago with only minor adjustments. The proof of concept used a custom two-word parser, but the preview runs on an actual interpreter with a proper library.

The system uses a JavaScript eval() stream from Dannii Willis’s Z-machine Standard 1.2 draft, along with some custom additions that allow the story output HTML tags. This lets the story file instruct Vorple how to display user interface elements and other features.

Interpreter enhancements

I’ve been able to include the feature I’ve wished for ever since I started playing IF: in the scrollback the previous turns are faded out so that the current turn stands out better. This makes it easier to see where to continue reading and less scanning with your eyes. A related feature is the addition of a smooth scroll animation to the bottom of the scrollback instead of an abrupt jump.

The big new thing is scrollback folding. If you enter an invalid command, the response is shown in a different style and hidden the next turn. The idea here is to keep the scrollback clean of noise so that only story-relevant content remains. Similarly any meta commands are displayed as notifications and not shown in the scrollback at all.

Note that this is mainly a tech demo and the behavior of these features will be later adjusted to fit.

Multimedia features

In theory any feature from the Vorple library can be added to the story. The preview uses mainly images and tooltips, but there’s no reason it couldn’t play sounds or create UI buttons.

Some of the features are created using plain JavaScript. A custom Vorple module has been made for the alarm clock. Some meta commands (ABOUT, CREDITS, TIPS) are put in a jQuery UI modal dialog which is not yet a part of the Vorple library.

Backwards compatibility

The interpreter will be fully backwards compatible with other story files (Z-machine only at the moment). Try for example Stephen Granade’s Fragile Shells. You get the same layout, current turn highlighting and smoother scrolling, although of course other features that require support from the story file aren’t available. (The status line is hidden and there are some glitches, most notably lockups if you try the in-game menus or when any time single-character input is required, but that’s all temporary.)

Not only that, but the Vorple-enhanced story files degrade gracefully to text-only versions. If you download the zblorb file and try it with an offline interpreter or with a non-Vorple installation of Parchment, you’ll get a text-only version of the same game (although not a very exciting one).

The story file can provide alternative content to multimedia features, showing text instead of images. Entire sections can be added or removed depending on the interpreter’s capabilities. In the non-Vorple version there’s a short explanation in the intro text that’s not in the Vorple version and so on.

The Future

As you can see from the preview, there are various smaller and larger issues that need to be ironed out. Internally things are bound to change radically as the related standards are still in a state of flux.

Most likely there will be one Undum-only release before a Parchment-compatible one, which will include the toolset for making stories with Inform 7.

The first release of Vorple

November 20th, 2011

It’s finally here: The first release of Vorple.

Some features have been left out from the first release, most importantly tabs, accordions, local video playback and multiple-choice link popups. It’s arguably better to have fewer features that work correctly than a large array of shoddily implemented features. More features will be added gradually in later releases.

Internet Explorer support especially for older versions is still spotty, but it will be improved in later releases.

No doubt there are still things that don’t work as they should and the early releases are essentially beta releases. Some things are bound to change later on. (Especially the button module that’s both undocumented and rather cumbersome to use at the moment.) The project’s source code is at Github. Bugs can be reported with the issue tracker there.

Now that the Undum version is out, work on the parser IF version can start. More on that later.

Considerations of time travel

September 14th, 2011

In my experience, writing code is at most 10% implementing the basic functionality and the rest of the time is spent taking care of exceptions. The same applies to authoring games and to making authoring tools. In the case of Vorple the single most imposing exception is that the stories can be saved and restored later, and in parser IF there’s the UNDO command that rolls the story back one turn.

Undum and Parchment handle save/restore differently. Undum saves the reader’s actions and replays the story from the start when the story is restored. Parchment saves the current story state and at restore jumps directly to that state.

From the UI standpoint these methods are crucially different. Let’s say we have a story where every location has theme music associated with it. When you move to another location the music changes. In Undum the system shouldn’t load and play the theme music for every location the reader had visited previously, just the latest track. And what if there’s a sound effect every time the reader clicks on a choice? If they’re played also when the story is being loaded the reader would hear them all at the same time as a jumble of sounds all mixed together.

That problem is relatively easy to fix: the latest version of Undum has a way to check whether the story is being played normally or replayed by the restoring mechanism. Any elements that are affected by the problem described above can disable themselves during the reload.

With Parchment there wouldn’t be a problem with the sound effects because when restoring the story you leap straight into the situation instead of replaying from the start. The system must instead know the exact state of the user interface at the time when the story was saved. Not only that, but it must also know what to do when the reader uses undo to move back one turn or more.

Let’s take a simplified example of a story where you drive a car and there’s a graphical gauge depicting the current gas level. Every turn the gauge’s needle moves back a notch. It’s not enough to just decrement the value that moves the needle every turn. Otherwise the system doesn’t know where to point the needle when the story is loaded from a save state. Similarly when undoing it must know what was the previous state. It’s not enough to just counter the normal effect by moving the needle to the opposite direction, because the rule is probably more complex than “decrement every turn” (what if the car was stopped the last turn? Or if the gas tank was refilled last turn?)

The solution is to build the UI such that every turn all the information that’s needed to remake the current state is saved into memory. When a leap in time is requested, either by restoring or going back with undo, the UI resets itself and uses the saved information to get back to the previous state.

Getting saves and undo working correctly will probably be the biggest challenge to come. It’s also a challenge to the author, who must take saves and undo into consideration. The simple way out would be to just disable saving and undoing, but that would cripple the player experience more than what the benefits for the author would be.


August 30th, 2011

Buttons are an important concept of Vorple and user interface design in general. Almost all interaction with a computer is done by pushing (virtual) buttons on the screen. Most buttons have two states, enabled and disabled, sometimes more (active, pushed, …)

Buttons are the basic building blocks for many user interface elements. IF and game interfaces (outside the parser of course) are full of buttons:

A graphical compass rose with W in black lettering, NW highlighted and other directions grayed out
A grid of icons representing inventory items
A grid map showing locations of London

(Compass rose from Glimmr, inventory screen from Monkey Island I SE, map from The King of Shreds and Patches.)

“Button” might not be the best word since there’s no requirement that it can be interacted with. A Vorple button can be a non-clickable icon or a string of text if there’s benefit to using the button features to control it. By assigning buttons to a button group they can be manipulated as a single entity: displayed, hidden, moved, disabled or animated. Buttons in the group can be reordered and buttons can be removed and added as necessary.

The challenge to both the system and the author is that if the buttons are used inside the story text and the reader repeats an action or for some other reason the buttons are displayed again the old set should be removed, synchronized with the new ones or cloned as a new set. The buttons might be a part of an in-story machinery and they’re displayed every time the reader examines the machine. Let’s assume at some point the machine breaks down and the buttons are disabled. In this case all instances of the displayed buttons should be disabled, not just the latest set or the reader could just scroll up the transcript and click on one of the old buttons.

More Undum link types

August 15th, 2011

Undum has two special link types, once and sticky. When you click on a once link it and all other visible links leading to the same situation or action are removed. Sticky links are not removed when the reader moves on to the next situation unlike normal links.

While not strictly in the project’s scope, Vorple will add two new link types:

When a disposable link is clicked, it and all others leading to the same place will be removed, now and in the future. This is similar to once, the difference is that once removes only the current view’s links, not any future ones. Using disposable the author can freely link to the same choice from multiple situations but still be sure that the reader can’t click on it more than once.

It will also be possible to manually mark links as disposed even if the reader hasn’t clicked or even seen the link. This can be used to have reader’s choices close off options later in the story.

If there would be more than one unique link leading to the same situation or action, all others except the first one are hidden. Only one unique link pointing to the same destination is shown on the screen at any time.

An Undum situation that has three links, each leading to an actions that have the word "raven" as a further link

In the above example there are three actions available from one situation, each containing a link leading further from the word “raven”. Now if clicking “raven” is required to advance the story and we don’t know which of the actions the reader will choose first, we can make each “raven” link unique so that it will always be made a link in the reader’s first choice, but not in the later ones. The story would of course work just as well with three links visible, but the author might want to have only one of them visible for esthetic reasons.

Choice popups

The text 'You are standing at the crossroads' with 'crossroads' as a link and a box with choices 'Go left', 'Go right' and 'Turn back'

In Undum each link leads to the next situation or they run a single action. With choice popups the author can create a list of choices that appear when the reader clicks on the main link. Quest already offers a similar feature where clicking on items shows a list of actions applicable to that object.

Choice popups will of course be available later for parser IF as well. In that case the choices auto-execute a command according to the player’s choice.