Class GameObject

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (→‎Code Examples)
m (→‎GetId)
 
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
*[[TrainzScript Language Reference|API Hierarchy]]
+
*[[TrainzScript Library Reference|API Hierarchy]]
 
**[[Class GSObject|GSObject]]
 
**[[Class GSObject|GSObject]]
 
***GameObject
 
***GameObject
Line 15: Line 15:
 
;Parameters
 
;Parameters
 
*'''target''' = Object to add the message handler to. This is usually ''me'' but can be any ''GameObject''.
 
*'''target''' = Object to add the message handler to. This is usually ''me'' but can be any ''GameObject''.
−
*'''major''' = Message ''major'' to listen for.
+
*'''major''' = [[List of Standard Messages|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.
+
*'''minor''' = [[List of Standard Messages|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)''
 
*'''Handler''' Name of the message handler method to call. This must have a prototype in of the form ''void MessageHandler(Message msg)''
 
;Returned Value
 
;Returned Value
Line 31: Line 31:
 
{{MethodHeader|public native void ClearMessages(string major, string minor)}}
 
{{MethodHeader|public native void ClearMessages(string major, string minor)}}
 
;Parameters
 
;Parameters
−
*'''major''' = Message ''major'' to listen for.
+
*'''major''' = [[List of Standard Messages|Message ''major'']] to listen for.
−
*'''minor''' = Message ''minor'' to listen for.
+
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to listen for.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 63: Line 63:
 
;Notes
 
;Notes
 
*The ID is unique to the current session.
 
*The ID is unique to the current session.
 +
'''This method is now obsolete. Replace GetId() with GetGameObjectID()'''
 
<br>
 
<br>
  
Line 84: Line 85:
 
;Parameters
 
;Parameters
 
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
 
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
−
*'''major''' = Message ''major'' to be sent.  
+
*'''major''' = [[List of Standard Messages|Message ''major'']] to be sent.  
−
*'''minor''' = Message ''minor'' to be sent.
+
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to be sent.
 
*'''seconds''' = Delay in seconds before the message is posted. If this is zero the message will be posted immediately.
 
*'''seconds''' = Delay in seconds before the message is posted. If this is zero the message will be posted immediately.
 
;Returned Value
 
;Returned Value
Line 100: Line 101:
 
;Parameters
 
;Parameters
 
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
 
*'''dest''' = Destination object for the message. If this is null the message will be broadcast.
−
*'''major''' = Message ''major'' to be sent.  
+
*'''major''' = [[List of Standard Messages|Message ''major'']] to be sent.  
−
*'''minor''' = Message ''minor'' to be sent.
+
*'''minor''' = [[List of Standard Messages|Message ''minor'']] to be sent.
 
;Returned Value
 
;Returned Value
 
*None
 
*None
Line 118: Line 119:
 
;Syntax
 
;Syntax
 
  Sleep(10.0);
 
  Sleep(10.0);
−
Sleep(World.Play2DSound(me,"bell.wav"));
 
 
;Notes
 
;Notes
 
*Causes the current thread to pause for the specified period of time.
 
*Causes the current thread to pause for the specified period of time.
−
*Can be used with methods such as World.Play2DSound, which return the period required to carry out a specified action, to cause the thread to delay until that action is complete.
+
*Warning! Sleep(World.PlaySound(...)) should no longer be used, as PlaySound does not return the file duration anymore!
 
<br>
 
<br>
  
Line 128: Line 128:
 
;Parameters
 
;Parameters
 
*'''target''' = Game Object to which the handler will be attached.
 
*'''target''' = Game Object to which the handler will be attached.
−
*'''major''' = Message ''major'' to listen for.
+
*'''major''' = [[List of Standard Messages|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.
+
*'''minor''' = [[List of Standard Messages|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.
 
*'''state''' = Boolean flag to set whether or not the handler is currently active.
 
;Returned Value
 
;Returned Value
Line 153: Line 153:
 
  void SetupHandler(Message msg)
 
  void SetupHandler(Message msg)
 
  {
 
  {
−
     if(msg.major == "Setup" and msg.src == me)
+
     if (msg.src == me)
 
     {
 
     {
 
       MoreSetupTasks();
 
       MoreSetupTasks();

Latest revision as of 07:17, 11 October 2023


  • 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

[edit] 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.


[edit] 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.


[edit] 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.


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

[edit] 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.


[edit] 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.


[edit] 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.


[edit] 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!


[edit] 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.


[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

Retrieved from "https://game.ts2009.com/mediaWiki/index.php?title=Class_GameObject&oldid=39058"
Personal tools