Trainz/AM&C/data model

Trainz Asset Maintenance and Creation Trainz Fundamental Knowledge Base

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

[e ]
KINDs (type asset groups) and containers
KIND Achievement-category  KIND Achievement-group  KIND Activity  KIND Asset-group  KIND Behavior  KIND Bogey  bogeys container  KIND Buildable  class library  KIND Controlset  KIND Consist  KIND Drivercharacter  KIND Drivercommand  KIND Engine [1]  KIND Enginesound  KIND Environment  extensions container, or extensions  KIND Fixedtrack  flowsize container  KIND Gameplaymenu  KIND Groundbrush  KIND Groundtexture  KIND Hornsound  KIND HTML-asset  KIND Industry [2]  KIND Interior  junction-vertices container  KIND Library [3]  kuid-table  KIND Map  KIND Mesh [4]  member-of-groups  mesh-table container  KIND Module  KIND MOCrossing [5]  KIND MOJunction [6]  KIND MOSignal [7]  KIND MOSpeedboard  obsolete-table  privileges  queues container  KIND Pantograph  KIND Product [8]  KIND Product-category [9]  KIND Profile [10]  KIND Region  season-selector container  KIND Scenariobehavior  KIND Scenery[11]  KIND Scenery-Trackside[12]  KIND SceneryWithTrack [13]  script-include-table container (TBS)  KIND Servlet  smoke container  KIND Steam-engine [14]  KIND Texture [15]  KIND Texture-group  thumbnails container, or (TBS)  KIND Track [16]  track-lod-tree container  KIND Tracksound [17]  KIND Traincar [18]  KIND TrainzBaseSpec [19]  KIND Turntable  volume container  KIND Water2

The Trainz Data Model

It is said that if you are going to carry digital bits around, you need a container, a bucket with a handle you can grasp to move it around and do things within its capabilities. In Trainz, written under the Windows operating system that bucket is the data folder or directory, which all Trainz versions turn into a set of folder arranged in a tree hierarchy.
The early Trainz releases established a hierarchy of folders relative to the game root folder path that was relatively rigid. Certain types of assets were mandated to put data in a specific place so the asset would work. The good news is the head of that path wasn't forced (dictated), so instead of hiding the data three or four layers deep in some schema defined by Microsoft, the path could be started in the root of a main hard drive, or on a different hard drive and unlike many software installations the user could and can still give each install's a folder name of her choice in whatever root path she deems appropriate.

Configs, Trainz Utility Managers

In all Trainz releases, the boss in an asset folder is the asset's config.txt file. In that file, each line (sic) contains data pairs, a 'keyword' and a paired 'value'. Legally formatted tags (keywords) and container names begin in the left margin. Within a container, which is set off by paired curly braces:

keyword-containername  {
       indented words and container guts
 }

the trailing & matching closing curly-parenthesis needs to balance. CONVENTION has it under the first letter and lined up with the keyword's first letter. Given that some containers can go hundreds of lines, you must wonder how we can still say "each line (sic) contains data pairs, a 'keyword' and a paired 'value'." The answer is both procedural and conceptual; it is procedural and the keyword being a container name passes control to a handler subroutine. These handlers know where to put data associated with the keywords legal to that sort of container, and how to find the next non-white character which is evaluated as tag, value or brace, then repeat as needed until it finds a closing brace which pairs to the brace following the first (opening) curly brace. So long as each keyword, internal brace (Yes, Matilda, there are containers with subcontainers, and containers with a variable number of subcontainers. Thanks for asking!) is whitespace separated, and legal in 'expectable context', all the subcontainers of a large long queues container are still only part of that second criteria—a tags value. In this case, the tag in control, has children who have children, and each line of those is still just one tag, one value. (Just twist your brain around a bit, and pretty soon you'll get used to it. Never you mind that - that there passenger station has over 120 text lines in that subcontainer--in container math, it is a mere single value. <g> Just don't make a typo inside... you're likely to get far more than a single error message, when you do so!)

In the simplest sense, all Trainz data is organized in pairs on a data line of a text file, a keyword which tells software how to process the data which follows it.

Every part of Trainz loadable into the game from the tiny bit of configuration data found in a texture (color & lighting resources) the largest route (layout or map) must have a config.txt file. Trainz milieu is inside computers, so no surprise that those files address and list other files.

1. You probably know, suspect, or have heard Trainz uses various kinds of image files to texture objects. These have varying strengths, capabilities, and size impacts, but are well established types; excluding the newest post-TANE types, 99.99% of the 500,000+ assets downloadable from the DLS rely on combinations of .JPG files, .TGA files, and Windows own .BMP files, nowadays, all common file types. Of these the TGA format, invented for commercial applications in graphics arts and television is likely the least familiar —and was hardest to find graphics editors to process. The great majority of Trainz textures will use .tga files in defining the asset.
   Was because the popularity of digital gaming required the masking/transparency Alpha Channel or layer behind their capabilities to blend with other projected images.
   
2. There are files with 'How-To' apply a texture — these carry the suffix: .texture.txt

All config files may contain 'any' of the keywords and containers whose meaning and legal data types are enumerated in the TBS, except most of those—can be legally skipped depending upon whether the enumerated Kinds requires that tag-value pair, but more since most TBS tags are more for human convenience than the rendering of any module. There are a handful which have paramount importance.

• At a minimum all configs contain an data base asset index/unique identifier:
   • the line pair of kuid--KUID,
   • the KIND line (kind--TBS),
   • and a (external file) reference tag--value pair of one sort or the other.
  

In the given minimal lines case the asset defaults to the original TBV 1.3 asset technology standard, and the extern reference would be the asset-filename tag—a tag obsolescent from TRS2004 on, triggers a warning in the Trainz Classics (TBV 2.7) and one which triggers an error message above V2.9 (TS2009-SP0, fall 2008). This 'old tag elimination' enforcement first arose to prominence in the V2.7/TCC releases, wherein major changes occurred in the list of allowed tags and containers in the engine specs, steam, electric, and diesel.

There are several salient lessons in the preceding paragraph:

1. The Trainz Data Model is a moving target.
2. Exactly what it means at any given era (release) depends on previous practices as modified by new features, keywords, constraints, requirements, or methods added to the previous releases technology and practices.
3. There are quite a few tags which are solely for human convenience, such as author, organization, email, and internationalization data (language translations) we depict as '-XX' variants like 'description-es' or 'username-ru'. These affect sortings, or displayed information so as to make things more convenient to other users, but are not mandatory values.

This is great news for the beginner—it means many config tags and their lines can be ignored. The bad news is that the trick of course is knowing which and why, and which combinations and data arrangements are illegal together. That is the job of the KIND—here we will link kinds when we think it apropriate.

Data arrangement 1999

Learning old data practices is alas, necessary. With any sort of significant experience in acquiring content, there will be occasions when something simply won't be acceptable to the Content Manager of the release. The misnomers regarding the situations commonly found as used in the Trainz community is to call these faults, faulty content, fixing faults, error messages. A more accurate term would be outdated, out of date, updated, modernize(d) and reconfigured. There are a few genuine bad assets on the DLS, but these are vanishing rapidly as the DLS cleanup project whittles down what was once a lengthy list.

• The first rule of Trainz data is there is always a config file.
• The second is all meshes and all relevant texture.txt files referenced by the meshes must be co-located in the same folder or subfolder.

• The texture is two parts, the instructions about it in the texture.txt file, the actual image file(s) the first references explicitly.
• An important rule of thumb if editing an asset: If after running PEVtool Images2TGA on the folder, there are any .texture files still present, run it a second time to be sure, then delete the .texture file(s) before commiting the asset.

In the oldest practices a reference tag always required to generate a mesh in an asset was 'asset-filename' which depending upon the kind value referenced either an image file (textures, both types) or a mesh file (an simple object skeleton). Beyond those two building block types, even a name for the asset was not required. More complex kinds however required more definitions:

1. the fact that Trainz is an international product demanded internationalization abilities, these will be easily recognizable because they all suffix a hyphen and two letter language codes to the base tags 'username', 'description', and
2. objects displayable in the run time menus required images, the standard mimicked practices in the commercial 3ds Max generated modeling world, and incorporated a sub-folder to contain such asset-filename plus
3. various advanced objects required more flexible data connectivity than placing additional meshes in sub-folders.
   1. After the first mesh consumed the asset-filename slot, how were auxiliary meshes to be specified? In point of fact, asset-fileaname was envisioned and implemented as a suffix to several standard subfolders:
      1. main mesh       In traincars, the primary (or organizing) mesh might be visualized as the undercarriage and structural framework. This is rarely visible,

}} but the analogy is sound because all the attachment points organizing the joining into a whole all the parts is in asset's (asset-filename) root folder.

1. 1. 1. _body       folders suffixed with '_body' was designated to hold the primary sub-mesh.
   2. Primary animation consumed one tag name, shadows mesh another. This initial technique will still be commonly seen in plenty by new Trainzers examining rolling stock, where even sub-subfolders are employed to hold sub-submeshes such as doors and hatches which open and close with animations which are decidedly not the primary car anim mesh set.
   3. Similarly, objects which cast shadows had a subfolder for shadow's meshes, most often imaginatively named 'shadow.im'. Hmmmm, creative, these Aussies!

 

KINDs in the model

There is not one single data model for Trainz digital objects, but an extensive series of asset requirements that gradually grew differently for each varied kind of parts-of-models resulting to a set of data with different importance given to intrinsic changes and timings. Consider that the original Trainz 0.9 CDROM 'Beta' release happened during the Y2K run up, when some thought the computer world was about to melt down and thrust the planet into the stone ages once more. Ahem. As funny as that became, it was in those very worrisome days that Auran shipped the Beta version to their collaborators in those many world wide hobby groups for evaluation. In essence, the way that release defined modeled data sets is still much with us today. It has flexed and shed skin cells, had hair cuts, and gotten sunburned on some occasions, but the core... is still stable and recognizable within a few different data structures added to generate even more ease of capability, capacity, or flexibility. Those key improvement features, as well as the driving requests by the Trainz community while maintaining a large degree of backwards compatibility is why many users stay with the products, despite the occasional swearing-at occasion.

Definitions Under-construction

Early Trainz was an experiment in search of finding out whether there was a market niche. Consequently, while the designers and software engineers of the Game Company, Auran felt there would be such a market, no one was sure. In the event, they did due diligence, research, in contacting many railroad hobbyist groups and did a pretty fair job of putting together a specification for modeling requirements inside their proprietary JET I game engine. The evidence supporting this statement is that the controls and options, the way the software functions in the surveyor module have gone through the least evolution since Trainz 1.0 was in the research phase now over twenty years ago.

Obsoleted tags

Most of these tags began in the original Trainz release.

The following 'tag list' are 'de facto' because their 'use-convention' antedate the formal compilation of the above listed TBS tags but not the specification for using them, and indeed, also antedates the coining of the term TrainzBaseSpec (introduced with the TrainzOnline Wiki in 2008-2009), or it's formal definition in the N3V Wiki pages 11:32, 12 May 2009.

Editor's note: These 'TrainzBaseSpec tags' are obsolescent by programmer fiat in some cases with TB V2.7, and in all cases, after TS2009-SP0 and all N3V Games releases after it (despite the utility that many users found in some of them, the time penalties it would impose on the content creators, nor the ability to just ignore those no longer useful in a preprocessing operation) and will generate Faults (error messages) if the asset is opened for edit and partially upgraded by raising the trainz-build tags to V2.9 and greater data models. Conversely, by keeping the TB value sufficiently low, removal of said tags is unnecessary (at least up through TS12). Assets may be upgraded to V2.8 and before locally, and most often made to work, even when given several generations of data model elements improvements, then operate normally. It this way many assets can be made to function with TRS2004 or TRS2006 data modeling, yet be conformable with TS-releases in-processing and rendering. Experience shows an older asset made warning and fault free at trainz-build 2.6 (TRS2006-SP1) will generally work without further change in TS09-TS12. The exception are the programmer gaffs introduced in the parsing of TS09, left uncorrected until TS12 restoring the prior status-quo-ante: Single Track Bridges and tunnels in those versions need a second (and incorrect) parameter for track offsets and track-direction parameters, and the enginespec For example, most pre-TRS era data model assets (v1.0–v2.3) can be made to work in the TS releases simply by adding a mesh-table to replace the ignored former effects of 'asset-filename' as ignored in the TSes. Conversely, often TS-release assets with TBs v2.9 and above can be back-fitted to work with earlier data models by understanding the effects and use of some of these tags, and a little judicious alteration to eliminate texture.txt modifier lines (e.g. AlphaHint needs commented out, etc.) which are not understood by earlier versions.

• asset-name, name, and name-XX — V1.3–v2.8 —found historically in virtually all scenery, spines, and Trackside assets. Asset-name was the primary folder name for the asset in the Trainz 1.x--TRS2004 Trainz era; within such assets today one generally finds the asset-name is also used for that early-Trainz era's data sub-folder's system, giving sub-folder names 'asset-name_art', 'asset-name_body', 'asset-name_shadow' in a traincar asset, and perhaps others in other types.

 

• 'name' and 'name-XX' were early forms of the longer tags username and username-XX, the XX representing ISO two letter suffixes of non-English language translations of the English 'name tag' (or today's 'username' tag); the 'XX' forms as with description-XX being part of 'Localisation' support for other language's user-friendly values.

• Replace with username and username-XX in oldest Trainz era (v1.0-v2.4) assets if present, or delete.

Note: Username (English) is the official asset name on the DLS, and should never be in a foreign language; it also supersedes and replaces 'asset-filename'. Subfolder names by convention will have pathspec names beginning with the username/asset-name field and utilize the suffixes _art, _body, and _shadow as part of the normal naming conventions. This may be a 3ds Max and gmax convention carried over into Trainz, which has historical ties to said graphics development software. (Gmax was bundled with Trainz releases V0.9—v2.4)

 

• category-era-nn — V1.3–v2.8 s.a. {tag: category-era-0, category-era-1, category-era-2, ...} —a former dating system with a numeric suffix—found historically in virtually all date-worthy assets upto Trainz-build 2.4 when the current category-era string array was introduced to combine these onto a single config.txt line. While not directly accessible in Surveyor, after TR06 and CMP, one could define a filter to select a date range and use that filter along with region and type in Surveyor to vett assets that were listable in Surveyor's placement and selection tools. Obsoleted in and after TS09 which uses the shorter category-era string array in a single line instead of using multiple '-nn' suffixed tag-value pairs.

• Whitespace in the string array will cause an error; all values must be suffixed with an 's' and have four digits, s.a. 1880s;1950s;2010s (which might be wholly appropriate for a woman's garment of certain types that go in and out of fashion!). Defining a range is alas, not currently possible, but has been requested by the user community.

• Replace with string-array type category-era tag with no whitespace and semi-colons between date codes; these are given as full four digit decade numbers followed by a 's' (Small Ess) suffix.

 

• types category-region-nn — V1.3–v2.8 —found historically in virtually all locale-worthy assets. These have been superceded by the 'string-array' of two letter enumerated ISO country codes in the category-region tag.

• Replace with string-array type category-region with no whitespace and semi-colons between the two character country codes enumerated in that referenced tag section; these are given as full two uppercase letters comprising enumerated codes followed by a ';' separator between codes, but not at the last before the terminal end-quotes.
• Any whitespace in the string array will cause an read error, and fault message, including space(s) at the end before the trailing quotes.

 

• region —valid part of TBS V1.3–v2.8 as a built-in filter and Map asset custom localization identifier (kuid); now the only legal tag use is in kind map (layout) assets.

 

• See current use of this tag below in Region tags in config.txt files.

As a former filter modifier, the tag is found historically in virtually all older assets, but it was especially prevalent in rolling stock, scenery, spline assets, Track types (including tunnels and bridges) and Trackside assets with a degree of localisation.

• Map assets still retain the keyword Region which was defined in Map configs with a contrary use—to be a kind region kuid reference. Hence, Region is required in Maps, and since TRS2012, like the tag type, illegal in the very large number of assets where it once occurred as data.
• Any region tag to a text string is obsolete after the TRS2009, as in the programmer's mind they replaced the crude filtering group selector of 'type and region' string-values in the Surveyor tools with the Pick List. Both these tags had some benefits and drawbacks and both date back to Trainz 0.9 Beta release.

• type — V1.3–v2.8 —a former filter modifier, and found historically in virtually all assets, but were especially prevalent in rolling stock, scenery, spines, Track types (including tunnels and bridges) and Trackside assets. Type was used in Trainz 0.9—TC3 releases as an in Surveyor filter which combined with region, gave groups of assets instead of being overwhelmed by a whole list of placement tool selections. Both defaulted to 'All' giving the same mega-list as tools do in TS09 and after.

• Every type tag is obsolete after the TRS2006 spinoffs (i.e. TC3), as in the programmer's mind they replaced the crude filtering group selector of 'type and region' in the Surveyor tools with the TS09 Pick List.

Region tags in config.txt files

Region tags, a Surveyor quick sort-by-grouping-tag filter implemented as part of Trainz are no longer acceptable tags in TS2009 and later Trainz versions, outside the kind map assets (where they are still a KUID reference, not a filter). category-region tag, specified by two-letter codes, are still used to aid sorting in CM and Surveyor modules.

The region keyword is now limited to a legal presence in only kind map config files, where they are specified as a kuid to a predefined 'cookbook' region setting various geographic and era specific criteria such as lists of Trainz Carz automatically generated on the roads, the carrate value-dictating the density and frequency of said Trainz Carz generated, the base altitude, latitude, longitude co-ordinates and such regional variables that could be bundled rationally together now; these keywords and the purpose have been stable—in use both historically, and in the newer TS2009-TS2012+TANE data models). One of the quickest ways to give a Route a different feel, is to point to another kind region kuid—the sun angle changes, as does the seasonal look, the cars on the map change and so forth.