Story Structure Generator

A creative writing tool that generates branching narrative structures based on narrative function theory. This tool doesn't write stories—it creates coherent structural frameworks that writers can use as scaffolding for interactive fiction.

Inspiration

This project is inspired by Vladimir Propp's seminal work "Morphology of the Folktale" (1928), which identified 31 narrative functions that appear consistently across Russian folktales. Propp discovered that while the characters and settings varied, the underlying structure and sequence of functions remained remarkably consistent.

The included configuration file (lackDefaultConfiguration.json) adapts Propp's theory, focusing on a subset of his functions and adding mechanisms for branching narratives and alternative story paths. Rather than strictly following Propp's linear sequence, this tool allows for:

• Elaboration: Adding prerequisite narrative functions (e.g., a "Liquidation" requires prior "Guidance" and "Donor Sequence")
• Branching: Creating alternative narrative paths (e.g., "Consent" vs "Refusal")
• Continuation: Extending completed arcs with new narrative sequences

The result is a procedurally generated story structure that maintains narrative coherence while allowing for the complexity and choice-driven nature of modern interactive fiction.

Features

• Generates branching narrative structures through iterative elaboration
• Configurable rule systems based on narrative function theory
• Multiple output formats:
  • Mermaid flowcharts for visualization
  • Twee files for import into Twine interactive fiction editor
• Probabilistic rule application for varied output
• Automatic spatial layout for Twine editor

Installation

npm install

Usage

Basic Command

node src/cli.js generate [options]

Or, if installed globally:

story-structure generate [options]

Using npx (No Installation Required)

You can run the tool directly without installing it first using npx:

npx story-structure-generator generate [options]

This will download and execute the package in one step, perfect for trying it out or one-off usage.

Options

| Option | Description | Default | |--------|-------------|---------| | -c, --configuration <path> | Path to configuration JSON file | config/lackDefaultConfiguration.json | | -i, --iterations <number> | Number of revision iterations | 5 | | -m, --mermaid | Generate Mermaid flowchart output | false | | -t, --twine | Generate Twee/Twine output | false | | -n, --name <name> | Story title (for Twee output) | Generated Story | | -o, --output <name> | Output file name prefix | story | | -p, --probability <number> | Probability for rule application (0-1) | 1.0 | | -v, --verbose | Enable verbose logging | false |

Examples

Generate a story structure with 10 iterations and output both formats:

node src/cli.js generate -i 10 -m -t -n "The Hero's Journey" -o hero_story

Generate with 80% probability of applying rules (more variation):

node src/cli.js generate -i 15 -t -p 0.8 -o variable_story

Use a custom configuration file:

node src/cli.js generate -c my_config.json -i 10 -m -t

How It Works

1. Start: The generator begins with an initial chain of narrative functions (e.g., "Lack → Mediation → Consent → Liquidation")

2. Iteration: For each iteration, the generator:

   • Traverses the story tree bottom-up
   • Examines each node to find applicable rules
   • Probabilistically selects and applies rules to elaborate, branch, or continue the narrative

3. Rules: Three types of rules shape the narrative:

   • Elaboration: Adds prerequisite functions before a node (e.g., before "Liquidation" can occur, the hero needs "Guidance")
   • Branching: Creates alternative paths (e.g., the hero can "Consent" or "Refuse" the call to action). By default, newly created branches are automatically elaborated to match the current iteration depth, preventing early branches from being much longer than later ones. For terminal branches (like failure states), set suppressElaborationAfterBranching: true to prevent this automatic elaboration.
   • Continuation: Extends terminal nodes with new sequences (e.g., after "Liquidation" comes "Pursuit" and "Rescue")

4. Constraints: Rules can have conditions:

   • cardinality: Limits how many times a rule applies
   • mutuallyExclusiveWith: Prevents conflicting elaborations
   • regularity: Probability threshold for application

5. Output: The final tree structure can be exported as a Mermaid diagram for visualization or as a Twee file for import into Twine.

Output Formats

Mermaid Flowchart

Generates a Markdown file with Mermaid syntax showing the complete story structure as a flowchart. Perfect for visualizing the narrative paths.

Example output:

flowchart TD
    node0[Lack, Insufficiency]
    node1[Mediation, the connective incident]
    node0 --> node1
    node2[Consent to counteraction]
    node1 --> node2

Twee (Twine)

Generates a .twee file that can be imported directly into the Twine editor. Each narrative function becomes a passage with:

• Function title and description
• Links to subsequent narrative functions
• Automatic positioning for the Twine editor
• Breadcrumb trail showing the path from the story's beginning

Import into Twine via: File → Import From File → Choose .twee file

Configuration Format

Configuration files define the initial story, rules, and function labels. See config/lackDefaultConfiguration.json for a complete example.

Basic structure:

{
  "initialStory": {
    "chain": [
      { "functionType": "a" },
      { "functionType": "B" },
      { "functionType": "C" }
    ]
  },
  "rules": [
    {
      "id": "unique-rule-id",
      "type": "elaboration|branching|continuation",
      "appliesTo": "C",
      "regularity": 0.5,
      "result": { "functionType": "K" },
      "conditions": {
        "cardinality": 1
      }
    }
  ],
  "functionLabels": {
    "a": {
      "name": "Lack, Insufficiency",
      "description": "The initial state of deficiency that sets the story in motion."
    }
  }
}

Testing

Run the test suite:

npm test

Tests use Vitest and cover the core story generation logic, tree operations, and output formatting.

Creative Writing Workflow

1. Generate Structure: Run the tool to create a narrative structure
2. Import to Twine: Load the .twee file into Twine
3. Add Content: Replace the generic descriptions with actual story text, dialogue, and choices
4. Polish: Add styling, variables, and conditional logic as needed in Twine
5. Publish: Export your finished interactive fiction from Twine

The generated structure provides narrative coherence—your job as a writer is to bring it to life with compelling prose and meaningful choices.

License

MIT

Author

Paul Michelotti