Saving and Restoring Data, Using Properties.

Apart from Init() there are several other standard methods which you can include which will be called at the appropriate time by the game. Two of the most important are GetProperties() which is called when Trainz needs to retrieve any useful data which your object might wish to save to the session file, and SetProperties() which is called when your object might want to read or update any data which has been saved by the game.

• SetProperties() is called at the start of a Surveyor or Driver session and whenever the Object Property dialogue is saved. It is also used by the Undo system.
• GetProperties() is called when the Object Property dialogue is opened and when the current session is saved and exited.

To demonstrate this we have a further script:

include "MapObject.gs"

class Tutorial isclass MapObject {

   string Now;
   string Then;

   string GetTime(float GameTime) {
      string result = "Good Afternoon";
      if (GameTime >= 0.25) result = "Good Evening";
      if (GameTime >= 0.5) result = "Good Morning";
      return result;
   }

   public void Init(void) {
      inherited();
      Now = GetTime(World.GetGameTime());
      AddHandler(me,"Reminder","","ReminderHandler");
      PostMessage(me,"Reminder",Now,5.0);
   }

   public void SetProperties(Soup soup) {
      inherited(soup);
      Then = soup.GetNamedTag("last");
   }

   public Soup GetProperties(void) {
      Soup soup = inherited();
      soup.SetNamedTag("last",Now);
      return soup;
   }

   void ReminderHandler(Message msg) {
      if (Then != "") {
         Str.TrimLeft(Then,"Good ");
         Then = "\nLast time we met was in the " + Then;
      }
      Exception("Hello World, " + msg.minor + Then + "\n\n");
   }

};

string Now;
string Then;

• The declaration of Now has been moved from Init() to the body of the script.
• A second declaration, Then has been added in the same place.
• Declaring them here makes them global, meaning that they can be used by any method within the script.

public void SetProperties(Soup soup) {

• This is the standard declaration of SetProperties()
• The method is public, since it needs to be called from outside the current script.
• It requires one parameter of type Soup (a Trainz database), which is supplied by the game.
• This database contains all the data about our object which has previously been saved to disc.

inherited(soup);

• As with Init() the equivalent function in the parent MapObject must be called first.
• The Soup which the game has supplied is passed on to allow the parent to extract any data that it might need.

Then = soup.GetNamedTag("last");

• We need to know whether it was morning, afternoon or evening the last time that the session was saved.
• GetNamedTag("last") retrieves this data from the Soup by specifying the key that will have been used to save it.
• The first time that we place our asset the tag will not contain any data and will return an empty string.

public Soup GetProperties(void) {

• This is the standard declaration of GetProperties
• This is a public function which returns a Soup but requires no parameters.

Soup soup = inherited();

• The equivalent function within the parent MapObject class must be called first.
• A Soup database is declared and the contents of the parent's Soup are assigned to it.

soup.SetNamedTag("last",Now);

• Once the parent has provided its data we need to add our own information to the database.
• We can do this by creating or updating information referenced by the tag name "last", so we set this item to be the current value of Now.

return soup;

• Having added our data we send the modified database back to the game to be written to disk.

ReminderHandler

• This method has been amended to look at the value of the global variable Then which has been retrieved from the session files via the SetProperties() method.
• If the value of Then is not an empty string it is chopped and formatted so that it can be included in our Exception() message.
  

To test this out:

• Modify the script as before.
• Load TRS and start a new map in Surveyor.
• Place a copy of your object, wait for the message which will be the same as before.
• Quit the map making sure to save the Surveyor session.
• Reload and wait for the Exception() message.
• This time it should look like this:
  
  

From now on every time the session is saved and reloaded your object will remember the time of day when it was last saved. Rather than just saving Morning, Afternoon and Evening we could have updated the actual game time throughout the session and used the same mechanism to save the time when the session is closed down. We could also use similar techniques to reset the clock on reloading the session.

You have now used the most important of the standard method calls and learned how to send messages and how to save and retrieve data. Now we can move on to creating an asset and making it do something useful.

Next Tutorial: Setting Up the Asset.