Snowman Dev Update (2.2: 12 June 2022)

On By Dan CoxIn code, twine

Snowman 2.2 Development Updates:

Embracing Undo

Snowman is the only official story format in Twine 2 without explicit undo functionality. Sure, yes, you could fake undoing to some degree by navigating “Back” in the browser, but few projects used this functionality, and as I documented a couple weeks ago, working with the HTML5 History API is both frustrating for me to reliably test and for authors to use by using compressed strings and location hashes.

Moving into Snowman 2.2, one of my goals is to meet authors where they are. Most people come to Twine with no knowledge of how story formats work, and very few bother to read the documentation to learn of its macros or API. As I mentioned a couple of weeks ago, the expectations of a Twine author have changed a great deal in the last nearly nine years. The assumptions for editing content on the web in 2022 are much higher than they were in 2014 when Snowman was first introduced. Most authors, having learned to use Twine with Harlowe, the default story format, now expect things like the ability to “undo” and to use a toolbar to when editing a passage.

Development screenshot of Snowman 2.2 showing the “Undo” icon on the left and the text of “Something” as rendered by the story format in a passage in the middle of the screen

One of the things the new State global object and its internal event system allows is the ability for any other objects to define their own events. In the latest build, the Undo icon is another case of this. There is a jQuery event listener bound to the icon. When it is clicked, it emits the “undo” event for all listeners. Currently, only the history is affected. The reader is navigated “back” to the previous entry, if there is one, in an array tracking where the reader has visited. However, if wanted, an author could listen for the “undo” event and provide their own state rewind functionality as well.

Once once I finish the API, one of the examples I want to provide for authors, and eventually get into the Twine Cookbook, is how to implement state management functionality where a reader could “undo” and “redo” their own state values. This might mean also implementing a Redo icon as well, something both Harlowe and SugarCube have, but I have not added such an icon yet.

On why there will never be usable Twine standards

I served on the Twine Committee in the Interactive Fiction technology Foundation for almost five years and then was around as a consultant of sorts for the Twine Cookbook for another year after I left the working group as well. One of several reasons I left the committee was because multiple members of the committee were either not interested in or were actively resistant to documenting how things work in Twine and its surrounding ecosystem. What we have now as the “Twine Specs” is much of my work behind the scenes to push for documentation of how story formats work and what Twine outputs.

One of my breaking points for the work on standardization happened when one of the core developers within the Twine ecosystem, after spending weeks on trying to figure out how to document an issue raised in the specifications, began to actively try to get other people interested in a completely different format. Instead of using the specifications we had spent over a year trying to find compromises on within the working group, this person told those who were present in a meeting they were going to support something completely different in their own code and were not interested in continuing to work on the specifications. This was, at the time, also the point where Harlowe had adopted its use of a toolbar when editing passages by using functionality purposely hidden from the public by one of the core developers from the committee in the Story Format specification and Tweego, a Twee compiler, was ignoring the Twee 3 specification. The standards I had worked hard to try to document for others to use were being ignored by multiple core developers to a point where they were nothing but loose guidelines for those not aware of certain information still not released to the greater community.

I mention all this because one of the areas we considered but never made it out of committee discussion was on Twine HTML element standardization. Because both Twee compilers and Twine itself parse the HTML created by Twine, the Twine 2 HTML Output specification defines multiple HTML elements and their attributes for data storage. These elements all use the “tw-” prefix to differentiate them from other possible elements defined in HTML or by other projects. Harlowe, in being one of the first story formats for Twine 2, continued this trend. Examining the HTML output produced by the story format shows the use of the “tw-” prefix for its elements. However, SugarCube and Chapbook do not follow this prefix and use HTML elements with specific attributes values for id or class attributes for query selector and mutation internally in their code.

Snowman, beginning with 2.0, has been moving in the direction of adopting the “Harlowe standard” of using the element name prefix, something which breaks from previous versions but helps, in a small way, of bringing a standardization across story formats. Starting in 2.2, internal links are now “tw-link” and the new Undo icon is a “tw-icon” element, following how Harlowe defines the same elements. I am extremely doubtful there will ever be a specification for HTML elements for story formats coming from the Twine Committee, given my own experiences with its processes and who remains on it, but this work for Snowman 2.2 should, I hope, be a small step toward helping others understand how story formats work and setting down guidelines for future development in this area.