Trainz/AM&C/config.txt files

←  Prev  Introductory Trainz, config.txt files ↑   Trainz Asset Maint & Creation  Managing Data, config.txt files  Next  →

Trainz Asset Maintenance and Creation Trainz Annotated Reference Pages

TOC | Beginnings | Fun | AM&C | Creation | InBook Refs | ORP Refs:  • Index • Containers • Kinds • Tags | Appendixes  • Vers

Glossary

HKeys-CM

HKeys-DVR

HKeys-SUR

HKeys-WIN

Mouse use

Notations

For the introductory article on config.txt files, see Trainz/Config.txt files. For the reference information on the topic, see Trainz/references/config.txt file.

Fundamentals

All assets must have a config.txt file to be placed in Trainz, else they aren't an asset. Also called a 'config file' or just a 'config', the config.txt file by any name contains essential information about the asset, most importantly its Kinds = <value> and including its username, kuid number, trainz-build, category-region, category-era, region tags, etcetera (and their <values>) and also some optional but non-essential historical tags (prototype railroad, company), authorship, licensing, and ownership information tags such as creator, organization, contact email, 3rd Party website, etc.—all the 'defines' which allow the asset's folder to be a self-defining AND SELF-DOCUMENTING Trainz compatible asset. Well, except a config change record, or ways to review successive changes.   In the forgoing, several times we encapsulated the label '<value>' to emphasize two important points. ALL data in Trainz is defined and manipulated by a KEYWORD -- LEGAL VALUE relationship. In computer science, the <value> (or Legal Values) are an list constrained by membership in the enumerated data type.
 • For example the type Binary (also often termed 'Boolean') is an enumerated type with just two legal values: { binary: 0, 1 }, which notation *'{'+term+':'+list of values+'}' is read 'the set Binary has the members zero and one'. The list of values, is also known as an enumerated list, in this example of length two, with two permissible values. Anything not on the list, is illegal, and will generate a Trainz Fault, and a related error message, as well as prevent you from committing the asset into the database. The prevention of committing a faulty asset into the database began somewhere in the trainz-build corresponding to their overlap in TBVs (and so capabilities) of TS10 and TS09.

 • Knowing what's-what, and does what, when it's appropriate and when not is the subject —this page is dedicated to removing the mystery from all the 'defines' which a studious glance at the more formal N3V Wiki can leave even a veteran software professional perplexed and daunt or likely even dismay the novice. Let us put you on a firm path to grasping Trainz Basic Knowledge (TBK).

In this page, we are going to get into some of the nuts and bolts of assets, and help you learn easily, what it took some of us years to grasp! What a deal!

 

Some General points on config.txt files

Many of the problems with faulty assets are caused by simple typing, nesting, or spelling mistakes in their config.txt files. A spin-off effect of this type when the nesting of quotes is incorrect, usually because of missing or extra quote-marks. When this is true CM/CMP when opening the file will attempt to fix what it finds and this creates a string or series of bad tag name errors when it attempts to parse the text paragraph as keywords and values. This gives a cascade of faults (loads! 20+), generally inserts whitespace and the resultant text is even more badly quoted—the text looks like Armageddon hit the page for a bit of it. This usually occurs inside the larger blocks of text like license or description. Fortunately, these 'unhelpful assists' can be hand edited in a few moments to be corrected. (This 'blow up auto-fixing' is better action than with TRS2004 and earlier Trainz—everything below such typos used to disappear! Vaporware!)

Using a Search " to check quotation nesting when making any edit to large text fields is a good software practice to avoid this minor trouble and instead have a working repaired asset.

Other faults, particularly after V3.3 are due to changes in the data model definitions and enforcement of what is since V2.8 and is now called the TrainzBaseSpec—which data set always initializes the body of any and all config.txt files and sets up the system of self-defining assets. Based on some of those TBS values, other data is then added to configure the asset, including references to other included asset component files such as images, script files, texture.txt files, and Level of Detail (LOD) *.LM files. The starting point for that self-definition is the role of the TBS and the definition and referencing of all elements in the asset is the role of it's config.txt file. Bottom line, virtually all asset repairs require changes to the config.txt file—and it is a rare error which needs another fix which does not!

The terms Texture file or LOD file are contextually confusable. If the programmer's mention one on the forums, they likely mean a compressed resultant file. If the term is used by a user or content creator, they may mean an image file, or that and the applicable texture.txt file—together the uncompressed forms of the binary .texture files created by CM when committing an asset. This is why the config.txt file references to texture.txt files MUST NOT contain the .txt extension—the data base sees only the .texture files and the filepath reference need refer correctly to it for internal database linking. Similarly, the Mesh references of LM and LOD meshes get combined and compressed. Ø

Tips and Tricks

1. Since the config files are the heart of a self-defining asset, while new to asset fixing and updating, or well after as a good practice, when opening the asset for edit in CM:
   1. Method 1: (SHFT+CTRL+E opens asset then puts you into the folder)
      1. before editing the config file duplicate it using 'Save As'
      2. or first use Windows to make a copy (select, CTRL+C, select the folder, CTRL+V). Use F2 to rename the file Config.org.txt... or leave the name alone with the (copy) inserted in the filename by Windows.
      3. then and only then open the original config file for editing.
   2. Method 2: (Fastest: may depend upon your text editor)
      Open the config.txt file from it's folder, then immediately ALT+Tab ↹ back to the folder.
      1. The config.txt file should still be highlighted (selected) so next press F2 and insert .org or .v2-4, etc. in front of the .txt extension. (Trainz will not tolerate unknown data file types when validating and committing the asset, so only the legal text based file types, .txt extension or .htm, can be used.)
      2. When you're done, ALT+Tab ↹ back to the editor.
          • Notepad++ will complain (notify you) the file is missing, asks if it should retain the file in memory. Say Yes. Windows Notepad won't have noticed it missing. Your editor...???
         
2. A programmer's editor with multiple tabs able to open many files; search and replace in regular expressions, replace in multiple files, and/or ability to compare files is highly recommended. Notepad++, Programmer's Notepad, and Crimson Editor are all available as freeware (and time available, will be covered in this Wikibook) and each has most of these useful features.
    • At the least, Notepad++—which can also search and replace across end of line characters, which is very useful for compounding multiple kuids into a comma separated list (CSV) acceptable to CM will be featured in many a Trainz screenshot.
   
3. Target your Downloading and take small bites! When downloading early on in your Trainz experience, target your download carefully in small groups of assets, no more than a couple of screenfuls.
   1. After the download, view the group in Main View, Copy All, and transfer the CSV list into a spreadsheet like Open Office Calc. You may have to clean up a few cells when there are commas in titles (usernames, but you'll have two columns of sortable data as a log file.
       • Get in the habit of saving as soon as you put data down and tidy it up before leaving the Application. You might loose power or worse forget!
   2. If you keep that as a running log, appending as you go, add in some type data in another column, it makes a handy list for a special selections filter to route build with per the next paragraph.
       • Of course you need not limit such copies to downloaded content, any main view listed item can be highlighted and added!
   3. Copy the kuids only column, take it to Notepad++, and Search from '>' to the next '<kuid' and Replace (SAR) with ">,<kuid" to quickly obtain a CSV with your entire download.
   4. However, note your filter is already showing only those kuids, from the download+show in Main View, so save that in 'Last Download'.
   5. As practice of a useful technique, Add a second kuid search field to the 'in place' filter and separate the two with an AND NOT filter modifier. Apply, and the list should show nothing if you got the whole list!
   6. Since you've saved it, you can now address any faults AND keep the same display order by ANDing it with Faulty, and only the Faulty one's on that list will appear.
       • Other faults not on the list won't—this let's you focus on what's important now, if you got greedy and suddenly have a whole lot of faulty content. Work your way through them by finding the routes+sessions you are most interested in, and use the ANDing technique to just fix the things you need for that goal referencing against a kuid CSV of their 'combined dependencies'.
       • Note: Using A saved filter with AND, AND NOT, and OR can help quite a bit in narrowing down, selectively looking at, or otherwise organizing your asset management tasks.
       • Practice, Practice, Practice--this technique will save you a lot of time once it becomes yours.
       • All filter techniques which eliminate the clutter (not showing content on the DLS is perhaps the most useful) along with Skill in selecting the screening criteria will to hone in your search for what you need or are looking for, all save time.
       • Another useful technique is Inverting your selections... Assume you have thirty assets showing as obsolete in that route you want to try. Highlight the group, RMBh AND select Show asset Versions, the display will show just your highlighted assets and their relatives. Now, RMBh AND select Invert Selections and voila' — all the updates are highlighted and you can drag the lot into the download helper in a block (or... RMBh AND select Download—which will add them for you and start an immediate download!
4. To be continued

 

Text editors

config.txt files are plain text (ASCII) files, though the oldest assets may have line one contain a BOM (Byte Order Mark) Code. They should be edited with a non-formatting program such as Windows Notepad, ConTEXT, Notepad++, Programmer's Notepad, or other non-word processor kind of text editor— many of them also known as programmers editors.

Warning:  The config.txt files must not be edited with a word processor program such as Microsoft's Works, Word, Wordpad, Magic Pencil, or Open Office's Writer—any WYSIWYG editor! Why? They all embed extra non-printing characters in the files as control codes and break the asset making it Faulty!. For an insight and rule on namings, see the ACS Text Format specification section linked.

One such text program is ConTEXT, which provides syntax highlighting when used with Wulf/Wulf9's TPR's syntax file post syntax files. You will need to register at the above link (TrainzProRoutes) to be able to download the syntax files. ConTEXT will also show matching brackets, which is very helpful when troubleshooting, and it should be noted is the text editor N3V Games has mentioned in a few TrainzOnline wiki articles.

Many examples in this book will use the freeware Notepad++ programmers editor with multiple tabs (files handling), search and replace (SAR) in files and across open files, regular expressions (REGEX) searching and SAR processing, SAR across line breaks (newlines or line feeds), and so on. These features go a long way in overcoming dumb output from Content Manager or in fixing faulty content.

example 1A

2014-0417-1 List of 982 DAVESNOW assets crossloaded new TS12 to old F~TS12

Anhaen,<kuid2:95148:10182:1>
AnhaengerLeer,<kuid2:68787:25265:9>
Anhaen 1,<kuid2:95148:10183:1>
Appliances Industry Corp,<kuid:58223:26098>
Arcon Mk V,<kuid:225064:4010965>
ATLS CONTROLLER,<kuid2:76656:500010:8>

Notepad++ can turn the above (or 890 Lines like that) into a CSV KUID list like the following in less than 2 minutes and 30 seconds with practice using REGEX SARS:

example 1B

<kuid2:95148:10182:1>,<kuid2:68787:25265:9>,<kuid2:95148:10183:1>,<kuid:58223:26098>,<kuid:225064:4010965>,<kuid2:76656:500010:8>

example 2

The same CSV can be obtained in 30-60 seconds using a open spreadsheet and a scratch file (CTRL+N in Notepad++. Another Notepad++ TAB can be used to keep a running list of such groups for future filter use.
 • (DO centralize your Trainz document storage place in only one main directory--looking for something months later is Soooo very annoying!)
 • A kuid field can literally hold thousands of CSV kuids, so such bundles have a great deal of value, if saved with a heading. Suggest 'ZZZ-nn' Description of download that will mean something in 9-12 months plus - YYYY-MMDD so a CTRL+F+ZZZ- can navigate save to save up or down!  

Correct Spelling is a precise need

Tag keywords must be spelt correctly, and the correct syntax must be used when specifying the parameters of each tag or container value(s). Since a computer program will be interpreting the contents, precise accuracy is required.

Note some terms will seem oddly spelled to North American English speakers, and others odd to those schooled in societies spawned by the former British Empire. Australian railway culture leaned on both countries for equipment and trainers who imported their respective traditions, so railroading terms have a bit of a mix and so go some of the terms spellings.

 

Curly Braces rules

Curly braces { and } are used to designate the starting and ending points of the contents of those tag pairs of groups of associated data pairs which require multiple lines. These are known as Containers and a special container type, the KIND in large part determines how the data in the config.txt file is processed (and so which errors will happen if specified wrongly.) Every open curly brace must have a corresponding closed curly brace, and ALL 'Open Curly Braces' MUST ALWAYS be prefixed by whitespace (Space or Tab ↹s in other words). Some tags can be nested in which case structures such as { { } } are permitted, with the preceding whitespaces proviso.

 

Kuids and Kuid2s

kuid's must be specified using one of the following formats:

• <kuid:nnnn:nnnn>
• <kuid2:nnnn:nnnn:nn>,(where the number of digits may vary)

note by definition, <kuid:nnnn:nnnn> is defined the same as <kuid2:nnnn:nnnn:0>

A kuid or virtually any specification in the config.txt file that is not text double-quoted already can optionally be enclosed in a pair of double-quotes, for example: "<kuid:nnnn:nnnn>", trainz-build "2.9"

 

Tags, Kinds, and Container Names

Every value in Trainz is part of a data pair — keycode called a tag or references name and data

1. Containers contain multiple definitions, including mixes of data types such as decimals, integers and strings but which are associated with one another.
2. Kinds are containers which are unique to a particular type of asset, whereas a container is a collection of related data elements which is needed by more than one type of KIND.

The following tags are mandatory:

• kind
• kuid
• username
• category-class
• category-era
• category-region

Some Common Errors In config.txt Files

• Mismatched curly braces.
• Any non-spacing character immediately followed by an open curly braces.
• Any non-spacing character immediately followed by an open angle bracket, except in HTML where it is allowed.

For the items in the following table, an error will only occur if the item is used as a keyword. Inside text strings such as descriptions any spelling, spacing and punctuation can be used.

Incorrect	Correct
behaviour	behavior
colour	color
discription	description —Jcitron's favorite dumb mistake
independent	independant (i.e. Aussie-speak! contrary to correct U.S. English spelling)
kuid {	kuid-table {
kuid{	kuid-table {
kuid<kuid:...	kuid <kuid:...
kuid table	kuid-table
kuidtable	kuid-table
for Any hyphenated keywords	keyword-table {
obsolete	obsolete-table {
obsolete{	obsolete-table {
obsolete table	obsolete-table
obsoletetable	obsolete-table
table{	table {
trainz-build "utc"	trainz-build 1.5 trainz-build "1.5"

TRS 2004 and TRS 2006

Special circumstances...

In TRS2004 and earlier versions of Trainz, after editing a config.txt file it is necessary to delete the Cache\world_cache_Dispatcher.chump file, otherwise Trainz will use the old version of the file. This is only required if the config.txt file being modified is in the World\Dispacher\ hierarchy. If you are editing files in the World\Custom\ hierarchy, the .chump file does not need to be deleted.

For TRS2004 users, the Trainz Objectz free third-party utility can be used for scan installed assets for common errors in their config.txt files, and optionally automatically correct some of the errors. This inspired Content Manager's development.

For TRS2006-SP1 and TC users, CMP provides good error-checking but be careful, mess up the brackets and you may find anything following disappears. So making a backup before editing is recommended.

Further PEVtools in the newer releases (ca 2010) are supposed to not work in the TR's, but placing a copy of the batch file the installers place in ..\bin\...\Openwith in more recent releases, allows them to function. Unlike TS09 and above, they cannot be launched from inside CMP. An additional correction may have to be made in some texture.txt files to comment out any 'AlphaHint' line if present using a hack-hack ("//") style line-beginning comment. Once the PM2IM and Images2TGA PEVtools have been run, for older assets, update the [[Trainz/refs/TrainzBaseSpec# trainz-build| trainz-build]] to v2.5 or above and even PEV's Mesh Viewer 2 utility will run properly, and let you explore where textures are applied (useful if one is missing!), take screenshots, etc.)

 

 

 

References

• Trainz printed or pdf file Manuals, applicable version - usually in the ..\extras or ..\extras\manuals folder
• TrainzOnline Wiki Config.txt file page and various other pages
• TrainzOnline Wiki Content Creator's Guide pages (various)
• Various CCG and Auran websites