Class GameObject

Latest revision as of 07:17, 11 October 2023

• API Hierarchy
  • GSObject
    • GameObject

• 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.

[edit] AddHandler

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.

[edit] ClearMessages

Parameters

• major = Message major to listen for.
• minor = Message minor to listen for.

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.

[edit] Exception

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.

[edit] GetId

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()

[edit] GetName

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.

[edit] PostMessage

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.

[edit] SendMessage

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.

[edit] Sleep

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!

[edit] Sniff

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.

[edit] 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();
   }
}

[edit] Related Methods

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

[edit] Categories