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.

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.

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)