Category List

From TrainzOnline
Revision as of 16:38, 3 April 2017 by Pw3r (Talk | contribs)

Jump to: navigation, search

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:


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