Echo Hollow

Digital Degeneracy! Yay!

User Tools

Site Tools


tweegoeclipse

Developing Twine/Twee Games in Eclipse

Why?!?

Twine 1 is out of date and no longer worked on. Twine 2 is buggy and slow as hell, and the developer doesn't seem to do much to make it more useful for large/complex projects.

It is also extremely difficult to use external Javascript libraries in Twine.

Additionally, Twine saves the whole project in one huge file. This makes it extremely difficult to use version control to collaborate on Twine projects.

The solution to these problems is a commandline Tweecode compiler called Tweego. Think “Twine without the graphical user interface.”

Among other things, it allows you to:

  • Split your project into multiple files, vastly simplifying the use of version control and collaboration.
  • Create games of huge size without lagging the editor all to hell.
  • Easily include external Javascript libraries.
  • Compile images, sounds, and video directly into the .html file, greatly simplifying distribution.

Unfortunately, Tweego (being a commandline program) may be difficult or fiddly for some to use, and you also lose the graphical interconnected passage map.

In practice, losing the graphical passage map is a non-issue, as 99.9% of the time a story's scene structure isn't complex enough to require graphical visualization. (If it is, I'd suggest that you may have a design issue rather than a tool issue, anyway.)

Having to use the commandline to build the project after you save your work can be an issue for some. Even for those who possess the technical literacy to develop software in this way, it can still be a time-sink to have to manually build the project every time you save something. This isn't just a Tweego issue, it's something that affects programming in general.

The solution to commandline use and manual building is to use an Integrated Development Environment (or “IDE”). An IDE automates and encapsulates many tools and tasks, making your workflow more efficient. Typically file management, text editing, and in many cases even version control are all brought together into one graphical tool.

Additionally, most IDEs provide “autobuild” functionality. That is, whenever you save a file, the IDE detects this and rebuilds your project so that it is immediately available for testing, without having to tab out to a command prompt and build the project by hand.

Unfortunately, there are no IDEs for Twee development. But there are many IDEs that can be made to work with it, kind of.

My personal favorite IDE is Eclipse. It was originally written as a Java IDE, but over time has been extended to work well with almost all common programming languages (except for C#, grumble). Many people don't like Eclipse. I happen to be one of those weirdos who likes it. It is an extremely large program, but it is very mature and has many plugins for about whatever you might want to use it for.

Unfortunately, it has no Twee plugin. But we can work around that, and turn it into a pretty decent Twee development environment that does about everything except for .twee syntax highlighting.

Installation and Setup

Step 1: Install Eclipse

Download the Eclipse installer from https://www.eclipse.org/ and run it. When it starts up, you'll be given a list of meta-packages to install, for different development environments. You want to install the Eclipse IDE for JavaScript and Web Developers.

Once it has been installed, launch it.

Eclipse will ask for a workspace location. This is where all of your projects will be saved. Go ahead and accept the default if you want to, but I prefer to change it to something a little easier to navigate to, such as “C:\EclipseWorkspace”. Regardless, remember where your workspace location is, because we'll have to navigate there and fiddle with some metadata in there later on.

Eclipse will grind for a moment, and then start up. You can go ahead and close the Welcome tab.

The IDE window is split into several panes, like so:

Step 2: Install Version Control Plugins (Optional)

If you don't know what version control is, well, don't worry about it too much. It's essentially a way to keep track of all the changes you make to your project over time, giving you the ability to roll back if you make a huge mistake. Also, version control generally catches and merges edit conflicts, which is a huge help if you are collaborating with other people on a project.

If you only want a file history that you can roll back, you may be able to just use a mounted Google Drive location for your workspace. I think Google Drive does versioning and rollback itself when you do that. But I've never tried it, so I could well be wrong.

If you do know what version control is, and want to use it, Eclipse comes with a Git plugin installed by default. If you are that kind of user, I leave it to you to find some tutorials and learn to use Eclipse's “Team” context menu and perspectives to get into Git. If you are a luddite like me and still use SVN, you'll have to install a 3rd party plugin, which I also leave to the advanced reader.

This is a pain in the ass. By default, Eclipse doesn't do word wrap, which is great for most programming languages. But not for Twee.

There is a button in the toolbar that toggles word wrap on and off:

Unfortunately, this button toggles word wrap per file and its setting is forgotten when you close and reopen a file. This means that you'd normally have to manually toggle word wrap on every time you open a file. Which you can do. But it's a real pain in the ass.

Doubly unfortunately, there is no GUI preference setting to turn word wrap on by default.

However, we can manually turn on word wrapping by default, by editing a file.

Remember when we were talking about the workspace location, and I said to remember where that was? Ok, good. Tab out of Eclipse and go there. Go into “.metadata/.plugins/org.eclipse.core.runtime/.settings/”.

There you'll find a file called “org.eclipse.ui.editors.prefs”. Open it in good ol' Notepad.

In that file, look for a line that reads “wordwrap.enabled=false”, and change it to “wordwrap.enabled=true”. If there is no such line, just add it at the end of the file.

Save the file, exit Notepad, and exit and restart Eclipse. Now whenever you open a file in that workspace, word wrap should be turned on by default.

This is a known bug with Eclipse, and they're supposed to be fixing it Sometime™. I'll update this document with something easier when they do.

Step 4: Install Tweego

Download Tweego and the story formats package from https://www.motoslave.net/tweego/.

At the time of this writing, Tweego and the story formats are only available as a .zip file. There is no automated installer. I like to install them to a path that is easy to find and remember (such as C:\Tweego\), because we'll need to manually set some paths and environment variables in Eclipse later, when we set up autobuilding.

Step 5: Create Your Project

Go back to eclipse, and right click somewhere inside of the “Project Explorer” pane on the left.

Select New→Project from the context menu. Select “JavaScript Project” from the rolldown on the next screen (important make sure you create a JavaScript project, not something else), and click Next.

In the next window, fill in the Project Name at the top (required), and uncheck the “Include Web Browser Library” box below.

Then press Finish. Your project will come up in the Project Explorer to the left. Later on, you can create any number of projects here, if you wish, with separate version control repos and whatever.

Right-click on your project there, and select New→Folder. Name the new folder “src”, and hit Finish. This will create a “src” folder within your project.

Use the same procedure to create a “build” folder in your project, too.

Next, right click on the “src” folder that you just created, and select New→File. Name this file “Start.twee”. The file will be automatically opened in the editor pane.

Your project should now look something like this:

Step 6: Create a Couple of Test Passages

In that “start.twee” file, enter something like this:

:: Start

Ohai, this is the start passage.

[[Next Passage]]


:: Next Passage

Welp, you got to the next passage.  You win!!!

This is Twee notation. It's the same as you'd use in Twine, except that you can have several passages in one file, each denoted by “:: Passage Title”.

To learn all about Twee syntax, read this: https://www.motoslave.net/tweego/docs/#twee-notation

Step 7: Set up Auto Building

Alright, this is the skeeziest part to get set up, but it's worth it. Otherwise you might as well just be using notepad++. What we're going to do here is set up an autobuilder that calls out to tweego.exe every time a file in “src/” gets saved, to rebuild the game's .html file.

The worst thing about this is you have to do it for every project, and you can't have two builders with the same name in a given workspace. That probably sounds like greek at the moment, but you'll see as we do this.

First, right click on your project, and select “Properties”. Then click “Builders” on the list to the left. You'll see a big almost empty pane with “Validation” checked in it, and some buttons on the right. Click on the “New…” button. On the window that pops up, select “Program” and press “Ok.” This will pop up a big ol' bunch of shit window.

In this big ol' window, you'll see four tabs: “Main”, “Refresh”, “Environment”, and “Build Options”.

Before we do anything else, change the name of the builder to something other than “New_Builder”. If you create more than one project later, you'll have to remake this builder for it, and builders can't have identical names, so I like to name them something relevant to the project. In this case, I might name it “Tweego_KinkyPr0nGame”.

Now we'll fill in the “Main” tab.

Under “Location”, enter the path to “tweego.exe”. In my case, it's at “D:\Tweego\tweego.exe”, but for yours, enter whatever location you installed it to in the previous step.

Under “Working Directory”, click “Browse Workspace”, select your project, and hit “Ok”. It should now read something like “${workspace_loc:/My Kinky Pr0n Game}”.

Under “Arguments”, enter “-o build/KinkyPr0nGame.html src”. You can change “KinkyPr0nGame.html” to whatever you want your output .html to be, but make sure that you leave it as being put in the “build/” directory.

Next we'll set up the “Refresh” tab.

Check “Refresh Resources upon completion.”

Ensure that “The entire workspace” radio button is selected, and that “Recursively include sub-folders” is checked.

Next we'll set up the “Environment” tab.

Assuming that you'll be using the Sugarcube story format, there's only one environment variable we need to set up here. Hit the “New” button, and set “TWEEGO_PATH” to whatever path you installed Tweego's story formats to. In my case, it's “D:/Tweego/story-formats”.

Finally, we'll set up the “Build Options” tab.

Ensure that “Allocate Console” is checked.

Under “Run the builder:”, only the two “during builds” options should be checked. The “Clean” options should be unchecked.

Finally, check the “Specify working set of relevant resources” box, and press the “Specify Resources…” button. In the window that pops up, roll open your project and check its “src” folder. Press “Finish”.

Done.

Everything should be set up now. Press “Apply”, “OK”, then “Apply and Close”.

You'll see an error (from Tweego) in the console pane saying “Special passage “StoryTitle” not found.” So, following the documentation at https://www.motoslave.net/tweego/docs/#twee-notation, add a StoryTitle passage to your .twee file. You'll also need to add an ifid, which tweego will also warn you about, and generate one in the Console pane, which you can copy and paste into your .twee file.

Once you get all that taken care of, your screen will look something like this. Notice that an .html file has appeared in the “build/” directory. Now every time you save anything in “src/”, that html file will be updated.

You can open that html file in your web browser, and bookmark it to your toolbar. As you work on and bugfix passages, you can tab out to the browser and reload the page to immediately pull in changes without having to start the game all over again. It's really VERY handy, far nicer than trying to fight with the Twine program.

The End

Eclipse is a really big IDE, with a lot of features and a good bit of power. It's beyond the scope of this document to go into all that. But if all those buttons are a little overwhelming, there are plenty of good Eclipse tutorials out there to get you started on the basics.

I hope that this document has been helpful. Good luck with your authoring!!!

If you discover any errors, please drop me an email at lee@echohollow.net.

tweegoeclipse.txt · Last modified: 2018/03/20 19:03 by lee