HowTo/Upgrade obsolete script functions
| Line 7: | Line 7: | ||
'''Previous Usage'''<br> | '''Previous Usage'''<br> | ||
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. | 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'''<br> | + | <br>'''Reason for Obsoletion'''<br> |
With the advent of [[Asynchronous_Route_Streaming|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. | With the advent of [[Asynchronous_Route_Streaming|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'''<br> | + | <br>'''Replacement Function'''<br> |
Standard uses of the integer ID can be swapped to using the objects GameObjectID instead. Call GameObject.GetGameObject() to get the ID. | Standard uses of the integer ID can be swapped to using the objects GameObjectID instead. Call GameObject.GetGameObject() to get the ID. | ||
| − | '''Further Reading'''<br> | + | <br>'''Further Reading'''<br> |
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class. | * 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. | * See [[HowTo/Upgrade_GameObject.GetId]] for a practical example of how to replace some common integer ID uses with GameObjectID. | ||
| Line 18: | Line 18: | ||
'''Previous Usage'''<br> | '''Previous Usage'''<br> | ||
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. | 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'''<br> | + | <br>'''Reason for Obsoletion'''<br> |
This script name was often confused for the objects localised (translatable) name, and (despite script comments to the contrary) was never truly guaranteed unique. | 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'''<br> | + | <br>'''Replacement Function'''<br> |
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. | 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'''<br> | + | <br>'''Further Reading'''<br> |
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class. | * 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. | * See [[HowTo/Upgrade_GameObject.GetName()]] for a practical example of how to replace some common script name uses with GameObjectID or localised name. | ||
| Line 29: | Line 29: | ||
'''Previous Usage'''<br> | '''Previous Usage'''<br> | ||
Returns a GameObject instance from either it's script name or integer ID. | Returns a GameObject instance from either it's script name or integer ID. | ||
| − | '''Reason for Obsoletion'''<br> | + | <br>'''Reason for Obsoletion'''<br> |
As both GetId() and GetName() are obsolete, both the string and int variants of this function are also obsolete. See GameObject.GetId and GameObject.GetName above for more information. | As both GetId() and GetName() are obsolete, both the string and int variants of this function are also obsolete. See GameObject.GetId and GameObject.GetName above for more information. | ||
| − | '''Replacement Function'''<br> | + | <br>'''Replacement Function'''<br> |
All uses of the integer ID and script name identifiers should be replaced with GameObjectID. To retrieve an GameObject which is currently loaded into memory, a script may then call Router.GetGameObject(GameObjectID) or World.GetGameObjectByIDIfLoaded(GameObjectID). | All uses of the integer ID and script name identifiers should be replaced with GameObjectID. To retrieve an GameObject which is currently loaded into memory, a script may then call Router.GetGameObject(GameObjectID) or World.GetGameObjectByIDIfLoaded(GameObjectID). | ||
If a script requires access to an object which may not be loaded, it may call World.GetGameObjectByID(GameObjectID) to request that native code loads the object. Note that this requires native code to load the entire tile/section that the object is in, which may impact performance, and may take some time. As the call may take a while, it behaves asynchronously, returning a [[Class_AsyncObjectSearchResult|AsyncObjectSearchResult]] to the caller. | If a script requires access to an object which may not be loaded, it may call World.GetGameObjectByID(GameObjectID) to request that native code loads the object. Note that this requires native code to load the entire tile/section that the object is in, which may impact performance, and may take some time. As the call may take a while, it behaves asynchronously, returning a [[Class_AsyncObjectSearchResult|AsyncObjectSearchResult]] to the caller. | ||
| − | '''Further Reading'''<br> | + | <br>'''Further Reading'''<br> |
* See GameObjectID.gs in your Trainz installations resources/script folder for more information on the GameObjectID class. | * 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 upgrade uses of Router.GetGameObject(string). | * See [[HowTo/Upgrade_GameObject.GetName()]] for a practical example of how to upgrade uses of Router.GetGameObject(string). | ||
Revision as of 12:47, 3 March 2022
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.
Contents |
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
Previous Usage
Returns a GameObject instance from either it's script name or integer ID.
Reason for Obsoletion
As both GetId() and GetName() are obsolete, both the string and int variants of this function are also obsolete. See GameObject.GetId and GameObject.GetName above for more information.
Replacement Function
All uses of the integer ID and script name identifiers should be replaced with GameObjectID. To retrieve an GameObject which is currently loaded into memory, a script may then call Router.GetGameObject(GameObjectID) or World.GetGameObjectByIDIfLoaded(GameObjectID).
If a script requires access to an object which may not be loaded, it may call World.GetGameObjectByID(GameObjectID) to request that native code loads the object. Note that this requires native code to load the entire tile/section that the object is in, which may impact performance, and may take some time. As the call may take a while, it behaves asynchronously, returning a AsyncObjectSearchResult to the caller.
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 upgrade uses of Router.GetGameObject(string).
World.Get*List
TODO
Asset.GetConfigSoup
TODO
Asset.GetStringTable
TODO
TrainzScript.GetAssetList
TODO
TrainzScript.SearchAssets
TODO
