DOCSEARCHbyAlgolia
Submit Docs

Tweego Compiler

repository·master·Indexed 41 days ago

https://github.com/tmedwards/tweego

A command-line compiler written in Go for Twine/Twee story formats. It allows developers to compile Twee source files into playable Twine stories, supporting Twee v3, Twee v1, and Twee2 notations. Tweego provides extensive CLI flags for configuring output modes, story formats, and encoding, and supports the TWEEGO_PATH environment variable for managing story format search paths.

Tokens
11K
Snippets
36
Records
59
Agent score
47%

What's inside Tweego

  2. Use the `Start` passage to define the entry point

    master

    By default, Tweego uses a passage named Start as the first normal passage displayed to the player.

    To override this behavior, you can either:

    1. Set the start property within the StoryData passage.
    2. Use the command line option -s NAME or --start=NAME during compilation.

    Note: All special passage names are case-sensitive.

  3. How Tweego searches for story formats

    master

    When executed, Tweego searches for story formats in the following order:

    1. Program directory: The storyformats or .storyformats folders located where the Tweego binary resides.
    2. User's home directory: The storyformats or .storyformats folders in the user's home directory (determined by $HOME or OS defaults).
    3. Current working directory: The storyformats or .storyformats folders in the directory from which you are running Tweego.
    4. Environment variable: Any directories specified in the TWEEGO_PATH variable.

    Legacy Support: Tweego also checks story-formats, storyFormats, and targets during steps 1–3, but it is strongly encouraged to use the standard storyformats or .storyformats names.

  4. Configure project settings with the `StoryData` passage

    master

    The StoryData passage is used to specify basic project settings via a JSON chunk.

    Core Properties (All formats)

    • ifid (string, Required): The project's unique Interactive Fiction IDentifier. If omitted, Tweego will automatically generate one and provide instructions on how to copy it into your chunk.
    • start (string, Optional): The name of the starting passage. Defaults to the Start passage if omitted.

    Twine 2-style Properties

    • format (string, Optional): The name of the story format (e.g., SugarCube, Harlowe, Chapbook, Snowman).
    • format-version (string, Optional): The version of the story format following Semantic Versioning (e.g., 2.30.0). Tweego will attempt to use the greatest version that matches the specified major version.

    Important JSON Rules

    • Property names must be double-quoted.
    • Do not include a trailing comma after the last property.
    • The chunk is a JSON object, not a JavaScript object literal.
    :: StoryData
{
	"ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
	"format": "SugarCube",
	"format-version": "2.30.0",
	"start": "My Starting Passage"
}

  5. Understand Tweego configuration precedence

    master

    Tweego configuration settings follow a cascading hierarchy. If a setting is defined in multiple places, the one lower in this list takes precedence:

    1. Program defaults: The built-in fallback values.
    2. Environment variables: System-level settings.
    3. Story configuration: Settings defined within the story itself (see StoryData documentation).
    4. Command line: Options passed directly when running the Tweego command.

    To begin using Tweego, the only strictly necessary configuration step is ensuring it can find your story formats.

  6. Understand Twee notation versions

    master

    Tweego supports multiple Twee notations used to arrange stories into passages. Passages consist of a name, optional attributes (tags/metadata), and content.

    • Twee v3: The current official notation. It supports tags, metadata (JSON), and name escaping. This is the recommended format for new files.
    • Twee v1: A legacy official notation and a compatible subset of v3. It lacks metadata support and name escaping. Use only for Twine 1 interoperability.
    • Twee2: An unofficial notation used by the largely abandoned Twee2 compiler. It includes an optional position block but lacks v3 features.

    Tweego Compatibility Note: Tweego compiles v3 and v1 by default. To compile unofficial Twee2 files, you must either use the .tw2 or .twee2 file extensions, or use the --twee2-compat CLI flag. It is strongly recommended to avoid Twee2 unless absolutely necessary.

  7. Convert Twee2 files to Twee v3

    master

    You can convert files using the Twee2 notation to the Twee v3 notation using the -d (dump) flag.

    If the source file uses a non-standard extension (like .tw2), use the following syntax: tweego -d -o <output_file.twee> <input_file.tw2>

    If the Twee2 file already uses standard extensions (like .tw or .twee), you must include the --twee2-compat flag to ensure correct processing during conversion.

    # For .tw2 files
tweego -d -o twee_v3_file.twee twee2_file.tw2

# For standard .tw or .twee files using Twee2 notation
tweego --twee2-compat -d -o twee_v3_file.twee twee2_file.twee

  8. Build Tweego from source

    master

    To build Tweego from source, you must have Go (version ≥v1.13) and Git installed on your system. Follow these steps to clone, fetch dependencies, and compile the binary.

    # 1. Clone the repository
git clone https://github.com/tmedwards/tweego.git

# 2. Enter the directory
cd tweego

# 3. Switch to your desired branch (master for stable, develop for development)
git checkout master

# 4. Fetch dependencies
go get

# 5. Compile and install to your GOPATH/bin
go install

  9. Install Tweego via precompiled binaries

    master

    You can download precompiled binaries for multiple operating systems in both 32-bit and 64-bit versions. These are available on the official Tweego website.

    Download from: http://www.motoslave.net/tweego/

  10. Avoid processing unwanted files during compilation

    master

    To prevent Tweego from attempting to compile files that are not source code (such as images or notes), ensure they are located in directories outside of the path passed to the tweego command.

    A recommended directory structure is to keep assets in an images/ directory and source files in a src/ directory, then pass only the src directory to the CLI.

    Example structure:

    project_directory/
	images/
	src/
    tweego -o project.html src

  11. Write passages using Twee v3 notation

    master

    In Twee v3, a passage declaration must be a single line containing these components in order:

    1. Start Token: :: (required).
    2. Passage Name: (required).
    3. Tags Block: [tag1 tag2] (optional). A space-separated list of tags inside square brackets.
    4. Metadata Block: An inline JSON chunk containing optional properties like position and size (optional).

    The passage content begins on the line immediately following the declaration.

    Escaping Rules: If passage or tag names contain delimiters like [, ], {, or }, you must escape them with a backslash (\). To include a literal backslash, escape it as \\.

    Tip: Avoid using delimiters or link markup separators (|, ->, <-) in names to prevent the need for escaping.

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


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

  12. Basic Tweego CLI usage

    master

    Tweego is a command-line tool used to compile Twee source files into HTML or archives, or to decompile HTML/archives back into source code. The basic syntax is:

    tweego [options] sources…

    sources can be individual files or directories. When a directory is provided, Tweego recursively searches it for all supported file types.

    tweego [options] sources…