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 and Searching for Specific Objects

TBD

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