HTTPS SSH
# SugarCube # [SugarCube](http://www.motoslave.net/sugarcube/ "http://www.motoslave.net/sugarcube/") is a free (gratis and libre) story format for [Twine/Twee](http://twinery.org/ "http://twinery.org/"). By: @tmedwards. Contributions by: @hogart and @klembot. Downloads and documentation may be found at [SugarCube's website](http://www.motoslave.net/sugarcube/ "http://www.motoslave.net/sugarcube/"). ## REQUIREMENTS ## SugarCube's sole requirement is a modern web browser, and by *modern* I mean one released within the last several years (you do not need the absolute latest and greatest shiny). **Caveat for Internet Explorer:** SugarCube only supports versions of IE ≥ 9. Users of Windows XP (who are limited to IE8) will not be able to play/view stories built with SugarCube with their version of IE. They would either have to use a different browser (e.g. Chrome or Firefox) or upgrade to a less obsolescent version of Windows (Microsoft ended public support for Windows XP in April, 2014). ## GETTING THE SOURCE ## You may get SugarCube's source in one of two ways, by downloading a specific tagged release or by cloning the repository. If you only wish to build the latest release in the v2 or v1 series, then the former option is probably easiest. If you wish to hack on SugarCube at all, then the latter option is probably best. ### Downloading a specific tagged release ### From the main repository's *Downloads* page, go to the *Tags* tab and download only the specific release you're interested in. ### Cloning the repository ### This requires you to have the [Mercurial (`hg`)](http://mercurial.selenic.com/ "http://mercurial.selenic.com/") source control management tool installed (knowing how to use it also helps). If you go this route, know that there are several active branches, so be sure to update your local clone to the branch you wish to work on by issuing the appropriate `hg update` command. The current permanent branches are: - `default`: The v3 development branch - `v2-devel`: The v2 development branch - `v2-release`: The v2 release branch - `v1-devel`: The v1 development branch - `v1-release`: The v1 release branch ## BUILDING ## If you want to build SugarCube from scratch, rather than grabbing one of the pre-built packages off of its website, then these instructions are for you. SugarCube uses Node.js as the core of its build system, so the first thing you need to do is to install it if you don't already have it. - [Node.js website: `http://nodejs.org/`](http://nodejs.org/ "http://nodejs.org/") After downloading and installing a recent version of Node.js (≥ `v8`), change to the root of the `sugarcube` project directory. You'll now need to download and install dependencies required by the build script, `build.js`, which you do by running the following command: ``` npm install ``` Dependencies will be installed to the root of the `sugarcube` project directory, nothing will be installed elsewhere on your computer. Assuming that completes with no errors, run the following command to build the story format: ``` node build.js ``` If you're running this from a UNIX-style shell, simply running `build.js` should also work as it's shebanged. If there were no errors, the story format, in both Twine 2 and Twine 1 compatible releases, will be output to the `dist` directory. Congratulations! **NOTE:** SugarCube's development dependencies are occasionally updated (last updated on: Jan 30, 2018). If you receive errors when attempting to build, then you probably need to update your cached dependencies. You may do this via the `npm update` command or, in extreme cases, by deleting the local `node_modules` directory and rerunning `npm install`. ---- If you'd like additional options when building (debug builds, limiting the build to a particular version of Twine, etc.), you may request help from `build.js` by running the following command: ``` node build.js -h ```