SugarCube

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 IE ≥9. So, 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 or upgrade to a less obsolescent version of Windows (Microsoft ended public support for Windows XP in April, 2014).

If you notice any errors or broken links within this documentation, please let me know.

• SugarCube v2 Documentation

  Quick links:

  • Guide: Installation – How to install SugarCube.
  • Guide: Code Updates – How to update existing code to work with newer versions of SugarCube.

• License (Simplified BSD License) @github.com

SugarCube v2.37.3 (released on: 2024-07-26)

See the release notes to learn what's changed.

• For Twine ≥2.1 & Twee compilers (local/offline) [ZIP archive] [159 KiB] – The recommended release.

• For Twine 1.4 & Twee compilers [ZIP archive] [157 KiB]

  NOTE: Due to a flaw in the current release of Twine 1 (v1.4.2), if you rename the directory included in the archive (or simply copy its contents to your current SugarCube v2 install), then you must ensure that the file with the extension .py (the story format's custom Twine 1 Header class file) within is named the same as the directory (i.e. the name of the directory and .py file must match).

  For example, if the name of SugarCube's directory is sugarcube, then the name of the .py file within must be sugarcube.py. Similarly, if the directory is sugarcube-2, then the name of the .py file within must be sugarcube-2.py. Etc.

  The directory and .py file names within the archive available for download are already matched—as sugarcube-2 and sugarcube-2.py—and to avoid issues it recommended that you simply do not rename them.

Stylesheets

• Bleached [ZIP archive] [1006 Bytes] – A primarily white style.

Localizations

Contributed localizations of SugarCube's default UI strings. All localizations are JavaScript which must be placed within a script section (Twine 1: script-tagged passage; Twine 2: Story JavaScript).

• (none at this time)

Add-ons

Either code/macros that I've written for SugarCube or SugarCube-compatible conversions of other people's code/macros (hosted here with permission). These are for SugarCube and will not work in other Twine story formats.

• <<numberpool>> macro set [ZIP archive] [7 KiB] – Number input macros with support for pools.
• <<shake>> macro set [ZIP archive] [5 KiB] – Macros for applying a shaking animation to various element(s).
• <<audioloopto>> macro set [ZIP archive] [7 KiB] – Macros for switching from a looping track to another track upon navigation.
• <<replacelink>> macro set [ZIP archive] [8 KiB] – SugarCube version of Leon's Combined Replace Macro Set.

• <<bugreport>> macro [ZIP archive] [6 KiB] – Debugging aid.
• <<checkvars>> macro [ZIP archive] [5 KiB] – Debugging aid.

• SugarCube v2 source code repository @github.com