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 "vorple.media.image( '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 "vorple.media.youtube( '[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.

§ One Response to Vorple for Parchment: The Inform 7 code

  • Jim Munroe says:

    Really looking forward to this extension! Seems like a good way to get my graphics using Everybody Dies working with Parchment. Let me know if you need testers.