Converting Twine 2 Stories to Android APK Apps for the Google Play Store

In our last part you learned how to write a Choose Our Way tale with Twine 2, and share it on a website so that it could be shared with people outside of the classroom.  Now you will learn how to transform your Twine 2 story into an Android APK App file which can be played on Android phones and tablets.



Examples of apps made using this method can be found at: Sammi’s Quest: Google Play Store

Free Demo can be downloaded to your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Demo)

The Full Version can be purchased for your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Full Release)



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:

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.

  1. 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.
  2. 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.
  3. For more information about creating a Twine 2 story feel free to read this tutorial:

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.

  1. Create a directory named WWW. Do this by Right Clicking on your desktop, selecting New/Folder, then naming it WWW.
  2. Copy StoryName.html to your WWW directory.
  3. Rename StoryName.html to index.html. You can do this by right clicking the file, and selecting Rename.  Then, type in index.html
  4. 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
  5. 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="<a href=""></a>"
        xmlns:gap="<a href=""></a>">
    <name>Your App Name</name>
        Replace this line with a description of your app.
    <author email="" href="<a href=""></a>">
        Your Company Name
    <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" /> 

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 5 change “Your App Name” to the name of your app.
  • On line 7 change “Replace this line with a description of your app.” to a description of your app.
  • On line 9 change “” to your e-mail address
  • On line 9 change “” to your website link, or leave blank.
  • On line 10 change “Your Company Name” to your company name.

Final steps in Adobe PhoneGap Preparation

  1. Next select File and choose Save As. Name your new file xml  This new file must be saved in your WWW directory.
  2. Finally, navigate back so you can see your WWW directory icon.
  3. 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
  4. 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.

  1. Navigate to
    This is the website that will convert your file to an app.
  2. Click “Sign In” in the top right, then select “Sign up for a new account”.
  3. Choose “Completely Free” then select an option to create an account. I recommend using Google as your sign in option.
  4. 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.
  5. 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.)
  6. 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.
  7. 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:

  1. Override the previous html file in your WWW directory.
  2. Re-ZIP the entire directory.
  3. Navigate to Adobe PhoneGap Build and click on Update Code.
  4. Select the new ZIP file you just created.
  5. 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)

Common Errors

  1. Ensure that there are no blank lines at the top of your CONFIG.XML file
  2. If you have added the code for app icons, ensure the icons are in the correct directory
  3. Confirm that the icons are the correct size
  4. Check to see if you have renamed your story file to html
  5. Make sure you have a xml file that conforms to the requirements
  6. Double check that you have added a png file that fits the required size


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

  1. 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 png in your WWW directory.
  2. Add the following lines to CONFIG.XML before </widget>
    <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" />

Adding an Icon

  1. To create an icon for your application you will first need to create a folder named res in your WWW directory
  2. Inside the res directory, create a new directory named icon.
  3. Inside the icon directory, create a new directory named android.
  4. Now you will need to create your icon file.
  5. 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
  6. Direct your webbrowser to
  7. Select Upload file, and wait for the icon to upload and be displayed.
  8. Scroll down the page until you see the heading Android. Click on All.  This will place check marks beside all the Android icon files.
  9. Scroll to the bottom of the file and click Download Selected.
  10. 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
  11. 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.
  12. Add the following lines to CONFIG.XML before </widget> :
<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" />

A little bit More

There may be a few more things you need information about.  Hopefully this section covers them.

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:

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:

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: or by reading the official Google documentation.

Long Story Assignment

Preparing for the long story assignment, I suggest you familiarize yourself with the snowflake method of writing. I created a handout that uses the snowflake method, adapting it for the needs of a Choose Our Way tale.  Once students have planned their story using this method, they can complete the assignment.


  • Be between 2000 and 5000 words long
  • Have at least six endings
  • Have at least ten pages where the reader can choose a direction
  • Be converted to Android APK using Adobe PhoneGap

Handout: The Snowflake Method for COWtales

Handout: Twine 2 Long Story Assignment

Next Steps

Now that you know how to use Twine 2, and convert Twine 2 files to Android APKs you’ve reached the end of these tutorials.  If you’d like information on how to upload your app to the Android Play Store, the official documentation can point you in the right direction.

In the next, and final part, you can access all the handouts that have been posted along the way.  You are free to distribute them for non-commercial use.

PART 1: Introduction to Choose Our Way tales





Using Twine 2 to Create Chooseable Path Stories

Twine 2 is a piece of software that allows you to create Choose Our Way tales.  In our last parts you learned about palm stories, familiarized yourself with the basics of choose our way tales, and then learned how to write basic choose our way tales.  Now we’ll look at how to digitize those tales using Twine 2.


Examples of apps made using this method can be found at: Sammi’s Quest: Google Play Store

Free Demo can be downloaded to your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Demo)

The Full Version can be purchased for your Android Device Here: Sammi’s Quest: Vol. 1 – The Wandering Ogres (Full Release)

The Basics of Twine 2

First, direct your browser to

If you’ve never used Twine 2 before, it will redirect you to!/welcome I suggest you click on tell me more and step through the information presented there.  The most important thing to remember is how Twine 2 saves your files.

How Twine 2 Saves Your Files

Twine 2 saves stories to the browser cache.  This means that you don’t need to log into an account to use it.  However, it also means that the stories you write on one computer will not be available on another computer unless you manually save it.

Saving the story is simple.  Either click on the cog image or the story name and select “Publish to File”.  This will save your file your story as an HTML file which can be saved to cloud storage, a network drive, or USB key.

You can copy this HTML file to another computer, and load it by using the “Import From File” option.

Writing with Twine 2

Twine 2 creates one page as a default option.  You can write in that page as you would anything else, however, the difference between linear stories and Choose Our Way tales comes when you add branching options.

[[Writing text in brackets]] creates links to new pages.


Page Name: Untitled Passage

Once upon a time there was a boy who went to the beach.

[[He built a sand castle]]
[[He ran into the water]]

This will create two new pages, one named “He built a sand castle” and another called “He ran into the water”.

From there, you can create more branching choices, or connect them back to one another.


Page Name: He built a sand castle

The boy made the greatest sand castle anyone had ever seen.  After it was complete…

[[He ran into the water]]
[[He rewound time and went into the past|Untitled Passage]]

The following link [[He rewound time and went into the past|Untitled Passage]] allows you to create a link that has text that says one thing “He rewound time and went into the past” that links to a different page “Untitled Passage” (To the left of the | is the text, and to the right is the page link.)

This story can end by simply not having any branching choices in on your final page.  While this example story will only have one ending, you should feel free to create multiple endings in your work.


Page Name: He ran into the water

As he was splashing around in the water he looked up in the sky.  A great ship sailed above him through a sea of clouds.  It was at that moment that the boy woke up.

The end.

Let’s not kid ourselves, it’s not a great story – but it’s a story that allowed for some reader participation.  It’s an acceptable place to start.

Further Reading

You can find additonal information for writing Twine 2 stories at the following links:

A Total Beginners Guide to Twine 2.1

Twine 2 Guide



Lesson 4: Your First Twine 2 Story

Before you write your first Twine 2 story, you will need to create an outline for your story.  This lesson will build from the framework created by running the Palm Story Lesson.

Twine 2 Story Outline

Once your students have completed the Palm Story, your students should create a Twine 2 story using the following flowchart pathways.

Day 5 - Palm Story to Twine 2-2.jpg


Twine 2 Story Example

An example of a complete Twine 2 story, based on the outline created from running the Palm Story Lesson can be seen below.

Day 5 - Palm Story to Twine 2-3.jpg

The above example has multiple endings, and a number of pages where readers can choose which direction they’d like their character to head.  With this story, the reader has agency to become a fully realized active participant in the narrative.

Sharing a Twine 2 Story

Once the story is complete, it can be hosted on which will allow students to share their story with anyone who has an internet connection.  The only requirement for uploading a story to is a twitter account, which can be created using a school or personal e-mail address.


The Twine 2 Assignments

You have been learned how to write with Twine 2, as well as how to create a branching story using a flow chart outline.  Now you’ll need to decide if you want your students to create a short story using the program.

Short Story Assignment

First use the Palm Story Lesson for the ideation stage of planning.  It will prepare the students for this assignment.


  • Be between 500 and 1250 words
  • Have at least three endings
  • Have at least five pages where the reader can choose a direction

Handout: Twine 2 Short Story Assignment


Student Examples

Medieval Adventure

To Live or To Die

The Files

The Boys are Back in Town

Rest in Peace



Next Steps

Now that you have familiarized yourself with Twine 2, and have learned how to have your students write a short COWtale in your class, you can move on and see how to write a longer story, as well as how to convert that story to an Android APK file that can be played on compatible phones or tablets.



PART 1: Introduction to Choose Our Way tales





Writing a Palm Story: Ideation for Creative Writing

Palm Stories are short stories that students write using nothing more than the palm of their hand, and a little bit of imagination.  Teachers ask students to close their eyes and picture a number of different things, making point form notes along the way.  At the end of their meditative journey, they will have the framework for a detailed story.


Running a Palm Story

The first things teachers need to do is ensure their students have something to write with, and write on, in front of them.  Next they need to ask their students to close their eyes.  This is a large ask, and requires teachers to have already created a caring environment that fosters trust.

Teachers will act as a guide through the story, instructing students to take notes along the way.  Alternately, teachers can provide their students with my Palm Story Handout to aid in the ideation process.

Handout: Palm Story Notetaking Sheet


Every Journey Begins…

Teachers need to ask students to look at their hand.  They should find one of the major lines on their hand.  They should then look for another line that passed through the first.

Students should then draw those two lines as a quick sketch.  If using the Palm Story Notetaking Sheet they can draw it in the space provided.

The Road

Ask students to look at the major line on their hand and envision it as a path.  They should then take a moment to close their eyes and picture the path.  They can envision it as a dirt road, an asphalt highway, a raging river, or even a pathway made of clouds that rests high above the world.  There is no limitation to where their story is set, or what their path looks like.

Once they’ve envisioned the road, ask them to look around and take in their surroundings.  What do they see?  Is it peaceful, or post-apocalyptic?  Are they in a fantasy forest, or a gritty urban centre?

Next, ask them to listen carefully and take note of what they hear.

Once students have had enough time to fully picture their surroundings they should pause, open their eyes, and take notes about what they heard and saw.

The Protagonist

The next time students close their eyes, rather than looking around, they should look down.  They should see their own feet, view their hands, or pull back and look at the protagonist in the third person.

Does the protagonist look like them, or are they someone different, entirely?  Next, becoming the protagonist they should be asked to consider what the protagonist wants.  What are the things that drive them into action, or make them pull away in fear?

After being given a few moments, they should make notes about the protagonist.

The First Steps

With knowledge of the protagonist and the path, students should be asked to close their eyes and begin their journey.  They should be asked to look around as they move through their world – note that I didn’t say walk through their world.  For all we know, they could be flying, swimming, or moving in a vehicle – while taking careful note of the sights, sounds, and experiences.

After some time, let them know that they suddenly see something!

The Item

Students should be informed that they see an item on the ground.  They’re not sure what it’s used for, but it’s definitely something interesting.  Even though they can’t be sure what its exact purpose is, they have a few good ideas.

Students should be asked to open their eyes and take notes about what the item was, and what it could be used for.  You may also want to ask them to draw a quick sketch of it.

At this point, redirect their attention at the line on their hand.  Tell them that soon they will be coming to the other line that crosses through it.

The Crossing

The other line on their hand is a crossing.  Something that is difficult for them to pass.  Perhaps it is a river, a checkpoint, a wall, or a crevasse erupting with flames.

They should be picturing this problem, when they realize how to overcome the issue.  Gaining the ability to pass the crossing, they will continue on their way.

All goes well until they seem something on the horizon.  As they get closer they realize that they’re not alone.  Just before them is…

The Other

The other in another character.  It could be a wise bearded man (I’m partial to those), or a talking rabbit.  It might be a little girl in a white dress, or a teenage boy in a flannel jacket.  Once again, it could be anything.  Though the protagonist has never seen this character before, they feel as if they know something about them.

The protagonist feels as if they know what the other desires.  Just as they pass this character, the character leans towards them and says just one thing.  That one line of dialogue would prove immensely useful to the protagonist.

Students should be asked to open their eyes, take notes about what the character looked like, what they wanted, and most importantly what they said.

Walking for some time, the protagonist has almost reached the end of the line of the student’s hand.  Soon they will reach the end of their journey.

The End in Sight

Before them looms the thing towards which they had been journeying.  Is it a concert venue?  A place of enlightenment?  A treasure chest full of cursed gems?  Maybe it’s a cat cafe where the protagonist can enjoy a latte while cuddling cute marmalade kitties?

As they reach the end, they suddenly become aware of why they’d needed the item all along.  With its use, they reach the end of their journey.  However, there are always new things on the horizon.

Students should pause and take notes about what the end was, why they were there, and how they reached it.

Distant Mountains

Finally, students should close their eyes and take a moment to appreciate the efforts of their protagonist.  They should enjoy the moment of denouement.  But, of course, things can’t stay the same forever.  Even though things seem well know, they should consider two things they experience in their journey that led them to feel as if a change would soon be coming.

Writing those final notes down, students should open their eyes and appreciate a palm, well journeyed.


Sharing the Stories

Sometimes I like to pause during the palm journey and allow students to share different parts as they make their way along the line on their hand.  I give them a chance to talk about their path and hear from other students what the paths before them look like.

Other times, I allow the students to complete the journey on their own.  Some teachers may find music helps the experience, though others may decide that they don’t want to influence the students’ visualizations with auditory stimuli.


Writing the Story

Students will now have the following elements:

  • A Protagonist
  • A Setting
  • An Important Object
  • A Rising Action blocking their way
  • A Secondary Character
  • A Line of Dialogue
  • A Destination

With these elements, you can ask them to chart them on a plot graph, or just allow them to dig in and start writing their own story with this new framework.


Possible Roadblocks

This is a very powerful activity, but there are a few things that can hold students back.  As I mentioned previously, feeling comfortable closing their eyes in an important step, but it is not the only possible concern.

An Inability to Visualize

Some people do not have the ability to visualize.  When you are asked to close your eyes and picture an apple, you can probably flip through an album of different apples from smell and yellow, to large and green.  But take a moment to appreciate that this is a gift that not all possess.

If asked to picture yourself canoeing on a lake as a loon calls out, you may be able to see the mist rise and hear the paddle splash as it enters the water.

Your students might not be able to do this.

How do People Know?

The easiest way to know if you have this ability is to think about when you read a book – when you read, do the words come to life like a movie playing in your head, or do you simply see black and white text in front of you as you read each and every sentence?

Some students may respond by saying, “it’s obvious that they see the book like a movie,” while others will be shocked that their peers have a personal holodeck inside their own brain.

Full disclosure

There are multiple levels of visualization.  Some can transport themselves to a strange world through the power of imagination, others can only hear sounds, or see objects, while some can do nothing at all.

I am one of the people who has no ability to visualize.  I’ve tried, I’ve practised, but I can’t even picture a green square with my eyes closed.  All I see are the rapidly changing blues and blacks as my brain tries to process what it is literally seeing.

I mention this because even though I can’t see or hear things in my mind, I can still think creatively, and this palm story still works wonders for my own creative writing ideation.

This is something to be aware of though because some students feel like they’re missing out on something.  They may need to be encouraged to participate even though it will be different for them – just as it is for me.


Downloadable Resources

Palm Story Notetaking Sheet

Introduction to Choose Our Way Tales

Choose Our Way tales (COWtales) are stories where the reader gets to make a choice about the direction the story will follow.  By being an active participant in the story, readers are more engaged and willing to press forward through the text.

COWtales have a number of branching plot threads, as well as a variety of endings.  By providing multiple outcomes readers are encouraged to read, and reread the same text over and over again.  Some people have even tried reading

Differnt types of COWtales


The first, and most beloved type of COWtale is Choose Your Own Adventure.  In fact, you may be calling all COWtales Choose Your Own Adventure stories, but you would be wrong to do so.  That term has been copyrighted for some time, and those seeking to use the term often find themselves in legal hot water.   Changing one or two words, however, puts you in the clear.

There are a number of types of COWtales such as: Plant Your Path, Choose Your Own Minecraft Story, Choose Your Own Misery, Choose Your Path, An Interactive Doomsday Adventure, A Chooseable-Path Adventure, You Choose, and Choose the Scare.

Obviously COWtale is another such term, but I choose to use it as a generic term that covers all the chooseable path adventures.

Where to Start?

The first thing you’ll want to do is familiarize yourself with some of the more popular texts.  There are a huge amount available through online book stores including your childhood favourites, long since out of print.

Next, you’ll want to familiarize yourself with the history of the genre.  Again, most of you are probably familiar with those brilliant white covered books you had as a child.

Many of them have been redrawn as “story maps” that show the various ways the stories connect, and split apart.

This brief introduction will provide you with everything you need to know about Choose Your Own Adventure stories: Hidden Structures of ‘Choose Your Own Adventure’ Books

Next Steps

Now that you’re familiar with COWtales it’s time to press on and discover how to introduce and write Choose Our Way tales with students.


PART 1: Introduction to Choose Our Way tales