A Markdown Based Adventure Engine – My First Playing Around With Elm

My recent little adventures in Elm have definitely been one of the most enjoyable programming experiences.

Elm is a purely functional programming language that compiles to JavaScript. It has static type checking, all values are immutable, there are no null references, and no runtime exceptions. Additionally Elm has a great performance due to the implementation of a virtual DOM. All apps written in Elm are structured by the same simple pattern called The Elm Architecure.

The following diagram shows a simplified view of the The Elm Architecture. The area above the line represents the runtime. CMD, MODEL and NEW MODEL are plain data structures. Whereas UPDATE and VIEW are pure functions.

Elm Architecture

alt text

Markdown based adventures

As a young teenager there was a short episode in my life where I was writing test based adventures in BASIC.

Neither was I very creative nor did I know much about programming. So that was over quickly.

However, it might have inspired the idea of implementing a light weight framework for creating and presenting text based, interactive stories. I know that the idea is not very unique and that there are a lot of way more fancy tools out there (even one written in Elm) but I took the opportunity to get some exercise in the programming language Elm.

How it works

The idea is that you can write your complete interactive story only with Markdown, augmented with a simple additional syntax. The story can be edited by uploading a new file. There is no need to write any Elm code or recompile the app when the story has changed.

There are a few rules when writing a story file.

A section is an atomic part of the whole story. A sections has to start with ***.

Also each section has to have an ID:

- id: <some_id>

After the ID the content of the section starts which can be written in plain Markdown or HTML.

At the end of a section there may be links to other sections that the user can choose to navigate to.

The list of links is marked with - continue and a new line. Which has to be followed by one or more links.

A link consists of a prompt and a next value. prompt represents the text that will show on the corresponding button and next is the ID of the section that is referenced:

- continue:
    - prompt: Take the boat
      next: boat
    - prompt: Enter the jungle
      next: jungle  

That's it.

The file that contains the story must be named story.txt and must be placed in the same directory as the Elm app.

Here is an example of the initial view of the story file provided with the Git repository:

alt text

Behind the scenes

To make this work a few common concepts are utilized such as:

If you are interested in concrete code examples please take a look at the source code.


Getting a little web app up and running with Elm was a really enjoyable experience.

The program design of my app, layout of the views and feature set could be improved, but that is not really the point.

Check out the Elm website for great documentation and how to get started!