Trainz/containers/extensions container

[e]

KINDs (type asset groups)
and containers

The Extensions container is a top-level config.txt file entry available to any Asset which derives from KIND TrainzBaseSpec—in short, all Assets. The purpose of the container is to allow content creator key words which hook together scripted features or inputs so that they can be defined (allocated as variables and initialized for the particular asset instince) without having ContentManager.exe or the DLS uploading software fault and validation testing fail the asset. In short they keep flexible extensibility as part of Trainz, one of it's hallmarks since Trainz (Beta) 0.9 release.

This container is intended to allow third-party developers to introduce custom Asset-keyed data which may be processed by custom scripts.

The extensions container is a list of custom tags or subcontainers with a specific naming convention.

From the standpoint of the average Trainz Owner, exposure to the need for adding this container will be to acceptably Fixing Assets update and fix up older assets off the DLS with software hooks. One of the key features giving Trainz an advantage over the various competing Train Simulators over the years is it's extendability — the ability of Content Creator to extend and enhance the base programs capabilities by adding software it For example, various Trainz extensibility schemes that offer alternative 'traincar liveries' (paint skins)—one series of these developed by TrainzProRoutes is known as 'Chameleon skins'—or instance auto-numbering system on a specific car type's kuid. Older assets on the DLS may not be reconfigured so throw an easily curable fault .

Supported Tags

The naming of top-level tags within the 'Extensions container' is important. Tag names should be meaningful and must end with a hyphen followed by the User ID Number of the content creator who is introducing the extension.

This content creator is solely responsible for determining any rules and restrictions which apply to the tag or subcontainer, and should ideally make an effort to provide this information to other creators via this wiki and the TrainzOnline wiki, with links to pages covering such in the Extension Documentation section below.

While content creators are permitted to make use of each other's extension formats, it is not permissible for a creator to introduce a new extension (or change the meaning of an extension) which exists in a namespace belonging to another content creator.

Each tag in the extensions container may be either a single value, or a subcontainer grouping a variety of data elements. If a subcontainer is used, the contents of the subcontainer should be specified in the extension documentation. No restrictions are placed by N3V Games on the values within a specific extension.

Validation

At the current time, the contents of the Extensions container is not validated. It is expected that future versions of Trainz and the Download Station will perform validation of the extensions container according to the rules described on this page. Furthermore, it is feasible that N3V will formally adopt specific extensions which have entered common use. In this scenario, N3V may choose to introduce asset validation to the extension creator's formal specification or, where such specification is not available, to a formal specification written by N3V derived from the common usage.

Extension Documentation

If you are a third-party content creator who has created a custom extensions according to these specifications, please document your extension on this wiki and link to your extension page here:

Add your entry here.

Extensions container Examples

Locomotive with running numbers

The following lines are taken directly from a Trainz 1.3 era locomotive later updated to or beyond V2.9 (TS09).

Example from a TBV 1.3 Locomotive upgraded to TBV 2.9. Locomotive configs and many other traincars which share 'traincar parts' will specify such parts (beginning with bogeys) by a kuid reference. 
 • Single key-word—value pairs signify either boolean parameters (only 1 or 0 meaning True or False are allowed) 
 • or an integer count= 'Number of fonts', (in this case-meaning font-sub-meshes (really meaning font locations where named attachment points are defined in the mesh) to permit showing a digit) with suffixed identities. 
 • These tell a script asset how many memory locations to reserve (allocate) for this traincar's scripts. The value pair with suffixed keywords assign values or initialize such values.^{[note 1]}

bogeys
{
...
}
enginespec                              <kuid:-1:42004231>
enginesound                             <kuid:-1:42003000>
engine                                  1
fonts                                   4

Prior TBV level parsing will tolerate the running-numbers container directly in the config.txt file.

extensions
{
   running-numbers
   {
     rn-0                                  "# 2004"
     rn-1                                  "# 2005"
     rn-2                                  "# 2006"
     rn-3                                  "# 2007"
   }
}
The script of such engine assets utilizes the labeled 'key-name — value-pairs' in the extension to assign a range of locomotive numbers. In this case, the prototype railroad had only four locomotives of this type which were assigned the numbers listed. Other arrangements to list a range of numbers are common, especially for dynamically numbered freight cars such as hoppers. boxcars, flatcars, etc. of specific types.

Notes, Footnotes & References

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

↑ The fonts themselves are provided as texture files—normally .TGA files, with a mixed color series of digits with suffixes such as a, b, c, d. Assuming the convention of possessing an suffix 'a', which convention ALSO means it can be used as an alphamask, the 'digit-6a.tga' texture doubles for black lettering and alpha masks so would be black lettering on white background. The 'b-suffixed' digit tga files might be in the operating companies road colors, for example Red; this would be used on a side of engine mesh with tall easy to read lettering, should the livery of our example company use such a motif.

Footnotes

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

This reference page is adapted from the TrainzOnline Wiki under the CC-BY-SA 3.0 License. This page will likely include more textual explanations, exposition, history, and/or examples than the source page on the same topic.

The TrainzOnline Wiki is for the most part maintained by the programmers or knowledgeable content creators and may have newer more up-to-date information on the current trainz-build code standards, which have some tendency to change as features are added to the software.

[1] The fonts themselves are provided as texture files—normally .TGA files, with a mixed color series of digits with suffixes such as a, b, c, d. Assuming the convention of possessing an suffix 'a', which convention ALSO means it can be used as an alphamask, the 'digit-6a.tga' texture doubles for black lettering and alpha masks so would be black lettering on white background. The 'b-suffixed' digit tga files might be in the operating companies road colors, for example Red; this would be used on a side of engine mesh with tall easy to read lettering, should the livery of our example company use such a motif.

[note 1]