twine-1-twsoutput.md

Twine 1 TWS (Archive) Output Documentation (v1.0)

Note: This is historical documentation on a version of Twine no longer maintained. It is provided to help current and future developers understand and potentially parse files created with Twine 1 or compatible Twee compilers.

In Twine 1, the archive TWS format was generated from byte-stream Python "pickle" serialization in Python 2. Story metadata and passages are encoded as properties of a single Python object.

Note: Although there is no formal specification of the pickle serialization, there are multiple protocols (versions) documented. For specific information on each protocol, consult PEP 307, PEP 3154, and PEP 574. It is strongly recommended to use an existing library or software tool to process the byte-stream rather than attempt to process binary data directly.

For greater human readability, this documentation will translate pickle byte-stream formatting into JSON-encoding to highlight expected properties and possible values.

Story Properties

Local filepaths for where the last build was saved (if any), buildDestination (string), and current, TWS file, saveDestination (string) are defined first.

Example

{
    "buildDestination": "<filepath>",
    "saveDestination": "<filepath>"
}

Story metadata, metadata (object), may also be found with an optional property, description (string), the description of the story, and an optional property identity (string), the noun describing the work such as "story", "game", etc set by the author.

Note: In TWS files generated by early versions of Twine 1, the metadata object and one or more of its properties may not exist.

Example

"metadata": {
    "description": "",
    "identity": ""
}

The story format chosen by the author will be encoded as the target (string) property:

Example

{
    "target": "sugarcane"
}

Story Panel

The storypanel (object) property contains all passage data as well as data on visual presentation:

• snapping: (boolean) true if passages should snap to visual grid; false otherwise.
• scale: (decimal) scale factor or using two presets:
  • 0: Zoom to fit
  • 1: Zoom 100%

Passage Data

Individual passage data is encoded within an array property named widgets (array).

Each passage object has three properties:

• selected: (boolean) true if the author had the passage selected when the file was saved; false otherwise.
• pos: (array) location of the passage within Twine 1 as an array of X (pos[0]) and Y (pos[1]) positions.
• passage: (object) data of the passage:
  • text: (string) content of the passage.
  • title: (string) title of the passage.
  • modified: (object) Python date structure. (See Date Structure section.)
  • created: (object) Python date structure. (See Date Structure section.)
  • tags: (array) Array of tag values (each a string).

Example

{
"storyPanel": {
        "widgets": 
        [
            {
                "selected": false,
                "pos": [
                    10,
                    10
                ],
                "passage": {
                    "text": "Your story will display this passage first. Edit it by double clicking it.",
                    "title": "Start",
                    "modified": {},
                    "tags": [
                        "tag1",
                        "tag2",
                        "tag3"
                    ],
                    "created": {}
                }
            }
        ],
        "scale": 1,
        "snapping": false
    }
}

Date Structure

In Twine 1, datestamp data is encoded using time.struct_time in Python 2. During parsing in JavaScript, this structure is often converted into a function and, in JSON, is represented as an empty object.

Depending on the conversion library or software tool used to read the data, this may result in an array:

Example

{
    [
        2023,
        9,
        3,
        14,
        38,
        52,
        6,
        246,
        1
    ]
}

In order, the array entries can be mapped back to the attributes of the original Python time structure:

• Year
• Month (range [1, 12])
• Day of Month (range [1, 31])
• Hour (range [0, 23])
• Minute (range [0, 59])
• Second (range [0, 61])
• Day of Week (range [0, 6], Monday is 0)
• Day of Year (range [1, 366])
• Daylight Saving Time Offset (0, 1 or -1)