https://github.com/cliffhall/slim-tweego

A streamlined, Mac & Linux friendly tweego project skeleton
https://github.com/cliffhall/slim-tweego

game interactive-fiction project-starter tweego twine twine2

Last synced: 4 days ago
JSON representation

A streamlined, Mac & Linux friendly tweego project skeleton

• Host: GitHub
• URL: https://github.com/cliffhall/slim-tweego
• Owner: cliffhall
• Created: 2019-09-02T21:36:38.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2019-12-03T16:04:29.000Z (about 5 years ago)
• Last Synced: 2024-12-09T18:33:38.441Z (2 months ago)
• Topics: game, interactive-fiction, project-starter, tweego, twine, twine2
• Language: JavaScript
• Homepage:
• Size: 354 KB
• Stars: 3
• Watchers: 3
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# slim-tweego

A streamlined tweego project skeleton

## STATUS

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

## DEVELOPER SETUP

### Prerequisites

* [Node](https://nodejs.org/en/download/) v12.6.0 or above (also installs npm)

* [Tweego](https://www.motoslave.net/tweego/) v2.0.0 or above

#### If Installing Tweego on Windows

* Here is [a handy project](https://github.com/ChapelR/tweego-installer) 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](https://github.com/cliffhall/mars-colony/archive/master.zip) 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](http://babel.ifarchive.org/) 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](https://github.com/ChapelR/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](https://twinery.org/) 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.