MSTS Reference Files

MSTS Route Editor reference files (.ref)

A route reference file is the Route Editor's placement catalog. It groups objects for the object-selector dialog and describes what kind of world object to create when an entry is selected. It is not an inventory of objects already placed in the route; those instances are serialized separately in world files.

On this page

• File: Location and structure · Catalog entries
• MSTS types: Object types · Static options
• Behavior: Grouping and placement · Implementation extensions · Validation and preservation

Location and structure

The primary-era authoring note places the file in the route root and says its basename is the route filename specified in the route properties. In other words, the usual relationship is:

ROUTES/<route>/<FileName>.trk
ROUTES/<route>/<FileName>.ref

The file is a Unicode Kuju/SIMISA structured-text file. The recovered note does not show its envelope line. TSRE5 recognizes SIMISA@@@@@@@@@@JINX0r1t______, skips other tokens beginning with SIMIS, and then reads a sequence of object blocks with no enclosing root and no declared count:

*object-entry

object-entry = object-type (
    Class       ( category-name )
    Description ( display-name )
    FileName    ( resource-name )
    *type-specific-record
    *unknown-record
)

The primary note says Class, Description, and FileName are compulsory for the documented object types and that their order within a block is insignificant. This is an authoring rule, not proof of how the original Route Editor handles every omission or duplicate.

The top-level token is semantic data: it selects the kind of object the editor creates. A preservation model must therefore retain the original token rather than reducing every entry to a generic shape reference.

Catalog entries

Record	Meaning in the primary-era note
Class	Name of the object-selector group.
Description	Text displayed beside the selector thumbnail.
FileName	Resource used to create the selected object; its resource kind depends on the top-level type.

The note recommends quoting strings and shows that the three common records may occur in any order. It discourages duplicate descriptions but does not forbid them. Preserve quotes, spelling, case, duplicate descriptions, and record order even when an editor presents normalized values.

Object types

The primary note documents five top-level types:

Type	Route Editor result	FileName target	Additional records
Static	Non-interactive scenery object.	Shape file.	Optional Anim and Shadow.
CollideObject	Static scenery with derailment collision behavior, subject to shape collision data.	Shape file.	No additional field is documented beyond applicable static behavior.
Pickup	Fuel or water pickup object.	Shape file.	PickupType.
LevelCr	Level-crossing object.	Shape file.	None documented.
Hazard	Track-hazard object.	Hazard definition file, not a shape.	None documented here.
Transfer	Terrain transfer.	ACE texture file, not a shape.	None documented.

The note says "5 class types" but subsequently names Static plus five alternatives, producing six serialized type tokens. Preserve this internal inconsistency as a source conflict rather than silently forcing the inventory to five.

PickupType accepts the three values shown by the note:

_FUEL_DIESEL_
_FUEL_COAL_
_FUEL_WATER_

The note's prose omits the trailing underscore in its first two displayed labels but its example uses _FUEL_DIESEL_. Exact accepted spellings and original-editor tolerance need confirmation from observed files or an experiment.

Static options

Static entries may add:

Anim ( )
Shadow ( shadow-type )

Anim requests animation by default; the note says this can be toggled in the Route Editor. Shadow selects one of:

Value	Documented default shadow
ROUND	Circular.
RECT	Squared-off.
DYNAMIC	Cast from the shape.

The note does not establish whether these options are accepted by CollideObject or other types, nor how absent Shadow differs from an explicit no-shadow value. Retain absence as a distinct state.

Grouping and placement

The original Route Editor groups entries by Class in its object selector. According to the primary note, comparison is case-insensitive: the first spelling encountered supplies the displayed group name and later case variants join that group. File order therefore affects presentation even though child order within an entry does not.

Selecting an entry creates a placed object of the top-level type, using the referenced shape, hazard definition, or texture. The resulting location, orientation, identity, and object-specific data belong to a world-file record. The .ref entry is an authoring definition, not a live foreign key: do not assume changing a catalog entry rewrites existing world objects.

Resource resolution must remain owner-aware. Most entries name route shape resources, while Hazard and Transfer deliberately change the target kind. See MSTS names and resource lookup, shape files, and texture files.

Implementation extensions

TSRE5's independent reader accepts any top-level token as the entry type, and recognizes these common children:

Class ( text )
*FileName ( resource-name )
Align ( text )
Description ( text )
SelectionMethod ( SequentialSelection | RandomSelection )
RandomRotX ( minimum maximum )
RandomRotY ( minimum maximum )
RandomRotZ ( minimum maximum )
RandomTranslationX ( minimum maximum )
RandomTranslationY ( minimum maximum )
RandomTranslationZ ( minimum maximum )

These records are implementation evidence, not all established original MSTS vocabulary. TSRE5 retains multiple FileName records. An absent SelectionMethod selects the first; SequentialSelection cycles through the list using an implementation-global counter, and RandomSelection chooses a random element. Unknown selection strings produce no selected filename in that implementation.

TSRE5 names the rotation setters setRandomRotDegX/Y/Z, supporting degrees in its internal contract. Translation values are retained as numeric ranges, but their source unit and original MSTS status remain unconfirmed. If any random-transform record is present, its writer emits all six ranges, filling unparsed axes from initialized zeros; this is a lossy normalization boundary.

The same reader recognizes top-level Include, Skip, and Comment. Its include handling inserts another file into the parser stream, but the source joins the include string to the complete current path rather than visibly taking the containing directory; exact resolution behavior and recursion safety require testing. TSRE5 also loads additional .ref files from an addons directory. Neither behavior is established here as original MSTS behavior.

TSRE5 does not parse the primary note's Anim, Shadow, or PickupType children in Ref.cpp; it skips unknown children. Its writer consequently drops them. This makes that implementation unsuitable for a lossless .ref round trip without a separate raw syntax model.

Validation and preservation

A validator can report:

1. Missing Class, Description, or FileName records under the primary authoring profile.
2. A resource name whose expected target kind is missing in route context.
3. A PickupType, Shadow, or SelectionMethod value outside its known domain, without deleting it.
4. Multiple FileName records without a selection method, or a selection method with fewer than two candidates.
5. A random range whose minimum exceeds its maximum.
6. Duplicate descriptions or class names differing only by case, as presentation diagnostics rather than corruption.
7. Unknown top-level types and child records as unsupported, not invalid by default.

Lossless handling should retain the SIMISA envelope, source encoding, entry order, exact top-level type, child order, duplicate children, raw strings and numeric lexemes, empty versus absent records, comments, skipped blocks, includes, unknown records, and unresolved resource names. Do not replace the catalog with resolved filesystem paths, collapse class spelling variants, select one filename during load, or derive world placements from the catalog alone.

Evidence and open questions

The purpose, route-root naming, count-free block structure, three common fields, selector grouping, six named types, static options, pickup values, and resource-kind distinctions come from the preserved primary-era note How to write a .ref file. Its publisher, author, date, and distribution provenance remain unverified. Independent implementation evidence comes from TSRE5 Ref.cpp, Ref.h, and Route.cpp. No dedicated .ref parser was found in the examined FTS/Open Rails runtime sources.

Still unresolved:

• the exact original .ref envelope and accepted text encodings;
• the source note's five-versus-six type-count conflict;
• original handling of missing, duplicate, or unknown fields and types;
• whether Anim and Shadow apply beyond Static;
• exact Align vocabulary and semantics;
• provenance and original-MSTS status of multiple filenames, selection methods, includes, and random transforms;
• random-translation units and axis conventions;
• exact resource lookup, extension handling, case behavior, and missing-resource response.