The 100% Good ChoiceScript to Sugarcube Guide is a coding guide meant for ChoiceScript creators looking to use the SugarCube format of Twine. It is meant as a quick start-up and comparison of the different commands and structures between the two formats, including explanations with examples.
The Guide is based on the ChoiceScript Wiki and covers all the necessary commands and informations required to make a ChoiceScript game, and how it translated in SugarCube in terms of formatting, plain code, and macro equivalence. It also includes resources to go further into the formats.
READ & DOWNLOAD THE GUIDE!
The Guide is sectioned into multiple sections:
The Differences between Twine/SugarCube and ChoiceScript
The Command Equivalences (or close substitutes)
The Creation of a New Project, and QoL functionalities (Stats, Saves, Achievements, Settings)
For further details on how the macros/markups/APIs should be used, check out my SugarCube Guide (as it goes into a lot more details). If you are looking for the Tweego Compiler Folder, see this post.
Twine® is an “an open-source tool for telling interactive, non-linear stories” originally created by Chris Klimas maintained in severaldifferentrepositories (Twinery.org). Twine is also a registered trademark of the Interactive Fiction Technology Foundation.
SugarCube is a free (gratis and libre) coding format for Twine/Twee created and maintained by TME.
Tweego is one of the most important tools I use for creating my game. It allows me to work with multiple, smaller HTML files instead of one gigantic one, and then compile them all into a single game file. This system is incredibly helpful when working with the Twine editor because the editor lags with larger games.
Lag will occur with any story format. It is not affected by word count or character count, but rather by passage count. Because the Twine editor is a visual editor and displays its information as nodes on a grid, lag occurs when there are too many passages for the editor to process and display at once. This usually happens around the 300 to 500 passage mark, although it can change from user to user and their specific version of the editor.
If you are working on a large game and intend to use the Twine editor, you should consider how you can minimize the amount of passages you create (for example, using HiEv’s Combining Story Passages sample code to put linear sections with a Continue/Next prompt into a single passage). You should also have a plan for working around the lag to make your development workflow as smooth as possible.
You can read more about why I compartmentalize and how I structure my game files in this post here. Consider it a Part 1 to this post.
What is Tweego?
Tweego is a command-line interface compiler. It uses the command prompt on your computer to take all of the files necessary for a Twine game and outputs them into a single, playable HTML file. Tweego is often used in conjunction with other workflow methods beyond using the Twine editor, such as using the Twee 3 language in Visual Studio Code or writing passages in plain text files and then compiling them together.
Because I like using the Twine editor for its visual display, this is a tutorial on Tweego’s most basic use: compiling multiple published HTML files created in Twine into a single file.
Installing Tweego
Tweego can get a little complicated to install on its own. The easiest way to install it is to use Chapel’s Tweego Installer for Windows. Read the instructions carefully; if things are not done properly, then the compiler will fail to work.
If you have issues using the installer, questions are best directed to the Twine subreddit. I cannot help troubleshoot the installer.
Checking the Command Prompt
Open your command prompt. On Windows 10, you can search for it in the search bar—it’s the Command Prompt App.
When you open your command prompt, you will get a black box that looks like this:
Command prompts work by inputting the interface’s name and the command or action you want it to take. This will appear like something like this:
tweego -h
tweego is the name of the interface.
-h is the command for what I want it to do.
In this case, -h stands for “help.” Hitting enter will bring up Tweego’s help menu.
So, after the command prompt brings up C:\Users\Anna> (which is the account I am using on my personal computer), I can type in
tweego -h
And it will pull up the help desk. Tweego’s help desk shows the list of commands you can use to achieve different goals.
There are many, many commands in Tweego’s list that can change anything from your game's starting passage to trimming whitespace in your passages, but let's keep this simple. The commands we’re interested are:
--list-formats
-o
Checking Story Formats
The next one you’ll want to test is --list-formats
This will bring up the list of available story formats that Tweego can use.
Story formats are very important. If you are using a story format that is currently not included in Tweego, you will have to add it for the compiler to work.
Check Tweego’s list of story formats against the story format used in your game. If it’s the same, then you’re good to go. If it’s not, you will have to manually add it to Tweego.
For example, when I downloaded and installed Tweego, its version of SugarCube 2 was an early version of the format. It did not match the version of SugarCube 2 I was writing my game in.
You cannot mix versions of story formats. If Tweego’s version of SugarCube is 2.2.1 and the version you’ve written your game in is SugarCube 2.34.1., then you will have to add your game's version of the format to Tweego.
To find Tweego’s files, go to your Local Disk (C:) -> Program Files -> Tweego -> Story Formats
Open the folder containing your story format’s language. In my case, this is sugarcube-2.
Inside, you’ll see three items.
Format – this is the story format’s language.
Icon – an HTML file containing the icon for the format.
LICENSE – a plain text file containing the format’s license.
You need all three files for a story format to work in Tweego.
I’m not sure if there’s a way to extract the necessary files from Twine itself. If you have mismatched story format versions, you may want to update both the Twine editor’s version and Tweego’s version to the latest version.
Updating Story Format for the Twine Editor (SugarCube Only):
You can download the latest version of SugarCube here. See the installation guide here for adding a new story format to the Twine editor.
Updating the Story Format for Tweego (Any Format):
Delete the old version from its folder (leave the folder itself alone) and add in the format, icon and license files for the new version.
Once you have the matching story formats in Twine and Tweego, you can make an output file.
Creating an Output File
“Output” is the command for having Tweego create a compiled HTML file. Output is commanded by using -o (o for output).
Preparing Your Game for Compiling
In the Twine editor, publish your game files to whichever folder you want to story your Twine files in. They will publish as HTML files (some may say CHROME HTML file or Firefox HTML depending on your browser preferences, but this doesn’t matter).
IMPORTANT: In order for your compiled game file to work, you need to be very careful about how you name your passages and make sure you have the appropriate connections.
Any passages that move on to a passage in a different story file need to have the exact name of that passage in their link. If you’re using the Twine link markup [[ ]] and the editor automatically creates a new passage, make sure you delete it. This will break the link in your story file, but when your game is compiled, it will move the player onto the next file seamlessly.
I explain more about this in this post here, with visuals.
Before we compile our game files, there’s a few important things to keep in mind:
1) Command-line interfaces cannot read spaces in file names. Your HTML files cannot have spaces in their names. If they have a space, replace it with an underscore _. If you include a space, Tweego will fail to locate it.
2) Tweego compiles backwards. Whichever file includes your starting passage must go at the end. It doesn’t matter which order the files go before it, but the one with the first passage of your game has to be at the end.
3) The Story Stylesheet and Story JavaScript of the final file will overwrite the Story Stylesheet and Story JavaScript of any files that come before it.
4) Passages with duplicated titles will be overwritten by any file that comes after it. It’s very important not to duplicate passage titles in your game except in specific cases.
For example, every HTML file of my game has the required StoryInterface and menu passages for its design to work. This is so I don’t have to work with the default SugarCube UI when I'm coding and testing additional story files. When I compile the files in Tweego, duplicates of the StoryInterface passage are overwritten by the file that comes after it, leading back to the starting HTML file of my game.
5) The StoryInit passage of your LAST HTML file will be the StoryInit passage that executes in the compiled file of your game. Make sure that the LAST file has all the code you want to run in your StoryInit passage when players start your game.
Compiling in Tweego
Open the folder where you stored your game’s published HTML files. Go to the location bar and hit backspace. Type in cmd and hit enter. This will open the command prompt with a direct path to the folder you are currently in.
Once the command prompt is open, type in
tweego -o
Next, type in the file name and file type of your output file. In this example, it’s WAYFARER_MASTER.HTML
Then type in the names of all the files you want to compile and their file types. Remember that you cannot have spaces in the file names.
Mine looks like this:
Hit enter and Tweego will compile your files and create a new output file in your folder. This process only takes a couple of seconds.
If you have duplicate passages, Tweego will throw up a warning that it has replaced the existing passage with a duplicate.
And you’re done! Open your newly compiled file and check to make sure everything is working properly. I usually run my game until I hit one of the file breaks and make sure I didn’t mess up on something.
It’s very difficult for Tweego to make a mistake. It will throw up an error if you do something wrong and it will tell you that it is wrong. For example, if you mistype a file name, it will tell you that it cannot find the file and will not include it in the output.
Final Thoughts
I know this is a lot and it can feel overwhelming if you’ve never used the command prompt before. I hope that this write-up helps explain the process. Once you get used to it, it’s a very simple task. While using Tweego is not necessary for small games, if you are working on a very large interactive novel with Twine, you will need to use it at some point.
My own game’s alpha build is over 700k words right now and it will likely be several million words by the time its done. I started to hit lag in the Twine editor when I was only a quarter of the way through my first chapter (around 200k and around 500-ish passages). I spent months trying to work through the lag, but the Twine editor is just not designed to handle that many passages. This may be something they can fix in a future version (Twine 2.4.0 is in beta right now), but there are other benefits to working in smaller pieces.
Using a compiler lets you break your game into smaller pieces, which ultimately makes it easier to code, test, proof, and debug. When there’s an error in a specific part of the game, I no longer have to sift through one very, very large file to find it. I cannot recommend using Tweego enough if you are working on a large game.
If you don’t like working in the Twine editor, you may want to look into using Twee 3 extensions and Visual Studio Code to create your game, particularly if you don't like working in visual grid editors.
I'm actually using your first template and managed to transfer it into vscode! I also find vscode much easier to use than the twine app. I remember that there was a twine template I found that had these handy files in them but I forgot what is was called :')
I am nowhere as experienced as you with this coding stuff and I don't get like half the stuff I have here but I hope it might help you a bit (I'm also terrible at explaining things so I apologise in advance)
There's a Twee extension you can install in vscode I think there's a twee 2 but I use the Twee 3 extension.
↑ The CSS goes in here! You just have to tag them accordingly.
↑ The Javascript goes in here!
↑ The UI design goes in here!
↑ I actually don't know what this is for but everything works fine so I keep it there. I put this code in the setting.json file in the .vscode folder
↑ I also don't know how this works but, again, everything works fine. I'm fairly certain at the part that says "start" is the passage you want your IF to load on when you first load the game.
↑ ...again I don't know how this actually works but it does... I think all you need to do is make sure the StoryTitle and the text within <title></title> has to be the same.
↑ You won't believe this but I also don't know how this works. All I know is that the compile.bat file is handy for converting all your files into the index.html! All you gotta do is click on compile.bat in your folder and it should update your index.html with any recent changes you made.
If you want to start off a passage you add "::" and then the title of your passage. (That's what I do anyway). If you want to add a link to go onto the next passage you can use:
<<link "next (customisable)" "name of passage">>
:: name of passage
Forgive me if you already knew how to use it but I was unsure so I added it in just in case. I just think it's neat and easier to use than [link]
I think this is just about everything.
You don't have to answer this! I don't want to bother anyone with this long ask! Scrolling can be...not fun. Especially on mobile.
Anyway, hopefully, you'll be able to make better sense of what I have here. Hopefully...😅 (I really am not an expert at this)
Ooh, well done you for making it work! I believe this is for Windows, and it's a little bit different for MacOS users like myself, but I'm sharing this in case it might be helpful to someone ✨Thank you so much for sharing @moonlitsorrows-if 🤎
The 100% Good Ready-to-Use Tweego Folder is both a coding guide for the Tweego compiler and an easy-install for the program. It is meant to complement the official Tweego documentation, and update the Tweego download folder (formats).
The Guide is fairly short and goes over installation of Tweego in Windows and MacOS, the Twee Notation (a.k.a. Passage set-up), and use of Tweego in Windows and MacOS as well as with Twine 1 and Twine 2 formats.
While the Guide was compiled with SugarCube 2.37.3, and the Ready-to-Use Tweego Folder has a base project with SugarCube 2.37.3, Tweego can be used with any Twine 1 and Twine 2 formats. Annotations are also provided to change formats.
READ THE GUIDE & DOWNLOAD THE FOLDER
Note: setting up Tweego is different depending on your device. Check the Guide for full instructions before downloading the Folder (esp. for MacOS).
The Folder includes:
the Ready-to-Use Tweego Guide
Tweego, all official Twine 1 & 2 formats, and relevant scripts
Twine® is an “an open-source tool for telling interactive, non-linear stories” originally created by Chris Klimas maintained in several different repositories (Twinery.org). Twine is also a registered trademark of the Interactive Fiction Technology Foundation.
Tweego is a free (gratis and libre) command line compiler for Twine/Twee story formats, written in Go, created by TME. The Ready-to-Use folder is based on the one put together by Sjoerd.
READ THE GUIDE & DOWNLOAD THE FOLDER
The previous version of this Guide and Folder (SugarCube 2.36.1/Windows only) is still available for download on my GitHub.
This was the last step on the Update everything because SugarCube broke everything with the last update tour: the templates. As of today, all the templates are now compatible with SugarCube 2.37.3 (passage code + APIs!).
The changes also include some fixes in the explanations, as well as reformatting the interface (a bit). The whole log of all the edits can be found by clicking on the link below:
Hello again person of the internet, It is me, your totally legit supplier of very good Twine SugarCube assets {100% GOOD!!! NO BUGS!!!}. Aft
The older versions of these templates (2.36 compatible) have been archived on my GitHub. And as of today, any new template created for SugarCube will only be available for 2.37 (too many changes).
If you liked a/some template/s, consider sharing the following posts:
User Interface Template:
Simple Book
One Page (à-la-Chapbook)
Space/Tech Double Whammy
VN-lite RPG
Title Page
Code Template:
Settings
Character creator (+ Guide/Tips)
Also, don't forget to change the IFID when using a template!
It is me again, your totally legit supplier of very good assets {100% GOOD!!! NO BUGS!!!}. I am back with a pretty useful file for you! This whole affair is still scam free and no bug included! Download another funky file to dive deeper into spaghetti SugarCube Code! Still in exchange for nothing {YES, THIS IS STILL 100% FREE!!!} but your love and adoration for my help. What a steal!
Been wanting to include a Character Creator in your project but don't know where to start?
I PRESENT TO YOU THE...
The Character Creator Template!
50+ different traits, all the interactive basic SugarCube macros, extra QoL functionalities (random/pre-set) and many many annotated passages, with tips and advice. The template is purposefully too extensive for its own good.
A starting point for inspiration!
Itch.io Announcement - GitHub Repo - Rate on Itch.io - Neocities
This template is free-to-use under the CC-BY license.
If you are looking for the 2.36 version of this template, it is archived on GitHub.
It is me again, your totally legit supplier of very good assets {100% GOOD!!! NO BUGS!!!}. I am back with another template for you! This whole affair is still scam free and no bug included! Download another funky folder to make your projects even more greater! A simple template, still in exchange for nothing {YES, THIS IS STILL 100% FREE!!!} but your love and adoration for my help. What a steal!
I PRESENT TO YOU THE...
Settings Template!
This template encompasses all kinds of settings, from your basic font change (type, size, alignment, line height), to save settings (autosave, autoname), and even some accessibility settings (theme toggle, volume slider, animation toggle, notification toggle).
Comes with annotations/explanations for both the JavaScript, StyleSheet and passages.
Itch.io Announcement - GitHub Repo - Rate on Itch.io
This template is free-to-use under the CC-BY license.
If you are looking for the 2.36 version of this template, it is archived on GitHub.
and why it's important to do so when you are using templates (mine or others).
A more serious looking post, but also a necessary one. IFID CHANGE ========What is an IFID? An IFID is a serial number assigned to every wor
Twine won't allow you to have two projects with the same IFID in its library. If you are using templates for multiple projects and want to avoid copy-pasting the different code every time, here's a workaround.
