This is just a small update that adds a new macro, <<disable>>, for disabling certain interactive elements, and makes a small usability change to the meter macro set.

This release includes two new systems and a few other updates.

The <<popover>> Macro

Creates an “popover” overlay to display text images, or anything else, really. Can be set up to close on click, to be opaque or transparent, and a few other options.

The <<preload>> Macro

A macro for preloading image assets.

The CMFSC2 Demo Source Code

The source code for the demo file is now publicly available at this repo.

Other Updates

Some of these updates were made over the course of the v2.5.x series.

• Added some new methods to the cycle macro set to help check the current phase more easily.
• Made some alterations to the build process of the custom macro set, including switching from uglify to terser for minification.
• Several improvements to the pronoun template set, many of which were made at the suggestion, and with the help, of AcademyOfFetishes.
• Retired the fullscreen macro set in favor of the built-in API included in SugarCube 2 as of v2.31.0.
• Added a synthetic event, :import, for when the import process ends (successfully or otherwise) in the import/export macro set.
• Several bug fixes and improvements.

Before we get into it, Nioh 2 is a great game and I recommend it almost without qualification. Unless you really don’t like these hardcore action RPGs in the vein of Dark Souls and Bloodborne, this is a great game with a ton of content. I like it more than the first game, if only just, and I think more complex and nuanced combat mixed with a well-designed loot system and incredibly deep customization is a great match along side Souls-like difficulty and game structure.

And make no mistake about it, while its a very different take on the concepts, Nioh and Nioh 2 owe a ton to From Software’s storied Souls series. The comparison is useful, but it doesn’t tell the whole story. The games wield their high levels of difficulty in very different ways to create different experiences, and I think the best parts of Nioh 2 are the parts that are unique to it, rather than the parts borrowed from Dark Souls.

Nioh 2 is largely more of the same compared to its predecessor Nioh, though I think it has several important differences. If you despised Nioh, you probably won’t like Nioh 2 and vice versa. However, if you instead wanted to like the game but felt that its difficulty leaned a bit too far toward bullshit or felt that you simply ran out of steam partway into the game, Nioh 2 may just win you over. I’ll get into this comparison more toward the end of this post, but I do think the sequel provides a smoother, and probably slightly easier, experience overall. I think this is a good thing, but again, we’ll get into this soon.

Nioh 2 plays a lot like Nioh even with some distinct differences.

Soul Train

Let’s get all the Dark Souls comparisons out of the way. Dark Souls, as you probably know, takes a bunch of mechanics from all over the place, from a variety of genres and mixes them all together in a way that creates a very specific experience: a high level of difficulty that requires you to stay invested even in fighting trash mobs; maze-like, “Metroidvania” environments with secrets and shortcuts; and a checkpoint system that features corpse-runs and punishes death rather stringently.

The Souls games create tension by punishing death and making death frequent, and in turn reward caution, patience, and attention. Bloodborne, often lumped in with the series, plays with the knobs: death is less punishing and the game rewards aggression more than caution. Last year’s Sekiro: Shadows Die Twice sort of tries to do both to, in my opinion, mixed results: it rewards aggression but punishes death so insanely harshly that many players tried to play it conservatively which actually makes the game even harder.

Nioh punishes death at about the same level that Bloodborne does, but also introduces fairly rare items that could be used to skip a corpse run, which made it even more forgiving than Bloodborne. Shrines replace the equivalent bonfires and lanterns and statues from From Software games, and while Nioh was level-based rather than being set in a single continuous environment, the individual levels are structure similarly to the areas in a Souls game, with shortcuts and secrets. Overall, Nioh‘s levels were honestly not that good. They weren’t terrible by any stretch, but the comparison to From Software’s games do not do them any favors.

Nioh 2 is largely exactly the same as Nioh, but with noticeably improved levels. Some of the levels are pulled directly from the first game, but the new ones are quite a step up. They feature more color and more landmarks, and are less confusing to navigate, while still feeling maze-like and large.

One of the bigger issues of both Nioh games, however, is something inherited from the Souls games that just doesn’t fit well in the game. Traps in Nioh and Nioh 2, whether they take the form of enemies hiding around corners, boulders being rolled down hills, or tricky falls, simply don’t belong in this game. In Dark Souls, for example, the combat is simple and straightforward, so learning where enemies are and what attacks they have is all you really need to worry about. This makes traps an effective thing to overcome—once you die to it once, you’re ready for it, and you’ll have only your own carelessness to blame if you fall for the trap again or let enemies push you into it. It’s never a black knight encounter that features hiding enemies and falls and blind corners. It’s always hollows or some other basic enemy. Traps are designed to be overcome basically immediately, and this makes them rewarding. They provide a sense of progress as you’re almost guaranteed to get farther on the next try after falling for one.

In the Nioh games, combat is the primary puzzle. Combat is complex and deadly (even late in new game plus with a completed build and at max level, enemies can kill you in two or three attacks if your build don’t prioritize survivability), and winning a fight even against basic enemies is tough. Nioh 2 absolutely loves to have it’s basic enemies dive out of blind corners and take one-half to three-quarters of your health in a single attack while you’re fighting another, tougher enemy. And you may think, “Well, now I’ll be ready for him.” But it’s rarely that simple. The combat in Nioh 2 is more complex than in Dark Souls, and enemies tend to one- or two-shot you a lot more. This means that hidden enemies you are unaware of is a knowledge check, much like in Dark Souls. You either know they’re there or you don’t. If you don’t, much like in Dark Souls, there is a relatively high chance you’ll die. Unlike Dark Souls, however, knowing an enemy is there does not necessarily give you the same advantage. It’s much more likely you’ll survive, but because combat is more complex, fighting them in addition to whatever other enemies are also around is still an execution check. And as if that wasn’t enough, the game also features much deadlier hiding enemies later on, including the devastating tengus and the one-shot-capable enkis. In other words, knowing a trap is coming isn’t significantly rewarding in Nioh and Nioh 2; it’s not progress. It seems lifted from Souls without much thought, and Nioh 2 in particular does it basically all the damn time, on almost every level, often a few times in each level. Nioh* did this as well but I don’t remember it being such a major and consistent part of the experience.

* Gaki damage was significantly reduced in a patch.

You may be thinking that this seems like a rather small issue in the big scheme of things, and you’d be right, except that it contributes to a feeling running through Nioh 2 that I feel hurts the experience compared to Dark Souls or Bloodborne. It’s a feeling of frustration, of the game being bullshit rather than a challenge. Now the second half of Dark Souls is actual bullshit and Bloodborne has its moments for sure. But those games never frustrated me the way Nioh 2 did. There were moments where I actually just had to stop. Where the Souls games largely feel like they reach out and invite you to try again when you die, Nioh 2 seems to relish your failure a bit much. There are other things that contribute to this issue, and we’ll discuss those soon. But the core of the game is combat, and that core is solid.

Samurai Swords and Ninja Stars

Nioh 2 adds two new weapons, yokai abilities, and a “yokai shift” form to combat, the latter of which replaces Nioh‘s “living weapon.” Overall, the new features and weapons in Nioh 2 feel like a small jump, but I never got tired of Nioh‘s combat, so I honestly don’t think this is a problem. Some skills have been rearranged, the skill trees themselves are totally different, and the progression of your combat skills in general feels fresh enough. Some things have definitely changed as well—skills have been added and removed—but the feel of each weapon is largely the same. In terms of weapons, there are now yokai weapons and blessed weapons, but these don’t feel like changes that are as major as the game wants you to think. They’re basically two new status effects/elements that replace two dropped status effects/elements from Nioh.

If you haven’t played Nioh, combat is fast-paced and revolves around the “ki pulse,” where you press a button to recover stamina (or ki). Pressing the button too early or late will result in only a portion of stamina being restored, but pressing it at the right time will allow you to recover almost all of your stamina. Because you sometimes need to block or parry or dodge or perform other attacks, it’s not really possible to string together an unending combo, but the skill ceiling introduced by the concept of ki pulsing is very high. Experienced Nioh players are almost playing a completely different game than the novices and Souls refugees.

Ki pulsing in the mid stance can give you a block that no longer costs ki, making it incredible for hard hitting enemies.

In addition to getting back your stamina, several other systems are related to ki pulsing: it’s how you purify the yokai realm (more on that later), you can heal off of them, stun enemies with them, or gain other benefits like being able to block for a short time without losing ki. Mastering the ki pulse is what provides most of Nioh 2’s depth, but setting up skills, buffs, and gear bonuses is equally important, and the core gameplay loop feels incredible. Even when the going gets hard, Nioh 2 feels like a power fantasy, except at the start of the game.

Nioh 2 shares Nioh‘s rough start. Getting your legs under you is tough, and not just because you might be new at the game. Even experienced players may find that their lack of skills and gear bonuses make the game a chore to play through the first few levels. Nioh 2 in particular has a boss, in around the third main level, a giant snake named Yatsu-no-Kami who has killed me more than any other enemy in the game by an order of magnitude. The final boss, an objectively tough fight, killed me about five times. Shibata Katsuie, widely considered an insanely tough enemy, took me four tries or so. Yatsu-no-Kami took me more than twenty tries. This boss was actually in the public beta as well and I just assumed it was a late game boss so while I eventually did beat it before the beta period ended, I don’t recall thinking it was too much.

I’ve refought Yatsu-no-Kami since both in the late game of Nioh 2 and in new game plus mode, and he isn’t nearly as tough when you have a build together that has options and important core skills unlocked and a few decent yokai abilities. But I think this boss is misplaced in the game. He’s just not a good early boss.

This is in contrast to Nioh 2‘s first two main levels, which are both excellent, especially the first one, which does an awesome job introducing you to this world and these mechanics in a way that feels achievable but isn’t a gimme either. After the first two missions, the game hits its low point for the next couple. It evens out and recovers after this. Since release, Team Ninja has adjusted the level recommendations for missions to be higher, sometimes by twenty or so levels, and these recommendations feel much more reflective of my actual experience. Once you have somewhat decent gear, a few levels (early levels are very noticeable in every stat), and some core skills you’ll end up using throughout the whole game, and maybe a bit of magic and ninjutsu to round out your options, the game feels much better to play.

Nioh 2 is more of a power fantasy than other hardcore action RPGs.

I remember having a similar reaction to the first game; not having a few core skills and some options makes the early game much tougher than it needs to be. Where I felt that Nioh just got easier and easier as it went aside from a random spike that felt more like bullshit than a correction, Nioh 2 manages to feel a lot more consistent to me overall. Whereas the Souls games and Bloodborne (but not Sekiro) scale up easily and mostly in a linear fashion—that is, you have more health, more damage, a bigger fireball, more heals, etc—Nioh 2 doesn’t, and that makes its balance feel much more impressive to me. Not only are the numbers bigger, but you have fundamentally different abilities and options by the end of the game than at the beginning, the evolution of your power over time is much less linear.

There are also a few enemies in the game that don’t work very well in my estimation and a couple of grab moves with broken hitboxes throughout. A certain enemy that limits your healing feels annoying to fight, since you’re usually one hit away from death even with a hair of health missing. I rarely ran out of heals in Nioh 2 but walking around without your health at 100% was inviting tragedy. And broken hitboxes are what they are. Most grab moves are one-shots or nearly so, so the occasional grab that hits you while you’re behind the grabbing enemy feels shitty. It wasn’t excessive, but two enemies, the Ubume and Waira, seemed to hit me with grab moves if I was in the same zip code with them. Fortunately both of their grabs are burst-counterable (more on that later), so, ironically, being close to these grabs keeps you safe from them. The Ubume in particular was so annoying to fight. So much so that I often considered shutting off the game for the evening whenever I came across one, often before even fighting it. They didn’t kill me that often, but man were they stressful and annoying to fight.

The yoki, a very common enemy, also has a grab that you can’t burst counter that comes out in 0.1 seconds. I don’t recall if that was a thing in the orignal Nioh. To be fair, standing a few feet away from a yoki when you aren’t actively attacking is a perfectly reasonable solution to this issue, but I did feel like that grab was occasionally frustrating and felt unnecessarily fast and deadly. And the occasional massive one-shot attack from off-screen is obviously always annoying, but it’s hard to fault the game for this as keeping enemies from overwhelming you and getting behind you is part of getting good.

Compared to the first Nioh, however, Nioh 2 has a lot more yokai, and most new ones are fantastic, and the returning ones are still great fun, too. They’re slowly introduced throughout the game and keep things fresh. The first Nioh had a relatively small number of yokai, so this was a much needed improvement. There’s more variation in human enemies as well. The game also features tons of variations in encounters, setting fights on bridges with distant archers, large open fields, narrow streets, stark cliffsides, burning buildings, and more, so that even encounters against similar enemies tend to feel different and dynamic. It will occasionally just lock you in a medium-sized arena and have you fight five waves of yokai, though, so not every encounter is worthy of praise.

I think the bosses of Nioh 2, excluding Yatsu-no-Kami, who I will never forgive, and two annoying, easy gimmick bosses, are quite good overall. I thought Katsuie, the final boss, and Kamaitachi in particular were my favorites, but I’m still going back and forth on that as I work my way through new game plus.

The Realms

The yokai realm is a puddle of bad ki (or something to that effect) that yokai spit up periodically. It makes their ki regenerate faster and yours regenerate much, much slower. The dark realm is a whole area that is under a similar effect. The yokai realm is purified (that is, removed) by a ki pulse. The dark realm is hosted by a specific enemy inside it, and ends when that enemy is killed. The dark realm and all the enemies in it stay dead if you end the dark realm, which gives a nice sense of progression while clearing levels. It’s possible for yokai to create yokai realms in the dark realm, which tend to stop ki regeneration almost completely. Bosses also tend to pull you in and out of the dark realm as fights go on. It has a nice rhythm to it, honestly.

I really like the dark realm as a mechanic. Your anima, which powers your powerful yokai skills, builds quicker in the dark realm, so while ki is slowed, you’ll find yourself throwing out yokai abilities more liberally. Against bosses, you’ll find yourself playing almost in two modes: one that is more defensive and conserves ki while simultaneously trying to end the dark realm by doing tons of ki damage with weapon skills like kicks and yokai abilities, and one that focuses a bit more on ki-fueled melee combat.

The only issues I have with the dark realm are that it’s sometimes hard to see in, especially in night levels, and I was squinting at my TV (which doesn’t help but I was doing it unconsciously) until I had a headache after just one or two levels, and that the dark realm is a bit overused. Every level, main or side, that isn’t just a boss has at least one, most levels have two, and many have three. Not to mention every yokai boss (e.g. almost every single boss in the game) being capable of taking you into the dark realm many times throughout a single fight, and the dark realm is basically everywhere. It’s a good mechanic that I do like, and it’s often like a puzzle in levels and provides a good rhythm, as I said, in boss fights. But by the end of the game I was sort of sick of seeing it.

Boss fights, even lengthy ones, have a satisfying rhythm thanks to the dark realm.

Yokai Shift

Yokai shift is the other big change from Nioh to Nioh 2. At first I kind of hated it. While burst counters (high risk, high reward counters to devastating “burst attacks”) are an excellent addition akin to a combination of the Dark Souls parry and the Doom 2016 chainsaw. But compared to living weapon from Nioh, yokai shift is shorter, weaker, and takes longer to charge. That contributes to a feeling of being underwhelmed the first time you pop it. But over time, and after acquiring several skills to make it longer and more powerful, it does start to feel okay. While it was possible in the original Nioh to sort of build around living weapon, you can’t really do that with yokai shift. But it can ultimately become a pretty powerful tool in your toolbox, and live living weapon you can use it to save yourself from a death too.

Yokai shift can save you from death.

Loot

Nioh 2 also has tons of loot with random levels, rarity tiers, and bonus effects. Compared to the first game, not much has changed. The game still manages to spit out tons of useful loot and provide tons of interesting options. Balancing loot drops so that what pops out of a monster is always exciting but never game-breaking is a fine balance dozens of games struggle with, but Nioh 2 manages to feel consistently rewarding while supplying a steady power curve. You replace loot often enough throughout the early and mid game that each drop feels worthwhile, and the endgame grind is set up so that even loot you don’t want is useful to you in some way.

Tempering, soul matching, and remodeling provide ways for you to fight back against the RNG and are satisfying to work with, and revenants provide ways for players to share loot indirectly with each other, on purpose or otherwise.

Nioh 2 also has a heavy focus on customization, with the ability to change your gear’s appearance unlocked from the start and incredibly cheap, though it could use some sort of preview mode. This pairs well with the game’s impressive character creator, as well.

A Person Named Hide

That’s hee-day. Hide is the name of the custom protagonist of Nioh 2: a mute, half-yokai warrior who teams up with a fast-talking, faster-living spirit stone merchant and a hot, ageless yokai-hunting badass to…uh…whatever I guess. Yeah, while the character creator is honestly incredible, the story is not good. Nioh‘s story didn’t set my world on fire but I thought it had some neat moments and William was bizarrely likeable and charismatic for a cocky Irish fish-out-of-water type. Hide and her buds definitely have personality but the story doesn’t really go anywhere. Hide’s muteness doesn’t help, but even aside from that, the story doesn’t really make sense.

Hide definitely has a personality of her own and cutscenes are often neat.

Because the story is largely following Japanese history with a twist of fantasy, the game will often have you play levels that take place years apart and make no sense sandwiched together with a brief cutscene. Like going from a triumphant battle to literally the victor killing himself in the next level. On top of that, the character relationships change over time, but we don’t see that. Suddenly one of your buds is a bit of an asshole. One mission you’re high-fiving, then there’s a cutscene with a bit of tension, and now he’s gone all murdery.

Nioh had some issues with this too, to be fair. But let me put it this way: I do not recommend playing Nioh for the plot, and I would even suggest that most of the cutscenes are more enjoyable as vignettes with some oddball humor or the occasional badass scene than a single story. Nioh 2 is noticeably worse and its cutscenes can almost only be enjoyed in that way, as the occasional silly or badass vignette bookending a level. While I think fans of the first game will be quick to attribute this to the custom character being unable to carry the narrative, I think the real problem is just the disjointed nature of the story. There are just too many time skips and too little character development and context.

I don’t expect everyone to agree with this take on the story, though. Those with foreknowledge of Japanese history may get a kick out of the game’s take on things, and have a better framework for understanding the story, much like the first Nioh. But a poorly told, poorly paced story is still poorly told and poorly paced, even if it’s more tolerable with the appropriate foreknowledge.

The end of the game is well done, though. It doesn’t make up for how bad the story is leading up to it, but its a much better ending than I had even dared to hope for, and I was pleasantly surprised.

A brief note about the voice acting: the English is distractingly bad. Like porn parody bad. I don’t know how good or bad the Japanese is, but it sounded better to my ears. Problem is there is a lot of talking during levels in this game and I cannot read subtitles while fighting things. In short, I wish the English voices were better, but if you’re of the persuasion that subs are always superior to dubs, this probably won’t bother you that much.

Final Thoughts

In spite of a number of shortcomings, Nioh 2 is a blast. There’s a ton of game here, at least 40 or 50 hours for a single playthrough, but dozens more for players who enjoy the grind and move on to new game plus and grind out that +10 gear and max out their character level.

I think Nioh 2 is ultimately a better game and a smoother ride than the first Nioh, and I prefer it to Sekiro‘s more scattered design. In short, it’s the ultimate weeb Souls-like experience. While I think most people who like Nioh 2 would also enjoy Nioh, starting here wouldn’t be a bad idea if you prefer. The things added to Nioh 2 largely improve it, and aside from the story, almost every part is the same or better.

I think the criticism that Nioh 2 doesn’t do enough new is fair, but I also think that it’s exactly what a lot fans of the first game wanted—smart changes and good ideas to evolve the experience without dramatically overhauling it. It won’t significantly expand the audience, but that wasn’t the goal. For what it is, it’s a fine game and a great sequel.

I recommend Nioh 2 to fans of hardcore action RPGs. Fans of the first Nioh will love it. If you felt the first Nioh was a bit prone to bullshit or had a bit of a rough start, this game may win you over, though be warned that it also starts sort of rough, particularly with the third main level. If you hated Nioh or get frustrated easily, you probably won’t enjoy the game that much.

My unofficial custom macro framework for Harlowe actually just reached version 1.0.1, but I didn’t have time to write up a release note when I released v1.0.0, so I’m writing these now. This version, 1.0.1 just adds a few new macros and addresses an error in the download utility, so the framework itself hasn’t changed. I have to version-bump it any time I release macros because of how the download utility works, though.

Version 1.0.0 didn’t really change much compared to 0.4.1, just featuring clearer names for APIs and cleaned up docs and such. So really there isn’t much to talk about, or there wouldn’t be. Instead of talking about the changes in 1.0.0, I think it could be more interesting and enlightening to talk about how I designed this framework and why I made the decisions I did. This may get technical at times, but I feel like the overarching story of this framework is pretty easy to grasp and shouldn’t require too much knowledge, of JavaScript or of the inner workings of Harlowe.

Harlowe Hacks

About two years ago, when I was working on Harlowe Audio Library, I was playing with the idea of exposing some Harlowe APIs used by the library to users, since I needed to access at least the State and Engine APIs for HAL. I didn’t wind up doing this because I was worried about the ramifications. Harlowe’s internal APIs aren’t designed for use by authors, and it’s easy to cause problems if you aren’t familiar with the inner workings of the engine.

As an example, consider the State, which is the API that handles story variables. Exposing this API to a user would let them set and retrieve Harlowe story variables from JavaScript code. That’s great! Now you can have various user inputs or offload hefty work to more performance-friendly JavaScript code! Except that the way Harlowe handles history means that storing data in story variables that the engine can’t serialize causes all kinds of issues. The engine can only serialize primitives, arrays, sets, and maps. Not even generic objects! And the format wouldn’t error or warn you, it would usually just try to keep going, making the problems even harder to find. I ultimately decided that if I wanted to expose these APIs, then I would probably need to create wrappers around them that checked for potential problems and threw useful error messages, and that if I was going to build end-user friendly API wrappers, then that was well beyond the scope of an audio library.

So I took my ideas to a project I nicknamed “Harlowe Hacks” and just dumped a bunch of code in there that I could one day release as a standalone project that did things like expose internal APIs in a safe(ish) way. While that project did eventually become my custom macro framework, custom macros were not really the focus at that point; it was just scope hacked Harlowe APIs with wrappers around them to prevent massive errors. I had no intention of messing with custom macros because I felt that Harlowe’s internal macro APIs were onerous to work with a difficult to understand.

After a few months I felt that Harlowe Hacks wasn’t really going anywhere. Working on Harlowe in JavaScript, even with my code there to fill in some gaps, still required a lot of understanding of Harlowe’s internals. Realistically, if you want an extensible format, you should probably just use SugarCube. This is still largely true, but it’s not helpful to the many users who have major projects already going in Harlowe, and users who have legitimate reasons to prefer Harlowe over SugarCube, but just want a normal textbox instead of an ugly prompt. It’s true but it’s also unhelpful, and I wanted to do better, but didn’t know how.

I shelved the project and moved on.

Everyone Hates HAL

While I had made HAL’s APIs as simple as possible, it was still JavaScript, and many Harlowe users proved more resistant to even considering using it than I could have ever imagined. There is a sort of flow to suggesting HAL to most Harlowe users. They ask how to use audio in Harlowe, and someone suggests HAL. They then claim it didn’t work, or was too much since all they wanted was X, Y, or Z, or they gave up on having audio at all after being frustrated that everyone kept suggesting this “compicated” HAL thing. Not very satisfying to see, for me, but I knew I had to swallow my pride and learn whatever lesson was wrapped in this reaction. There were plenty of people who did try HAL, of course, and ultimately figured it out and swore by it. But the overall reaction to HAL was disdain. While its true that the documentation could be gentler and read more like a guide, I knew the real thing people wanted was macros.

After a few illuminating discussions with GreyElf, Akjosch and TheMadExile on the Twine discord, I dived into Harlowe’s macro APIs. I hated what I found. I still hate it. The macro APIs, to say the least, are not designed the way I would do it. They’re bizarre, esoteric, and overly modular. They also require tons of type checks and other confusing, interlocking APIs that I largely don’t feel are necessary or helpful.

For HAL 2, I only needed the macros to run a function and return the occasional primitive value, so I wrote around the issue, constructing a simplified API that took an object full of functions and created a macro using the property’s name, then passed the macro arguments directly to the function inside. Everything else, including type checks, was circumvented by this simplified API and ignored.

HAL 2’s Macro Code

With improved documentation and a complete macro API, HAL 2 has proven to be much more popular. Some users still seem to approach it with skepticism and hesitancy, but the numbers don’t lie. HAL 2 gets downloaded three or so times as much in a given month, on average, that HAL 1 did at its peak. That’s really neither here nor there, though. The point is that I made a simplified, stripped down macro API for HAL 2 and that was a breakthrough for this project as much as for that one.

While support for HAL 2, among other things, occupied me for a few weeks thereafter, I was starting to think about Harlowe Hacks again, but ultimately made no decisions regarding it.

A Custom Macro Collection for Harlowe

In December 2019, I conceived of the idea of a custom macro collection for Harlowe and that became the basis for this framework. Unlike my SugarCube collection, this macro collection would need to be built around a central library file that added the required functionality.

That core framework would need to be simplified, similar to HAL. It would also require safe API access like what Harlowe Hacks was designed to provide. Mix in some helpers and other basic features, and you have this custom macro framework.

The framework’s simple macro creation function. Compare and contrast with HAL 2’s approach.

I had to make some decisions when providing the custom macro API. I ultimately made several decisions that I was pretty conflicted on, and I think it’s worth looking at those decisions in detail and presenting my reasoning. While I don’t think any of the decisions I made will be particularly controversial, I can imagine reasonable people coming to different conclusions and thus being interested in how and why I made the choices I did. We’ll be looking at a bit of code to ground us, but I’ll try not to get too into the weeds. Most of these decisions were actually not made for strictly technical reasons anyway.

A Single Macro Function for Two Types of Macros

It is possible to create two types of macros with this framework. One type simply executes a function, and can accept arguments and return values. The other type, “changer” macros, act on a hook (internally called a descriptor by the framework and Harlowe’s rendering engine). The framework omits “command” macros which are another class of macros used internally by Harlowe because they don’t really provide any features the other two don’t.

I decided to determine which type of macro is needed by the number of functions the user provides to the Harlowe.macro() function: changer macros execute two functions, while “basic” macros execute only one. In the former, the first function typically performs set up and type checking, while the second has access to the hook.

The framework determines which type of macro to create based on the arguments provided.

I could have split this into two separate functions, rather than determining which kind of macro to create based on the arguments passed, and there is a solid argument in favor of that, since the current function could be considered overloaded. That said, I think a single function works fine since there will never be any overlap. Theoretically a two function API could allow changer macros to omit the first function, but that is really the only benefit to having to separate functions.

I don’t like the aesthetic of an API like Harkowe.macro.changer(...), and I don’t think it’s hard to remember or confusing the way it is. I also already strongly dislike that Harlowe has different macro types with different API calls to set them up, and I think that’s a far more confusing way to approach it, especially for users experienced with making macros in SugarCube.

All you have to remember is this: if you just want to run some code or return a value, you only need one function. If you want to access or act on a hook, you need to provide a second function that handles the hook specifically.

Macro Execution Context

Users need to access a lot of information inside a macro. SugarCube exclusively uses an execution context class to do this: each macro has a context instance that holds all the relevant data, including arguments, the macro name, payloads, etc. Harlowe passes all this data in as arguments to the executing fucntion instead. This framework does both.

Arguments passed to the macro are passed directly to the executing function(s), straight through, as entered by the user into the macro. The rest of the data is handled by a SugarCube-esque execution context (the arguments may also be accessed from the context for those who prefer that). I felt that this kept function calls clean and concise, and it allowed be to include functionality not present in Harlowe’s macro APIs without much fuss.

The macro execution context constructor.

Of course, adding a whole execution context prototype and instantiating it for each macro call could fairly be called overkill when I could have easily just passed everything I wanted to include in as arguments, but I think the other conveniences of this implementation make up for it, particularly with how type checks are handled in the framework.

Simplified Type Checking

Harlowe introduces strict typing into its engine, but the way it does so for macro arguments is laborious for devs to implement. This framework simplifies the process and makes it optional (but highly recommended). Calling a method on the context and passing in an array of expected types mapped to each argument, with special syntax for providing multiple options for each argument, allows you to quickly check types and be done with it. This process is super simple and clean, if I do say so myself, and is possible because of the way the execution context is handled as a prototype.

Code for the type checking method of the macro context prototype.

The Future

I hope this post sheds some light on why and how I designed this framework. I’ve already been porting a lot of my custom macros over from SugarCube, and adding some systems to Harlowe that I think it needs, like clamping and dialogs. I plan to add new macros to the collection as I make them for Harlowe users, and I encourage users to share their macros, too. You can reach out to me in an issue or PR over on the repo if you’ve made something you’d like to share using this framework.

My ultimate goal is to have a stable bench of custom macros for Harlowe users to browse and use, just like my macros for SugarCube. There are, of course, some features that will remain out of reach, but I hope this helps users who feel more comfortable with Harlowe or who prefer it to be able to squeeze more out of it.

The over-under here is that Persona 5 Royal is, for the most part, an improvement on the original. It’s not a dramatic or massive improvement; instead, it is comprised of dozens of small improvements throughout the journey and an excellent additional palace complete with one month or so of additional daily life gameplay and another (very large) mementos section. It’s hard to say whether paying $60 to replay an 80-hour game for its 20-ish hours of new content is necessarily a good investment, but I think the game at least justifies being a full-price re-release rather than simply a DLC pack that just adds a palace and a month to the main game.

The changes are numerous and integrated well into the game. Not just new scenes, but also revisions and changes to several mechanics from every part of the game, from combat to confidants. All of these changes are smart and improve the game. No single one of them in itself dramatically improves the game over the original, but taken together they make Royal more streamlined, more fun, and more interesting.

We’ll start with story and characters, because while many of the most impressive and interesting changes are here, I also don’t want to say too much or spoil anything, so I don’t have too much to say.

First, some of the dialogue, particularly the localization, has been rewritten and re-recorded. The localization and English voices in Persona 5 were already above average, but most of the awkward and odd moments have been cleaned up. The original version has moments where the voice actors clearly lacked direction or where the localization team didn’t quite capture the original meaning of a scene, and in a game as text heavy as this one, and as steeped in Japanese culture, that’s not surprising. Awkward lines that feel out of place still exist in Royal. Bad voice acting, particularly from bit characters, but also the occasional odd delivery from a main character, remain. But the overall quality has been improved. I hope that some of these changes are patched into the original release, because most of them correct errors rather than add new content.

The second change is two new confidants, one of whom becomes a party member late in the game, and a major improvement and revision of a confidant that was already in the game but largely underwhelming. I don’t want to spoil too much, but these new confidants are incredible, and easily the best in the game. In my opinion, social links in previous games were always a mixed bag, but in Persona 5 I felt there were far fewer interesting ones. Royal‘s new confidants feel dramatically important and contribute to the new palace’s story at the end of the game; to even get there you have to focus on all three of these new confidants. That makes these stories integral to the game in a way past confidants and social links in both this game and in the whole series, never were. I can’t overstate how clever this is. Your confidants, from very early in the game, are already setting the stage for this new palace. It feels like two interrelated stories being told simultaneously, and both are satisfying. Persona 5 Royal is big enough (and long enough) that it supports the weight of these two narratives well.

Finally, there are several additional scenes and events throughout the game. Most of these are just fun. A few give you insight into your party members, some help serve to set up elements of the narrative that lead to the final palace, and some just round out minor plot holes or other rough spots in the original. A very small number of these feel redundant, but none of them were bad or unwelcome by any means.

Daily life has also seen some big changes. There’s a new area to explore that introduces new features, like a jazz club, billiards, and darts, all of which let you power up your party members in some way. Morgana is less of a bed time nazi, and you can now do things in Leblanc after going to the metaverse, like studying, tidying up for Sojiro and kindness points, and crafting tools. Confidants will give you a phone call after hanging out which gives you a bonus opportunity to earn some points and can help you get through them faster. There’s less time pressure in the game overall, so having three new confidants to level and all the power boosts you’ll want from the jazz club and darts and such doesn’t result in an over-stuffed experience. It’s still meaningfully challenging to get all the confidants in a single playthrough (not counting new game plus), but it also still feels like you have more freedom in how you spend your time.

However, that one part of the game during summer, where you go from scripted event to scripted event through finishing Futaba’s palace to being forced to hang out with Futaba every day for a week to going to the beach to finals to the Hawaii school trip to Morgana being temporarily unavailable, where you literally can’t do anything but what the game tells you to for a long, long time remains unchanged and as frustrating and boring as in the original game, and it’s especially jarring given the added freedom Royal grants you almost everywhere else. I expected this part of the game to still be a problem area but I wasn’t expecting absolutely nothing to be done to address it, given that it’s a fairly infamous sequence.

Palace design has been improved with new collectibles and a new grappling hook that can be used to find secret paths, and even to ambush enemies later. Overall though, the palaces remain mostly similar. There’s some new shadows and many of them have been altered or rebalanced both to keep you on your toes and to make for more interesting and dynamic fights. But the parts that were annoying before are still annoying. Okumura’s palace is still largely annoying. Shido’s palace still features braindead, time-wasting, backtracking mouse puzzles. The casino palace is still a pretty neat place with a bopping theme tune, and Kamoshida’s palace is still a great warm up with a lot of neat, varied areas. The game’s new palace, is pretty good. There’s a color puzzle area at the end that’s basically a worse version of Okumura’s air locks that many players will hate and that I found annoying but mercifully short.

Mementos is still a drag, but they’ve spruced it up where they could. Time spent in mementos is more rewarding and there are ways to increase your efficiency in grinding for XP, money, or items. You can also collect “flowers” to exchange with a new vendor, Jose, for various consumables, which also makes mementos useful for acquiring certain items, like SP potions and stat boosting incense. It’s not a dramatic improvement, but mementos is now much more useful and it is useful in shorter bursts, and both of those improvements take the edge off of the monotony of it.

Boss fights have been drastically changed, most for the better. I really like the new phases, and each one has been improved from its original incarnation except for Kamoshida. You’ll know what I mean when you play it but the new phase felt in poor taste, even if it makes sense, and sort of just cheapened some of the drama for me. It’s gross and cringey, but hey, that’s Kamoshida for you, I guess. The new boss of the new palace is excellent but is mechanically a little bit too much like Yaldabaoth for my liking.

Combat itself has been changed in a few key ways. Baton pass has been improved, with a new focus placed on it, and it’s available to every character from the start, and playing darts with your party members powers up their baton pass rank, meaning they give bigger buffs when they hand off to an ally. Stacking baton passes is an incredibly powerful and satisfying strategy and the game sets up a couple fights designed to let you take advantage of the mechanic to its fullest. Guns now have less ammo in total but that ammo refreshes after each battle, instead of each infiltration. Guns are absolutely busted early on but even out as the game goes on and remain a useful tool throughout, even into the late and end game. I think they probably could have adjusted the power curve a bit as they can trivialize fights that are clearly meant to be challenging early on, but I definitely prefer this approach to the original, even with the weird balance.

And otherwise, the balance of combat overall is pretty good. It’s different. I don’t know if the balance is necessarily better or worse than the original version, but the changes make the game feel fresh and, in my opinion, more interesting and kinetic. Persona’s combat system has always been simple and satisfying and Persona 5 was no different, aside from a flair for the dramatic and a few additions, like guns and new attack elements. Royal tries to make this core combat deeper without adding too much in the way of complexity, and I think it succeeds.

Personas now also have new innate abilities called traits that are similar to passive skills, but are generally more powerful than the passive skills a typical persona of that level would have access to. These can be transferred via fusion, and add another layer of depth to building personas. Personas themselves have been changed a bit. In addition to new personas and two new arcana, many returning personas have also been rebalanced or otherwise altered, which helps keep things feeling fresh and interesting.

A new, third awakening persona has also been added to each party member, which improves their stats and grants them a new, unique, powerful skill. Makoto for example has a multi-target debilitate spell and Ann can gets a variation of the concentrate skill that targets all party members. These skills cost an absurd amount of SP to use (around 80), so they aren’t quite as game breaking as they seem when you first get them. Still, they’re powerful and these third awakenings are definitely a fun addition, though they happen incredibly late in the game, so you want have much time to play around with them.

Another new feature are showtime attacks, similar to limit breaks or other similar mechanics in other JRPGs. Showtimes are team-up attacks that become available under certain conditions in combat. While they are powerful when introduced, they have a nice curve similar to summons in a Final Fantasy game where they are a useful crutch in the mid-game but ultimately become just another tool in your toolbox by the end, illustrating how powerful your other abilities have become. They’re an okay inclusion but probably one of the less major changes to combat overall. Each one is worth watching once or twice, and you can’t miss them as they’re simply unlocked as the story goes on. They’re fun and over the top, and Persona 5 is great at introducing these sorts of chance-based mechanics that always feel great when they trigger. It’s just more of that, like most of the things Futaba does during combat. I think the original game was great at leveraging these sorts of mechanics in ways that kept combat exciting and engaging, and showtime attacks are a natural fit.

As good as Persona 5 Royal is, though, and it is very good, I don’t think it’s perfect. Persona 5, when it came out, managed to be one of my favorite games ever, and while I still waffle about which Persona game is my favorite between 3, 4, and 5, I consider 5, and now Royal instead, to be my favorite a significant amount of the time. A great many things are addressed and improved, but Persona 5 Royal is still Persona 5, for better and worse.

Royal still does that thing where an event will happen, then the party will meet up and rehash it, then you’ll rehash it again in text message chains that go on for too long, then you’ll bump into Ann outside school and they’ll rehash it again, then you’ll go home and Ryuji will text you when you walk in the door to rehash it again. Then you’ll go to bed and Morgana will rehash it with you before you go to sleep. Then you’ll have a dream and Igor and the twins will rehash it in a vague way. And then there will be a fast forward and Sae Niijima will rehash it in the form of an angry interrogation. And then, finally, something new will happen and the cycle will repeat.

I’m being hyperbolic but I’m convinced the text message interface in Persona 5 was designed specifically to repeat story plot points every five minutes in case you ever put the game down for a few days. And that’d be smart if it was optional. Like you can’t remember what was going on in the story so you can pop out your cell phone and refresh your memory; that’s a great idea in a game this long and this story focused. Instead, though, it’s just grating being told the same plot points ten times in a row in one of several different boring formats. What’s more irksome is that this constant rehashing, and the fact that your phone is often cluttered with repeated invites from confidants, means that you often times wind up with good story and character stuff mixed in with these messages that you’ll miss if you decide to skip through them. There’s enough actual character and plot progression occasionally mixed into these rehashes that you probably won’t want to skip through them even though you’ll be tempted to after the umpteenth time you have to reassure your group that all you can do now is wait because you did indeed steal Kamoshida’s heart two weeks ago and Ann and Ryuji need to remind you of that, in the form of fretting, two times a day until something new happens.

In short, the message spam is boring, terrible and represents an inordinate amount of gameplay time for how pointless and unnecessary it is. Royal does nothing at all to address this. The new palace does have noticeably less message spamming and plot rehashing than the main game, though, so that’s something I guess. Though it does arbitrarily restrict your R1 fast travel menu and make you visit each of your party members over the course of several in-game days right at the start, which doesn’t exactly get the blood pumping. There’s no reason you shouldn’t be able to zip to your allies using the fast travel menu instead; you regain your use of it right after this sequence ends.

The other issue I had with Persona 5 in its original incarnation is the bickering and in-fighting, particularly among Ryuji and Morgana, and again, Royal doesn’t do anything to smooth this out. I like both characters, and their bickering was actually annoying, and there’s some merit to that. On your first day of school, getting lost looking for the right train is a neat little immersive trick the game pulls; it risks being annoying, but it does so to help you relate with Joker. Ryuji and Morgana’s fights are often uncomfortable because they know each other well enough to be actually mean to each other, and there’s merit in making us relate to how exasperating these fights must be to watch for Joker. But the frequency and duration of these fights make them actually trying, and they often pull an otherwise fine scene in a weird direction, letting all the drama, tension, or humor out of it. The game seems to believe that these sequences are funny, or that they inject levity into tense moments, and uses them accordingly. The game is very wrong about this.

The Phantom Thieves as a group have interesting dynamics. They are friends, sure, but they also have a sort of Ocean’s Eleven vibe. They’re a team of outlaws and the fact that they know each other’s secrets and that they often share short-term goals is usually how their relationship with each new member starts. The concept of confidants and the language used in the game about making deals reinforces this. But it also makes them feel a bit more distant from each other, and when they have what’s supposed to be a funny argument, you aren’t always sure how to take it. It doesn’t help that one relatively normal Morgana-Ryuji spat is arbitrarily determined by the story to be more severe than the others for some reason, even though they ultimately learn nothing and go right back to treating each other like shit after this with no further ramifications ever again. It’s like a bad action movie where you don’t have any sense of how much punishment a character can actually take, so there’s no real drama in it, it’s just down to the unknowable whims of the creators.

Another issue is a bit more spoiler-y, so people who haven’t reached the second palace in Persona 5 should be wary. The first palace in the game is rather heavy. Kamoshida is sexually and physically abusive toward his students, particularly Ann and her best friend Shiho. It’s implied that Kamoshida sexually assaults Shiho, ultimately causing her to jump off the school’s roof in an attempted suicide. This is a powerful and crystalizing moment for the Phantom Thieves. They know that stopping Kamoshida by stealing his heart carriers a chance of essentially triggering brain death in him if they make a mistake, and its not something they can do lightly. But when they realize what he’s actually capable of, they decide they have to act. That’s all well and good, and the game handles this sensitive subject matter with surprising grace and appropriate seriousness.

In the original Persona 5, however, the very next palace features the gang pressuring Ann into posing nude for Yusuke, and Ann clearly doesn’t want to and is obviously uncomfortable with the idea. Ann is described consistently as both being beautiful and standing out and it has caused no end of trouble for her. It also puts her immediately in a compromising situation again with Yusuke immediately after being in one with Kamoshida, but the game plays it for laughs the second time and the whiplash is just too much. Not only does Royal do nothing to fix this, it’s actually worse because it does something similar to Shiho.

Kamoshida’s new second phase in Royal features him calling “slaves” to help him fight. These slaves are his cognitive representations of the students he is abusing. The first one he calls is Shiho, the girl who was implied to have been sexually assaulted and who attempted suicide, and Ann’s best (and mostly only) friend. Again, it’s Kamoshida’s cognitive version of her, given that the real Shiho is in a self-inflicted coma she may never recover from. She’s dressed in a sexy bikini and wearing bunny ears, and you have to kill her. Ick. While I do think this makes sense given the context and given what we know about Kamoshida and his warped view of reality, the original version didn’t go there and in Royal it didn’t need to and doesn’t add anything by doing so. It is in poor taste and cheapens the drama that led up to the moment quite a lot. I don’t have an issue with the sexual jokes and such in the game, and I don’t think the other characters perving over Ann throughout the game is a problem or anything; in fact, a lot of those scenes are pretty funny. I think the issue is specifically that these are hard topics to watch and think about, and you want to feel like you can trust the creators to do it well and take it seriously so that you can let your guard down and really engage with these though subjects. When the creators are flippant about it, that undermines that trust, and that makes it more likely that people will keep the story at an arm’s length and keep themselves guarded. It’s not that this is necessarily some sort of moral failing, instead it’s simply poor storytelling.

Also, it’s worth mentioning that a scene featuring an eyebrow-raising depiction of gay men was reworked, or at least re-localized, to feel like it came from this side of the 1970s. The old scene was an uncharacteristically lazy joke anyway, so even if it didn’t bother you or make you raise your eyebrows, it’s now at least a little easier to laugh at Ryuji, which is always an improvement.

As a package though, I think I can generally recommend Royal for both new players wanting to see what all the commotion is and for older players looking for more Persona 5 or who were thinking about replaying it anyway. It’s not exactly a steal at full price, but I do think it justifies itself with a wealth of new and interesting content and a variety of improvements across the game in almost every area. If you didn’t like Persona 5 much, this won’t likely change your mind, but if you’re looking for the best version of one of the generation’s best JRPGs, then this is it.

---

Author’s Note I’m stuck in quarantine playing video games all day, and a lot of games I’ve been very excited about have released recently! I’ve decided to review/critique them. I enjoy criticism but reviewing games is new for me so there’s bound to be some growing pains and awkwardness. Please bare with me while I get a handle on this. In the coming weeks I want to talk about Nioh 2 and Final Fantasy VII Remake in some capacity, so I’ll see you then!

This is a pretty massive update, complete notes can be found in the changelog. The biggest additions are:

• A local storage interface.
• More helpers and functions.
• Three new macro examples.
• Cleaned up and streamlined source code and build process.

The additional macros are:

• A dialog macro for creating modal “windows” (like little pop-ups).
• An achievements system.
• A clamping macro.

Future Plans

This project on the repo details the plans I have headed toward a v1.0.0 release.

I have put fixing the basic macros on hold indefinitely, as I don’t think it’s a big deal and fixes would require an API change, one I think would largely be for the worse.

• Website
• Macro Demos
• Repo

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.

This release includes two new systems, one bug fix, and some documentation and website fixes.

The Continue <<cont>> Macro

A thing I see requested reasonably often is a “click anywhere to continue” style of macro. In fact I’ve written a few implementations for people in the past, but was never super happy with any of them. Well, I’m not super happy with this one either, it’s significantly clunkier to use than I think it should be, but it’s the best implementation I’m personally likely to develop, and it’s not bad, just probably not as slick as you may expect.

You can optionally make pressing any key also activate the macro, and adjust other options.

The Speech Box System

I sometimes call things a “macro” even when they have some JavaScript functions or interfaces built-in, as long as there’s just one macro in the script and that’s the primary interface most users will utilize. I often call things “macro sets” when there’s a few related macros involved. I use the term “system” when I’m not really sure what the hell to call something. This is one of those latter things, because what it actually does is give you a “macro factory” that creates macros at runtime. You plug a name and image URL into the <<character>> macro and it creates a shiny new macro you can use based on the supplied name for character speech / dialogue boxes (I avoid the term “dialogue” in favor of “speech” in the documentation and elsewhere for fear of confusion with the unrelated term “dialog”, which refers to a modal box, like an alert or prompt or similar).

Here’s an image of what I mean by a “speech box:”

It’s intentionally basic and bare bones. Whip up some CSS and make it your own! The minimalist look can probably work fine for games that use the basic SugarCube look, though, so I wouldn’t sweat it too much if CSS isn’t your thing.

(Note: This Lisa is apparently a K-Pop star. She’s basically the first page of results on Google image search. I picked the first square image I could see and basically used it in several examples. I do not own this image, but I believe this counts as having changed it significantly enough to count as fair use, and should be defensible as fair use given the educational nature of my documentation and examples. In other words, don’t @ me.)

Bug Fix in <<notify>>

Somehow missed this one. I did test it, but I must have made adjustments after testing it. The parsing of CSS time was throwing errors, even with valid CSS time arguments. Should be fine now.

Other Fixes

I made documentation fixes and patched up some dumb errors in the download utility. I also added the new macros to the downloader, the docs, and the demo.

Next Time on Custom Macros Z

That rounds up the changes in v2.5.0. I have more ideas I’m considering, and I do jot down questions I see more than a few times, so I’m certainly not done yet in that respect. But I do feel like I’m starting to approach a line with the cycles system, the meter macros, and the speech boxes. As I close in on these more complex and specific use cases, I’m closing in on concepts that are probably better off with bespoke solutions. This narrows the band of people these macros are useful for.

Consider the fading macros or the dice roller functions. There’s real value in these even for people capable of building such systems themselves because it’s already done for them and because their results would likely look almost exactly like mine.

But with meters and speech boxes: why settle for someone else’s structure and the limitations and inconveniences they introduce when you can build a bespoke system from the ground up. Sure it takes a little longer, but you get exactly what you want and nothing extra and no wrestling with someone else’s stuff. This means that the people who benefit from these kinds of systems are specifically people who can’t build it themselves or people who just happen to be looking for similar aesthetics or setups to what I’m providing.

This isn’t a huge deal in and of itself, but it is why I’ve been hesitant to make certain systems, like health bars and conversation boxes, in the past even though they are frequently asked for. It’s why I remain hesitant on re-making a consumable-style inventory and why I’m still sitting on ideas to extend the simple inventory to handle stackable items and other item metadata. I’m not looking for guidance or advice on this, though I welcome thoughts, I just wanted to give a small window into how I’m thinking about these things.

In addition to UI updates, accessibility improvements, and bug fixes, the main feature of this release is the new passage list interface, which lists the passages in your project for quick navigation in larger projects.

Clicking on the “hamburger” icon (☰) on the top left will toggle the passage list. This list reflects your current sorting and filtering settings.

In future releases

Additional improvements to the passage list are possible, and I’ll be looking into ways to make it more useful.

2019 was a pretty big year for Twine, and I think now is a great time to reflect on everything that’s happened. It’ll be helpful to me to collect my thoughts and talk through how I feel about the past year, but I think it’ll also help others get caught up on what’s been happening in the Twine community and ecosystem.

Twine 2.3.0 and Electron

Twine 2.3.0 entered beta in mid-December 2018, with a full release arriving in April 2019. This version of Twine represented a pretty massive change for the project, particularly the downloadable application version. Previous versions of the downloadable application version of Twine ran on the NW.js software, a browser shell based on Chromium that allowed web applications to run kind of like native apps by using a dedicated, stripped down browser. Applications like this are often called “hybrid applications.” With version 2.3.0, Twine switched to a different browser shell (also based on Chromium) called Electron. Why? Well it’s complicated, but you can read this comment from Chris Klimas for a very brief explanation.

As you may be able to imagine, a change this drastic in the underlying middleware of a fairly complicated app was a big deal and it took a few patches to smooth things over. Posts over on the reddit announcing each version 2.3.x release track the story if you’re interested. The big takeaway is that Twine 2.3.5 is now as stable as Twine has ever been.

Twine also now opens the test and play versions of your story in your default browser, which is a great change in my estimation. Subtle differences between the shells used by the Twine apps in the past and real browsers have always existed. These differences caused widely encountered issues in Twine 2.3.x, but it’s possible they could have caused issues anyway, so I think this change makes a lot of sense. Twine also now saves back-ups in case your main story files are corrupted or deleted. This feature was added due to a specific bug in the 2.3.0 release that was eating stories, but the Twine app has been known to eat stories outside of that bug, so this was another clever and welcome change.

What’s in store for version 2.4.0? Well, nothing too exciting, really. You can look at the plans so far here.

Chooseco vs the World

Chooseco is the company behind those Choose Your Own Adventure books you maybe read as a kid. They own the term and, apparently, its acronym, “CYOA.” Lately, they’ve been letting us know about it. Also letting Netflix know about it. In a way this is fair. Companies are required by US law to proactively defend their trademarks or risk losing them. But the loss of a useful descriptive term has been a bit of a blow to the Twine community. As an alternative, I suggest “choice-based.”

Note that it does not seem that Chooseco is actively suing any developers or anything like that, but instead trying to get people to stop using the terms. If you have a game published somewhere that is described as a “CYOA” or “Choose Your Own Adventure” consider changing that language in any official descriptions or in the game itself.

Trademarking Twine

Speaking of trademarks, the IFTF also officially trademarked the name “Twine” this year. What effect that has on the community, if any, remains to be seen. My guess is that this is not going to impact any of us in any major way, though referring to games as “Twines” or games made in other programs as “Twine games” may become a point of contention in the future.

Goodbye Q&A

In late July, the Twine Q&A was retired from active duty due to an overabundance of spam and a lack of time, manpower, and technology to deal with it. For reference, I was one of the mods. As bad as it looked to an end user, you don’t know the half of it. The Q&A site still exists for users to search through and still appears in searches, so the answers written there are still available, much like the old forum archive before it.

Twine’s official online community is now the Twine category at intfiction.org. The subreddit and Discord communities continue to exist as well.

The Twine Resources Guide

I released a curated list of Twine resources in June this year. While it’s my own guide so it may be a bit inappropriate to plug it here, it is, to my knowledge, the most exhaustive and well-tested list of its kind. You can make suggestions and contributions via its repo if you’re so inclined.

Flash in the Pan

The Twine news section of the official Twine website, meant to be a twice monthly report on the biggest happenings in the Twine universe ended in February 2019 after only five or so months of operation. This was a curious addition to the Twine website in the first place, in my opinion, as the Twine Twitter account seems like a better way to handle this, but I feel like it’s unceremonious end is just as curious. I don’t have much to talk about here, I just didn’t want this short-lived news section to be lost to the ages.

Narrascope

I didn’t go to the first annual Narrascope conference that happened in June, but I’m glad it exists and I’m interested in going to one of them someday, should one happen in my neck of the woods. I do know a lot of people who went and several who spoke at the event and it generated a number of great blog posts. If you’re interested, this year’s conference is going to be held on May 29-31 in Urbana-Champaign, IL, and is accepting proposals from speakers through January 17.

Chris Klimas, creator of Twine, spoke at Narrascope 2019. Here’s his talk in blog post form. I think it’s a fascinating read for anyone with more than a passive interest in Twine.

There’s also a Narrascope podcast now if that’s your thing.

Harlowe 3

Harlowe 3 technically released late last year, two weeks before the year ended with the first beta release of Twine 2.3.0 in mid-December 2018. However, it wasn’t widely used until April this year when Twine 2.3.0 had its full release, so I’ll consider it a 2019 development for our purposes.

I’m not a fan of Harlowe 3. It’s just Harlowe 2, honestly. Changes I feel Harlowe desperately needs, like any kind of mobile support or responsive design, did not happen, and those changes are likely to be breaking for users, meaning there is a high chance we’ll have to wait for Harlowe 4 to see them, if we ever see them at all (I’m not holding my breath).

Other than that, Harlowe 3 now has a few input types like dropdowns and cycling links, but still doesn’t have actual text inputs and still uses ugly prompts (though the situation there has improved somewhat) even though users have been asking for textbox inputs for years now. I should clarify, the new input macros could support a traditional textbox-style input easily, Harlowe 3 just hasn’t added it yet (and again, I’m not holding my breath).

Overall, I was disappointed with the limited changes here, especially for a major version bump. I do think Harlowe has great ideas. I’ve dug pretty deep into its source code in developing HAL, and I can assure you that there’s a stroke of genius every few lines.

But for as much brilliance is on display in some areas of Harlowe’s design, I think it is hamstrung by other design decisions. Decisions that box authors in, lock them out of any extensibility or options, or simply don’t make sense, like the aforementioned indefensible lack of responsiveness. Harlowe literally just needs a single line of HTML code to become responsive, but the so-called beginner format would instead force authors who want to fully support mobiles to manually add the line required.

In my opinion, Harlowe’s design decisions remain as at odds with themselves in version 3 as they were in version 1 and 2. It is a format that wants to be limited and focused and opinionated, but also strives to be as full-featured and wide-ranging as SugarCube. I think it’s spread too thin and I don’t know that it will ever strike that balance.

SugarCube 2

SugarCube 2 is still mostly what you probably expect. It’s still the format that’s hardest to go wrong with. It’s still clunky, but straightforward, syntax-wise. It’s still powerful, simple, and packed with features, options, and extensibility. That’s not to say there haven’t been improvements this year, though.

First, the SimpleAudio API is now fully documented, giving authors the ability to more easily leverage SugarCube’s audio subsystem from JavaScript code. SugarCube has also added a Template API and syntax for text replacements and now features a new State.metadata API that replaces the <<remember>> and <<forget>> macros. Improved documentation rounds out the changes we’ve seen from the format over the year.

So, all-in-all, nothing life changing, but the releases this year, particularly v2.29.0 in June, have been impactful and full of features and improvements.

As a general rule, I still recommend SugarCube 2 for most Twine users and that’s on track to continue throughout 2020. It’s as simple, or nearly so, as Harlowe, almost as extensible as Snowman, and it has the deepest bench of features, options, and functionality. It’s just so hard to go wrong with SugarCube.

Snowman 2

Snowman has impressed me this year. Chris Klimas has moved to developing Chapbook (more on that in a moment) and handed development duties for Snowman off to Twine guru and cookbook editor Dan Cox (AKA Videlais), who has been working on developing a second major version of the format and providing actual documentation for the first version.

Snowman 2 does make a small handful of changes I don’t like, but by and large it’s mostly just added some conveniences, features, and functions that make the format more usable by more people. Snowman was always meant to be minimal, and I think that central design concept needs to be respected. But I think you could argue that Snowman was too minimal in its first incarnation. I think adding a few bells and whistles is a great idea and is likely to make the format more appealing to the advanced users it was meant to attract.

Under this new direction, I think Snowman is gonna be a format to keep your eye on in 2020. That’s not to knock the solid base provided by Chris, but I do feel like Snowman was stagnant at best for the past few years and I’m excited to see where it ends up.

Chapbook

I love the idea of Chapbook even though I have some issues with its implementation and execution. I think that Chapbook could become what I feel like Harlowe should be, and that’s massively exciting to me, because there’s value in a simple, opinionated, somewhat limited story format. I feel that Chapbook fully commits to being different and more focused, whereas Harlowe seems to want to simultaneously compete with SugarCube’s wide-ranging design and provide a slimmer, more focused feature set. Where Harlowe is, in my estimation, at odds with itself, Chapbook strikes a completely different balance that has long been foreign to Twine. Or at least it’s on the way to doing that.

Chapbook has a neat backstage feature that provides the best built-in testing features in any Twine story format, with live updates, styling options, variable editing, and all sorts of other goodies, which is a stroke of genius, especially since you can omit all the backstage code to slim down your game when you go on to release it. Backstage is excellent and has no downsides.

My issues with Chapbook are mostly in the inconvenient way it handles control logic like if statements. Sure it has conditional assignment via the JavaScript ternary operator and a few other conveniences, but this limitation coupled with enforced separation of variable control and story content mean that it can be a challenge to make logic-heavy games compared to the other formats. I am also concerned by the fact that all variables are global unless you namespace them yourself (a sharp edge less experienced coders are likely to get cut on), that saves are automatic and very outside author control, and that Chapbook seems to lack a history system or a rewind/undo feature.

Taken together, I’m more excited to see what Chapbook evolves into throughout 2020 than I am to use it right now. I think the promise of what Chapbook could become is more exciting than what it is right now, but I don’t want to belittle what it is right now either. It is a bold, new direction for Twine story formats that does challenge some of the core concepts we expect, and I think that’s very much worth celebrating.

Paperthin

I think Paperthin should be replaced by Illume or poof (yes, I made poof, so I’m biased, but I hate Paperthin). We should bug Chris on Twitter about this. Otherwise, Paperthin remained bad throughout 2019 (it hasn’t changed since it was made, honestly). It still doesn’t let you print or copy paste passage titles along with passage content, and is basically useless.

Twee Compilers

It’s no secret to anyone who knows me that I prefer working with Twee and command-line compilers to the Twine application any day of the week. And this was a big year for Twee and Twee compilers. First, we finally got an official Twee3 specification so that tools using Twee can now enjoy greater interoperability and developers of such tools actually know what the rules are.

In response to the new Twee3 spec, Tweego 2 (by Thomas Michael Edwards, developer of SugarCube) and Extwee (by Dan Cox/Videlais, developer of Snowman and editor of the Twine Cookbook) were also released this year. While I still prefer Tweego overall, I really like Extwee, and that it’s an NPM package is sure to make it super tempting to some authors. It also has built in transpilation and minification, things I do anyway. I think there’s a chance it tries to do too much stuff at once for some people, but for most users, these are good choices and good inclusions. Tweego on the whole is more mature and has more features, though.

Other Twine specs are also in the works, so the future of third party tools for Twine is looking particularly bright for 2020. As a developer of a few such third party tools, I can’t begin to express how nice it is to have some real specifications.

Final Thoughts

2019 was a pretty big year for Twine, and I think looking back on it helps us see where we may be going, and how we’re going to get there. So let’s speculate a bit.

First, I don’t think we’ll see any big changes in the Twine app next year like we did this year with the jump to Electron. I do think 2.4.0 will arrive sometime next year, but I don’t foresee major or dramatic changes in the way we use the app, in how it feels to use, or in its underlying tech.

I don’t have any specific expectations for the story formats outside the normal updates we tend to see over time. I wouldn’t expect a Harlowe 4. I would expect Chapbook to change a lot over the course of 2020. Don’t hold your breath for a SugarCube 3, though the Trello for SugarCube should help you manage your expectations for what’s coming in SugarCube 2. There’s only so much you can add to a format that’s meant to be minimal, so I also wouldn’t expect Snowman 2 to get more than maybe a handful of additional convenience features. Dan Cox has shown a willingness to rethink parts of Snowman, though, so I’d still keep an eye on it in 2020.

I think we’ll see more custom story formats and other tools for Twine now that there’s actually documentation on Twine’s HTML data chunk, documentation on developing story formats, and a proper spec for Twee. I don’t expect things to suddenly explode, but having these things documented is step one in expanding the base of people who are capable of experimenting with them. I had to read source code to figure out how to make poof. I think now that you don’t have to do that, there’s no reason why other community members won’t start making their own tools.

Finally, I wouldn’t sweat Chooseco’s crack down too much, or Twine’s trademark. Chooseco has to protect their brand–that I, and many others, I’m sure, think of Twine or other computer software when I hear “CYOA” or “Choose Your Own Adventure” is proof of that. Likewise, I think Twine should be more proactive in protecting its own brand. Any old schlub can come along and make a website with the brand name in it, after all*.

I’m interested in hearing from others, too. I may release a follow up to this piece in early 2020 where I cover some of the things I missed in this article, but also some things I haven’t touched on, like game releases. If you have ideas or know something I don’t, leave a comment or drop me a line. I’m also interested in what Twine games you’ve played that were released this year and what you thought of them.

Thanks a lot for reading. Happy holidays and happy new year.

*Note: I actually doubt that TwineLab.net would run afoul of this trademark.