Entwine

Entwine is a tool that makes building large stories with Twine 2 easier. It's a good fit if you would like to:

Entwine is a command-line tool that integrates with Grunt, which is a tool that automates repetitive tasks. If you don't have experience with Grunt or the command line, this can feel intimidating. It will take some setup work to use Entwine, but this document will guide you through it, and once you're done, your project will be able to build itself automatically as you make changes to its sources. That is, you'll be able to edit an image or change a passage and your project will automatically rebuild without you having to even choose Publish to File in Twine. For large projects, this tradeoff can be worth it.

We'll assume you want to use Entwine with Grunt. If you're experienced with shell scripting, it's also possible to use Entwine on the command line by itself. To do this, follow the directions for installing Node below, then run npm install -g twine-utils. After that completes, running entwine --help will acquaint you with the direct command-line interface, and the Grunt Entwine task's documentation also provides more information as to what the options do.

There is no Entwine plugin for Gulp or Brunch, which are other popular task runners for Node, and no current plans to create them.

One-Time Setup

As the title indicates, you only need to complete the steps in this section once on your computer. You will need to be connected to the Internet.

  1. Download the LTS version of Node from the official web site and install it by opening the file you download. LTS stands for “long-term support” – it lags behind the most current version, but is better-tested.
  2. Open a terminal window.
    1. On Windows, make sure to do this by following this path of options from the Start menu: Start → All Programs → Node.js → Node.js command prompt. Doing so will make sure that Node is properly available to you.
    2. On OS X, open the Terminal application that's in the Utilities folder of your Applications folder.
    3. On Linux, how you open a terminal window depends on what distribution you're using. On Ubuntu, look under Applications → Accessories → Terminal.
  3. Type npm install -g grunt-cli and press the Enter key. This command asks npm – short for the Node Package Manager – to install Grunt for you. The -g part ensures that you'll be able to use Grunt across any project you create. The G is short for “global.”

npm will print out text as it installs Grunt, and it's normal for it to pause for a moment after you press Enter before printing any response. What it's doing is consulting a global repository to find the files you need – a lot more convenient than you having to hunt around on the Web. When you see the prompt again after it completes, you're done.

Project Setup

You'll need to do the steps in this section each time you set up a new project. We'll use a simple folder structure for your project, but you can use a different one if you prefer.

Given that, here's what to do. You will need to be connected to the Internet.

  1. Create a new folder for your project. In these examples, we'll call it my-project.
  2. Open a terminal window and go to this new folder with the cd command.
    1. On Windows, the easiest thing to do is to copy the address of your folder from the address bar of an Explorer window, and place quotation marks around it. The resulting command should look something like cd "C:\Users\You\Documents\my-project".
    2. On OS X, try typing cd with a space after it, then drag your project folder onto your terminal window. The resulting command should look like cd /Users/You/Documents/my-project.
    3. On Linux, the easiest way to get there varies by your distribution.
  3. Type npm init -y and press the Enter key. npm will create a file for you called package.json that we'll talk about in a second.
  4. Type npm install --save grunt load-grunt-tasks grunt-entwine and press Enter. npm will think for a moment, then install Grunt and Entwine for you.
  5. Create a folder named src inside the project folder. We don't need to create build or dist, but it doesn't hurt. Grunt will eventually create them for us as needed.
    1. You can do this from the terminal window by typing mkdir src and pressing Enter, or just create the folder the way you normally would.

If everything went correctly, you'll have three things in your project folder:

A Simple Grunt Task

Now that we have all the setup done, let's set up a Grunt task. In this example, and all the ones below, we'll assume you have a terminal window open at the top level of your project folder. If you're not sure how to do that, double-check the instructions above.

For starters, let's say you want to get a Twine story you've been editing into the src folder – let's say it's called “My Story.” To do this, we'll need another Grunt plugin to help. Type npm install --save grunt-contrib-copy and press Enter. As you might guess from its name, this plugin copies files from one place to another.

Now, create a text file with this in it:

Gruntfile.js
module.exports = function(grunt) {
  require('load-grunt-tasks')(grunt);
 
  grunt.initConfig({
    copy: {
      fromTwine: {
        files: [{
	  src: '???My Story.html',
          dest: 'src/'
        }]
      }
    }
  });
 
  grunt.registerTask('default', ['copy']);
};

You don't have to type it in yourself – just use the link labeled Gruntfile.js in the tab above the code to download it. Make sure to save this as Gruntfile.js at the top level of your folder. It has to be named exactly this, with the correct capitalization, for it to work.

Now type grunt in your terminal window and press Enter. If everything is correct, then Grunt will respond:

Running "copy:fromTwine" (copy) task


Done.

… but it won't have copied anything to src. We'll fix that in a moment.

Let's discuss what's in this file, because the format of a Gruntfile is always the same.

The reason right now why nothing is happening is that we haven't given Grunt a complete path to your Twine story file. To do that, open Twine and choose Show Library from the Twine menu. This will open the folder on your computer where Twine automatically saves your stories as you work. Update Gruntfile.js with this path. It'll look something like this:

Gruntfile.js
module.exports = function(grunt) {
  require('load-grunt-tasks')(grunt);
 
  grunt.initConfig({
    copy: {
      fromTwine: {
        files: [{
	  src: '/Users/Me/Documents/Twine/My Story.html',
          dest: 'src/'
        }]
      }
    }
  });
 
  grunt.registerTask('default', ['copy']);
};

If you are using Windows, you should always change the backslashes (e.g. \) in paths to forward slashes (e.g. /) when using Grunt.

How did we know about grunt-contrib-copy, and what syntax to use? Grunt maintains a searchable plugin registry of its own. Chances are, for whatever task you can think of, there is a Grunt plugin to help you.