Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pompom454/tea/llms.txt

Use this file to discover all available pages before exploring further.

The Story object is a static store that holds all of the story’s identity information and every Passage instance loaded from the compiled HTML. It exposes getters for the story’s name, ID, and IFID, along with methods for querying and mutating the passage store at runtime.
Methods that modify the passage store (Story.add(), Story.delete()) cannot operate on code passages or passages with code tags (init, widget). See the individual method notes for details.

​
Getters

​
Story.id

​
Story.id
string
The DOM-compatible ID of the story, derived by slugifying the story name.
Returns the story’s DOM-compatible ID. This is the slugified form of the story name and is used, for example, as a basis for the <html> element’s id attribute. 
Story.id // e.g., "the-dark-forest-saga"

​
Story.ifId

​
Story.ifId
string
The IFID (Interactive Fiction IDentifier) of the story, or an empty string if none exists.
Returns the story’s IFID. In the Twine 2 ecosystem, IFIDs are version 4 random UUIDs assigned when a story is first created. 
Story.ifId // e.g., "D674C58C-DEFA-4F70-B7A2-27742230C950"

​
Story.name

​
Story.name
string
The human-readable name of the story.
Returns the story name as set in Twine or the Twee source. 
Story.name // e.g., "The Dark Forest Saga"

​
Methods

​
Story.add(descriptor)

​
returns
boolean
true if the passage was added successfully; false otherwise.
Adds a new passage to the passage store at runtime. The descriptor must include name, tags, and text.
Cannot add code passages (e.g., StoryInit, StoryMenu) or passages tagged with code tags (init, widget).
​
descriptor
object
required
A passage descriptor object. All three properties are required.
The descriptor object must have the following properties:
​
name
string
required
The passage’s name.
​
tags
string
required
A whitespace-separated list of tags, or an empty string for no tags.
​
text
string
required
The raw TwineScript/wikifier text of the passage.
const descriptor = {
  name : "Forest 4",
  tags : "forest heavy",
  text : "You can barely see farther than arm's length for all the trees.",
};

if (Story.add(descriptor)) {
  // "Forest 4" is now in the passage store
}

​
Story.delete(name)

​
returns
boolean
true if the passage was found and deleted; false otherwise.
Removes the Passage instance with the given name from the passage store.
Cannot delete the starting passage, code passages, or passages with code tags.
​
name
string
required
The name of the passage to delete.
if (Story.delete("The Ducky")) {
  // "The Ducky" passage has been removed
}

​
Story.filter(predicate [, thisArg])

​
returns
Array
A new Array<Passage> of all Passage instances that passed the predicate, or an empty array if none did.
Searches all passages for those that satisfy the given predicate function. The predicate receives each Passage instance in turn; returning true includes it in the results.
Cannot retrieve passages tagged with code tags.
​
predicate
Function
required
A function (passage: Passage) => boolean that tests each passage.
​
thisArg
any
Optional value to use as this when calling the predicate.
// All passages tagged "forest"
Story.filter(function (p) {
  return p.tags.includes("forest");
});

// All passages whose names contain whitespace
var hasWhitespaceRE = /\s/;
Story.filter(function (p) {
  return hasWhitespaceRE.test(p.name);
});

​
Story.find(predicate [, thisArg])

​
returns
Passage | undefined
The first Passage instance that passed the predicate, or undefined if none did.
Searches all passages for the first one that satisfies the given predicate function.
Cannot retrieve passages tagged with code tags.
​
predicate
Function
required
A function (passage: Passage) => boolean that tests each passage.
​
thisArg
any
Optional value to use as this when calling the predicate.
// First passage tagged "forest"
Story.find(function (p) {
  return p.tags.includes("forest");
});

// First passage whose name contains whitespace
var hasWhitespaceRE = /\s/;
Story.find(function (p) {
  return hasWhitespaceRE.test(p.name);
});

​
Story.get(name)

​
returns
Passage
The Passage instance with the given name, or a new empty Passage instance if no such passage exists.
Retrieves the Passage instance by name. If the passage does not exist, returns an empty (error-rendering) Passage rather than null — so existence should be checked with Story.has() first if needed.
Cannot retrieve passages tagged with code tags.
​
name
string
required
The name of the passage to retrieve.
const theDucky = Story.get("The Ducky");

// Access its properties
theDucky.name  // "The Ducky"
theDucky.tags  // e.g., ["pond", "animal"]
theDucky.text  // raw passage text

​
Story.has(name)

​
returns
boolean
true if a Passage instance with the given name exists; false otherwise.
Checks whether a passage with the given name exists in the passage store.
Does not check passages tagged with code tags.
​
name
string
required
The name of the passage to check.
if (Story.has("The Ducky")) {
  const p = Story.get("The Ducky");
  // safe to use p
}

Build docs developers (and LLMs) love

Get started for freeTalk to us