An Ink Proof of Concept From Script to Android App

I ran across Ink in late 2021 and really enjoyed the idea - and it turns out I've known about it for awhile as I had watched videos of 80 Days and Sorcery! from the Yogscast back in the day.

I began wondering how easy it would be to write a piece of interactive fiction from script to app. And it turns out, it's not too bad (for a proof of concept at least) when using Ink, Inkle, Inkjs, and Cordova.

What is Ink?

Ink is an open source scripting language for writing interactive narrative.

Developed by inkle studios, it allows for interactive story branching, variables (e.g. item management), options, and more just with a language that looks similar-ish to markdown. You can then extend this to interact with your GUI or game space in Unity or JS (or anywhere else someone has written a wrapper for).

You might know inkle studios by these games:

You can find Ink either via the website or GitHub.

Writing a Story

How do we start? We can quickly get going with Inky, the IDE for Ink.

Open Inky and paste in the following to the left pane. We'll start with something really simple where both options conclude the same way:

Once upon a time...

 * There were two choices.
 * There were four lines of content.

- They lived happily ever after.
    -> END

If you're interested, there's a lot of documentation:

Writing web-based interactive fiction with ink

As used to author Heaven’s Vault, 80 Days and Sorcery!: produce interactive scripts by writing in pure-text with ink markup.

inkle home

ink/WritingWithInk.md at master · inkle/ink

inkle’s open source scripting language for writing interactive narrative. - ink/WritingWithInk.md at master · inkle/ink

GitHubinkle

But for the purposes of this proof of concept, I will be using the sample game, The Intercept. With the .ink file here via GitHub.

Exporting the Story

Sure we can play in the IDE, but let's put it on it's own two feet. It's pretty easy to do and we'll be using the in built Export to JS feature. So with the .ink version of The Intercept pasted into Inky, go to File > Export for web...

This uses Inkjs in the background to create a little website that runs the .ink story:

Double click index.html to run!

With this in mind, we can easily export a little bit of HTML, JS, and CSS to create a mobile app. First thing that comes to mind is Cordova.

Exporting as an App

Cordova (formally PhoneGap) makes it really easy to export a website as an application.

This is what I did to create a .apk for Android. I will be doing it from scratch and going over the steps above first:

Get the story website

This will get us the website of the Ink story ready for Cordova and we'll recap the steps we've seen previously too.

1. Download Inky
2. Run Inky
3. Paste the .ink file from the repo for The Intercept into Inky
4. Go to File > Export for web... and export the website to a folder called TheIntercept.

For me, this now looks like:

Done, now we have a website. You can open index.html and see the game running.

Creating the app with Cordova

First we'll need to grab Cordova and then install the Android dependencies in order to export our story as a .apk. Cordova doesn't come with some dependencies by default as the user may not want to export to Android - perhaps they want iOS.

This will be following the Installation Guide for Cordova for Windows.

First up, installing the things needed for Cordova to run:

1. Install NPM
2. Install Node.js
3. Run npm install -g cordova

Now we have the basic setup done, let's start digging into the actual application.

Go to a directory you want to create your Cordova app in. I created this folder: ~\documents\ink\ and in your shell/terminal/command line of choice, type

cordova create TheInterceptApp com.cordova.TheIntercept "The Intercept"

Breaking down each part:

1. cordova create kicks off the new Cordova project
2. TheInterceptApp is the folder this project will be created in
3. com.cordova.TheIntercept the reverse domain-style identifier for the app
4. "The Intercept" the display name for the app

What this does is create a default placeholder website (because remember Cordova exports websites) and you can find that under \TheInterceptApp\www\index.html and this looks like:

With all this done, we now have the original exported website directory (TheIntercept) from Inky and the app directory (TheInterceptApp).

Time to make the app our own, and this step is super easy. Just delete the contents of \TheInterceptApp\www and replace it with the website contents of \TheIntercept\. Or in graphical form:

Next up, let's add a platform we can target with the app. Because this example is for a .apk, it'll be Android. For this, make sure you go into the app folder, TheInterceptApp and add the Android platform:

cd TheInterceptApp
cordova platform add android

After this we need to get the Android SDK in order to build the app. When inside the TheInterceptApp directory, the following command will tell us what we need:

cordova requirements

For example, here is the output if nothing required is available:

The installation steps are long winded, but are well documented in the Installing the Requirements documentation.

After that's done, the output should look like:

Now we can build the app. For Android the command is:

cordova build android

After 2m 19s the .apk was spat out at \ink\TheInterceptApp\platforms\android\app\build\outputs\apk\debug\app-debug.apk. Note: After the first build, the build times were ~2s.

Side load it onto your Android phone and you should now have a functioning Ink app!

Conclusion

This was a really fun little proof of concept. Super easy to get going... aside from the Android SDK wiring up. That an Java version problems. Thanks Oracle.

I ran across a great tutorial by Edwin McRae that goes into how to get into Ink from simple to complex story flows. If you're interested, here's Learning Ink Script - Tutorial One.