This is a skeleton project folder that can help you get started with using Grunt and Entwine to build Twine stories outside of Twine. This doesn't replace Twine, but contains automated tasks that can help you build complex stories with it.
With this, you can:
- Build a large story by combining several individual stories, similar to the StoryIncludes feature of Twine 1
- Write some or all of a story using Twee source code
- Easily manage multimedia assets like images, audio, and video
- Use source control to keep track of the revision history of your story
- Publish a desktop app version of your story
This requires that you use a command prompt, but this document will guide you through what's needed.
If you already have installed Node and Grunt on this computer, you can skip this section. Otherwise, you'll need to follow these steps to do so.
First, download Node. It's the platform that the tasks in this project run on.
- Visit https://nodejs.org/ in your web browser.
- Choose to download the LTS version.
- Open the file you downloaded to install Node.
Then, you need to install Grunt, which is an automated task runner. Once it's set up, it will allow you to run tasks that involve multiple steps -- like copying files from one place to another and then publishing your story to an app -- with a single command. It's also able to do this for you automatically as you change files, without having to type a command each time.
Node has a program called npm, short for Node Package Manager, that will do the work of downloading and installing Grunt for you. To use npm, you'll need to use a command prompt. The way to do this varies by the operating system you are using.
On Windows, open the Start menu, then choose All Programs. In the folder named Node.js, there's an item named "Node.js command prompt." Choose this.
On OS X, open the Terminal application that's in the Utilities folder of your Applications folder.
On Linux, how you open a terminal window depends on what distribution you're using. On Ubuntu, open the Applications menu. In the Accessories folder, there's an item named "Terminal."
Once you have a command prompt open, type
npm install -g grunt and press
the Enter key. (In the rest of this document, we'll shorten this to just 'run a
command,' or 'run'.) npm will think for a moment, then print out text as it installs
Grunt for you. When the prompt reappears, it's done.
Don't close this terminal window-- you'll need it in the next section.
If you haven't already, download a fresh copy of the project
unzip it by opening the resulting file. You'll end up with a folder named
grunt-entwine-quickstart. Rename it to match the name of your project. You
can put this folder anywhere you like on your computer.
In order to complete setup, you'll need to navigate to your project folder from
a command prompt. Follow the directions above if you need a terminal window. To
navigate to your project folder, first type
cd (short for change
directory), then a space.
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
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
On Linux, the easiest way to get there varies by your distribution. On Ubuntu, try following these directions.
Once you do that, run the command
npm install. Similar to installing Grunt in
the previous section, this sets up everything behind the scenes for your
project. It's normal for npm to not print anything out at first while it does
this. You may also see warnings appear during this process. So long as npm's
output doesn't end with these warnings, things should be fine.
After npm completes and you see the command prompt again, run
This will ask you some basic questions about what should go into the story you
will build in your project. If you change your mind about your answers later,
you can enter
grunt setup again at any point to change them.
Important: when you're selecting what stories to use, make sure to use the space bar to select them, then press Enter when you're ready to move on to the next question. Watch the dots on the left side of the screen -- they will fill in when you have selected a story.
Once you've gone through
grunt setup, try running
grunt build. Grunt will
print text as it builds your story. If it concludes by printing "Done." in
green, look for a file under a new folder that Grunt created for you called
"dist" (short for "distribution" -- where versions of your story ready to be
published will appear). If it appeared, hooray! You have a working project.
Adding More Content To Your Story
To add another story you've created in Twine, run the command
again and select the story you'd like to add with the space bar. The stories you
have previously added will already be selected for you.
To add Twee source files to your project, copy them into the
src folder. You
can use any arrangement you like inside the
src folder, and nest them into
subfolders in whatever way makes sense to you.
src folder and
they'll be merged into your constructed story with
To use these, you must first have a command prompt open in your project's top-level folder. If you're not sure how to get there, follow the directions in the Project Setup section above.
You can always run
grunt help to see a full list of possible commands and a
short summary of what they do.
This constructs a story and saves it to the folder path
story will be constructed by following these steps:
Any stories you have added from Twine with
grunt setupwill be first copied to the folder named
twine-storiesat the top level of your project folder.
A new story will be created by merging:
- All stories in the
- Any Twine stories or Twee source code placed anywhere in the
srcfolder of your project. (They must have the file suffix
- Any files with the suffix
.css(for CSS rules) or
srcfolder of your project.
- All stories in the
Any image, audio, or video assets in the
srcfolder of your project will be copied to the same folder that your new story is in.
Keep in mind that you can organize files as you like inside the
including adding subfolders. When your story is built, all your assets will be
copied to the same level as the story file, regardless of what subfolder they
are located in in the
This does the exact same thing as
grunt build, but instead of it running
once, it constantly watches your Twine stories and contents of the
project folder for changes. As soon as something changes, the build process
will begin. You'll notice that this will occur even as you edit stories in
Twine, because it saves your work as you go.
To stop this process, go to your terminal window, hold the Control key down, and press C. If you use Windows, it'll ask you if you're sure you want to stop the task first.
This will not run
grunt build immediately, so if you'd like to build your
story and then watch for changes, run
grunt build watch instead.
This builds desktop application versions of your story for Windows, OS X, and
Linux. The resulting files will be placed in a folder named
app in the
You must run this on an OS X computer in order to create an OS X app, but otherwise it doesn't matter what platform you are using.
The first time you run this command, you must be connected to the Internet, as it will download NW.js, the engine that runs your stories. This can take a minute or more. After the first time, this command will finish much faster.
If you'd like to customize the icon of your app, place files named
app.icns at the top level of your project folder. They'll be used the
next time you run
To change the dimensions of the app window or start the app in fullscreen mode,
app-options.json with a text editor and change the values there.
This runs the setup process, asking you:
- What the name of your constructed story, e.g. the one created by
grunt build, should be.
- What story format you'd like to use for the constructed story.
- What stories, if any, in Twine you'd like to incorporate. Use the space bar here to select or deselect stories, and the Enter key to save your changes.
- What the name of your starting passage is. This is needed, since you may be incorporating multiple stories, each with a starting passage. It's important that you enter this name correctly. If your constructed story shows an error message when you first open it, double-check this.
The Anatomy of This Project Folder
Here's an explanation of what each folder and file does.
||This is a configuration file for app versions of your story. Read the NW.js documentation for detailed explanations of the settings here.|
||Your constructed story and supporting assets will appear here.|
||Twine stories you requested to be incorporated into your stories with
||If you're familiar with Grunt, you can add tasks of your own here without having to change
||The options you choose in
||The story format you would like the constructed story to use. Use
||Where all Grunt tasks are defined. You shouldn't need to change this.|
||A folder where the NW.js engine is stored after the first time you run
||General information about your project. You shouldn't need to change this.|
If Grunt runs into problems building your story, it will say:
Warning: Task "help" failed. Use --force to continue.
Sadly, this advice usually won't help. Some things to check if Grunt is not building your story:
Did you select at least one story from Twine with
grunt setup, or put story files into the
src/folder? Keep in mind that you need to select stories with the space bar, then press Enter to continue.
Did you enter the right starting passage name, with matching capitalization and spaces? This has to be exact, unfortunately.