Class GameObject

From TrainzOnline
Jump to: navigation, search


  • GameObject is the base class for any object that requires messaging and threading support.
  • GameObjects are placed in the game's object table, known as the Router.
  • You cannot create a GameObject using new() from a script, all game objects are created by the game.
  • Each game object has a unique ID (see GetId()) and many also have a name.
  • GameObject instances are often referred to as a node because they represent a message node in the Router.


Contents

AddHandler

public native void AddHandler(GameObject target, string major, string minor, string Handler)
Parameters
  • target = Object to add the message handler to. This is usually me but can be any GameObject.
  • major = Message major to listen for.
  • minor = Message minor to listen for. If this paremeter is null or an empty string then all messages that match the major parameter will be sent to the handler.
  • Handler Name of the message handler method to call. This must have a prototype in of the form void MessageHandler(Message msg)
Returned Value
  • None
Syntax
AddHandler(me,"Object","Enter","ObjectHandler");
AddHandler(me,"Object","","ObjectHandler");
Notes
  • Adds a message handler to the current class such that it will be called whenever the target GameObject receives a matching message.
  • Message handlers called by this means are not threaded and will be executed immediately.


ClearMessages

public native void ClearMessages(string major, string minor)
Parameters
Returned Value
  • None
Syntax
ClearMessages("Object","Enter");
Notes
  • Clears any outstanding messages of the specified major and minor types that have been sent via calls to PostMessage() and have not yet been processed.


Exception

public native void Exception(string reason)
Parameters
  • reason = Explanatory text to add to the message box.
Returned Value
  • None
Syntax
Exception("Fatal Error");
Notes
  • Raises an Exception on the current thread and prints out the contents of the reason parameter followed by a stack dump.


GetId

public native int GetId(void)
Parameters
  • None
Returned Value
  • The GameObject ID, an integer value which the Router uses to identify the current object.
Syntax
int ID = GetId();
Notes
  • The ID is unique to the current session.

This method is now obsolete. Replace GetId() with GetGameObjectID()

GetName

public native string GetName(void)
Parameters
  • None
Returned Value
  • The name of the current object if it has one, an empty string otherwise.
Syntax
string MyName = GetName();
Notes
  • The name returned is the text string that is shown at the top of the property object browser for the object concerned.
  • If the name has been assigned by the game this will be the asset's username followed by a serial number.
  • The string returned by this method is not guaranteed to be unique although TRS will issue prompts requesting confirmation in situations where duplication of names is about to occur.
  • The name persists from session to session.


PostMessage

public native void PostMessage(GameObject dest, string major, string minor, float seconds)
Parameters
  • dest = Destination object for the message. If this is null the message will be broadcast.
  • major = Message major to be sent.
  • minor = Message minor to be sent.
  • seconds = Delay in seconds before the message is posted. If this is zero the message will be posted immediately.
Returned Value
  • None
Syntax
PostMessage(me,"Timer","Tick",10.0); 
PostMessage(null,"Browser-URL","live://next",0.0);
Notes
  • Messages sent via this method are processed by the Router in the next game update after they become due.


SendMessage

public native void SendMessage(GameObject dest, string major, string minor)
Parameters
  • dest = Destination object for the message. If this is null the message will be broadcast.
  • major = Message major to be sent.
  • minor = Message minor to be sent.
Returned Value
  • None
Syntax
SendMessage(train,"Object","Enter");
Notes
  • Sends a message to the destination object for immediate processing.


Sleep

public native void Sleep(float seconds)
Parameters
  • seconds = Time to wait in seconds.
Returned Value
  • None
Syntax
Sleep(10.0);
Notes
  • Causes the current thread to pause for the specified period of time.
  • Warning! Sleep(World.PlaySound(...)) should no longer be used, as PlaySound does not return the file duration anymore!


Sniff

public native void Sniff(GameObject target, string major, string minor, bool state)
Parameters
  • target = Game Object to which the handler will be attached.
  • major = Message major to listen for.
  • minor = Message minor to listen for. If this parameter is null or an empty string then all messages matching the major parameter will be processed.
  • state = Boolean flag to set whether or not the handler is currently active.
Returned Value
  • None
Syntax
Sniff(train,"Object","Enter",true);
Notes
  • Attaches a message handler to another object allowing the current script to listen in on the specified messages.
  • Messages of the specified type received by the target object will be copied to the current script.
  • The current script will usually need a separate handler to process these messages and will normally need to check the identity of the message source.


Code Examples

Script calls made during the Init() method of an object can never be certain that other objects within the map have already been initialised. In cases where initialisation depends on the existence of other objects PostMessage() can be used to delay part or all of the startup. Messages sent in this way are never processed until the next game update and this does not occur until all objects have been initialised.

public void Init(void)
{
   inherited();
   SetupTasks();
   AddHandler(me,"Setup","","SetupHandler");
   PostMessage(me,"Setup","",0.0);
}

void SetupHandler(Message msg)
{
   if (msg.src == me)
   {
      MoreSetupTasks();
   }
}


Related Methods

Router.GetGameObject()
Router.PostMessage()
TrainzScript Message Reference

Categories

Personal tools