slim-tweego

A streamlined tweego project skeleton

STATUS

Production - Ready for prime time. Build the Twine game of your dreams!

DEVELOPER SETUP

Prerequisites

• Node v12.6.0 or above (also installs npm)
• Tweego v2.0.0 or above

If Installing Tweego on Windows

• Here is a handy project that may help. Good luck and godspeed.

If Installing Tweego on Mac or Linux

• Unzip distribution file in your home directory
• Assuming the unzipped folder was: tweego-2.0.0-macos-x86
  • Create a symbolic link to the executable: ln -s ~/tweego-2.0.0-macos-x86/tweego /usr/local/bin/tweego
  • Create a symbolic link to the storyformats: ln -s ~/tweego-2.0.0-macos-x86/storyformats ~/.storyformats
• Adjust the folder name in the above two commands based on your actual distribution folder name.

Download the project

• Download the project as a .zip file and unzip wherever you keep your projects.
• OR if you have git installed on your system:

cd path/to/your/projects
git clone https://github.com/cliffhall/slim-tweego.git

Install dependencies

cd path/to/slim-tweego
npm install

Build the entire project once

npm run build-once

FIRST TIME ONLY: Apply the generated IFID

By default there is no IFID for the story. If you plan to have your story published in any of the Interactive Fiction archives, you must have a unique IFID. When you ran the build-once script above, you should have seen some output like this:

error: Story IFID not found; generating one for your project.

Copy the following line into the "StoryData" special passage's JSON block (at the top):

	"ifid": "9E0E7A1D-DE49-432F-AA41-9FD9A582AB63",

In order to make use of the generated ID (don't quote the one above, it's for demonstration purposes only), copy the "ifid": "..." line that was output by the compiler and add it to the StoryData section in project/twee/story.twee like this:

:: StoryData
{
	"ifid": "9E0E7A1D-DE49-432F-AA41-9FD9A582AB63",
	"start": "In the park"
}

Then run the build again:

npm run build-once

Test the output

Open dist/index.html in your browser of choice

CONTINUOUS DEVELOPMENT

To work on JS, CSS, and TWEE sources and have them continuously compiled as you make changes, you need to open two dedicated terminal windows and run:

npm run watch:gulp

and

npm run watch:twee

CHANGE DEFAULT STORY FORMAT

The default story format is SugarCube 2. If you would like to change it, simply edit package.json and in the config section change the value of format. Currently it looks like this:

  "config": {
    "format": "sugarcube-2"
  }

Check the contents of ~/.storyformats for the names of the other supported formats:

$ ls ~/.storyformats
harlowe-1	harlowe-3	snowman-1	sugarcube-2
harlowe-2	paperthin-1	sugarcube-1

Also, if you want to install another format that doesn't ship with tweego, that's the place to put it.

PROJECT STRUCTURE / BUILD PROCESS

The structure and build process were inspired by and based upon tweego-setup by Chapel.

That said, a lot of changes have been made.

• It is Mac and Linux friendly.
• It does not have batch files for windows (the above project can help with that). Essentially the batch files were just helpers for running npm scripts, which if you're doing things in a modern IDE like Webstorm, you can launch automatically with a click anyway
• Folders have been moved around, renamed, or removed altogether in the interest of streamlining and clarity.
• Configuration of gulp (previously config.json) has been moved inside gulpfile.js. Since it wasn't being used for anything else, there was no need to arbitrarily separate the two.
• Support is added to start gulp and tweego in watch mode, so you can just edit your .css, .js, and .twee files at will and it will automagically recompile everytime you save.
• Configurable support for SASS/SCSS compilation instead of the default CSS. See below for instructions.

Ok, so where does stuff go?

• Media files that the project references (images, videos, sounds) should be placed directly into the dist/assets folder, as they are not handled at any stage in the build process.
• Custom JavaScript and CSS goes in the src/app folder.
• Third party JavaScript and CSS goes in the src/vendor folder.
  • If available, use the unminified vendor source (e.g, bootstrap.css and bootstrap.js instead of bootstrap.min.css and bootstrap.min.js).
• Custom fonts go in the project/modules folder and will end up being placed in the output file as raw data rather than files to be loaded.
• Finally, Twee source files go in the project/twee folder.

How and what does this thing build?

It is a two-step build whose final output lands in dist/index.html, which then is hopefully a playable Twine game.

1. Bundle vendor and app-specific JS/CSS.

This is achieved with gulp as configured in gulpfile.js. All of the .css and .js files found in src/app are transpiled from ES6 to ES5 and minified to /project/modules/app.min.css and project/modules/app.min.js. Similarly, any third party .css and .js files found in src/vendor are processed and placed in /project/modules/vendor.min.css and project/modules/vendor.min.js.

2. Compile twee source and bundled styles and scripts from step 1.

This is achieved with tweego as scripted in package.json in the scripts section. It compiles your .twee source code in project/twee and picks up any fonts you may have placed in the project/modules folder as well as minified app and/or vendor files that were left there by step 1. All this stuff -- fonts, transpiled/minified JS & CSS, and compiled TWEE -- are then baked into a single output file at dist/index.html.

Hey, I'd like to use SASS/SCSS instead of CSS!

I hear ya. Variables, amirite? Gotcha covered.

By default the system is setup to use CSS, just because that's what most folks know. To change this, just edit gulpfile.js, and change the variable CFG.CSS.SASS from false to true. Now any .scss files in src/app will be compiled to project/app.min.css and any .css files will be ignored - the opposite of what happens by default.

NOTE: If you already ran the watch:gulp task, you'll need to stop it and start it again after making this change.