Working with TinyQBN

• Part 1: Terms and Concepts
• Part 2: Writing QBN Stories Using Twine 2 Example
• Part 3: Working with Twee Code
• Part 4: Generating Dynamic Passages and Cards

TinyQBN is a JavaScript library and set of SugarCube widgets created by Joshua Grams for working with quality-based narrative (QBN) structures in Twine 2.

Part 1: Terms and Concepts

Storylet

The term storylet originates with the studio Failbetter Games and the design of a game initially called Echo Bazaar that would later become Fallen London (2009). In a blog post explaining its narrative structure, the term “storylet” appears as a definition of “discrete chunks of narrative” (Failbetter, 2010; para. 3). Later clarified as part of a developer diary post, Failbetter Games (2012) described storylets as “pieces of story like mosaic tiles, not pipes or complex machinery. Put them together. Build something wonderful” (para. 11).

In working with Failbetter Games and other projects, Emily Short (2019) has expanded on this term and refined its definition into three parts:

“[1] there is a piece of content. It might be a line or a whole section of dialogue, it might be narration, it might be an animation or scrap of film

[2] there are prerequisites that determine when the content can play

[3] there are effects on the world state that result after the content has played”

Storylets: You Want Them. Short (2019)

A storylet, in other words, consists of some lexia whose access is granted through qualifiers. When accessed, or as a part of content within it, its output or presented player choices produce changes to values external to the storylet itself. Depending on the changes to these values, access to other storylets may be affected or an ending to the game triggered.

While the term storylet is not used in descriptions of its design, Reigns (2016) has been described by both Short (2016b) and Kreminski and Wardrip-Fruin (2018) as an example using the concept. In Reigns (2016), the player is presented with a short text and two choices. Depending on the choice, one or more attributes (values) will be affected. If any of these values are decreased or increased beyond a set range as a result of choices made, the game ends.

Play progresses as the player is presented with storylets based on current attribute ranges, specific sequenced previously unlocked, and random choices from the total possible storylets in the game. Each choice counts as a year in the game, with the goal to “reign” as as long as possible before starting with the next king in line and beginning again.

King of Dragon Pass (1999) has been cited by Failbetter Games (2011) as an inspiration for Fallen London (2009). Failbetter Games (2011) writes:

Every other turn or so, you are confronted by an event like this: a slice of story and a set of responses, like an Echo Bazaar storylet. The art is beautiful. The text is clean and urgent, deftly distilling conflict into a single gripping decision. Each choice has its consequences and can trigger follow-up events, with some stories unfolding over decades of play.

Echo Bazaar Inspirations: King of Dragon Pass. Failbetter Games (2011). Para. 4.

Presented as tribal leadership governed by advisors, the player navigates a series of seasons for their people within a year with random events occurring between each. These random events are chosen based on previous decisions and the current resources of the tribe. During one, the player is presented with a short amount of text and choices whose outcome may affect their current resources or standing with other tribes and peoples in the game. While the game has a fixed narrative path, a pool of hundreds of random events creates different play-through experiences each time.

A Sharp, the company behind King of Dragon Pass (1999), created a scripting language, Opal Scripting Language (OSL), for its development. As shown as part of a “sample” posted on their website, OSL compares resources and uses conditions for influencing narrative presentation (OSL Sample, 2020).

text: <he/she> gives away clan wealth to those fiendish talking lizards.
[n AND dragonAttitude= 'positive] text: Despite <his/her> assurance, <he/she> has done little to help our case with the dragonewts.
[n AND dragonAttitude= 'neutral] text: <he/she> wastes time thinking about talking lizards, instead of clan concerns.
[a] text: <he/she> sends our weaponthanes into the woods on pointless hunts for the plant-folk.

Dunham (2011) has also written about King of Dragon Pass‘ (1999) development using the authoring tool mTropolis. The engine keeps track of the game’s state and values in such a way that scenes can access and react in different ways, creating a narrative experience based on scenes shown to the user based their previous choices and values of the game’s current state.

Quality-based Narrative (QBN)

In the same blog post defining storylet, Failbetter Games (2010) also describes the use of qualities that “tell storylets what to do” (para. 4; original emphasis). These serve as expressions of one or more values as part of the StoryNexus engine within Fallen London (2009). Anything a player has, including their attributes and current location, can be be used as part of qualities. These are then used as conditions for determining if accessing storylet content is possible.

For example, the player may need 4 Jade and to be at a location named Edge City to access a storylet. The condition “>= 4 Jade AND location = ‘Edge City'” exists as a combination quality for that storylet. Within the definition from Short (2016), this is part of its “prerequisite.” In order to access some content, its qualities must be met. Used across a collection of storylets, then, its overall structure can be defined as a quality-based narrative (QBN).

The metaphor of cards and a deck are often used to describe the process of selecting storylets, frequently labeled drawing based on the larger metaphor of card-based games. Given the current qualities of a player, storylet possibilities are drawn from a pool (deck). When random selection is used, some libraries (like TinyQBN) also use hand to describe a subset of cards from the deck currently being considered.

While many people have embraced the term quality-based narrative based on Failbetter Games and Emily Short’s work, Kennedy (2017), the creator of the term, has proposed ‘resource narratives’ or resource-based narrative (RBN) as alternatives because of the issue around a potential misunderstanding of “quality” applying not to measurements of a storylet’s prerequisite but its content (para. 3). As the term “resource” is used in StoryNexus’ documentation to discuss qualities as currency, such a usage has gained some interest (Storychoices, 2012).

The term salience-based narrative (SBN) has also been proposed by Short (2016) to describe a system using a drama manager like used in Façade (2005) to use salience to limit the current options or choices of the player (Mateas and Stern, 2005). Kreminski and Wardrip-Fruin (2018) have also proposed weights for storylets or the use of a system to manage storylet tracking.

Twine 2 Concepts

Passage

The smallest unit in Twine is a passage. In the Twine 2 editor, this is represented as a box connected by links between them.

Passage have three parts:

• title: A link between passages is created using the destination’s title. In some story formats, one passage can also be embedded in another using its title.
• tags: Twine 2 has the ability to change the outline color of a passage through colors assigned to its tags. Depending on the story format, tags can also be used to search for passages.
• content: Any textual data can be used inside of a passage. Some story formats allow for writing code that will be executed when the passage is shown to the user.

While passages can be thought of as nodes themed around locations, spaces, or times in a story, passages exist primarily as storage. When not shown, passages exist as part of a storyarea. They are shown to the user when using links or as directed by code within the story.

Some story formats like SugarCube and Snowman allow for accessing passages within the story and using their content outside of showing it. When working with these story formats and their functionality, passages can be treated as data storage for stories.

Story Format

Each story format in Twine 2 defines not only how the content of passages will be displayed on the screen, but also different options for scripting code within passages, how they relate to each other, and internal events triggered when the story format performs different actions.

For example, SugarCube uses two less-than and greater-signs around keywords to define macros, functionality built into the story format. An example of this syntax is the macro <<include>>, which embeds the content of one passage in another. Authors can also add their own new macros in SugarCube called widgets, which act like macros but are developer-defined functionality.

Story and Temporary Variables

The story formats Harlowe and SugarCube categorize variables according to their lifespan. A story variable, which starts with a dollar sign, exists for as long as the story is open. A temporary variable, which starts with an underscore, only exists during the current passage. It is deleted when a new passage is loaded.

TinyQBN Metaphors

Card

As passages are storage, they are treated as cards in TinyQBN if their tags include “card” or “sticky-card” marking them as such.

The difference between a card and a “sticky” one is in its usage. A card is normally “discarded” when it is accessed (shown to the user). However, a sticky card is never discarded and remains part of the deck into future drawings.

::Home [card]

Qualities for the cards are also included through using expressions in tags as well. A card is considered available if all of its qualities resolve to true and it has not be discarded previously.

Quality Expressions

Expressions can be written as “name-op-number” to compare an existing variable to a value or as “name-op-name” to compare one existing variable to another.

TinyQBN also borrows from SugarCube’s shorthand form of comparisons explained in the following table:

Shorthand	Comparison Operation
eq	==
neq	!=
lt	<
gt	>
lte	<=
gte	>=
eqvar	variable == variable
neqvar	variable != variable
ltvar	variable < variable
gtvar	variable > variable
ltevar	variable <= variable
gtevar	variable >= variable

For example, to write the quality “>5 Jade”, assuming the story variable $jade existed, it would be “jade-gt-5”.

::Home [card jade-gt-5]

Because SugarCube does not differentiate between story and temporary variables, neither does TinyQBN. When comparing variables, both can be used with the knowledge that any temporary variables created during the last passage loading event will be erased when the next happens in a story.

Locations

TinyQBN encodes locations using the following tag expressions:

• passage-title: If “title” matches current passage title, result is true.
• visited-title: If “title” exists in the history of the story, result is true.

Hand

A hand of cards in TinyQBN is created through the widget <<fillhand $hand limit #>> where a story variable $hand is filled with cards based on the number passed to the widget after the keyword limit or using the JavaScript method QBN.cards(limit=none), which returns a hand of cards based on the limit argument.

Showing Hand

The current Hand can be shown in a number of ways using widgets:

• <<cardlist $cards>>: Show cards stored in $cards as a comma-separated list
• <<cardrow $cards>>: Show cards stored in $cards as rows
• <<cardcolumn $cards>>: Show cards stored in $cards as columns

Deck

All available cards (passages with “card” not yet discarded or containing the “sticky-card” tag) can be drawn from to fill a hand at any time. Individual card’s qualities can be checked using the QBN.visible(card) method; if all of the requirements are met, the method will return true.

References

Dunham, D. (2011). An Architecture Overview. King of Dragon Pass. Retrieved from https://kingofdragonpass.blogspot.com/2011/02/architecture-overview.html

Failbetter Games. (2010). Echo Bazaar Narrative Structures, part two. Retrieved from http://www.failbettergames.com/echo-bazaar-narrative-structures-part-two/

Failbetter Games. (2011). Echo Bazaar Inspirations: King of Dragon Pass. Retrieved from https://www.failbettergames.com/echo-bazaar-inspirations-king-of-dragon-pass/

Failbetter Games. (2012). StoryNexus Developer Diary #2: fewer spreadsheets, less swearing. Retrieved from https://www.failbettergames.com/storynexus-developer-diary-2-fewer-spreadsheets-less-swearing/

Façade (2005). Procedural Arts.

Fallen London. (2009). Failbetter Games.

Galatea. (2000). Emily Short.

Grams, J. (2019). Tiny-QBN. GitHub. Retrieved from https://github.com/JoshuaGrams/tiny-qbn

Kennedy, A. (2017). I’ve stopped talking about quality-based narrative, I’ve started talking about resource narrative. Weather Factory. Retrieved from https://weatherfactory.biz/qbn-to-resource-narratives/

King of Dragon Pass (1999). A Sharp.

Kreminski, M., & Wardrip-Fruin, N. (2018). Sketching a Map of the Storylets Design Space. In R. Rouse, H. Koenitz, & M. Haahr (Eds.), Interactive Storytelling (Vol. 11318, pp. 160–164). Springer International Publishing. https://doi.org/10.1007/978-3-030-04028-4_14

Mateas, M. & Stern, A. (2005). Structuring content in the Facade interactive drama architecture. Proceedings of the First AAAI Conference on Artificial Intelligence and Interactive Digital Entertainment. pp. 93-98.

OSL Sample. (2020). A Sharp. Retreived from http://a-sharp.com/kodp/osl.html

Reigns. (2016). Nerial.

Short, E. (2016a). Beyond Branching: Quality-Based, Salience-Based, and Waypoint Narrative Structures. Emily Short’s Interactive Storytelling. Retrieved from https://emshort.blog/2016/04/12/beyond-branching-quality-based-and-salience-based-narrative-structures/

Short, E. (2016b). Reigns. Retrieved from https://emshort.blog/2016/08/20/reigns/

Short, E. (2019). Storylets: You Want Them. Emily Short’s Interactive Storytelling. Retrieved from https://emshort.blog/2019/11/29/storylets-you-want-them/

Storychoices. (2012). Design before you write. Storychoices: Building stories with interactive narrative platforms. Retrieved from http://wiki.failbettergames.com/wiki:design-before-you-write