nijikokun / sugarcube-starter

Easy to use starter kit for creating stories with Tweego, Twine and SugarCube.

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.

sugarcube-starter's Issues

Add a 'cleanall' type of npm command for cleanup between builds.

This is a very cool system, but I have had trouble with updates. Each time it fails in some way that npm reports as unfixable. So what I usually need to do is re-download the entire updated repo in a new directory and than copy my files over top. This is the 3rd time since I started using this project.

I kind of want to have my files checked into local git repo, but even that won't solve this problem. Could we get an npm command to clean up the old built/downloaded version of code?

Live reload doesn't work after the first reload

Hello! I'm trying out this starter, but I noticed that the Live Reloading feature only works on the first rebuild, and not on subsequent rebuilds. I tried using the "--watch" option in the config file like this:

"tweego": {
  "dir": "./.tweego",
  "options": ["--watch"],
  …
}

… but the terminal stays stuck at this message when it's building the index.html file:

[builder] [init] Running build.

Watch mode started.  Press CTRL+C to stop.

Recursively watched paths: 3
  src\story
  dist\scripts
  dist\styles

BUILDING: dist\index.html

Is there any way to get both the Tweego rebuilding and style/js rebuilding processes to work at the same time?

.build/tweego_Installer.js not found due to case sensitive filesystem on Linux

Hello,

npm start fails on Linux (and probably MacOS) because tweego_Installer.js is imported from .build/build_command.js but filename is tweego_installer.js.

Easy fix, replace line 9 in .build/build_command.js with:

import { Installer } from "./tweego_installer.js";

Wrong version of tweego is pulled for macOS ARM platforms

Hi,

Decided to give this a spin and mess around with it a bit, got some spawnsync errors that it wouldn't run tweego however so decided to try to see if I can fix it. I am not sure which version gets downloaded really but whichever one it is it is the wrong version for macOS arm computers. The one that should be pulled is the tweego-2.1.1-macos-x64.zip (64-bit) version of tweego. I fixed it myself locally by just replacing the file but I thought I should at least give a headsup since twine and typescript seems like a great idea and I am very happy this project exists!

Add types-sugarcube

Add TypeScript definitions for the SugarCube Twine format.

npm install --save-dev @types/twine-sugarcube

Add Snowpack

A new bundler with a bunch of features and lightning fast compilation.

Lack of error messages

[builder] [init] Running build.

PS Dir>

Sometimes the builder just ends without an explanation. And a build is not even constructed. Without an error message, it's hard to debug.