Harlowe Macro Framework (v0.3.0)

Custom macros for—wait for it—Harlowe. I’ve created a framework for creating custom macros at runtime in Harlowe, and went ahead and developed some custom macros to go along with it, too. Most are “ports” of custom macros I’ve previously developed for SugarCube, but still, I think its a pretty neat, though currently very small, collection of things. I also intend to pull together come scripts I’ve written for Harlowe and possibly some cookbook recipes and give them macro wrappers.

This project is made out of a few parts, so I’ll go over them here in sections.

The Custom Macro Framework

This is a script you have to install both to create and use custom macros. Since custom macros will depend on it, and because it provides a handful of nifty features and functionality, you’ll probably want to put this in your Story JavaScript first. It has no explicit relationship with HAL even though HAL also has custom macros, so you can add those two scripts in either order. HAL does not add this framework to your game for you, nor does it depend on this framework. That is unlikely to change.

The custom macro framework has fairly extensive docs with a lot of simple examples, and you can look at the scripts for my own custom macros here for more detailed and involved examples. You can also compare the scripts to their SugarCube versions where appropriate if you’re familiar with SugarCube’s macro API to see the differences and similarities.

There are two generic “types” of macros: simple macros and changer macros. Simple macros execute a single function and return values, while changer macros are similar to SugarCube “container” macros, and have associated hooks. Child tags are not really a thing (in Harlowe or in this framework), so for now I suggest avoiding and such things until I figure out a decent implementation.

There is definitely some wonkiness in the implementation here, and this framework is still very much in a pre-release state. I can’t promise that future releases of the framework will not introduce breaking changes.

I intend to speak more at length about the decisions I made regarding the interface and how it works, but for now I’ll leave things there.

The Custom Macros

I made six custom macros, two are whole-cloth, four are “ports” of macros I originally made for SugarCube.

  • Textbox: a basic text input macro that isn’t a f*cking prompt for once. Works like a SugarCube-style macro with a string receiver variable as I’m not sure how Harlowe’s bind data works.
  • Hotkeys: a basic hotkey implementation: allows keypresses to activate links or other clickables.
  • Playtime: a port of the playtime system and macro; keeps track of user playtime. Works across saves and loads.
  • Speech box: a simplified port of the speech box system; a basic UI component for creating speech boxes with portraits, names, and content.
  • Dice: a port of my SugarCube dice roller; since macros can return values in Harlowe, this is an actual macro, rather than just a function. Parses discreet numerical arguments or dice notation.
  • Articles: a port of the SugarCube macros; appends text with the correct article “a” or “an” based on a fairly complex internal ruleset that can correctly choose even fairly difficult cases, like a UFO, an honor, a horror, an S, etc.

Documentation and scripts can be found here.

Documentation and Website

Like most of my stuff I have a website and a bunch of documentation for users. I will probably eventually create a download utility similar to CMFSC2 that bundles the framework with the selected macros and generates a single, simple download, but that’s a ways off yet. There’s also a very bare-bones demo file here. I hope to close the gap in terms of features and quality with the CMFSC2 demo file over time as well.

Future Plans

This project on the repo details the plans I have headed toward a v1.0.0 release. I will probably also work on porting over a few other CMFSC2 macros and maybe even a few completely new ones.