Script Weaver Format Tutorial

Script Weaver lets you write interactive games using a simple, human-readable format that closely resembles cinema script formatting with some changes to make it easily readable by a game programmer. The intent is that given that script, game studios can produce a narrative-driven game without having to do any directorial decisions and staying close to the author's intent.

Or, thinking about it another way, providing an actor or tabletop game master with such a script should allow them to run the scenario as the author intended without making anything up and without a serious headache.

Core Concepts: Blocks

Your script is composed of text blocks. Think of them like paragraphs or distinct beats in your narrative. Blocks are separated by at least one completely blank line or a change in indentation level. The game progresses by moving from one block to the next, following rules based on the block type and your instructions.

Narrative Text Block

This is the most common block, used for dialogue, descriptions, and actions. It has three optional parts:

NAME
(Conditions and state changes)
The actual text dialogue, description, or action goes here.
It can span multiple lines.

NAME: A short and consistent title case line. Who is speaking or what is the focus? Examples: Elara, Narrator, Mysterious Box - everything that deserves a name can be named. If omitted, it is assumed to be read by the Narrator or to be the protagonist's internal thoughts or actions.
(Logic): A single line in parentheses written in simple language. This is not intended to be read by the player but is for anyone behind the scenes, be it producer, programmer or a tabletop gamemaster.
- The first sentence inside the parentheses acts as a condition. It must be true for the block to appear at all and to be considered played. For example, (Player has the rusty key.) is a good condition to check whether the chest can be opened.
- Anything else is a state change or behind-the-scenes instruction executed if there are no conditions or they are satisfied. These can set facts for future condition checks, trigger sounds, or provide notes for production/casting. Example: (Player uses the key. Chest is now open. Play tense music.) It is better to keep those simple and clear.
Text: The dialogue, action, or description shown to the player. This is the information that you want to be seen. Standard screenplay formatting for dialogue under a NAME and prose with direct speech will fit well here.

Indentation and Flow

Think of your script like an outline. Blocks at the same level follow one after another. But when you indent a block using spaces (typically 4), you're creating a sub-point or a dependent step. This indented block will only be considered or shown after the less indented block directly above it has been successfully shown or completed. It's a way to tuck specific details or follow-ups directly under the event that triggers them.

NARRATOR
You see an old, dusty chest in the corner. It looks locked.

CHEST
(Player has the rusty key.)
You try the rusty key in the lock. It clicks open!
    (Chest is now open. Player used rusty key.)
    Inside, you find a small pouch of coins.

CHEST
(Player does not have the rusty key.)
The chest is firmly locked. You'll need a key.

In this example the NARRATOR block is the parent. The two CHEST blocks are indented further, making them children. Because they are at the same indentation level, they are siblings. Only one will be shown, depending on whether the player meets the condition in its (Logic) line.

Choice Blocks

When you want the player to make a decision, use a choice block. This one itself isn't shown. It presents its indented child blocks as options. There are two types, defining what happens after the player explores a choice:

`EXPLORE` (The Persistent Loop)

Always returns the player to the choice list after any option is finished. Use this for main locations, central dialogue hubs, or menus. The player needs an explicit way out, so one of the options has to have a CONCLUDE keyword block to get out of the loop. CUT TO option described later can be used to escape too.

NARRATOR
You are in the bustling tavern.

EXPLORE
    (If barkeep hasn't left yet.)
    Talk to the barkeep.
        You approach the bar.

        BARKEEP
        What'll it be?

        You have a long talk with a barkeep.

    Scan the room.
        (Player is now aware of the Ranger.)
        You notice a shadowy figure in the corner.

    You head for the door.
        CONCLUDE

`CHOICE` (The Decisive Moment)

Once the player picks any option and finishes that branch, the story moves on past the CHOICE. No going back to try other options. Should be used for cases where exploring multiple choices does not make sense.

VILLAIN
(Requires Villain to be cornered.)
Make your choice, hero! Surrender or fight!

CHOICE
    Surrender.
        You lower your weapon.
        The villain smirks victoriously.

    Fight.
        You ready your stance.
        The final battle begins!

Important Notes on Choices:

Options: The actual choices presented to the player are the child blocks indented directly under the EXPLORE or CHOICE keyword.
Visibility: A choice option (an indented Narrative Block) will only be shown if its own (Condition) is met.

Scenes and Cuts

Sometimes you need to structure larger narratives or reuse sections. Scene headers are not expected to be used as a child of another block.

SCENE: Scene Name (The Label): Marks a specific point in your script with a unique name (e.g., SCENE: The Old Library, INT. CASTLE THRONE ROOM - DAY). Acts like a bookmark you can jump to.
CUT TO: Scene Name (The Jump): Immediately sends the player to the specified SCENE block. Useful for moving between locations or skipping sections based on logic.
CUT BACK (The Return): Sends the player back to *right after* the CUT TO that brought them to the current scene block. Essential for making reusable scenes. Put CUT BACK at the end of the reusable scene.

SCENE: Check notes.
You fish out a thick folio with notes.

EXPLORE
    Check train timetable.
        ...timetable exploration...

    Look again at the photos from museum.
        ...looking at the photos from museum...

    Nothing catches my eye right now.
        CONCLUDE

CUT BACK

# Somewhere else in the script:
PROTAGONIST
Maybe I should check my notes.

CHOICE
    Check notes.
        CUT TO: Check notes.
        # <--- CUT BACK returns here

    No, I have everything in my head.

PROTAGONIST
Okay, done checking. Now, where was I...

`END` Block

Quite obviously, every story or game eventually has to end. Use the END block to denote that.

Intention and Style

As you can see, structuring the narrative game doesn't require many complex tools. The key principle is clarity and unambiguity. The script's structure and logic should be readily understandable by another person reading it for the first time, just as it needs to be clear for the system processing it.