HowTo/Upgrade obsolete script functions

This page serves as a hub for how to upgrade/replace uses of various obsolete script functions.

Note that this is not a comprehensive list. Trainz has existed for more than two decades and there are dozens of obsolete script functions as a result. This guide aims to cover only the more complex upgrade cases, where the replacement functions may not be immediately obvious, or may be considerably more difficult to use.

GameObject.GetId

Previous Usage

Returns a numeric ID used to identify a GameObject within the script context. This ID is not consistent between Route/Session loads and cannot be used for long term storage.

Reason for Obsoletion

With the advent of Route streaming world objects may now be unloaded/reloaded during gameplay, and these IDs can be reused by different objects. This makes the ID itself unreliable, and uses of it are better served by more modern functions.

Replacement Function

Standard uses of the integer ID can be swapped to using the objects GameObjectID instead. Call GameObject.GetGameObject() to get the ID.

Further Reading

• See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class.
• See HowTo/Upgrade_GameObject.GetId for a practical example of how to replace some common integer ID uses with GameObjectID.

GameObject.GetName

Previous Usage

Returns a string ID used to identify a GameObject within the script context. This ID is automatically generated by Trainz code, using the object type or asset name as a prefix. It can generally be considered constant between runs of the game, and was therefore suitable for long term storage.

Reason for Obsoletion

This script name was often confused for the objects localised (translatable) name, and (despite script comments to the contrary) was never truly guaranteed unique.

Replacement Function

Cases which use of the script name as an ID can be swapped to using the objects GameObjectID instead. Cases which use it for display to the player should instead use the localised name.

Further Reading

• See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class.
• See HowTo/Upgrade_GameObject.GetName() for a practical example of how to replace some common script name uses with GameObjectID or localised name.

Router.GetGameObject

TODO

World.Get*List

TODO

Asset.GetConfigSoup

TODO

Asset.GetStringTable

TODO

TrainzScript.GetAssetList

TODO

TrainzScript.SearchAssets

TODO