Twine

Table of Contents

Use these instructions to import Twine 2 stories into the Dialogue System.

Importing Twine Stories

Each Twine 2 story will correspond to a Dialogue System conversation. Follow the steps below to import your stories into conversations in a dialogue database.

Export Twine Stories to JSON

To prepare your Twine story for import:

  • Use Harlowe story format syntax. For example, macros should use this form: (set: $torch to "lit")
  • Use Twison story format to publish your story to a JSON text file.

Save each story's Twison output as a JSON-format text file.

To change your story format to Twison, use menu item Story > Details:

Import Twine JSON Into Unity

Once you have prepared your stories in Harlowe story format and exported them using Twison, use these steps to import them into the Dialogue System.

  • In Unity, select Tools → Pixel Crushers → Dialogue System → Import > Twine 2 (Twison). This will open a window similar to the one shown below.

Note: The first time you select this menu item, the Dialogue System will ask if you want to enable Twine import capability. Click Enable. After the Dialogue System has recompiled with Twine import capability enabled, select the menu item again.

  • Assign a dialogue database to the Database field. Use the Dialogue Editor to add any actors that your Twine stories reference.
  • Add each JSON file to the JSON Files list. Select the story's primary actor and conversant from the dropdown menus, and whether pipe characters (|) should split passages into multiple dialogue entry nodes.
  • Click the Import button. This will import the JSON Files into the dialogue database, replacing any existing conversations with the same name if they exist.

Twine Format for the Dialogue System

Actors

By default, passages are imported as dialogue entries assigned to the conversant. Links are imported as entries assigned to the actor.

To specify an actor, include the actor's name at the beginning of the text. Example: "Narrator: And they lived happily ever after."

Links

To link one passage directly to another without an intermediate link entry, enclose the link text in parentheses. Example: [[(Enter Cave)]]

The importer handles these link formats, including any special twineFormatFormatting:

  • [[link]]
  • [[text -> link]]
  • [[link <- text]]

It does not handle links in this format: [[$variable]]

Note: If a link connects to a node whose text is exactly the same as the link in Twine, then in the Dialogue System they'll be treated as the same node instead of duplicating.

Formatting Codes

The importer translates //italic//, ''bold'', italic, and bold to rich text codes.

It does not support strikethrough or ^^superscript^^.

Cutscene Sequences, Conditions, Scripts, and Description

When editing a dialogue entry (Twine passage) in the Dialogue System's Dialogue Editor, the inspector provides Sequence, Conditions, and Script fields. These fields are not present in Twine, of course.

To specify a Sequence for a passage, at the bottom of the passage write "Sequence:" on a line by itself. All lines after "Sequence:" will be interpreted as sequencer commands until the end of the passage text or "Conditions:" or "Script:". Example:

Hello, world!
Sequence:
AudioWait(hello);
AnimatorPlay(wave)

To specify Conditions and/or Script fields, write "Conditions:" and/or "Script:" on lines by themselves, followed by Lua expressions. Example:

Hello, world!
Sequence:
AudioWait(hello);
AnimatorPlay(wave)
Conditions:
Variable["saidHello"] == false
Script:
Variable["saidHello"] = true

By default, Conditions are set to Block when false. To make Conditions passthrough, add "(passthrough)" to the Conditions: line. Example:

Hello, world!
Conditions: (passthrough)
Variable["saidHello"] == false

To specify text for a dialogue entry's Description field, write "Description:" on a line by itself, followed by the description. Example:

Hello, traveller.
Description:
Generic greeting if NPC doesn't have a quest for the player.

Macros

The importer handles (if:) and (set:) macros.

Other macros will currently be imported as a Lua function that reports an error. For example, (current-date:) will be translated to Lua as: UnhandledTwineMacro("(current-date)")

Please contact us (see How to Get Help) if you'd like any additional macros to be supported. Twine support is an ongoing process. Your feedback will help us prioritize which macros to add first.

<< Import & Export