Custom Macro Collection v2.3.0 Release Notes

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
  • 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

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.