├── .gitattributes ├── .gitignore ├── LICENSE ├── README.md ├── build.bat ├── build.js ├── dist ├── assets │ └── favicon.png └── compiled projects will output here ├── docs ├── installing-node.md └── installing-tweego.md ├── package-lock.json ├── package.json ├── project ├── compiled │ └── compiled scripts and styles will go here └── twee │ ├── compiler-options.twee │ └── story.twee └── src ├── head-content.html ├── modules └── place modules here ├── scripts └── put your scripts here └── styles └── put your css here /.gitattributes: -------------------------------------------------------------------------------- 1 | # Auto detect text files and perform LF normalization 2 | * text=auto 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | 8 | # Runtime data 9 | pids 10 | *.pid 11 | *.seed 12 | *.pid.lock 13 | 14 | # Directory for instrumented libs generated by jscoverage/JSCover 15 | lib-cov 16 | 17 | # Coverage directory used by tools like istanbul 18 | coverage 19 | 20 | # nyc test coverage 21 | .nyc_output 22 | 23 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 24 | .grunt 25 | 26 | # Bower dependency directory (https://bower.io/) 27 | bower_components 28 | 29 | # node-waf configuration 30 | .lock-wscript 31 | 32 | # Compiled binary addons (https://nodejs.org/api/addons.html) 33 | build/Release 34 | 35 | # Dependency directories 36 | node_modules/ 37 | jspm_packages/ 38 | 39 | # TypeScript v1 declaration files 40 | typings/ 41 | 42 | # Optional npm cache directory 43 | .npm 44 | 45 | # Optional eslint cache 46 | .eslintcache 47 | 48 | # Optional REPL history 49 | .node_repl_history 50 | 51 | # Output of 'npm pack' 52 | *.tgz 53 | 54 | # Yarn Integrity file 55 | .yarn-integrity 56 | 57 | # dotenv environment variables file 58 | .env 59 | 60 | # next.js build output 61 | .next 62 | 63 | dist/*.html -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Basic Tweego Setup (v3) 2 | 3 | > If you want to use Tweego v1.x, you'll want to switch to the `tweego-1` branch of this repo. 4 | 5 | This is the basic setup I use for creating Tweego projects. It's here so I can clone it when I need it, but you may find it useful, too. 6 | 7 | **Note**: When you compile your game for the first time, Tweego will throw an error. This is normal. It will complian that you don't have an IFID, and generate a new one for you. Take the number it gives you and add it to the `ifid` property in the `StoryData` passage in the `project/twee/compiler-options.twee` file. **Your game will NOT compile if you don't do this first!** 8 | 9 | ### Installing 10 | 11 | You'll need [NodeJS](docs/installing-node.md) and [Tweego](docs/installing-tweego.md) installed. Click the links to find my step-by-step instructions (with pictures) on how to do this on Windows systems. You will need to combine my instructions with a bit of Googling to get these working on other OSes. 12 | 13 | After getting all that squared away, clone or download this repo. Open a command prompt and navigate to the repo's root directory (where the `package.json` file is) and run the command `npm install`. This may take a couple of minutes, just let it go. After that, everything should be ready to go. 14 | 15 | ### Features 16 | 17 | Tweego Setup is a project skeleton/boilerplate that is intended to make getting started with Tweego easier for novice users. It provides the following tools already configured and ready to go. 18 | 19 | #### For JavaScript: 20 | 21 | - **Transpiling to ES5**: [Babel](https://babeljs.io/) is a JavaScript code transpiler that takes modern ES6 JavaScript and converts it to older ES5 code that works on older browsers, allowing you to write your code in modern JS without sacrificing browser support. 22 | - **Minification**: A minifier compresses your code by shortening expressions, removing whitespace, and more to save on file size, which improves the speed at which pages load on the web. This project skeleton uses [Terser](https://github.com/terser/terser) for JavaScript compression. 23 | 24 | #### For CSS: 25 | 26 | - **Auto-prefixing**: Some CSS properties require vendor prefixes to work in certain browsers. This project skeleton will use [autoprefixer](https://github.com/postcss/autoprefixer) to automatically determine which prefixes your CSS code needs and add them for you. 27 | - **Minification**: A minifier compresses your code by combining rules where possible and removing spaces and newlines to make code as lightweight as possible. This project skeleton uses [Clean-CSS](https://github.com/clean-css/clean-css) for CSS minification. 28 | 29 | #### Additional stuff: 30 | 31 | - **NPM Scripts**: A set of NPM scripts to run all the necessary commands to test and build your project. 32 | - **Localhost Server**: Includes [http-server](https://github.com/http-party/http-server) to allow you to run a simple localhost server to test your game if you need it. 33 | 34 | #### Linting 35 | 36 | Linting has been removed from the new version of this repo. Linting is fraught and a lot of people have strong opinions about which linters to use and how to configure them. In general, if you are a novice, you are probably best served by setting up a linter in your IDE of choice. For example, here is [ESLint for VSCode](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), and here's [jshint for the same](https://marketplace.visualstudio.com/items?itemName=dbaeumer.jshint). 37 | 38 | ### Recommended IDE for Tweego 39 | 40 | If you are new to writing code in an IDE and not sure what to use, I highly suggest using [VSCode](https://code.visualstudio.com/), an excellent all-around IDE for web development. VSCode also has a very powerful extension called [Twee 3 Language Tools](https://marketplace.visualstudio.com/items?itemName=cyrusfirheir.twee3-language-tools) that is ideal for working with Tweego. 41 | 42 | ### Structure 43 | 44 | There are three main folders that you'll be working with here. The first is the `dist` folder. When you compile your project, it will get sent here as `dist/index.html`. If you have external resources using relative links, like fonts, sounds, or images, you'll want to put them in here. 45 | 46 | The `project` folder is where you'll edit your passages, and only your passages. Your JavaScript and CSS code will wind up here eventually, but you won't write it here--just ignore the `compiled` directory. For scripts and styles that are already compiled and ready to include (e.g., one of my custom macro scripts) you can drop these files directly into the `project/compiled` directory. 47 | 48 | The `src` folder is where your custom JavaScript and CSS code will go. Place JavaScript files in the `src/scripts` folder, and make sure they have the extension `.js`. Place your CSS files in the `src/styles` folder and make sure they have the extension `.css`. Files in these folders will be concatenated, minified, (for JS) transpiled, and (for CSS) autoprefixed, then sent to the `project` folder to be picked up by Tweego. 49 | 50 | The `src/modules` folder allows you to add scripts, styles, fonts, and more directly to the document's ``. Things like Google analytics scripts, web libraries, and favicon code will go here. Code included in this way is not processed and is simply included as-is. 51 | 52 | Finally, there's the `head-content.html` file. You can add HTML code to your project's `` using this file. If you don't need it, just leave it blank. 53 | 54 | ### Usage (CLI) 55 | 56 | The following scripts are run from the command line. Simply navigate to the project's root directory and type in the appropriate command. 57 | 58 | * `npm start`: Starts up a simple localhost test server. Not needed for all projects. 59 | * `npm run build`: Compiles your JS and CSS, then compiles everything with Tweego and drops the compiled file in the `dist` folder. 60 | * `npm run build:test`: As `npm run build`, but compiles your story in test mode. 61 | * `npm run compile:src`: This command only runs the non-Tweego portion of the build process. Probably not very useful. 62 | * `npm run compile:twee`: This command only runs the Tweego portion of the build process, so files from `src` aren't added in. Useful for building faster when you're only working on TwineScript. 63 | * `npm run watch:twee`: As `npm run compile:twee`, only compiles the Tweego portion, but does so in watch mode. 64 | * `npm run test:twee`: As `npm run compile:twee`, only compiles the Tweego portion, but does so in test mode. 65 | 66 | On Windows, you can double-click the `build.bat` file to run `npm run build` for you without needing to use the terminal. 67 | 68 | ### Configuration Settings 69 | 70 | At the top of the `build.js` file are a number of options you can alter. 71 | 72 | #### Files and File Paths 73 | 74 | ![](https://i.imgur.com/SVMEKPG.jpg) 75 | 76 | At the top of the script are two arrays (by default, they are empty), one for JS files, and one for CSS files. If you leave these empty, Tweego Setup will grab all the `.js` files from the `src/scripts` folder and all the `.css` files from the `src/styles` folder (subdirectories will be recursively searched as well), and they will be concatenated in the order provided by your operating system (*usually* alpha-numeric order). However, if you need your files to be compiled in a specific order, you will instead need to provide an array of file names to one or both of these. 77 | 78 | If you provide filenames to one of the arrays, the directory associated with that array will no longer be searched, and only files listed in the array will be compiled, so this is an all-or-nothing kind of thing, either the directories are searched recursively, or you provide all the file names. 79 | 80 | By default, the files will be grabbed from the `src/scripts` and `src/styles` directories for each array, so if the file path is `src/scripts/test.js`, you only need to provide `test.js` in the array. 81 | 82 | ![](https://i.imgur.com/tJJXjQF.jpg) 83 | 84 | You can alter the base file paths here, if you want to. By default, Tweego Setup looks for JavaScript in `src/scripts`, CSS in `src/styles`, and deposits the compiled files to `project/compiled` to be picked up by Tweego. You can change these defaults if you want to restructure the directories. 85 | 86 | #### Tooling Options 87 | 88 | ![](https://i.imgur.com/dDYbncm.jpg) 89 | 90 | Most of the tools used by Tweego Setup have configuration options that can be altered. You edit those options here, as plain objects. Visit the provided URLs to see documentation regarding the options for each tool. 91 | 92 | #### Changing Story Formats 93 | 94 | ![](https://i.imgur.com/btJGIMc.jpg) 95 | 96 | You can change the story format used to compile your project in the `project/twee/compiler-options.twee` file. This file contains [a passage named `StoryData`](https://www.motoslave.net/tweego/docs/#special-passages-storydata) that accepts plain JSON. You can change the story format and version to a different one Tweego has access to from here. Use the command `tweego --list-formats` from the command line to see a list of available formats. 97 | 98 | **Note**: When you compile your game for the first time, Tweego will throw an error. This is normal. It will complian that you don't have an IFID, and generate a new one for you. Take the number it gives you and add it to the `ifid` property in the `StoryData` passage in the `project/twee/compiler-options.twee` file. **Your game will NOT compile if you don't do this first!** 99 | 100 | ### Donations 101 | 102 | Note: I suggest donating to [Twine development](https://www.patreon.com/klembot) or [SugarCube development](https://www.patreon.com/thomasmedwards) if you really want to help out, but I'd welcome a few dollars if you feel like it. 103 | 104 | [![ko-fi](https://www.ko-fi.com/img/donate_sm.png)](https://ko-fi.com/F1F8IC35) -------------------------------------------------------------------------------- /build.bat: -------------------------------------------------------------------------------- 1 | @echo off 2 | call npm run build -------------------------------------------------------------------------------- /build.js: -------------------------------------------------------------------------------- 1 | // list of javascript and CSS files (optional) 2 | // leave the arrays empty and the files in the relevant folders will be compiled in the order provided by the OS 3 | const files = { 4 | // if you choose to include lists of files, only the included files will be compiled! 5 | js : [ 6 | // if order of files is important, list them here in the correct order 7 | ], 8 | css : [ 9 | // if order of files is important, list them here in the correct order 10 | ] 11 | }; 12 | 13 | // paths to directories containing raw source files 14 | const jsPath = "src/scripts/"; 15 | const cssPath = "src/styles/"; 16 | // path to project files 17 | const outputPath = "project/compiled/"; 18 | 19 | const cleanCssOptions = { 20 | // CleanCSS options (https://github.com/clean-css/clean-css#constructor-options) 21 | }; 22 | const terserOptions = { 23 | // Terser options (https://github.com/terser/terser#minify-options) 24 | }; 25 | const babelOptions = { 26 | // Babel options (https://babeljs.io/docs/en/options) 27 | presets : [['@babel/preset-env', { 28 | targets : [ 29 | "> 1%", 30 | "last 3 versions", 31 | "last 10 Chrome versions", 32 | "last 10 Firefox versions", 33 | "IE >= 9", 34 | "Opera >= 12" 35 | ] 36 | }]] 37 | }; 38 | 39 | // you shouldn't need to change anything below this comment if you're just editing your compiling options! 40 | 41 | const jetpack = require("fs-jetpack"); 42 | const postcss = require("postcss"); 43 | const autoprefixer = require("autoprefixer"); 44 | const CleanCSS = require("clean-css"); 45 | const Terser = require("terser"); 46 | const Babel = require('@babel/core'); 47 | 48 | function compileCSS () { 49 | const css = (files.css && files.css instanceof Array && files.css.length > 0) ? 50 | files.css.map( fileName => { 51 | return jetpack.read(`${cssPath}${fileName}`); 52 | }).join("\n\n") : 53 | jetpack.find(cssPath, { matching : "*.css" }).map( fileName => { 54 | return jetpack.read(fileName); 55 | }).join("\n\n"); 56 | 57 | postcss([ autoprefixer ]).process(css, { from : undefined }).then(result => { 58 | result.warnings().forEach( warn => console.warn(warn.text) ); 59 | jetpack.write(`${outputPath}build.css`, new CleanCSS(cleanCssOptions).minify(result.css).styles, { atomic : true }); 60 | }); 61 | } 62 | 63 | function compileJS () { 64 | let js = (files.js && files.js instanceof Array && files.js.length > 0) ? 65 | files.js.map( fileName => { 66 | return jetpack.read(`${jsPath}${fileName}`); 67 | }).join("\n\n") : 68 | jetpack.find(jsPath, { matching : "*.js" }).map( fileName => { 69 | return jetpack.read(fileName); 70 | }).join("\n\n"); 71 | 72 | js = Babel.transform(js, babelOptions).code; 73 | 74 | Terser.minify(js, terserOptions).then(result => { 75 | if (result.error) { 76 | console.error(result.error); 77 | } 78 | 79 | jetpack.write(`${outputPath}build.js`, result.code, { atomic : true }); 80 | }); 81 | } 82 | 83 | // run 84 | compileCSS(); 85 | compileJS(); -------------------------------------------------------------------------------- /dist/assets/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/dist/assets/favicon.png -------------------------------------------------------------------------------- /dist/compiled projects will output here: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/dist/compiled projects will output here -------------------------------------------------------------------------------- /docs/installing-node.md: -------------------------------------------------------------------------------- 1 | ## Installing NodeJS 2 | 3 | You can install node from [here](https://nodejs.org/en/). You want to grab the LTS version, usually the one on the left. This will download an msi file, that will then install node on your system. 4 | 5 | The only thing to watch out for when installing Node is to make sure that it is added to your path, and that you include npm. By default, both of these options will be enabled. For best results, install node on your main hard drive (usually C) with your operating system. 6 | 7 | ![alt text](https://i.imgur.com/uaXMM9k.png "Make sure to include npm and add to path!") 8 | 9 | To make sure eveything works, you can open a command prompt and type `npm`. If the command isn't recognized, you've messed up! Otherwise, a help message explaining npm should display. 10 | -------------------------------------------------------------------------------- /docs/installing-tweego.md: -------------------------------------------------------------------------------- 1 | ## Installing Tweego 2 | 3 | On most versions of Windows, you can use [this installer](https://github.com/ChapelR/tweego-installer/releases) to set up Tweego instead of installing it manually. If you cannot use said installer or prefer to set it up manually, carry on with these instructions. 4 | 5 | Installing Tweego globally is probably your best bet. You can also install it locally, which has some benefits. I won't cover the latter right now, but it may be added in the future. 6 | 7 | These instructions are for Windows 10. Windows 7 follows a similar process, but you'll need to add to the path variable manually. This guide may help you get started on other operating systems, too. 8 | 9 | ### Step 1: Download Tweego 10 | 11 | ![alt text](https://i.imgur.com/VhjWCad.png) 12 | 13 | You can grab both Tweego and a collection of Twine 2 formats from [Tweego's site](http://www.motoslave.net/tweego/). You may need to update some of the story formats in the collection. Regardless, download both and unzip them. 14 | 15 | ### Step 2: Find a home for Tweego 16 | 17 | You can put Tweego anywhere, but the simplest places that are closest to your main drive's root are probably best. I usually put my stuff right on C. 18 | 19 | ![alt text](https://i.imgur.com/zExCubX.png) 20 | 21 | I create a folder called `tweego`, then place the tweego binary and the `story-formats` folder inside it. 22 | 23 | ![alt text](https://i.imgur.com/BEMfQaw.png) 24 | 25 | Just to be safe about it, make sure that the inside of the `story-formats` folder looks something like this. 26 | 27 | ![alt text](https://i.imgur.com/8skfhb4.png) 28 | 29 | ### Step 3: Adding Tweego to you PATH 30 | 31 | Next we'll need to add Tweego to out PATH environment variable. You'll need to go to the `System` section of your control panel. You can search for it. In the picture below, it's the second option. 32 | 33 | ![alt text](https://i.imgur.com/BWA8QDF.png) 34 | 35 | Go to `advanced system settings`. 36 | 37 | ![alt text](https://i.imgur.com/kjGOVGb.png) 38 | 39 | Click `environment variables` on the bottom right. 40 | 41 | ![alt text](https://i.imgur.com/jmOwmFa.png) 42 | 43 | Under `system variables` at the bottom, find `Path`. Highlight it and press `edit`. 44 | 45 | ![alt text](https://i.imgur.com/HTS76WV.png) 46 | 47 | On the resulting screen, click `new` on the top right. 48 | 49 | ![alt text](https://i.imgur.com/6C69SoU.png) 50 | 51 | Type in the path to the folder containing tweego. If you did this like I did, you'll type in `C:\tweego\`. 52 | 53 | ![alt text](https://i.imgur.com/7rDJ22z.png) 54 | 55 | Click OK when you're done, but don't close the Environment Variables window yet! 56 | 57 | ### Step 4: Add the TWEEGO_PATH variable 58 | 59 | This step is optional but recommended. You may as well do it while you're here to prevent potential headaches later. 60 | 61 | Back in the Environment Variables window, click `New`. 62 | 63 | ![alt text](https://i.imgur.com/LnZ3chF.png) 64 | 65 | Set the variable name to `TWEEGO_PATH` and the value to the path that leads to your `story-formats` folder. If you set it up the same way I did, that path will be `C:\tweego\story-formats` 66 | 67 | ![alt text](https://i.imgur.com/vJrHaLe.png) 68 | 69 | ### Step 5: Testing Tweego 70 | 71 | Open a command prompt and type `tweego`. If the command is unrecognized, something was messed up, otherwise, an explanation of tweego should print out. Type in `tweego --list-formats` to make sure you've installed all the formats correctly and set up `TWEEGO_PATH` correctly. It should display all the formats you have in your `story-formats` directory. -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "tweego-setup", 3 | "version": "3.0.0", 4 | "description": "A basic project setup for Tweego with all the trimmings using Node.", 5 | "main": "build.js", 6 | "scripts": { 7 | "start": "cd dist && npx http-server -c0 -o", 8 | "compile:src": "node build.js", 9 | "compile:twee": "tweego -o dist/index.html -m src/modules/ --head=\"src/head-content.html\" project", 10 | "watch:twee": "tweego -o dist/index.html -m src/modules/ --head=\"src/head-content.html\" project -w", 11 | "testmode:twee": "tweego -o dist/index.html -m src/modules/ --head=\"src/head-content.html\" project -t", 12 | "build": "npm run compile:src && npm run compile:twee", 13 | "build:test": "npm run compile:src && npm run testmode:twee" 14 | }, 15 | "keywords": [ 16 | "twine", 17 | "tweego", 18 | "twee" 19 | ], 20 | "author": "Chapel", 21 | "license": "Unlicense", 22 | "directories": { 23 | "doc": "docs" 24 | }, 25 | "devDependencies": { 26 | "@babel/core": "^7.18.9", 27 | "@babel/preset-env": "^7.18.9", 28 | "autoprefixer": "^10.4.7", 29 | "clean-css": "^5.3.1", 30 | "fs-jetpack": "^4.3.1", 31 | "http-server": "^14.1.1", 32 | "postcss": "^8.4.14", 33 | "terser": "^5.14.2" 34 | }, 35 | "repository": { 36 | "type": "git", 37 | "url": "git+https://github.com/ChapelR/tweego-setup.git" 38 | }, 39 | "bugs": { 40 | "url": "https://github.com/ChapelR/tweego-setup/issues" 41 | }, 42 | "homepage": "https://github.com/ChapelR/tweego-setup#readme", 43 | "private": true, 44 | "browserslist": [ 45 | "> 1%", 46 | "last 3 versions", 47 | "last 10 Chrome versions", 48 | "last 10 Firefox versions", 49 | "IE >= 9", 50 | "Opera >= 12" 51 | ] 52 | } 53 | -------------------------------------------------------------------------------- /project/compiled/compiled scripts and styles will go here: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/project/compiled/compiled scripts and styles will go here -------------------------------------------------------------------------------- /project/twee/compiler-options.twee: -------------------------------------------------------------------------------- 1 | :: StoryData 2 | { 3 | "ifid": "", 4 | "format": "SugarCube", 5 | "format-version": "2.36.1" 6 | } -------------------------------------------------------------------------------- /project/twee/story.twee: -------------------------------------------------------------------------------- 1 | :: StoryTitle 2 | Tweego Basic Setup 3 | 4 | :: Start 5 | @@#hello;Hello World!@@ -------------------------------------------------------------------------------- /src/head-content.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /src/modules/place modules here: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/src/modules/place modules here -------------------------------------------------------------------------------- /src/scripts/put your scripts here: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/src/scripts/put your scripts here -------------------------------------------------------------------------------- /src/styles/put your css here: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ChapelR/tweego-setup/3e3061de1010933725626795b3a247eef50dffbe/src/styles/put your css here --------------------------------------------------------------------------------