Please Read for Updated Version:
For the most updated version of this tutorial please visit: Converting Twine 2 Stories to Android APK Apps for the Google Play Store [2018 Updated Tutorial]
Note: This version linked above solves, and walks users through all known errors.
This tutorial will teach you how to create a Choose Your Own Adventure Android App. It’s easier than you could imagine. To create your app you will need to use:
- Twine 2
- Adobe PhoneGap Build
While it may seem difficult, at first, you should be able to build your first Android App in less than two hours.
Creating your story with Twine 2
Twine 2 is a web-based Choose Your Own Adventure program. You can access it here: https://twinery.org/2/#!/stories
The Basics of Twine 2
This tutorial is focused on converting a finished Twine 2 story to Android APK, however I will include some basic information for creating a Twine 2 story.
- When editing your first page, you create options by writing [[Go to the fountain]]. This will create a link reading [[Go to the fountain]] and a new page called Go to the fountain.This is not the best way to do things, as you may want to have a number of options send the user to that location.
- If you want the displayed link to look different than the page reference you need to write it like this [[Go to the fountain|Fountain]]. This will display the text “Go to the fountain” as a link to a page titled “Fountain”.This allows you to have another page reading [[She ran to the fountain|Fountain]] that also takes the user to the same location.
- For more information about creating a Twine 2 story feel free to read this tutorial: http://www.adamhammond.com/twineguide/
Once you have created your Twine file select Publish to File. This will download a file titled StoryName.html This file is your complete story. You can open the file and play through your story in a web browser.
If that’s all you want, you’re good to stop. However, if you want to convert it to an Android APK keep reading.
Preparing your Story for Phone Gap
Once you have your StoryName.html file you need to prepare a folder for it. This folder will eventually be Zipped, and uploaded to Adobe Phone Gap Build for conversion to APK.
- Create a directory named WWW. Do this by Right Clicking on your desktop, selecting New/Folder, then naming it WWW.
- Copy StoryName.html to your WWW directory.
- Rename StoryName.html to index.html. You can do this by right clicking the file, and selecting Rename. Then, type in index.html
- Finally, you will need to create a config.xml file. This is what provides the information about your app to Android. To do this, right click in your WWW directory, and select New Text Document. Leave it named New Text Document.txt
- Open the file, then copy and paste the text below into that document (you do not want to copy the numbers on the left hand side):
<?xml version='1.0' encoding='utf-8'?> <widget id="com.YourName.AppName" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0"> <name>Your App Name</name> <description> A description of your App!. </description> <author email="email@example.com" href="http://your.website.com"> Your Company Name </author> <content src="index.html" /> <access origin="*" /> <preference name="DisallowOverscroll" value="true" /> <preference name="android-minSdkVersion" value="14" /> <preference name="phonegap-version" value="cli-6.3.0" /> <preference name="orientation" value="default" /> <plugin name="cordova-plugin-splashscreen" source="npm" spec="~3.2.1" /> <preference name="SplashScreenDelay" value="3000" /> <preference name="ShowSplashScreenSpinner" value="false" /> <preference name="FadeSplashScreen" value="false" /> <preference name="SplashMaintainAspectRatio" value="true" /> <preference name="SplashShowOnlyFirstTime" value="false" /> <splash src="splash.png" /> <platform name="android"> <icon density="ldpi" src="res/icon/android/ldpi.png" /> <icon density="mdpi" src="res/icon/android/mdpi.png" /> <icon density="hdpi" src="res/icon/android/hdpi.png" /> <icon density="xhdpi" src="res/icon/android/xhdpi.png" /> <icon density="xxhdpi" src="res/icon/android/xxhdpi.png" /> <icon density="xxxhdpi" src="res/icon/android/xxxhdpi.png" /> </platform> </widget>
Modifying the config.xml
You will need to add your own personal information to the config.xml file. Make the following changes:
- On line 2 change com.YourName.AppName to your information. (i.e. com.JonSmith.CoolAlienStory)
- On line 3 change “Your App Name” to the name of your app.
- On line 4 change “A description of your App!” to a description of your app.
- On line 6 change “firstname.lastname@example.org” to your e-mail address
- On line 6 change “http://your.website.com” to your website link, or leave blank.
- On line 7 change “Your Company Name” to your company name.
- Next select File and choose Save As. Name your new file xml This new file must be saved in your WWW directory.
- Finally, navigate back so you can see your WWW directory icon.
- You need to ZIP this WWW directory. To do that right click the folder icon, and choose Send To then Compressed (zipped) folder. This will create WWW.ZIP
- You will need to upload this WWW.ZIP folder to PhoneGap Build.
Using Adobe PhoneGap Build
Once you have prepared your ZIP file, it’s time to upload it to Adobe PhoneGap Build, and convert it to an app. To do this please follow the next few steps.
- Navigate to https://build.phonegap.com
This is the website that will convert your file to an app.
- Click “Sign In” in the top right, then select “Sign up for a new account”.
- Choose “Completely Free” then select an option to create an account. I recommend using Google as your sign in option.
- Once you have signed in, you will be taken to the main page. There you will see an option called Upload a .zip file. Click on this, navigate to your zip file, and it will upload.
- Once you have uploaded your ZIP file, you will notice a number of things are automatically filled out. (The name of your app, the summary of it, etc.)
- You will now see an option called Ready to Build. Click on this button and the file will build. This can, sometimes, take a while.
- You will notice a QRC when the file is built. This QRC can be used to link other people to your APK file. You will also notice a little android icon over the Update Code button, or a blue button with a down arrow beside the word APK. Clicking on this icon will download the APK file, which can be installed onto android devices.
Updating your Story
If you want to change something in your Twine 2 story, you can re-edit it using Twine 2, and then Publish to File again. Once you have exported the new StoryName.html file you need to:
- Override the previous html file in your WWW directory.
- Re-ZIP the entire directory.
- Navigate to Adobe PhoneGap Build and click on Update Code.
- Select the new ZIP file you just created.
- Click Upload and your new APK will be created.
Note: You may find it helpful to create a new .ZIP file, rather than overriding the original, so you don’t lose copies of your previous versions. I suggest dating each ZIP file as YYMMDD.TIME – StoryName (i.e. 171011.1344 – Sammi’s Quest)
Personalizing your App
There are a number of ways you can personalize your application. The easiest ways to do this are by adding a Splash Screen that displays when you start up the app, and by adding a personalized icon to be displayed on your Android device.
Adding a Splash Screen
To create a splash screen use any photo editing software to create an image file that is exactly 360×480 pixels. Save this file as splash.png in your WWW directory.
Adding an Icon
- To create an icon for your application you will first need to create a folder named res in your WWW directory
- Inside the res directory, create a new directory named icon.
- Inside the icon directory, create a new directory named android.
- Now you will need to create your icon file.
- To create your icon, first create a high resolution file using an image editing program. Create the icon to be 1024×1024 pixels. Save this file as png
- Direct your webbrowser to https://resizeappicon.com/
- Select Upload file, and wait for the icon to upload and be displayed.
- Scroll down the page until you see the heading Android. Click on All. This will place check marks beside all the Android icon files.
- Scroll to the bottom of the file and click Download Selected.
- This will download and AppIconResizer ZIP file. Open this zip file, and move all the png files from the zip to your WWW/res/icon/android directory.
- Since your config.xml already points to this directory to find the icon files, once you copy these files you’re ready to re-ZIP your WWW directory, and upload it to PhoneGap Build.
Creating iPhone Apps
You’ve done most of the heavy lifting already. All that is required to make this an iPhone app is to add a little bit of information to the XML file. To learn more about that process read the following website: http://docs.phonegap.com/phonegap-build/configuring/preferences/
A little bit More
There may be a few more things you need information about. Hopefully this section covers them.
Downloading your APK to an Android Device.
You can select the “Download” option to save the APK file to your computer, and then transfer it to your device if you want. However, there is a far easier way.
You can scan the QR code with your phone or tablet, and it will download your app.
If you don’t have a QR scanner on your android device you can download one here: https://play.google.com/store/apps/details?id=me.scan.android.client&hl=en
Navigate on your device to the download directory, and install the APK file. You can now enjoy your story in app form, and distribute it to your friends.
Hosting your App on the Google Play Story
If you’d like to host your story on the Google App store, you will need a developer account. For information on that can be found here: http://support.andromo.com/kb/distributing/how-to-put-your-app-in-google-play