Fiction is a Three-Edged Sword

Fiction, interactive fiction and narrative

The Kindliser

This page is about the Kindliser, a tool for writing interactive ebooks for the Kindle platform.

Download Now

What It Is

The Kindliser is a Perl script. When executed, it will read in a source file written in a simple markup format, and convert it into a html file.

This file can then be converted to Kindle / e-book format using a free application such as MobiPocket.

For more information on creating Kindle-ready files, see this page.

But note, you don’t need to do any HTML authoring yourself. That’s what the Kindliser is for.

The Ebook Output

The ebook produced is not a Kindle app, but an ebook with hyperlinks, that looks and plays like a CYOA gamebook.

However, unlike a normal gamebook, the Kindliser allows you to create and store true/false information as the game moves forward, so you can track (limited) information about what the player has done and what choices they’ve made.

This data tracking is invisible to the player, but can be used to produce varying text. For example, the source format might contain a line like:

Jenny approaches, looking {JennyIsHappy:pleased|terrified}.

In the final game, the player will only see one alternative of the two specified in the braces, depending on the value of the JennyIsHappy flag.

To see this in practice, try out the Flaws example ebook (UK/US/DE download).

(Note, that as part of the Mobipocket process you’ll be able to add things like the author name, and a front cover image. The Kindliser doesn’t care about such things; it’s only purpose is to help you write your game in the first place.

The Source Format

The Kindliser uses a simple, easy-to-read, easy-to-write source format, that doesn’t really look like programming. A game might start as follows:


_The Great Metro Train Robbery_

startparagraph
The policeman pulls my hands more tightly behind my back.
* Talk [talk]
* Don’t talk [silent]

silent
I don’t say a word; don’t even whimper.
-> conversation

talk
“Please!” I exclaim. “I’ll tell you whatever you want to know!”
The policeman seems pleased. His grip relaxes a little.
-> conversation

conversation
“Okay, punk. I’ll ask you again. Where did you put it?”
* “Put what, officer?” [reply:putwhat]
* “I don’t know, okay!” [reply:dontknow]

reply
- putwhat
“Put what, officer?”
“Like you don’t know,” he growls.
–> continue
- dontknow
“I don’t know, okay!”
“A likely story,” he growls.
–> continue
- continue
* “Honestly, I’ve no idea.” [noidea]
* “Just let go of me, okay?” [letgo]

… and so forth.

(Those -> commands, by the way, are “direct links”. They’ll glue paragraphs together seamlessly, which can be really useful for bringing story paths back together.)

Data Tracking

The Kindliser allows us to store a little information as we pass through the game. This is done by defining a variable, then setting it or unsetting it, and then changing the games options, direct links and text output depending on what’s set and what’s not.

Here’s an example:
_Sit or Stand_

first_paragraph
The bus is full today. There’s only one seat left.
An old lady gets on the bus.
define(SittingDown)
* Take the seat [seat:take]
* Stand [seat:donttake]

seat
- take
set(SittingDown)
I go quickly for the seat.
–> oldladyon
- donttake
unset(SittingDown)
–> oldladyon
- oldladyon
The old lady totters up the bus towards me. {SittingDown:Another passenger, a girl, stands to let her sit down.|I gesture at the seat with a hand, as if it was mine to give.}
* Talk to the old lady [talk:lady]
* Talk to the girl [talk:girl] {SittingDown}
* Stare out the window [lookat:window]
* Look around the bus [lookat:bus] {!SittingDown}

In this short example, we invent a SittingDown flag. It’s defined in that first paragraph, ready to be used. In the next section, depending on what the player chooses, we either set it or don’t set it (that unset is unnecessary, actually, as unset is the default.)

Then, in the oldladyon subsection, we see a line of text that will change, depending on what the player did previously, and options that will only occur under certain circumstances.

(That ! mark means ‘Not’, and that last option will only appear if the player is not, in fact, sitting down.)

Limitations

Data like this shouldn’t be held onto for very long – the longer a variable is remembered, the bigger your gamefile will get. So this is a system designed to keep the player either on track – or on wildly diverging tracks.

The rule is: once you’re finished with a variable, you should ditch it:

ditch(SittingDown)

And remember, the only data you can store is true, or false. You can’t, say, count how many times a player has done something.

Testing

So, you’ve written a game and you want to try it out. Does that mean you have to upload it to Amazon every time?

No. You can test the game in your web-browser by just opening up your .html file. It won’t look right — it’ll be one large document with all the text of your game — but when you click the links, they should take you to the correct pages.

And when you want to test it natively, you should be able to make the .prc file using MobiPocket and load it onto your iPhone/Android/Kindle device. The Kindle app should find it automatically, so you can test it that way.

Perl, or “How do I do this again?”

The Kindliser is a Perl script. That means you’ll need a perl interpreter to run it. If you’re on a Mac/Linux, you’re in luck as there’s one built in. You can probably even get a text editor that’ll run the script on a button press (I use TextWrangler, which can run perl scripts when you hit apple-R, which is great.)

If you’re on Windows, you could try StrawberryPerl, which has a nice logo, and is free.

You’ll also need to tell the script where you source file is. At the top of the .pl file (which you can open in any text editor) there are two variables:

my $filename = "example";

my $path =”/Users/joningold/Documents/Code/Kindliser/”;

This will look in the folder (which you won’t have, as it’s on my computer); and load up a file called “Example.kll”.

Once you’ve made your own “.kll” file, you’ll just need to change these variables to point to the right places, and you’re away!

File Structure

You’ll need a base file, which is the one written into the Perl script as shown above. But you can include additional source-code files in the same folder, if you want to break your text up a bit. This is done using the include command:


include: flaws_part2

Note it assumes, and appends, a “.kll” suffix to the filename.

Validation

The Kindliser will check for the following and report if it finds them:

  • Headings defined but not linked to
  • Duplicated headings
  • Headings linked to but not written
  • Bit flags defined but never used
  • Bit flags ditched but never defined
  • Bit flags used but never ditched (these are expensive)

5 thoughts on “The Kindliser

  1. Pingback: Announcing the Kindliser | Fiction is a Three-Edged Sword

  2. Pingback: Kindliser update | Fiction is a Three-Edged Sword

  3. Pingback: links for 2011-08-28 | Kristian Still's Blog

  4. Pingback: House-sized stories for Kindle | Fiction is a Three-Edged Sword

  5. Pingback: inkle’s Frankenstein is released! | Fiction is a Three-Edged Sword

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 717 other followers