SugarCube Starter

The easiest starter kit for building SugarCube stories with Twine / Tweego.

🎨 Features

• Automatic Tweego & SugarCube Install ✅
• Fully Configurable ✅
• Automatic Builds ✅
• Local server with Live Reload ✅
• Directory for custom fonts ✅
• Directory for third-party scripts ✅
• Up to date packages and frameworks ✅

🗃 Tech Stack

Built in to this template are a number of frameworks to get you going.

• Webpack v5
• Typescript
• Babel with @babel/preset-env for vendor scripts
• Sass with Modern CSS Support

ℹ Requirements

• Node.js 14+

🚀 Getting Started

1. Clone the repository

   npx degit nijikokun/sugarcube-starter <project-name>
   

2. Install modules

   npm install
   

3. Start developing

   npm start
   

New to SugarCube?

• Check out our SugarCube Basics

👩‍💻 Commands

• npm start - Alias for npm run dev
• npm run dev - Starts development server and watches src directory.
• npm run dev:prod - Starts development server and watches src directory in production mode (NODE_ENV=production).
• npm run build - Compiles and bundles the story in the dist directory.
• npm run build:prod - Compiles and bundles the story in the dist directory for production.

📁 Directory Structure

• .build — Webpack configuration and Build scripts
• src — Story and Story Assets directory
• src/assets — Story Assets (Scripts, Styles, Media, Fonts)
• src/assets/app — Story JavaScripts and Stylesheets
• src/assets/app/styles — Story Stylesheets (SASS)
• src/assets/fonts — Static Fonts to be hosted / distributed
• src/assets/media — Images and Videos
• src/assets/vendor — Third-Party Scripts and Modules
• src/story — SugarCube / Twine .twee files
• config.json — Webpack, Tweego, Babel and Build Configuration.

Auto-Generated Directories

• .tweego — Tweego installation and story formats are installed here
• .prebuilt — Staging directory, files are processed and moved to dist
• dist — Compiled output directory

🙋‍♂️ How To

How do I update?

Before continuing make sure you back up your existing code!

1. Download the latest release
2. Copy over the package.json, config.json, tsconfig.json files and the .build directory.
3. Run npm start

And that's it!

Note You might want to use something like jsondiff for the config.json if you have made changes.

---

How do I disable Debug View?

Debug View looks like this:

Option One (Production Mode)

Run development in production mode:

npm run dev:prod

Option Two

Create src/story/PassageReady.twee and put the following code inside:

:: PassageReady
<<run DebugView.disable()>>

Option Three

Open src/story/Start.twee and add the following code:

::StoryJavaScript[script];
predisplay["debug-disable"] = function (taskName) {
  DebugView.disable();
};

Option Four

Open src/story/Start.twee and add the following code:

::StoryJavaScript[script](function () {
  Setting.addHeader("Debug Settings");

  function initSettingDebug() {
    Config.debug = settings.debug;
  }
  Setting.addToggle("debug", {
    label: "Enable test/debug mode?",
    default: false,
    onInit: initSettingDebug,
    onChange: function () {
      initSettingDebug();
      window.location.reload();
    },
  });
})();

---

How should I initialize variables?

You should initialize your story variables using the StoryInit passage.

A good place to start is in src/story/Start.twee:

:: StoryInit
<<set $health = 100>>
<<set $maxHealth = 100>>

:: Start

HP: <<= $health>> / <<= $maxHealth>>

---

How do I install macros?

Macros scripts and styles go into src/assets/vendor

---

How do I link to media files?

To reference images and media at src/assets/media/<asset_path> you'll use media/<asset_path>. For eample:

• src/assets/media/favicon.png → media/favicon.png

Here is an example in html (example):

<link rel="icon" type="image/png" href="media/favicon.png" />

---

How do I add Google Analytics?

Paste the following snippet into src/head-content.html:

<script
  async
  src="https://www.googletagmanager.com/gtag/js?id=YOUR_TAG_HERE"
></script>

and replace YOUR_TAG_HERE with your Google Analytics ID (UA-########).

---

How do I change the app directory name?

I don't suggest doing this, but if you really want to... You need to modify all instances of src/assets/app in two locations:

• config.json
• tsconfig.json

Good luck!

🛣 Roadmap

• Automatically install tweego for users so they don't have to.
• Add typescript support out of the box.
• Add configuration, commands and build process for production.
• Add command for testing build before distribution.
• Add support for packaging dist directory.
• Add support for compiling to Electron application.

🤝 Helpful Resources

Starter Kit Resources

• Niji's SugarCube Basics

Official Resources

• SugarCube Docs

Third-Party Resources

• Chapel's Custom Macro Collection
• Hogart's SugarCube Macros and Goodies
• SjoerdHekking's Custom Macros
• GwenTastic's Custom Macros
• Cycy Custom Macros
• HiEv SugarCube Sample Code
• Akjosch SugarCube Resources
• Mike Westhad SugarCube Resources
• HiEv Universal Inventory

💜 Acknowledgements

We are grateful to these individuals for their ideas and contributions.

• @ryceg
• @cyrusfirheir

📝 License

Licensed under the MIT License.