HowTo/Read string table or Config text

Revision as of 17:42, 22 May 2023

This page is the continuation of the How To/Upgrade obsolete script functions.

More precisely, it's about the new method to read the config file of an object, and thus its string table or another element of its configtext. Two cases are presented to us : the reading concerns the own string table or configtext of an object (in Trainz, an asset), or we want to read the same thing from an object into another object.

Reading its own string table or configtext.

Begin your script by the mandatory :

 public void Init(Asset asset)
 {
   inherited(asset);
 }  

This method gets the asset subject of this script as a parameter. This guarantees that the config file is already available for reading.

Thus, and further on in the script, you only have to introduce :

 StringTable MyStringTable = me.GetAsset().GetStringTableCached();
 or
 Soup MyConfigSoup = me.GetAsset().GetConfigSoupCached()

Note that the function GetStringTableCached replaces the obsolete GetStringTable. The same with GetConfigSoupCached.

Here is a basic exemple.

Assume we have an object whith this string-table :

 String-table
 {
  string0     "Hello"
 }

The following script will result in throwing a exception message : 'Extract = Hello'.

   include "MapObject.gs"
             
   class MyObject isclass MapObject
   {
   void ReadStringTable (void);
  
   public void Init(Asset asset)
   {
   inherited(asset);
   ReadStringTable();
   }
                   
   void ReadStringTable (void)
   {
   StringTable MyStringTable = me.GetAsset().GetStringTableCached();
   string ExtractFromStringTable = MyStringTable.GetString("string0");
   Exception("Extract = "+ExtractFromStringTable);
   }
   };

Reading the string table or configtext of another object

This time, the config file of the second object is not directly accessible. We have to introduce an additional step.

After the mandatory 'Init (Asset asset)....', we have to launch an asynchronous query to cache the config file of the second object. But don't worry, it's finally quite simple.

Here are the codes to implement :

  Asyncqueryhelper asyncqueryhelper = SecondObject.GetAsset().CacheConfigSoup();                      //Starts a query to cache the config file of the second object
  asyncqueryhelper.SynchronouslyWaitForResults("AsyncResult");                                        //Waits for the query to be completed
  string ExtractFromStringTable=SecondObject.GetAsset().GetStringTableCached().GetString("string0");  //Reads a string 'string0' into the string table of the second object

To note :

- 'SynchronouslyWaitForResults' function is usable only by script 'thread' functions

- the first object has to 'know' the second object as an asset (refer to HowTo/Search_for_objects_in_the_world in this wiki)

Here an exemple of implementation, with a loco that needs to read the config file of the cars of its train.

 include "locomotive.gs"
   
 class MyScript isclass Locomotive
 {
  thread void ReadConfigFile(void);
     
  public void Init (void)                                                           //Note that here we don't need to use the formula "Asset asset'. A simple a 'void' will be enough, since we don't need 
  {                                                                                 //to guarantee an access to the configfile of our object : we will read the configfile of another object.
  inherited();
  ReadConfigFile();
  }
    
  thread void ReadConfigFile(void)
  {
  Train mytrain = me.GetMyTrain();                                                  //Gets the train to which the loco belongs
  Vehicle[]vehicles = mytrain.GetVehicles();                                        //Makes up a list of the cars in this train, including the loco
  int i;                                                                              
  for(i=1; i<vehicles.size();i++)                                                   //Inspects each car of the train vehicle[0], vehicle[1],....vehicle[i]
     {                                                                              //We assume that the loco is in front of train (i=0) ; so the first car should correspond to the i=1 vehicle.
     Asyncqueryhelper asyncqueryhelper = vehicle[i].GetAsset().CacheConfigSoup();   //Starts a query to cache the config file of the car[i] 
     asyncqueryhelper.SynchronouslyWaitForResults("AsyncResult");                   //Waits for the result (infinitesimal on a human scale)
     StringTable stringTable = vehicles[i].GetAsset().GetStringTableCached();       //Gets the cached string-table of the car[i]
     string Coupling = stringTable.GetString("coupler");                            //In that string-table, read the line 'coupler' to get the associated string (e.g. 'animated' or 'not animated')
     }
  }
  };