tweego/docs/core/twee-notation.md

Twee Notation

In Twee and Twine, stories are arranged into units called passages. Each passage has a name, optional attributes, and content.

There are two official Twee notations, Twee v3 and Twee v1, and an unofficial Twee2 notation.

• Twee v3 is the current official notation—see the twee-3-specification.md for more information.
• Twee v1 is the classic/legacy official notation, which is a compatible subset of Twee v3.
• The unofficial Twee2 notation is primarily generated and used by the Twee2 compiler, which is largely abandonware.

By default, Tweego supports compiling from both of the official Twee notations and decompiling to Twee v3. Compiling from the unofficial Twee2 notation is also supported via a compatibility mode, but is not enabled by default. To load files with the Twee2 compatibility mode enabled, either the files must have a Twee2 extension (.tw2, .twee2) or its command line option (--twee2-compat) must be used.

Warning: It is strongly recommended that you do not enable Twee2 compatibility mode unless you absolutely need it.

Twee v3 Notation

In the Twee v3 notation, passages consist of a passage declaration and a following content section.

A passage declaration must be a single line and is composed of the following components (in order):

1. A required start token that must begin the line. It is composed of a double colon (::).
2. A required passage name.
3. An optional tags block that must directly follow the passage name. It is composed of a left square bracket ([), a space separated list of tags, and a right square bracket (]).
4. An optional metadata block that must directly follow either the tag block or, if the tag block is omitted, the passage name. It is composed of an inline JSON chunk containing the optional properties position and size.

The passage content section begins with the very next line and continues until the next passage declaration.

Tip: For the sake of readability, it is recommended that each component within the passage declaration after the start token be preceded by one or more spaces and that, at least, one blank line is added between passages.

Note: You will likely never need to create metadata blocks yourself. When compiling, any missing metadata will be automatically generated for the compiled file. When decompiling, they'll be automatically pulled from the compiled file.

Passage And Tag Name Escaping

To prevent ambiguity during parsing, passage and tag names that include the optional tag or metadata block delimiters ([, ], {, }) must escape them. The escapement mechanism is to prefix the escaped characters with a backslash (\). Further, to avoid ambiguity with the escape character itself, non-escape backslashes must also be escaped via the same mechanism—e.g., foo\bar should be escaped as foo\\bar.

Tip: It is strongly recommended that you simply avoid needing to escape characters by not using the optional tag or metadata block delimiters within passage and tag names.

Tip: For different reasons, it is also strongly recommended that you avoid the use of the link markup separator delimiters (|, ->, <-) within passage and tag names.

Example

Without any passage metadata

Exactly the same as Twee v1, save for the Passage And Tag Name Escaping rules.

:: A passage with no tags
Content of the "A passage with no tags" passage.


:: A tagged passage with three tags [alfa bravo charlie]
Content of the "A tagged passage with three tags" passage.
The three tags are: alfa, bravo, charlie.

With some passage metadata

Mostly likely to come from decompiling Twine 2 or Twine 1 compiled HTML files.

:: A passage with no tags {"position"="860,401"}
Content of the "A passage with no tags" passage.


:: A tagged passage with three tags [alfa bravo charlie] {"position"="860,530"}
Content of the "A tagged passage with three tags" passage.
The three tags are: alfa, bravo, charlie.

Twee v1 Notation

Warning: Except in instances where you plan to interoperate with Twine 1, it is strongly recommended that you do not create new files using the Twee v1 notation. You should prefer the Twee v3 notation instead.

Twee v1 notation is a subset of Twee v3 that lacks support for both the optional metadata block within passage declarations and passage and tag name escaping.

Example

:: A passage with no tags
Content of the "A passage with no tags" passage.


:: A tagged passage with three tags [alfa bravo charlie]
Content of the "A tagged passage with three tags" passage.
The three tags are: alfa, bravo, charlie.

Twee2 Notation

Warning: It is strongly recommended that you do not create new files using the unofficial Twee2 notation. You should prefer the Twee v3 notation instead.

The unofficial Twee2 notation is mostly identical to the Twee v1 notation, save that the passage declaration may also include an optional position block that must directly follow either the tag block or, if the tag block is omitted, the passage name.

Example

:: A passage with no tags <860,401>
Content of the "A passage with no tags" passage.


:: A tagged passage with three tags [alfa bravo charlie] <860,530>
Content of the "A tagged passage with three tags" passage.
The three tags are: alfa, bravo, charlie.