MSTS Kuju Format

Kuju structured file format

The term Kuju format is commonly used for the family of structured files used by Microsoft Train Simulator (MSTS). It is not one file schema. It combines a SIMISA envelope, a token-and-block data model, and text or binary representations. File-specific schemas then define which tokens and values are valid.

For example, path (.pat), route (.trk), track database (.tdb), rolling-stock (.eng and .wag), world (.w), and shape (.s) files can share this serialization machinery while describing entirely different objects.

On this page

• Foundations: Terminology · SIMISA envelope
• Representations: Structured text · Structured binary
• Engineering use: Parser design implications · Known uncertainties · Sources

Terminology

Term	Meaning in this wiki
SIMISA signature	The identifying header at the start of many MSTS files.
Structured Text Format (STF)	The whitespace-delimited, parenthesized text representation.
Structured binary	A binary representation of nested blocks using numeric token identifiers and typed values.
Token	A keyword in text, or its numeric identifier in structured binary.
Schema	The file-specific tokens, field order, types, and relationships.

FTS code uses STFReader for many text files and a Structured Block Reader (SBR) abstraction for data that may be structured text or structured binary.

SIMISA envelope

A typical text file begins with a signature such as:

SIMISA@@@@@@@@@@JINX0P0t______

The characters following JINX identify a content family and representation. Known examples vary by file type, and the final t in common signatures denotes structured text. Signatures must be treated as format identifiers rather than decorative comments.

At the lower-level envelope, FTS distinguishes:

• SIMISA@@: uncompressed content;
• SIMISA@F: compressed content, whose payload is zlib/deflate encoded;
• a text subheader, ending in t;
• a binary subheader, ending in b.

Both single-byte text and UTF-16 little-endian text exist in real content. A UTF-16 byte-order mark may precede the envelope. Readers should detect the encoding and envelope from bytes rather than assume either from the filename extension.

Not every MSTS asset uses STF or structured binary. ACE textures and some terrain-related files have their own binary structures even where they use a SIMISA-style envelope.

Contemporary authoring guidance

The preserved Train Simulator authoring note How to Convert Files to Binary Format adds evidence from the original tool workflow:

• Train Simulator authoring tools normally wrote data files in text form so they could be inspected during development.
• World (.w) and shape (.s) files were candidates for binary distribution because they were loaded progressively and binary files were smaller and faster to load.
• The note recommends retaining text files for editing and archival, then converting distribution copies with the ffeditc command-line utility. It states that ffeditc identifies the file type automatically.
• Conversion input had to be Unicode text in that workflow. World files were already Unicode, while shape files produced by Conv3DS were ASCII and were converted in place with txt2uni before use.

This is evidence for the supplied authoring pipeline, not proof that every producer or every MSTS parser accepted exactly the same encodings. The document is preserved locally and identified in the MSTS research source register; a stable public copy has not yet been verified.

Structured text

STF is a sequence of whitespace-delimited items. Parentheses form nested blocks:

TokenName ( value1 value2 )
Container (
    ChildToken ( 42 )
    NamedChild Label ( "text value" )
)

The exact meaning and expected type of each value comes from the file schema, not from STF itself.

Lexical rules

• Whitespace separates unquoted items.
• ( and ) open and close blocks.
• Quoted strings preserve whitespace; parser implementations also handle escape sequences such as \n, \t, \", and \\.
• Token matching in FTS and Open Rails parsers is generally case-insensitive.
• Numeric values may carry unit suffixes. The accepted suffix and default unit depend on the field being read; see MSTS units and numeric values for the shared interpretation and preservation model.
• A token may be followed by an optional label before its opening parenthesis. This is common in some asset schemas.

Preprocessor-like constructs

Content encountered in practice includes:

• COMMENT and SKIP, followed by an item or block to ignore;
• tokens beginning with # or _, commonly treated as comments or extensions by tolerant readers;
• include ( filename ), which inserts tokens from another file relative to the including file.

These are parsing behaviors, not a guarantee that every MSTS tool accepts every variation. A preservation-oriented parser should retain unrecognized data where possible; a simulator reader may instead warn and skip it.

Counts and blocks

Many schemas place a declared count at the start of a block:

TrackNodes ( 3
    TrackNode ( ... )
    TrackNode ( ... )
    TrackNode ( ... )
)

Real content can contain stale counts, extra records, unknown tokens, and malformed parentheses. FTS and Open Rails frequently parse known child tokens and skip unknown blocks so that recoverable content remains usable. Editors and validators should report these discrepancies rather than silently normalize them without the user's knowledge.

See MSTS references, collections, and graphs for the shared distinction between declared values and actual cardinality, along with ordering, duplicate, index, sentinel, and repair rules.

Structured binary

Structured binary preserves the nested token model but replaces token names with numeric IDs. In the FTS/Open Rails SBR implementation, a binary child block begins with:

Field	Size	Meaning
Token ID	2 bytes	Numeric identifier mapped through the token table.
Flags	2 bytes	Block flags.
Payload length	4 bytes	Number of bytes in the block payload.
Label length	1 byte	Number of UTF-16 code units in the optional label.
Label	variable	UTF-16 label data.
Payload	variable	Schema-defined typed values and nested blocks.

Integers and single-precision floats are read as four-byte values. Strings carry a two-byte character count followed by UTF-16 data. Binary world files use an offset when mapping stored token numbers into the shared token table; therefore, raw token IDs cannot always be interpreted without knowing the content family.

The token vocabulary used by FTS is recorded in TokenID.cs. Its comments identify original sources such as coreids.tok and loadstr.hdr, but also mark IDs inferred from observed files. The table is valuable implementation evidence, not a formal schema for every file type.

Parser design implications

A parser or editor should keep these layers separate:

1. Envelope reader: identifies encoding, compression, and text/binary representation.
2. Block reader: exposes tokens, values, labels, and nested blocks.
3. File schema reader: validates and maps the blocks for .tdb, .trk, .pat, or another type.
4. Domain model: represents the route, track, vehicle, or activity independently of its original serialization.

This separation is visible in FTS: STFReader and SBR handle serialization, classes under Orts.Formats/Msts/Files select a file's root tokens, models under Orts.Formats/Msts/Models parse its records, and import handlers convert the legacy models into FTS models.

Known uncertainties

• The complete origin and specification of every SIMISA signature character is not established here.
• Some numeric token IDs were inferred from files rather than recovered from an original published token list.
• Tolerant behavior in FTS or Open Rails does not prove that the original MSTS tools accepted the same malformed or extended input.
• Text encodings and producer quirks vary across original and community-authored content.

Sources

• How to Convert Files to Binary Format, preserved Train Simulator authoring note: text/binary workflow, Unicode input, txt2uni, ffeditc, and progressively loaded .w/.s files. See the source register for identity and preservation status.
• FTS STFReader.cs: text tokenization, blocks, includes, comments, quoted strings, and units.
• FTS SBR.cs: envelope detection and structured text/binary block readers.
• FTS TokenID.cs: binary token mapping and provenance comments.
• Open Rails units of measure: accepted units and MSTS compatibility notes.

See MSTS content for the wider content map and [[track database (.tdb)|MSTS-Track-Database]] for the first file-specific schema.