Revision as of 16:38, 3 April 2017

Every Asset known to the Trainz environment has an associated Category List which helps to identify how the asset is used within Trainz. Unlike Category Class, Category Era, and Category Region codes, these category codes are intended purely for machine parsing and are not typically displayed to the user. They do not distinguish between items that a user might see as different (for example: "person", "house", "plant") but rather between items that the game code needs to treat differently (for example: "track", "scenery", "script library"). The category list implementation primarily exists for N3V Games internal reasons, however there are some very specific cases where this information is used externally (such as when writing certain types of script).

An asset's category list is typically determined by the game as the content is being installed, however it is also possible to introduce Custom category identifier for custom machine-parsing purposes. Custom codes always start with a hash ("#") character, whereas builtin codes never do.

Syntax

A category list is formed of a small number of short codes, each separated by a semicolon; for example "TR;CMP;BOGY" is the current internal code for a bogey asset. No other assumptions should be made about the category list - the ordering of the codes may vary, additional codes may be present, and so on. There is no guarantee that a given asset will map to the same set of codes in every version of the game, however in practice the list is fairly stable.

When performing a search operation, the semicolon (";") character effectively acts as a "logical and" operator, hence "TR;CMP" matches "TR;CMP;BOGY" but not "TR;BOGY". The bar character ("|") is used in search terms to act as a low-precedence "logical or" operator, so "TR;CMP;BOGY|TR;CMP;PANT" will match any bogey or pantograph asset. Search queries should typically be qualified to the maximum extent possible; for example "TR;TV" is preferred to "TV" if you wish to indicate a train vehicle. This helps ensure that future additions "fail safe", in the sense that they will not suddenly become "visible" to a script which does not know how to handle them correctly.

Builtin Codes

The following builtin codes are commonly used:

• "ACHC" - A KIND Achievement-Category asset
• "ACHG" - A KIND Achievement-Group asset
• "AGRP" - A KIND Asset-group asset
• "AQUA" - A KIND Water2 asset
• "BOGY" - A KIND Bogey asset
• "BDB" - A KIND Buildable asset
• "BRG" - A bridge spline. This typically runs above ground level and typically has child splines.
• "BRSH" - A KIND Groundbrush asset
• "CMP" - A non-placeable component
• "CN" - A KIND Consist asset
• "CROS" - A KIND MOCrossing asset
• "CS" - A KIND ControlSet asset
• "DR" - A KIND DriverCharacter asset
• "ESND" - A KIND Enginesound asset
• "ESPC" - A KIND Engine asset
• "FIXD" - A KIND FixedTrack asset
• "GRND" - A KIND Groundtexture asset
• "HORN" - A KIND Hornsound asset
• "HT" - A KIND HTML-asset asset
• "IND" - A KIND Industry asset
• "INTR" - A KIND Interior asset
• "IT" - A KIND InterlockingTower asset
• "LOCO" - A locomotive vehicle
• "MESH" - A KIND Mesh or equivalent asset
• "PANT" - A KIND Pantograph asset
• "PRDC" - A KIND Product-category asset
• "PROD" - A KIND Product asset
• "REGN" - A KIND Region asset
• "RLTM" - A KIND Behavior-Template (Session Rule Template) asset
• "ROLL" - A rolling stock vehicle
• "RT" - A KIND Map (Route) asset
• "RU" - A KIND Behavior (Session Rule) asset
• "SCEN" - A KIND Scenery asset
• "SG" - A KIND Savegame asset
• "SLIB" - A KIND Library (Script Library) asset
• "SNDS" - A KIND Soundset asset
• "SPLN" - A "non track" spline. Shows in the object tab in Surveyor. Train vehicles cannot run on this spline.
• "SS" - A KIND Profile (Session) asset
• "SVLT" - A KIND Servlet asset
• "TC" - A KIND TestTrack-Course asset
• "TCB" - A track circuit block related asset such as KIND TrackCircuitDetector or KIND TrackCircuitInsulator
• "TEND" - A tender vehicle
• "TK" - A "track" spline. Shows in the track tab in Surveyor. Train vehicles run on this spline or its child splines.
• "TO" - A trackside object
• "TR" - A train-vehicle-related asset
• "TUN" - A tunnel spline. This typically runs under ground level and typically creates exit holes in the ground mesh.
• "TURN" - A KIND Turntable asset
• "TUT" - A tutorial session
• "TV" - A KIND Traincar (train vehicle) asset. Shows in the Train tab in Surveyor.
• "TX" - A texture asset such as KIND Texture or KIND TextureGroup

Other builtin codes exist, however they are more limited in use and more likely to be replaced in the future. If you have a specific need to use a builtin code that is not listed here, it is recommended that you contact N3V Games with the code(s) and the proposed use-cases so that the usage can be vetted for future compatibility.

Script Functions

The following script APIs utilise category lists:

• class TrainzAssetSearch (via FILTER_CATEGORY)
• class NamedObjectInfo (via categoryString)
• World.GetNamedObjectList()