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.
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:
/*QBN 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.
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
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
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.
If you make changes to
rebuild the minified version, you’ll need
README.mdfile is located (
npm installto download the necessary tools.
npm run exampleswill build the examples (assuming tweego is available).