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.

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 probably want to start by skimming some of these walkthroughs (video versions on YouTube):

The new features in this version of the library are:

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.