A simple toolkit for creating filtered-card-deck stories (aka storylets or quality-based narratives or resource narratives) with Twine 2 and SugarCube. Use Twine’s passage tags to mark cards and their requirements, and a couple of simple functions and macros to select and display cards. Continue to use Twine links as usual when those are the appropriate tool.

As of version 3.2.1, Harlowe has storylets, using the (storylet:) command to define requirements for a passage and (open-storylets:) to get a list of the open (available) storylets for display.

If you’re comfortable with some JavaScript, David Masad’s StoryletManager adds parameterized storylets to SugarCube, where the “same” storylet can appear in different places (or even multiple times in the same place) with different objects or characters filling certain roles.

Dan Cox’s SimpleQBN is a JavaScript library for storylets that isn’t tied to a particular story format or to Twine at all.


For easier editing, you can now put the TinyQBN “tags” in comments in the passage itself:

/*QBN card req-lizard-eq-Sam req-transformations-gt-2 */

If you use req: instead of req-, the rest of the line will be treated as a TwineScript expression:

  card  req: $lizard eq "Sam"
  req $transformations gt 2

I ran through the examples quickly and they all still seem to work, but by all means let me know if I broke anything horribly.

Adding TinyQBN to your Story

Now you can simply generate a blank TinyQBN project, save it and import it into Twine.

Or you can add the library to a story manually: copy the Story Javascript (the minified or the readable version), the widgets (create a passage with a widget tag for these) and optionally the Story Stylesheet into your game. Click the “Raw” button when viewing these for easier copy/pasting.


You may want to start with Dan Cox’s new Working with TinyQBN articles: they give a clear overview of the concepts and get you started by translating some examples from the Twine Cookbook into QBN form:

Or you can dive into my walkthroughs (video versions on YouTube):

I also wrote some completely undocumented code to create stats that improve as you use them, using the “Basic Ability” math from StoryNexus. That code is split between basic-ability.txt and the “choice helpers” at the end of widgets.txt.


This is still missing a good way to automatically display storylet requirements to the player. That’s…a complicated thing to do in a generic library like this, and I may or may not ever figure out how to do a good job of it.

And it hasn’t been used for a real game/story, so it could have hidden design flaws.

I believe that my examples exercise all the features, and everything works there, but I don’t have a proper test suite for the code.

Other than that, I’m regarding this as feature-complete. I’d like to add a bunch more documentation and examples, but that’s not my strong point, so it’s slow going. There might also be a few more convenience features I could add.

But I think this is about as far as it makes sense to go in Twine without writing an entire new story format. And since Twine’s editor is not designed for this, if you’re going that far you might as well spend the time to bang together a more suitable editor and make a full custom tool. My two cents, YMMV, etc.

Rebuilding the Minified Javascript

If you make changes to story-javascript.js and you want to rebuild the minified version, you’ll need Node.js installed.