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:
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:
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
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.
- Download Inky
- Run Inky
- Paste the
.inkfile from the repo for The Intercept into Inky
- Go to File > Export for web... and export the website to a folder called
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:
- Install NPM
- Install Node.js
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:
cordova createkicks off the new Cordova project
TheInterceptAppis the folder this project will be created in
com.cordova.TheInterceptthe reverse domain-style identifier for the app
"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:
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.
cordova-androidversion 10+." I had to downgrade my JDK to 8 even with
cordova-androidversion cordova-android 10.1.2. Or else I would get "Android target: avdmanager: Command failed with exit code 1" as an error.
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!
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.