0 votes
by (160 points)

This wiki page has code that references variables like "state" and ""Wikifier", but I haven't been able to find anything that lists the available JavaScript-facing API.  Is the API described in documentation anywhere?

I don't care if it's Harlowe or Snowman or anything else, as long as its API is documented somewhere, I'll use it.

1 Answer

+2 votes
by (63.1k points)
selected by
Best answer

For Harlowe 1.x and 2.x:

Harlowe goes to great lengths to make its APIs specifically unavailable, in my experience.  If you need to use JavaScript, you're probably not going to want to use Harlowe.

For Snowman:

Snowman is basically all JavaScript.  It has decent documentation on the wiki, and is simple enough that you can generally just take a look at the relevant part of the source code if you need more than that, or ask questions here.

For SugarCube 1.x or 2.x:

You probably shouldn't use v1.x anymore, but the documentation is still around.  Here's the v2.x documentation, which details most of the APIs (the second large list of links).  The Wikifier API, for whatever reason, is undocumented, but here's its source code.  There's a few other parts of SugarCube that are also undocumented.

Why on earth are features undocumented???

I'm not a developer, but here's my guess.

Providing documentation for a given API implies that the developer wants you to use it.  They certainly don't care if you use it, but if it's not in the documentation, that gives them greater flexibility in updating their code, since you shouldn't necessarily expect undocumented features to be as well supported in new versions as the documented features.  A lot of the undocumented features are also lower-level (meaning they handle more engine-y things, like parsing, in the case of the Wikifier), and at some point there has to be some cutoff for documentation. Besides, in this case, the jQuery wiki() methods are documented, and you should usually be using them in any place you might be considering use the Wikifier. 

In the case of Harlowe, it seems to draw this line in the sand as soon as TwineScript stops, hiding and locking down most of its JS to the point that it requires hack-y workarounds to use it's JS APIs.

About that inventory code from the wiki.

That example you found on the wiki should be deleted, in my opinion, as it's not a great example of how to use the SugarCube APIs it uses (no offense to the original author) and we see a lot of poorly written code here that's modeled off it. On top of that, while it will probably work in v2 thanks to a number of compatibility shims present in 2, you're better off using 2's APIs.

If you have specific questions about SugarCube 2's APIs, or want to know more about its undocumented or under-documented features, this Q&A is probably the best place to ask.

by (160 points)
Thanks so much for the thorough answer!