tiny-qbn

TinyQBN

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.

New!

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.

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.

Documentation

Quick reference.
Older, more verbose reference (doesn’t cover the newer features).

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:

Terms and Concepts
Writing QBN Stories
…and he has two more planned.

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

Getting Started with TinyQBN: twee, html.
Seasonally Available Items (more complex conditions and a yearly loop structure): twee, html.
Single-Use Cards for Story Passages: twee, html.
Three Ways to Track Progress. This doesn’t have a good example yet, but there is an “example” testing that the code works: twee, html.
Cards with Covers: twee, html.
Inline Choices: twee, html.
Card Priority: twee, html.
Dice Rolls: here’s a quick example of doing Powered by the Apocalypse style dice rolls (roll 2d6 plus a stat modifier, 10+ is success, 7-9 is mixed results, 6- “life is interesting”): twee, html.
Setting up Tweego and VSCode to build Twine stories from text files instead of using Twine’s graphical editor.
Weather the Storm is a small (around 2500 words?) complete story I wrote that fakes a parser-ish world model, using cycling links to enter verb/noun commands and storylets (with a how-many-conditions salience filter) to respond to them. The source has its own GitHub repository, and you can play it on itch.io.

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.

Status

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.

Open a command-line window.
Go to the folder where this README.md file is located (cd blah/blah/blah).
Run the command npm install to download the necessary tools.
npm run build will create the minified version of the story javascript.
Once that’s done, npm run examples will build the examples (assuming tweego is available).

This site is open source. Improve this page.