Scheduling SimObject methods

Scheduling allows for an action to occur sometime in the future. In TorqueScript we may have a schedule to trigger a method of an object after a specified amount of time has passed. In this recipe, we will learn how to schedule method of a SimObject instance.

Getting ready

We will be adding a new TorqueScript function to a project based on the Torque 3D Full template and try it out using the Empty Terrain level. If you haven't already, use the Torque Project Manager (Project Manager.exe) to create a new project from the Full template. It will be found under the My Projects directory. Then start up your favorite script editor, such as Torsion, and let's get going!

How to do it...

We are going to write a TorqueScript function that will demonstrate how to schedule a method of a SimObject instance as follows:

1. Open the game/scripts/server/game.cs script file and add the following code to the bottom:

   function scheduleObjectMethod1()
   {
      // Create a new ScriptObject that will have a
      // method scheduled
      new ScriptObject(MyScheduleObject);
      
      // Schedule a method to execute 250ms from now.  This
      // method is found in the MyScheduleObject namespace and
      // takes one parameter: the time the schedule was started.
      // We store the returned event ID in case we want to cancel
      // the schedule before it calls the method.
      MyScheduleObject.eventId = 
         MyScheduleObject.schedule(250, myMethod, getRealTime());
   }
   
   // Our function that will be executed by the object's
   // schedule.
   function MyScheduleObject::myMethod(%this, %startTime)
   {
      // Get the current time
      %currentTime = getRealTime();
      
      // Calculate the time delta
      %delta = %currentTime - %startTime;
      
      // Output to the console
      echo("Event ID " @ %this.eventId @ " sat for " 
           @ %delta @ "ms before it was called");
   }

2. Start up our game under the My Projects directory and load the Empty Terrain level. Open the console using the tilde (~) key and enter the following at the bottom of the screen:

   scheduleObjectMethod1();
   

   In the console we will see the following output:

   ==>scheduleObjectMethod1();
   Event ID 1 sat for 256ms before it was called
   

How it works...

The example code begins by creating a ScriptObject instance with a globally unique name of MyScheduleObject. This name is later used as the namespace for the method that will be scheduled. The example code then schedules the method using the SimObject schedule() method as follows:

   MyScheduleObject.eventId = 
      MyScheduleObject.schedule(250, myMethod, getRealTime());

The schedule() method has the following form:

eventID = SimObject.schedule( time, method, args… );

Here the time parameter is the delay in milliseconds before the method is executed, the method parameter is the name of the method on the SimObject instance to execute, and the args… parameter is actually a variable number of optional arguments that are passed to given method. The eventID value of the scheduled event is returned by schedule(), so that we may cancel the schedule before it is invoked.

The actual time it takes for the scheduled method to execute may be greater than the delay time requested. This can be due to a number of factors, such as current engine load. However, the delay will never be less than the requested time.

There's more...

If the SimObject instance is deleted before the schedule has fired, the schedule will automatically be canceled. It is also possible to manually cancel a schedule by using the cancel() function. This function has the following form:

cancel( eventID ); 

Here the eventID parameter is the value returned by the schedule() method of the SimObject instance.

See also

• Scheduling functions