Trainz/Config.txt files

Config.txt files

edit
This page is a brief laypersons and beginners introduction to Config.txt files—an very important data defining element in Trainz;

Introduction

edit


This is the introduction to Trainz config.txt files, a type of ini file used to track and initialize literally every asset in the Trainz data definition and database system.

Younger readers will likely be less familiar with the INI file concept, but the technology is still in use in modern applications, though much of the setup data once ensconced in ini files is now put into Windows registry entries, and the rest is usually hidden away in a folder not normally accessed by the casual Trainz Windows user.{{efn| A search from the C:\ root for *.ini will find the ini file is still alive and well, even inside the Microsoft Windows C:\Windows (system) folder and its sub-folders. Newer Windows often places user controlled choices for applications into a \Users\User's-LogInName\...\AppData folder in .ini files — and so there is little mystery that Trainz which antedated Windows 2000 and Windows ME releases bridging the Windows NT releases,[note 1] would maintain the technology in use if it serves it well.

Trainz however, cannot take that registry route for there are over 130,000 built-in assets in a typical Trainz release, and some might double that count—before adding in free or payware content from the Download Station or 3rd-party site, and using the registry to record even just added content would quickly swell the windows registry into behaving with glacial slowness, a result contrary to the idea of historic design goals of the registry which was supposed to make Windows application launches faster and increasing reliability (from the Software support folk's point of view) by hiding various things where the average user couldn't get at them and fiddle with settings. (Yes, Nanny-state thinking!)   Overall, with the registry now over a decade old, Window process switching does go much faster and applications trust the registry so have been empowered to incorporate less safeguard testing on self-booting operations.

  Then there is a second issue, Trainz asset ini files are .txt files, and most Trainz ini files are soon missing—their very root folders are temporary in existence and as a file containing a data defines set, they're component files are often compressed into other partially processed, organized and indexed files (see chump files) which the Trainz data base uses in the run-time GUI modules and CM. This processed 'Asset status' is called being committed, meaning the temporary files in a root folder are bundled up and inserted into the Trainz Asset Data Base (TAD) ready for inclusion in a route or session, or further referencing by CM operations such as checking for dependencies or dependent assets.

Assets in brief

edit

So we now have to address an important introductory question:

What the Heck is a Trainz Asset, anyways [note 2]???

Trainz elements, Trainz activities, and anything you want to do, short of uninstalling an Trainz Install, depends on Kuids and Assets. A session you drive, populating a route (map, virtual world) you've access to using with tasks for you to accomplish are setup by programming 'Scriplets' (referencess),, its list of possible messages (HTML or Text Assets), and of course rolling stock — basically every item that can be defined as code, or an element that is a part of the whole of some part of Trainz is an asset. We keep all that straight in Content Manager using Config.txt files uniquely identified by KUIDs, an indexing and inter-relationship identifier that can be used to unite all the diverse and disparate parts of color (textures, or visible skins), meshes (Shapes coated by skins), mesh conglomerates (parts of say a traincar, the wheels, the coupler systems, the trucks or bogeys, the cargo frame and shape [another mesh, possibly a part of a mesh-library asset], all of which are covered by colorfiles and reflection attributes for making an invisible shape seem to have a real form.


So What's a config.txt file?

edit

Each asset (or content item) in Trainz starts in a file folder setup and with each part defined by the content creator. In the early days of trainz for technical reasons, each kind also had a defined folder and sub-folder structure, with some names being constrained, suffixed, or by common convention, traditionally defined in some particular way. Some graphics packages, notably Autodesk's 3ds Max which N3V's developers use and the simpler game focused Gmax sub-set of 3ds Max formerly 'bundled-with-Trainz' liked to use certain sub-folder arrangements and many of these carry over into Trainz folders organization.   Thus, for a traincar asset you will generally see the following sub-folders off its root folder, which by the older standard (pre-TRS2006) will be named by what was once the value of the 'asset-filename' tag (AssetName), and in later data models, is most often the value of the username tag value (Asset_Name):[note 3] The early Trainz data model (structure) was dependent upon 'asset-filename' with the suffixes _art, _body, and _shadow. An asset referenced as Asset_Name (username) with its 'slightly different' asset-filename would define the following folder structure inside the root folder 'Assetname':

  • Assetname\Assetname_art
  • Assetname\Assetname_body
  • Assetname\Assetname_shadow, with its obvious redundancies.

Some other asset type may, especially a scenery asset will have a different folder structure. A simple building with lights ('nightmode') might have a body sub-folder, but likely will instead just have its component files filed in its local root folder, but still have the old-school folder 'night', which contains the different meshes and textures to display the object in the dark. This generates pools of light under streetlights, neon lights of commercial buildings like bars, illuminated windows, clear views of lobby contents in a automobile showroom, and so on.   The key point is this, while the placement file hierarchy and naming conventions are no longer necessary in the era after the inclusion of the mesh-table container and the diminution and eventual elimination of the asset-filename tag, the active content creators will still be leaning heavily on those habitual definitions and the way things were organized by the succession of Content Creator's Guides published with each release up to TRS2009. The TC3 CCG for that reason was put up on the Trainz Wiki by the user community, despite objections of the N3V programing staff, and remains still a great asset to consult when wondering how to fix assets.

The config.txt file is the glue that holds together the parts of a self-defining 3D graphics model defining and giving instructions for how those files and sub-folders fit together as interpreted by the Auran JET 3.0 graphics engine behind the Trainz virtual worlds. It can reference other assets, aliasing their mesh and substitute a different suite of textures changing the railroad livery of a traincar accomplishing a procedure known as reskinning. Both sets of textures are applied to the asset's meshes, but the ones visible and on top are the ones from the asset defined to reskin the other base asset. Config files also glue a complex of assets together; sometimes by incorporating references to a number of meshes directly, and others by referencing a part by its KUID.   This will be clearer by considering common freight cars. Such an asset has meshes defining couplers, brake hoses, trucks (bogeys), wheels, and finally a body. If the body allows a visible load such as a hopper, gondola, flatcar, or well car, the asset definition will likely include animation components for the associated load type(s) which can display the illusion of a draining or filling load level. Two of those types generally take not bulk loads, but discrete loads, such as crates, the product type Auran called 'General Goods'. They can also take odd shapes like farm equipment, building products, scrap. Accommodating each of those within the traincar definitions would be a waste of effort. Instead, each load possible has attachment points creating invisible docking points for a load with a self-defining change of appearance, if need be.   All these pieces need defined and configured to work together. Such attachment points need be oriented the same way as the load types which might 'dock' to it. This magic takes place in the config file of the asset. Many of those pieces list above are generalized and common to many vehicles, so will likely be defined by their own config files, and referred to (referenced) by Kuid. What is required, and how it may be specified and gathered into the whole depends on the asset Kinds.  

Various data elements must be defined in a config file, and others are optional. Such data elements are set forth in the TrainzBaseSpec, a KIND classed data collection which may be or must be defined in each Trainz sub-asset. A sub-asset are parts, wheels, Locomotive Cabs, bogeys (trucks), couplers, track attached to an interactive factory and so forth which might be used by numbers of larger assets. The track in the factory or wheels of a freight car (wagon) being two easy to understand examples.

The Flavor of a Config

edit


The following is a small taste of a config file from an actual locomotive asset engine component file folder. Sounds are parts assets too, and this one connects the sounds (which might be apropos to other locomotives) to the "engine spec" config.txt file which calls this by reference to its KUID "<kuid:32711:100430>" (find below). The engine-spec asset is in it's turn referenced in the locomotive's config.txt file, meaning this asset has both a parent and a grand-parent asset level; and possibly many such associations:

username                                "0-4-0T Sounds"
description                             "0-4-0T sounds"
category-class                          "ZS"
kind                                    "enginesound"
{{TR|T|trainz-build}}                            2.9
author                                  "Ben Neal original author/ updated and reskinned by Dap"
contact-email                           "dawxyz-ha-ha@noway.com"
license                                 "You may not sell this package. You may not claim it as your own.
You may repaint it if you wish, just give bdaneal credit for original mesh and textures.
All items are presented as is, no warranty is included nor implied. I doubt this would 
cause any damage to your computer, but if it does bdaneal and/or Dap may not be held liable. 
The contents of this package are copyright 2008 Ben Neal. Thank you for your cooperation."

{{TR|C|thumbnails}}
{
  0
  {
    image                               "preview.jpg"
    width                               240
    height                              180
  }
}
{{TL|kuid}}                                   <kuid:32711:100430>
kuid-table
{
}

Mandatory tags and containers

edit
Note, this list has been evolving inordinately quickly the past couple of years as Trainz and the MAC computer world interacted. Tags which were optional are now showing up on the TrainzOnline Wiki as being mantatory after trainz-build 3.4, or whatever. Further, the DLS acceptance testing is ahead of Trainz software releases as a rule, so uploaded assets may be bounced back with a requirement such and such a mandatory tag list needs defining.

The assets elements contained between '{' and '}' are inside a 'container' or KINDS

 

* Setting the 'freeintcam' switch parameter in trainzoptions.txt (TR04—TS12) or checking the clickbox with the same function (Freeing Internal Cameras) in TANE and after, changes the function of the keyboard arrows from rotate and tilt functions, to instead slide the camera position forward and back, or side to side. Freeintcam mode enables the user to move many cameras entirely outside the CAB or to a much better advantaged viewing (and mouse-controlling) angle.

Notes, Footnotes & References

edit

Config.txt files are endemic and ever present in Trainz assets, for no asset can be defined without this type of Computer Science container. The keyword-value_of_key pairing must always be kept in mind in editing or creating Trainz content. The TrainzBaseSpec contains values and containers which are most common in asset defining config.txt files.  

Notes

  1. Windows 98 and early Windows NT drastically increased the harddisk space addressable by the Operating System—disk size had hit a ceiling, and the new schema's in Windows NT and the bridge technology in Windows 98 allowed much larger hard disks to be utilized.
  2. Deliberate 's'... native dialect of the Editor. Ask anybody from Western Pennsylvania!
  3. New Trainzers will learn or are reminded that the asset-name tag was made obsolete in TRS2009, and since will generate a fault if present and the asset is given a trainz-build tag value higher than 2.8. which corresponds to the TC3 technology level.

 

Footnotes

 

References