Named Objects Library

Revision as of 12:58, 15 October 2018

Named Objects Library (SP2 and later)

The Named Objects Library is a library that may be used to manage information about available named objects in the current session. The library can manage cached data for several common objects type, which can be individually asynchronously refreshed in the background using threads inside the library, and can return at any time synchronously the content of any of the managed caches.

Usually, an asset using the Named Objects Library will first load and initialize the library in its init routine, will then register the objects type to be cached in the library (which will immediately start the asynchronous process of collecting the cached data for this object type), and will later use the cached data by calling the library to retrieve the current cached data. The library uses all the new object search API available since Tane SP2 and will automaticly refresh in the background any expired cache data. Under surveyor mode, all cached data are refreshed every 3 seconds to include new added objects edited under surveyor ; under driver mode only consists cached data are refreshed every 3 seconds to ensure that consists emited from portals are added to the cached data.

The present article is for scripters who wants to use the Named Objects Library and details below how to configure an asset to use the Named Objects Library, how to initialise in an asset the library and how to register the objects type you want to cache, and finaly how later to retrieve the current content of a cache for a specific object type.

Named Objects Library : How to use it ?

To use the Named Object Library in any of your assets, you need first to modify its config.txt file to add the Named Objects Library in its kuid table section and in its script include table so that your asset can reference the Named Objects Library to import the Named Object Library API as a static class nochelper contained in nochelper.gs inside the Named Objects Library Asset.

The current Named Objects Library available on DLS is <kuid2:61392:4053:10> but there will be soon a new release 11 <kuid2:61392:4053:11> that will bring supports for track circuit blocks objects.

Your asset config.txt file should include the following sections to be able to load the Named Objects Library API as nochelper static class :

script-include-table
{
   . . . 
   noclib    <kuid:61392:4053>
   . . .
}

and

kuid-table
{
  . . .
  noclib     <kuid2:61392:4053:10>
  . . .
}

with these two modifications in your asset config.txt file, you should now be able to import the noclib API by adding :

import "nochelper.gs"

to your assets script files needing to call the noclib API

Named Objects Library : How to initialise it ?

Now that we have imported the file "nochelper.gs" in your scripts, all other needed steps will be done by calling some API functions defined in the nochelper static class.

First, you need to initialise the library by calling

public void Init(Asset p_asset) ;

this call is mandatory with p_asset being the current asset that will use the library. You can check that the initialisation has been successfull by calling

public bool IsLibraryAvailable(void) ;

that will return true if the library has been initialised and false if it is not the case. These calls are generally made inside your asset init function but can be located else where as long as they are done before any other call to the library.

For example, your asset init function may look like :

public void Init(Asset p_asset)
{
  . . .
  my asset initialisation code
  . . .
  nochelper.Init(p_asset) ;
  if (!nochelper.IsLibraryAvailable())
    {
      . . .
      my asset error code for noclib not available
      . . .
    }
  . . .
}

Named Objects Library : How to register the objects type you want to be cached

Next step is to register the objects type you want to be cached.

The Named Objects Library currently supports 13 objects type that are defined in nochelper static class as integers :

public define int NOC_TRACKMARK = 1 ;		// for trackmarks names
public define int NOC_TRACKMARK_LIST = 2 ;	// for trackmark list names
public define int NOC_TRIGGER = 4 ;		// for triggers
public define int NOC_SIGNAL = 8 ;		// for signals
public define int NOC_JUNCTION = 16 ;		// for junctions
public define int NOC_CROSSING = 32 ;		// for crossings
public define int NOC_TCB = 64 ;		// for track circuit block detector
public define int NOC_ITS = 128 ;		// for interlocking towers
public define int NOC_CONSIST = 512 ;		// for trains or consists
public define int NOC_VEHICLE = 1024 ;		// for vehicles
public define int NOC_INDUSTRY = 4096 ;         // for industries
public define int NOC_STATION = 8192 ;		// for passenger stations
public define int NOC_PORTAL = 16384 ;	        // for portals

and to add or register an object type to be cached by the library, you only need to call one of these functions :

public int AddNamedObjectsTypeToCache(int cacheType, string searchFilter, bool autoupdate, float period, GameObject notifyGameObject) ;		
public int AddNamedObjectsTypeToCache(int cacheType, string searchFilter, bool autoupdate, float period) ;	
public int AddNamedObjectsTypeToCache(int cacheType,GameObject notifyGameObject) ; 													
public int AddNamedObjectsTypeToCache(int cacheType) ;																						

where cacheType defines the type of objects to be cached
      searchfilter is an optional string to limit the search to all objects whose name are prefixed by searchfilter
      autoupdate is now an obsolete bool parameter that will be ignored. autoupdate is always done in surveyor mode every 3 seconds and only for consists in driver mode every 3 seconds.
      notifyGameObject is an optional GameObject reference that will receive a message "Noclib","CacheRefreshComplete" when the cached data will be available (Cf RefreshNamedObjectsCache below)

These calls are generally located also in the Init function of your asset and there is one call for each of the objects type to be cached.

for example, if you want to cache both interlocking towers and consists, you will have in your asset init function :

public void Init(Asset p_asset)
{
  . . .
  my asset initialisation code
  . . .
  nochelper.Init(p_asset) ;
  if (!nochelper.IsLibraryAvailable())
    {
      . . .
      my asset error code for noclib not available
      . . .
    }
  AddNamedObjectsTypeToCache(nochelper.NOC_ITS) ;
  AddNamedObjectsTypeToCache(nochelper.NOC_CONSIST) ;
}