Named Objects Library

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
(Named Objects Library : How to register the objects type you want to be cached)
(Named Objects Library : How to retrieve the cached objects)
Line 188: Line 188:
 
     }
 
     }
 
   
 
   
 +
=== Named Objects Library : How to request to refresh a Named Object Cache
 +
 +
In order to refresh a named objects cache you will call one of these functions :
 +
 +
public int RefreshNamedObjectsCache(int cacheType, string searchFilter, GameObject postGameObject) ; // refresh cached type with post option
 +
public int RefreshNamedObjectsCache(int cacheType, GameObject postGameObject) ; // refresh cached type with post option
 +
public int RefreshNamedObjectsCache(int cacheType) ; // refresh cached type
 +
 +
where cacheType defines the type of objects to be refreshed
 +
      searchfilter is an optional string to limit the search to only objects whose name are prefixed by searchfilter
 +
      postGameObject is an optional GameObject that will be notified that the cache refresh operation is complete by receiving a message "Noclib","CacheRefreshComplete" from the library
 +
 +
It is not needed to call RefreshNamedObjectsCache(. . .) just after a AddNamedObjectsToCache(. . .) as the AddNamedObjectsToCache processing includes already an implicit RefreshNamedObjectsCache call to initialise the cached data.
 +
 +
It is also possible to check if a cache refresh is complete by calling one of these functions :
 +
 +
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter, int refreshSerialValue, GameObject postGameObject) ;
 +
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter, GameObject postGameObject) ;
 +
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, GameObject postGameObject) ;
 +
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter) ;
 +
public bool IsNamedObjectsCacheRefreshComplete(int cacheType) ;
 +
 +
where cacheType defines the type of objects being refreshed
 +
      searchfilter is an optional string to limit the search to only objects whose name are prefixed by searchfilter
 +
      refreshSerialValue is an integer value identifying the cache refresh operation to check, which has been retuned by the RefreshNamedObjectsCache or AddNamedObjectsToCache request.
 +
      postGameObject is an optional GameObject that will be notified that the cache refresh operation is complete by receiving a message "Noclib","CacheRefreshComplete" from the library
 +
 +
 
   
 
   
 +
  
 
[[Category:Help|Named Objects Library]]
 
[[Category:Help|Named Objects Library]]

Revision as of 15:30, 15 October 2018

Surveyor's Hotkeys
Driver's Hotkeys
Notations
Glossary

Contents

 


Named Objects Library (SP2 and later)

NamedObjectsLib.jpg



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) ;
}

Named Objects Library : How to retrieve the cached objects

Now that we have registered the objects we want to be managed in the cache, the last step is to call the library to retrieve the data currently in the cache

To retrieve the data currently in cache, you will call this function :

public NamedObjectInfo[] GetNamedObjects(int cacheType,string searchFilter) ; // returns named objects cache with filter
public NamedObjectInfo[] GetNamedObjects(int cacheType) ; // returns named objects cache
where cacheType defines the type of objects to be retrieved
      searchfilter is an optional string to limit the search to only objects whose name are prefixed by searchfilter

These calls returns an array of NamedObjectInfo containing all the current data for the target cacheType and searchFilter.

For readers that do not already know NamedObjectInfo class data, NamedObjectInfo class object is a class defined in World.gs that is used to return available data on exisisting objects in a route and session. You will find below its class definition extracted from World.gs :

//=============================================================================
// Name: NamedObjectInfo
// Desc: The result type used by AsyncObjectSearchResult, see below for more.
//=============================================================================
final class NamedObjectInfo
{
  public GameObject   objectRef;          // A reference to the object, if it's loaded
  public GameObjectID objectId;           // The unique ID of the object
  public string       localisedUsername;  // The display name for the object, in the current language
  public string       categoryString;     // The category code string for the object
};

For each object returned, NamedObjectInfo gives you its reference if loaded, its unique GameObjectID, its display name and its category list string for future search.


Take care that reference to the object may be no longer valid if the object has been unloaded since the information was cached, and you should check if the reference is still valid by calling

bool isStillValid = Router.DoesGameObjectStillExist(GameObject obj);

before using the object reference. If the reference is null or is no longer valid, you can retrieve a reference on the object by calling some functions in world.gs using the unique object gameobjectid :

  public native GameObject GetGameObjectByIDIfLoaded(GameObjectID objectID);  will return a GameObject reference if the object is currently loaded and null if it is no longer loaded
  public GameObject SynchronouslyLoadGameObjectByID(GameObjectID objectID) ; will load the gameobject and return the new gameobject reference. This primitive can only be called under a thread


for example, if you want to loop on all existing interlocking towers, you will use the following code :

. . .
NameObjectInfo[] itInfos = nochelper.GetNamedObjects(nochelper.NOC_ITS) ;
if (itInfos.size())
  for (I=0;i<itInfos.size();I++)
    {
       . . .
       processing to be done on each itInfos
       . . .
    }

=== Named Objects Library : How to request to refresh a Named Object Cache

In order to refresh a named objects cache you will call one of these functions :

public int RefreshNamedObjectsCache(int cacheType, string searchFilter, GameObject postGameObject) ; // refresh cached type with post option
public int RefreshNamedObjectsCache(int cacheType, GameObject postGameObject) ; // refresh cached type with post option
public int RefreshNamedObjectsCache(int cacheType) ; // refresh cached type
where cacheType defines the type of objects to be refreshed
      searchfilter is an optional string to limit the search to only objects whose name are prefixed by searchfilter
      postGameObject is an optional GameObject that will be notified that the cache refresh operation is complete by receiving a message "Noclib","CacheRefreshComplete" from the library

It is not needed to call RefreshNamedObjectsCache(. . .) just after a AddNamedObjectsToCache(. . .) as the AddNamedObjectsToCache processing includes already an implicit RefreshNamedObjectsCache call to initialise the cached data.

It is also possible to check if a cache refresh is complete by calling one of these functions :

public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter, int refreshSerialValue, GameObject postGameObject) ; 
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter, GameObject postGameObject) ;
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, GameObject postGameObject) ;
public bool IsNamedObjectsCacheRefreshComplete(int cacheType, string searchFilter) ;
public bool IsNamedObjectsCacheRefreshComplete(int cacheType) ;
where cacheType defines the type of objects being refreshed
      searchfilter is an optional string to limit the search to only objects whose name are prefixed by searchfilter
      refreshSerialValue is an integer value identifying the cache refresh operation to check, which has been retuned by the RefreshNamedObjectsCache or AddNamedObjectsToCache request.
      postGameObject is an optional GameObject that will be notified that the cache refresh operation is complete by receiving a message "Noclib","CacheRefreshComplete" from the library


Personal tools