How to develop a custom toolbar like Harlowe's?


I’m developing a custom story format for Twine (i’m using 2.3.16 version).

I’d like to implement a simple UI toolbar like the one Harlowe uses (i’m not saying that the one Harlowe uses is simple, of course :wink: ) I’m quite skilled in JavaScript (is my job actually), but i can’t find any documentation on that.

The only thing i get is that Harlowe uses a deprecated “setup” JSON key in setting up the storyFormat object, and apparently it uses it for syntax highlighting (and i do not know if it uses it for anything more).

I’ve tried to study either the source code of Twine and Harlowe, but i honestly can’t pretend to rapidly understand what probably a lot of people had surely created in a lot of time :wink:

Can someone give me some directions? Thank You in advance!

The reason you can’t find any documentation about extending the User Interface of the existing releases of the Twine 2.x applications (eg. the versions pre 2.4) is because there isn’t any, as currently extending that UI is done via a “hack” which exposed parts of the CodeMirror widget’s internals (1).

For examples on how Harlowe builds it’s Twine v2.3.x implementation I would look at Line 24 and lines 76 to 83 of the Makefile for the v3.2.3 tagged build.
For examples on how Harlowe interfaces with the application’s UI I would look at the files in the codemirror folder of the v3.2.3 tagged source.

The expected v2.4 and later releases of Twine 2.x will include a formal method of extending the application’s UI, and information about this can be found in the file of the Twinejs project’s GitHub repository. There are also v2.4 and “Extending Twine” related issues in the repository’s Issues section.

(1) so that Harlowe could add its “toolbar” and code highlighter functionality, and which is why no other Story Format currently has such features.

Looking at the twine-2-story-format-starter repo might also be helpful. It has tooling set up that handles compiling Twine extensions for you. If you don’t want to use it, you can probably crib Webpack config from it for your own format.

Soon I’ll have a prerelease version of Chapbook committed as well which will include its own toolbar and extensions, so it’ll hopefully be a good set of example code for how to use the various extension methods documented in It uses Rollup for bundling so the setup will look different than in the format starter. (I picked Webpack for that because it’s more popular, but I personally don’t prefer it.)

There’s also a #format-development channel on the Twine Discord for discussion if you’re a Discord person.

Thank You all for the detailed answers, very appreciated! :+1:t3: