Tin Cans: Making Twine Work on Phones

**UPDATE**

This tutorial was written as I figured it out, while working on my #1GAM entry for March: Dinner, Dancing, and Death in a Dungeon
I've gone through this whole process again, tidied a few things up, and repackaged the twine storyformats in a zip, rather than linking to the header.html files.
The terminology still fluctuates a bit, especially between "game", "story" and "app". You know what you're making.

DOWNLOADS

The Twine story file for Dinner, Dancing, and Death in a Dungeon
The Twine story format files
The Resources folder for use with Appcelerator Titanium in part 3-4

EXAMPLES OF TWINE GAMES PORTED TO TIN CANS

Town by Anna Anthropy
Dinner, Dancing, and Death in a Dungeon

Twine is an amazing tool that lets people tell meaningful stories without needing to understand a lot of code. It also doesn't work well on mobiles. Tin Cans is a new story format for Twine, that's based on the popular jQuery Mobile framework, that takes care of a lot of the issues of making things look good on phones.

Here's Anna Anthropy's "Town" game using the Tin Cans format

I'm spitting this tutorial / blog up into five parts:

DOWNLOAD AND INSTALL TWINE

First things first. You'll need to download and install Twine.
Download Twine here (1.3.5).
Download Twine here (1.3.6 alpha)

MAKE YOUR GAME

This should be obvious. Now this isn't a tutorial on using Twine, so I'll just dump a bunch of links to people who've explained it better than I could.

Tutorials:

Making and working with macros:

Help:

Otherwise, download AuntiePixelante's Towns and follow along with the conversion.

Notes on macros:
All macros that work with sugarcane SHOULD work, as tin cans is based on sugarcane, but honestly, some things that affect the menus might not work.

Notes on CSS:
Feel free to use custom css to colour links or text, but don't set widths or anything to set px amounts. Use percentages if possible, because a phone could be just about any resolution these days.
Images are set to scale to fit the width of the content if they're too big, so be careful about putting text in images, as on a phone the image could be so small the text is unreadable.

ADD THE SETTHEME MACRO TO YOUR STORY

Create a passage with the title "setTheme" and put "script" in the tags field, and put this in the content:

try {  	version.extensions['setTheme'] = {   		major:1, minor:0, revision:0   	};  	macros['setTheme'] = {  		handler: function(place, macroName, params, parser) {  			setTheme(params[0]);  		},  		init: function() { },  	};  } catch(e) {  	throwError(place,"setTheme Setup Error: "+e.message);   }  

call it with <<setTheme "THEME_LETTER">> ("THEME_LETTER" can be any letter you have a theme for)

By default, jQuery mobile comes with 5 built in themes:

  • "a" is black
  • "b" is blue
  • "c" is white
  • "d" is grey
  • "e" is yellow
  • "a", b" and "c" are used in the header and side bar.

INSTALL THE STORY FORMAT

Download the Tin Cans story format files

This zip contains 2 story formats:

  • tincansmobile, which should be used for compiling for mobile devices using Titanium
  • tincansweb, which is for putting on a webserver

Once you've got the zip file, you can do one of three things:

a) If you're using Twine 1.3.6, create a new story format
You'll find the story formats in "C:\Program Files (x86)\Twine\targets\" - I don't know where the files are on mac.
Extract the two folders from the zip there.

b) If you're using Twine 1.3.5, find the directory the formats are kept in, and replace a story format file you're not using.
You'll find the story formats in "C:\Program Files (x86)\Twine\targets\" - I don't know where the files are on mac.
I replaced the header.html file in "C:\Program Files (x86)\Twine\targets\jonah" because it's not a format I plan on using at the moment.

If you're using Windows Vista or Windows 7, you may need to change to admin permissions to make the files writable. Here's how to do that

c) Copy the twine code manually into the new file
Build the html file witht the sugarcane format as normal.
Open it up in a text editor, cut out everything before the '<div id="storeArea">' area, and replace it with everything before the '<div id="storeArea">' area in the header.html file from this site.

You should now be able to run your story on a phone, if you upload it to a website.
All the steps from here on are optional but even if you don't want to package your story as an app, you should still look at the next step.

It'd be a good idea to through your game completely now, just to test nothing's broken.

NEXT: Adding your own themes, and using the setTheme macro