HowTo/Search for objects in the world

Scripted asset may sometimes wish to search for other objects within the world, either in bulk lists, or for a specific single object. This page is intended to provide an overview of how this is achieved in the latest versions of Trainz. Details about certain legacy search methods and how to update them to modern techniques are also provided, once the initial concepts are introduced.

Object Identification

Scripted objects identified in script using several different methods, many of which have become obsolete as Trainz and the script environment has grown in complexity. As of trainz-build 4.5 (TANE SP2 and later) scripted objects should be identified using their GameObjectID, where present. This ID format has been designed to be future-proof/extensible, should the need arise, and supports various lookup and generic storage functions as per the legacy integer and string based IDs. For more information about legacy ID formats, see here.

The GameObjectID class is defined within GameObjectID.gs, which can be found in the Trainz core script folder (resources/scripts). For the most up to date and accurate usage instructions please see the comments within that file.

Named Object Searches

It is occasionally desirable for scripted assets to be able to search for objects within the world. Most commonly, this is a requirement of session rules, which frequently require a session creator to specify target trains, junctions, signals, etc, in order to perform some gameplay function. Occasionally, placable assets such as industries etc may also require this feature. One such example is the Interlocking Tower asset type, which performs complex management of track blocks using management of user defined signals, junctions and crossings.

As of trainz-build 4.5 (TANE SP2 and later) manual object searches are performed via the World.GetNamedObjectList() function. This function takes both a category list and a partial name, allowing for very specific searches, or quite broad ones. Once called, this function returns an object of type AsyncObjectSearchResult, which is used to monitor for the search completion, and then to retrieve the results. For the most up to date and accurate information on how to use GetNamedObjectList and AsyncObjectSearchResult, please see their script comments. Both are currently defined in World.gs, which can be found in the Trainz core script folder (resources/scripts).

Usage example:

thread void SearchForTrains()
{
  // Start a search for any traincars within the world
  AsyncObjectSearchResult searchObj = World.GetNamedObjectList(AssetCategory.TrainCar, "");
  
  // Sniff for search related messages, and then wait for either completion or failure
  Sniff(searchObj, "ObjectSearch", "", true);
  Message msg;
  wait()
  {
    on "ObjectSearch", "Failure", msg:
      if (msg.src == asyncSearch)
        break;
      continue;
    
    on "ObjectSearch", "AsyncLoadComplete", msg:
      if (msg.src == asyncSearch)
        break;
      continue;
  };
  
  // Check the results
  int errCode = asyncSearch.GetSearchErrorCode();
  if (errCode != AsyncObjectSearchResult.ERROR_NONE)
  {
    // TODO: Add any error handling here, such as waiting and reattempting the
    // search later, showing an error message, throwing script exceptions, etc.
    return;
  }
  
  // Get the search results
  NamedObjectInfo[] results = searchObj.GetResults();
  
  // TODO: Add any processing of the results here
}

Storing References to Specific Objects

As shown in the example above, named object searches return their results as an array of NamedObjectInfo objects. Currently, this class has 4 member variables:

* objectRef - A reference to the object, if it is currently loaded
* objectId - The GameObjectID for the object (see GameObjectID.gs)
* localisedUsername - The localised name of the object, for displaying to the player
* categoryString - A category string, usable to further determine the exact type and features of the object

Any script which wishes to save a reference to specific named object should /always/ do so via the GameObjectID. This is currently the /only/ safe and reliable way to store and later retrieve a specific object. If the object is currently loaded it is of course also safe to access and store a reference to the object itself, but note that Trainz may choose to unload the object at any time (if it is inactive, and sufficiently far enough away from the player, etc). Attempts to use an object which native code has unloaded may result in native call errors. To avoid this scripts should call Router.DoesGameObjectStillExist() before attempting to use any object reference that has been stored for some time.

Unlike the named object itself, a referenced GameObjectID will never be deleted by native code, and may be held by a script indefinitely. It can also be stored directly into a Soup database for storage and retrieval between runs of the game, over a network, etc. For details about saving a GameObjectID into a Soup database please see the comments in Soup.gs, located in the core Trainz script folder (resources/scripts).

In addition to Soup storage, a GameObjectID can be serialised to a string for *temporary* storage. This allows scripts to do thing like store the ID directly in a trainzhttp link, etc (provided it is also appropriately escaped). However, it is crucial to note that the format of this string is *not* guaranteed and may change between versions of the game. As such, no attempt should be made to machine parse it, save it between runs or send it over a network. To convert the string back into a GameObjectID, use Router.SerialiseGameObjectIDFromString().

It is also safe to cache and store the localised display name for an object, but it is important to remember that objects can be renamed, and that this object name may become out of date at any time. As such, scripts which store it should remember to update their cache whenever an opportunity arises (e.g. during any validation steps).

Script Library Lookups

Script library assets are unique within script in that they exist without any visual presence to the end player, and are shared across all scripts that access them. i.e. It is not possible to instantiate multiple instances of the same library asset within a single script context. This makes them extremely useful for managing, organising or communicating between other scripted asset types. For more information about library assets, see the KIND_Library page.

As libraries are added to the world by script, and the not the player or session creator, they require a script accessible function to create and load them. This function is TrainzScriptBase.GetLibrary(). When this function is called the library asset will be immediately loaded and returned by Trainz native code. Once loaded, the library will remain loaded in script, and any future calls to GetLibrary() will return the same instance.

Example usage:

public void Init(Asset asset)
{
  inherited(asset);
  
  // Load our shared library asset
  KUID libraryKuid = asset.LookupKUIDTable("shared-library");
  m_sharedLibrary = World.GetLibrary(libraryKuid);
  
  // Add any library specific init, registration, etc code here
}

Legacy Search Functions

TBD