Category List

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(Created page with "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, [[Categ...")
 
Line 5: Line 5:
 
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.
 
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.
+
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.
  
 
The following builtin codes are commonly used:
 
The following builtin codes are commonly used:
Line 41: Line 41:
  
 
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.
 
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()

Revision as of 17:37, 16 March 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 identifiers for custom machine-parsing purposes. Custom codes always start with a hash ("#") character, whereas builtin codes never do.

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.

The following builtin codes are commonly used:

  • "TK" - A "track" spline. Shows in the track tab in Surveyor. Train vehicles run on this spline or its child splines.
  • "SPLN" - A "non track" spline. Shows in the object tab in Surveyor. Train vehicles cannot run on this spline.
  • "TUN" - A tunnel spline. This typically runs under ground level and typically creates exit holes in the ground mesh.
  • "BRG" - A bridge spline. This typically runs above ground level and typically has child splines.
  • "AGRP" - A KIND Asset-group asset.
  • "SS" - A KIND Profile asset.
  • "RT" - A KIND Map asset.
  • "SG" - A KIND Savegame asset.
  • "TUT" - A tutorial session.
  • "TO" - A trackside object.
  • "TEND" - A tender vehicle.
  • "LOCO" - A locomotive vehicle.
  • "ROLL" - A rolling stock vehicle.
  • "TV" - A KIND Traincar (train vehicle) asset. Shows in the Train tab in Surveyor.
  • "TR" - A train-vehicle-related asset.
  • "CMP" - A non-placeable component.
  • "ESPC" - A KIND Engine asset.
  • "BOGY" - A KIND Bogey asset.
  • "INTR" - A KIND Interior asset.
  • "PANT" - A KIND Pantograph asset.
  • "HORN" - A KIND Hornsound asset.
  • "ESND" - A KIND Enginesound asset.
  • "REGN" - A KIND Region asset.
  • "RU" - A KIND Behavior (Rule) asset.
  • "DR" - A KIND Drivercharacter asset.
  • "SLIB" - A KIND Library (Script Library) asset.
  • "PROD" - A KIND Product asset.
  • "PRDC" - A KIND Product-category asset.
  • "HT" - A KIND HTML-asset asset.
  • "MESH" - A KIND Mesh or equivalent asset.

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()
Personal tools