A Guide to Checking and Fixing an MSTS .REF file
by Yuri Sos


The REF file is used to list the objects used when creating a route using MSTS Route Editor. It is not required when running a route, but is essential if you wish to create or edit routes using Route Editor.

Unfortunately, it sometimes becomes corrupted, usually caused by the route builder adding references incorrectly. This tutorial walks you through correcting the .REF file using both Route Riter and TsUtils. It is recommended that you install or upgrade to Route_Riter 7.0.43 or higher to make best use of the REF File Editor.

TsUtils, designed by Carl-Heinz Rive, is like having a Swiss Army knife within the Route_Riter Swiss Army knife. The very comprehensive Integrity-Check ("ichk") report has a section that reports any errors within the route's REF file.


The One-Shot Quick-Fix-It-All Function

I normally write tutorials demonstrating a problem followed by the means of solving the problem.

I'm going to break from my normal pattern and suggest that you run this following option as a matter of course before doing anything else. This Route_Riter module is SO good that it will fix 98% of your REF file errors in one pass.

Route developers should run this option from time to time to ensure that they have access to all the shapes they think they have: dropping a bracket is so easy to do. The "quick-fix" method demonstrated here fixes bracket errors, "names-with-spaces-not-enclosed-in-quotes" errors and removes duplicate shape references in one pass

Open Route_Riter.

  1. Select your route (arrow #1).
  2. Click on "Confirm Route" (arrow #2).
  3. Click on the route's REF file (arrow #3).
  4. Click on the REF File Editor button (arrow #4).

  5. Route_Riter will then check all the shapes in the Shapes folder and compare them to the REF file. The REF file is then presented in an Excel-like spreadsheet format. It doesn't display the four standard items - DYNTRACK, PLATFORM, SIDING, CARSPAWNER: Route_Riter will add these definitions to the top of any REF file automatically on saving. Route_Riter also saves the original REF file as a backup in case you've made an error.

    The quick-fix method is to

    1. click "Delete Duplicates" (arrow #1); Route_Riter will ask you to confirm (some route developers have the same shape file in two separate classes for ease of use);
    2. re-index .REF file (arrow #2); then
    3. click "Save New REF" (arrow #3).

This has taken care of over 98% of REF file errors. If you want to / have to read on, TsUtils will now help you to correct any REF file errors that are left.


Getting Started With TsUtils

Read Understanding the TsUtils Integrity-Check Report File: the Getting Started section shows you how to generate the report we are going to use.

Once you've generated the report, scroll past the thousands of Missing Shapes messages until you come to the .REF file section. If there's no error, you will get a one-line message that the .REF file has been loaded and checked - like this.

Commonly, though TsUtils will return a variety of errors. We propose to run through these errors and give you hints on their correction.


Error Correction Part 1: The Most Common Error - The Missing Bracket

Typically and most commonly, the errors that are found within the REF file are related to missing brackets and missing or erroneous parameters. You need to find and correct this error as shapes referenced below the missing bracket cannot be accessed in Route Editor. The missing bracket also masks errors further down the REF file.

Let's look at an example - here's a typical REF file report:

If you look at the report, you can see that there is a keyword error: this is usually the giveaway for a missing bracket: note that the number AFTER the keyword STATIC points to the line number in the REF file.

Let's open the REF file in ConTEXT, turn on line numbering (Options | Environment Options | Editor [x] Line Numbers) and jump to the line number in question (Ctrl-G):

It's immediately very clear that the problem with the keyword Static is that the shape reference immediately above is lacking a closing bracket. This is why the ref file is not examined below this error and may account for the subsequent EOF error.

There are two ways to correct this error: insert the closing bracket at line 2654, save the .REF file and run the ichk again: this certainly works but the quick-fix-it-all function described above is better because it corrects a few other errors at the same time.


Error Correction Part 2: A Shape Is Listed In The REF File That Is Not In The Shapes Folder

This one is self-evident: there's no matching shape in the SHAPES directory. Either place the shape's files (.S, .SD into Shapes folder, .ACE(s) into Textures folder) or delete the entry using the Ref File Editor.

This one appears a little trickier at first glance, but it isn't. As there's no filename in the error message it means there is a static shape definition with no shape specified or a blank shape specified, ie the REF File definition will have either omitted the Filename line altogether or have a line such as Filename ( "" ).

Repair by the following method:

  1. In Route File Editor, click on Delete duplicates, then click on Filename column header (arrow #1 below) to sort the REF file entries.
  2. The top static entry/entries will contain a blank for filename (arrow #2).
  3. Select row by clicking on index number. Click Delete Row (arrow#3). Click Re-index REF File. Click Save New REF file.


Error Correction Part 3: some of the rest!

(Section Incomplete - I'm still looking for more examples to demonstrate repair techniques - email me if you have one of interest)

Back to the REF file we looked at before - now we have an error on line 4747 (beyond where the bracket error was - note that this error only appeared after we corrected the bracket error).

Here's the area in ConTEXT.

Remove the invalid "ALIGN" line and after tunning "ichk" again, all errors in this section are cleared - thus the REF file is now correct.


Fine-tuning your REF file (mainly for route developers)

Route developers are a smart lot - they can work it all out from this screenshot.