Transmatte: An IF Excerpter

I wrote this tool to solve a problem: how do you include examples when you write about IF? If you write about a book, you can include excerpts. For film, you can include video clips. But including a sample of a game is tricky.

IF presents more excerpting options than, say, a FPS, but none of them are great.

You can include transcripts. But demonstrating one piece of interactivity might require several transcripts, and the reader's eyes tend to glaze over quickly.
You can include the game's source code. This is basically impenetrable. (Remember, we're talking about ways to demonstrate how a game plays out, not how to implement it.)
You can insert the game itself into a web page, in a playable form. (Thank you, Parchment.) But a casual reader might not be interested in diving in, learning the commands, and trying it. Even if he does, he might not try the thing you want to talk about.

After musing on this subject, I came up with an approach: present several game transcripts, but layer them in an interactive web page, so that the reader can easily flip between them. The result is dimly related to a CYOA hypertext game -- the reader is selecting choices that influence the following text -- but the effect is of overviewing the game, not playing it.

Let's try it

Here is the proof-of-concept I threw together:

Excerpt from the beginning of Adventure (Javascript required.)

The page shows a short transcript, with pseudo-scholarly annotations on the right. The left column has links, which change the course of the game being played. (The boldface link is the current state; click an underlined link to switch to a different one.) This example shows two player choices, of which one is initially hidden.

That example was hand-rolled. The following one was generated from a set of transcript files:

Excerpt from Shade: finding the plane tickets (Javascript required.)

This example is drawn from real life. When Jeremy Douglass first contacted me, writing his article Enlightening Interactive Fiction, he had misunderstood the behavior of the plane tickets. (He'd read the source code, but that failed to enlighten him!) This excerpt of Shade demonstrates, in a compact way, the actual behavior, as (correctly) described in his final article.

So how did I generate that?

Behold my clever Python script: transmatte.py

It's not actually that clever, and using it is very simple. Run it on the command line, and pass in the filenames of two or more transcripts. It will merge them into a dynamic web page, just like my examples, and spit it to stdout.

python transmatte.py trans1.txt trans2.txt trans3.txt > page.html

To define link names and game notes, annotate the transcript files with lines beginning with "!". Annotation lines have the form !FUNCTION: VALUE.

!title: Defines the page title. This must be placed on or before the first command.
!subtitle: Defines the page subtitle. This must be placed on or before the first command.
!note: This line defines a game note for the current command. Game notes appear as-is in the right column of the generated page.
!option: This line defines the label for a command. (In the choice links in the left column.) When two of your transcripts differ, use this annotation on the commands that are different.
!otheroption: Sometimes you have one transcript that differs only in the absence of a command. So there's no command there to put an "!option" line on. Instead, put an "!otheroption" line in the other transcript, on the appropriate command.
!priority: This defines the (numeric) priority for a command. In the choice links, the high-priority command appears first, and is the default choice. (That is, it will be visible when the page is first loaded.)

If you want to try a complete example, download these three transcripts: advent-trans1.txt, advent-trans2.txt, advent-trans3.txt. They generate this page, which is pretty much (although not exactly) like my original Adventure example.

Notes and so on

A certain amount of cleanup is done on the transcripts. Trailing whitespace is stripped from each line. Blank lines before and after a command line are ignored (but blank lines in the middle of a game response are kept).

Transmatte has a simplistic notion of merging transcripts: it looks for common sequences at the beginning and ending of the transcript. It is not capable of recognizing a common sequence in the middle.

(I originally wrote a much more complicated processor that could match sequences anywhere in any pair of transcripts. Then I gave up on it, because I couldn't figure out what to do with a center match. If you think about it, a center match means that the beginning and end of the document don't match, which means the user clicks a link and the beginning and end of the document change. That's not really distinguishable from the whole document changing.)

A nice addition to this model would be a change bar, indicating what sections of the transcript have just changed. (That would resolve the problem I just described.) It would also be cool to use jQuery-style animations to swap blocks in and out, while the unchanging blocks slide up and down. (When I say "cool", of course, I mean "more visible and comprehensible.")

Last updated March 4, 2010.

Zarfhome (map) (down)