This update consists largely of internal improvements geared toward optimizing performance, particularly when proofing large Twine projects. A JSON export feature was also added, along with a few minor UI tweaks to improve consistency across window and screen sizes. Finally, Snowman now has a second major version which adds some additional global functions, so a linting profile for Snowman v2.x was added.

The biggest change that effects users is the new JSON export. For the uninitiated, JSON is a data format that can be imported into various programs and tools. Only passage data is sent. By default, passage source code, tags, pids, and titles are included in the data, but you can optionally include extra metadata, including passage position, size, raw tag data, and passage reference data as understood by poof. You can also elect to pretty print the output file, making it more human readable.

Settings regarding the JSON export have been added to poof.config.

In future releases:

Other than keeping on top of any bugs my optimizations may have caused here, I don’t have any solid plans for right now. I do envision the possibility of a major UI overhaul, but I don’t know what I want that to look like, only that I’m not completely pleased with what we have right now. Changes that drastic may require a version 2.0.0, though, in case people prefer the current interface to whatever I may come up with. If I do make a v2, though, I want to rewrite more than just the UI, and I don’t want to undertake any massive projects on poof for right now, so those ideas are on hold at present.

As always, I’m open to suggestions, ideas, and contributions.

HAL v2 is here. This version represents a fairly large refactor of most of the code base, many usability improvements, and some improved or additional functionality. It also, unfortunately, means that some code written for HAL v1 may no longer work, or work slightly differently. I kept the APIs as similar as possible, but some behavior may not always be as you expect, so if you decide to upgrade from v1, test carefully and keep the docs on hand.

Special Passages

HAL v2 now uses special passages both to configure the library and to set up track definitions.

The hal.config special passage is the new way to configure HAL. You no longer have to hand-edit the libraries source code, which was a hack-y nightmare, especially when you needed to upgrade to a new version. Do not attempt to hand-edit the source code anymore.

The hal.tracks special passage is the new, recommended way for users to define tracks and assign them source files. The old A.newTrack() method is still available and still works, and is joined by the (newtrack:) macro, so you have options if you want them.

Macros

HAL v2 adds a number of custom macros to the library that allow you to use macro code to interact with HAL instead of JavaScript.

The macros are:

• (masteraudio:)
• (newtrack:)
• (newplaylist:)
• (newgroup:)
• (track:)
• (playlist:)
• (group:)

Details on the macros are in the docs.

The Guide

In addition to rewritten reference documentation, HAL now includes a gentler guide to help get novices acclimated quickly with just the info needed to get started. Docs for v1 are still available.

Please Report Problems

Changes this big rarely go completely smoothly. If you find any bugs or other issues, please report them on the issue tracker.

This release updates a few macros, adds one new macro set, and features a few meta and documentation updates.

The Articles Macro Set

This is a new macro set than tries to figure out and append macros to strings. Overall, I feel pretty clever: the macro will correctly determine the articles in pretty complex situations, like “a UFO”, “an X”, “an honor”, and “an 8”.

Pronoun Templates Update

Not yet finished with my English language programming battle, I tackled pluralizing third person pronouns for the pronoun templates system. Again, it’s pretty clever, successfully getting “die” from “dies” and “fly” from “flies.” I was going to bundle this macro as an add-on, but it’s not terribly large so I built it in.

Dialog API Macro Set Update

The <<dialog>> macro has two new child tags: <<onopen>> and <<onclose>> that let you run code when a dialog is opened or closed.

Documentation Updates

I fixed a few errors and organized the list of macros int groups for easier reading.

Download Utility

This update adds a download utility that allows you build customized downloads to simplify the installation process, an idea I’ve been tossing around for a while. Just select the macros / scripts you want and click the download button and the utility will spit out a zip file containing a single JavaScript file and (in some cases) a single CSS file that you can then add to your project. This will become the recommended way to download custom macros going forward.

A handful of usability improvements and a few new passage tag features round out what is mostly and internal upgrade here. The most obvious update for most users will be that the view settings have been moved out of the view menu, making the view menu completely dedicated to switching between the passage, JavaScript, and stylesheet views. The view options are now in their own little settings menu with checkbox-like inputs.

I edited the CSS for tags in the passage card. Tags now also come with a little box displaying their tag color from the Twine 2 editor, and clicking on a tag now performs a filtering operation using that tag, just as if you had used Tools > Filter... and typed in the tag’s name. You can now also clear filters by clicking the so-named button on the top-right of the passage view whenever any filtering is enabled.

I also ironed out a few graphical bugs with how certain combinations of view options interacted and a few other rare and non-critical bugs I found.

Poof also now has official internal support for Chapbook. Chapbook inserts that reference other passages have been added to the parser, and most of its globals have been added to the linter configuration.

In future releases:

I want to improve poof’s accessibility and usability, so some updates regarding that will probably be coming in the future. I also need to stay on top of Chapbook—it’s still in beta, so I intend to keep an eye on it and address any changes I need to on poof’s parser or linter.

This is a pretty big update, so we’re gonna break this all into chunks and go through it piece-by-piece. As a brief overview, the changes are:

• Three brand new macros / macro sets / scripts.
• One additional system from v1.x of the collection has been rewritten and re-added: the cycles system.
• Several scripts have been refactored to better adhere to best practices, improve performance, and rise to my evolving standard for code quality. These changes are internal and shouldn’t effect you as a user.
• The documentation has been improved, and the collection how has a dedicated web page at https://macros.twinelab.net
• A demo project to show off the basic functionality of each system.
• Finally, a changelog has been added so that changes can be tracked more easily. The v2.3.0 update represents the biggest update since v2.0.0, so it seemed wise to start documenting these changes more clearly.

New Systems

I’ve added a <<css>> macro that lets authors programmatically customize the CSS style rules of elements on the page. This is still the worst way to change CSS, but it is useful in certain scenarios.

The next addition is the meters macro set. It gives authors access to fully customizable meters for things like health bars, timers, and progress bars, all in SugarCube macro code. It has a few stipulations and limitations you need to be aware of to make good use of it, but I think it works well for what it is. It also includes a JavaScript API if you’re into that sort of thing.

The final addition are the pronoun templates, a complete, drop-in pronoun configuration system for SugarCube leveraging the brand new Template API and syntax, and it can plug in to the Setting API as well.

The Cycles System v2

The new cycles system is similar to, but better, than the old implementation. Code written for the old system will not be compatible with this one. Check the docs for more on how the new system works and how you may need to update your code.

The only other system that is worth bringing forward to v2 is the consumables inventory system. If I do so, it will be as an extension to the existing Simple Inventory v2.x system.

Refactored Scripts

The Simple Inventory, the Playtime system, the operations API (the dice roller and fairmath systems), and the fullscreen macros have all been refactored. Only the fullscreen macros and operations API have seen any end-user changes, in the form of a proper JavaScript-facing API for the former and support for Fate/Fudge dice for the latter (e.g., "2dF"). That said, all of these systems should now be more stable and perform better, and their code should conform better to best practices.

Documentation Changes

In addition to a shiny new website, much of the documentation has been clarified, improved, and fixed and several new examples have been added to several pages, while previously undocumented features have stabilized and been documented.

You don’t need to re-read any of the docs, as none of the changes are specifically breaking.

The Demo Project

The demo project includes demonstrations and examples of the basic usage of each system, and provides source code for each example passage, so that users can see how exactly each example is put together on the code side.

Links to the demo and each relevant passage are in the documentation.

The Changelog

The changelog is mostly accurate to my recollection, though there may be some gaps or inconsistencies between it and the repo’s commit history. Since I typically only create releases when a system is retired, given the nature of this project, some changes that happened over short periods of time or weren’t given specific version numbers (e.g., fixed typos in the docs) have been retroactively bundled together and given a version number.

Going forward, I intend to follow semantic versioning a little more closely for the sake of everyone’s sanity.

Other News

• My proofing format, poof, has received a big update as well in v1.3.0.
• HAL (my Harlowe audio library) has received an update for better compatibility with Harlowe 3 in v1.3.0.
• My episodic fiction framework for the web, Serious, has reached v1.0.0.
• The tweego-setup boilerplate and tooling was updated recently to address some issues with Babel and ES6 to ES5 transpilation.

Coming Soon

• My tweego-installer will get its bundled formats updated in the coming month or so; I expect a v1 release of Chapbook and a new Harlowe version to be on the way soon, so I will wait for a bit before updating it’s SugarCube version to 2.29.0.
• Once more compilers adopt the new Twee3 specification, poof’s default Twee encoding method will be set to Twee3. Chapbook support will also be forthcoming, but probably later in the year.
• I’m investigating issues with HAL’s functionality on mobile devices, particularly iOS. If you’ve encountered weird behavior from HAL on mobiles, please comment on this issue.

This version of HAL comes with a few important updates for greater compatibility with Harlowe 3, and fixes you’ll want even if you’ve stuck to Harlowe 2.

The biggest addition is that HAL now preserves and restores it’s own state separately from Harlowe. In Harlowe 2, reloading the browser simply restarted the game, and this restarted HAL along with it. Loading a saved game had no meaningful effect on HAL. In Harlowe 3, browser reloads now preserve Harlowe’s state, but not in a way similar to loading a saved game. Instead, Harlowe reconstructs the history in a different way that completely ignores startup passages, meaning HAL tracks, playlists, and groups set up in such passages break even though the game itself is fine, and this failure was not handled well.

Now, HAL will attempt to preserve it’s own state and restore it. This preservation only applies to tracks, playlists, and groups, and restores the ability of authors to use startup passages with these features.

The menu API, however, cannot be easily serialized, and therefore must always be defined in user scripts.

It is still gently recommended that you try to stick to Story JavaScript as much as possible, but this change should make it so you no longer have to rewrite code that was valid for Harlowe 2.

Some other bug fixes, updates, and internal improvements are also included in this release, so it’s recommended you update even if the above problem wasn’t an issue for you.

In future releases:

I will continue monitoring issue and clashes with Harlowe v3 and look into reported issues on mobile devices.

Poof v1.3.0 has arrived. In addition to dozens of small changes and improvements, the big news here is passage references and an updated Twee encoder.

A passage reference is, as you may imagine, when one of your passages references another passage through a link, include/display, or goto. Poof will parse SugarCube and Harlowe stories for a certain subset of common macros used to transition passages as well as for markup links (e.g., [[links like this]]). The macros parsed are not exhaustive–for example, SugarCube’s <<textbox>> macro can send users to new passages, but is not parsed by poof because there has to be a cutoff somewhere. JavaScript functions and methods that transition passages are also not parsed. Additionally, poof can only parse string literals. So, <<link 'Next' 'some passage'>><</link>> will work, but <<link 'Next' $somePassage>><</link>> will not.

Here’s a list of things poof will try to parse for valid passage references in each format:

All Formats

• Markup links of any kind, including arrow markup links ([[passage<-text]]).
• Setter links. Even though these are only supported by default by SugarCube, poof will try to parse setter links when it sees them regardless of the format.

Harlowe

• (link-goto:)
• (click-goto:)
• (link-reveal-goto:)
• (goto:)
• (include:)

SugarCube

• <<link>>
• <<button>>
• <<goto>>
• <<include>>
• <<display>>

Poof will display passage references to and from each passage as links you can click to zoom to those passages, allowing you to essentially play along with your game while editing. This is my solution to requests for a “play order” sorting method.

Note that parsing for passage references is somewhat slow. You cna shut this feature off if you’d prefer faster load times to having it via poof.config.

The second change here is the Twee encoder. Poof now exports to classic Twee, the Twee2 version of Twee (previously unsupported) and the new Twee3 spec. This last spec is still a draft and is widely unsupported, so the default is still set to Twee classic for now. You can change the Twee encoder in the poof.config special passage.

The smaller changes included in this update are:

• a starting passage tool to quickly zoom you to the starting passage,
• updates to SugarCube globals for the linter,
• a bunch of other internal and code-side improvements.

In future releases:

Eventually Twee3 will be the default Twee encoder. SugarCube is also undergoing fairly major changes in v2.29.0, so I’ll be updating poof’s SugarCube support a lot. This will mostly be maintenance though.

Note on Twine v2.3.2:

Twine v2.3.2 currently has a bug in how it handles proofing formats, see this issue. This means if you want to use poof, you need to use an older version of Twine 2 until this gets sorted out.

Serious has been officially released.

For the unaware (most people I imagine), Serious is my software framework for creating serialized web fiction. You can read more here and here.

While there’s still some rough patches, I think I’m at least generally happy with how it works. A guide for authors and non-programmers will be coming at some point. I’m tossing around the idea of some sort of Twine integration that will allow you to use Twine/Twee as an editor for Serious stories; in this case, passages will be mapped to episodes and meta posts, but this idea is purely theoretical at the moment. I may create a bare-bones markdown editor in NW.js that compiles to Serious instead, but both honestly feel like a lot of work for minimal payoff.

Regardless, let me know what you think if you’re interested, either via comments here or issues in the relevant repositories.

In Other News

I’ve been busy lately; here’s some of the things I’ve been working on.

I’ve created a curated list of Twine resources. Check it out here.

A new version of poof is in the works. This one is gonna have some pretty major additions.

My custom macro collection is getting its biggest single update since the overhaul to v2. Several new macros, refactored code, a complete demo file, and more. The release of the new version of the collection will probably coincide with the next release of SugarCube, since some of the systems rely on new features in the pipeline.

I have unfortunately not been spending much time on Holy Land lately, but a beta of Deep Dive is in the cards for later this year, and it will be coming to IFComp this year unless something crazy happens. Wish me luck!

Harlowe Audio Library v1.2.0 has just been released.

This release adds a few built-in methods for creating event handlers, so that users don’t need to use jQuery events anymore. These methods and the events they can be used to handle are now documented.

In future releases:

HAL will be going back into maintenance for the foreseeable future. As always, let me know about any bugs, feature requests, or weirdness.

Poof v1.2.0 is here (already). This version ties up some loose ends in the re-implemented PDF export feature.

Note: If you’re having trouble with updating, grab the new link from the poof documentation. I’ve updated the link there to always, always grab the latest stable version.

You now have options (configurable by the poof.config special passage) to control some basic styles of the generated PDF. First, you can select from one of three basic fonts: a serif option (Georgia), a sans-serif option (Roboto), and a monospace option (Consolas). Because the PDF export process requires fonts to be loaded as base-64 data into a “virtual file system”, the best I can do is provide basic options. Having three inoffensive options from the main font categories seemed like the wisest choice. Users can now also specify font sizes, the options are very small, small, normal, large, and very large. Normal is 12-point, very small is 8-point and very large is 16-point. The final option given is one for line height (or line spacing, if you prefer). You can set this option to a value between 1 and 2, with 1 being single-spaced and 2 being double-spaced. The defaul line height is 1.15.

The style options provided above are all the low-hanging fruit I could manage. Since the new implementation generates a PDF on the fly from the HTML data, rather than generating a canvas image from the same, the styling options are fairly limited; it’s not as simple as recreating what appears on the screen anymore. In other words, we lost line numbers but gained copy/paste. And I’m alright with that. The simpler structure should be nicer for printers anyway. As always, though, if you want more, let me know and I’ll see if it’s at least possible.

In addition, a the loading screen is now called when a PDF generates. For short projects, you’ll see nothing at all, maybe a flash. For lengthier projects, the process can take several seconds or more, and messing with the filtering or sorting during this process is probably unwise, so I decided to lock out the screen completely instead of risking that happening. It shouldn’t take more than fifteen or so seconds to generate the PDF, even in novel-length projects, but the speed of the operation will vary from machine to machine and browser to browser.

In future releases:

Poof is going back on my maintenance shelf for now. I’m pleased with the new PDF implementation as it’s been a net positive all across the format, and getting the Twee encoder to respect filter and sort was something I was happy to knock out along the way. But other than those things, I don’t think there’s much more that needs to be done here.

I’ll be on the lookout for bugs, problems, and feature requests, as always.

In a future version made by someone smarter than me:

I jest, but I’ve been asked about implementing a “play order” sorting method. While this is theoretically possible, the only real way to do it would be to load up the story format engine in question, crawl the file somehow, and then interpret that order in a way that could be meaningfully sorted. I’m open to ideas, but I don’t believe this is possible–even parsing just the markup links in each passage to construct a rough order would be expensive performance-wise and time-consuming to implement. Not to mention that it wouldn’t really return a reliable play order. It’s an interesting problem, but I can’t think of a solution, outside using passage naming conventions, like numbers, in the first place.