HowTo/Search for objects in the world

Revision as of 15:40, 6 July 2018

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

TBD

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