Torque Game Engine Documentation
TGE Version 1.5.2

Simulation

Overview

Introduction

The simulation of objects is handled almost entirely in the game portion of the engine. All simulation object classes are derived from GameBase, which is a subclass of SceneObject. GameBase objects that wish to be notified of the passage of time can be added to one of the two process lists - the global server or global client process list, depending on whether the object is a server object or a client ghost.

All objects in the process list are "ticked" once every 32 milliseconds. The ordering of the objects is determined by the GameBase::processAfter method, which is called if an object must be processed at some time after another object (not necessarily immediately afterward). For example, a player mounted to a vehicle would be set to processAfter the vehicle, so that after the vehicle moved the player's position could be updated to the correct position on the vehicles new position.

Update Interfaces

Game objects are updated in three separate functions, overridden from GameBase: GameBase::processTick(), which takes a single Move structure as an argument (it may be NULL) and advances the object in time by one 32 ms tick, GameBase::interpolateTick(), which interpolates a client object backwards from the end of its current tick to the present time, and GameBase::advanceTime(), which allows a client object to advance animations and effects by the full duration of the time event.

Server side objects are only simulated on even tick boundaries, but client objects, in order to present a smooth view when the frame rate is high, are simulated after each time event. GameBase::processTick is still only invoked on even tick boundaries, but at the end of the time advance, objects are essentially rewound by the time difference to the end of the tick. Also, client objects that need to animate only by the total elapsed time can do so in the GameBase::advanceTime function, which is only called once per time advancement.

Note:: If the control object is sent new object state from the server, it will be advanced by every Move the client has recorded that the server has not yet acknowledged - this is because the server has old data as far as the client is concerned, so the client skips forward through all the new data it knows about.

Simulation Objects

SimBase (engine/console/simBase.*) defines the foundation SimObject classes that form the basis of the simulation engine.

SimObject is the base class for all objects that the console language can create and manipulate. All game classes (Player, InteriorInstance, Terrain, etc.) and GUI classes (GuiCanvas, GuiControl, etc). are all derived from SimObject. SimObject maintains the list of dynamic fields, has name and ID properties, and can register itself with a global object manager, as well as providing several other services.

A SimSet is a simple collection of SimObjects. The set has console methods for adding and removing objects and iterating through the set.

A SimGroup is a derivative of SimSet that "owns" the objects in its collection. When a SimGroup object is destroyed, it destroys all of its members. GuiControl is derived from SimGroup - thus making the GUI a hierarchal set of objects.

SimEvent is a special class objects can use to send time-delayed messages to objects.

SimManager (engine/console/simManager.cc) is a collection of functions for managing all of the objects and events in the simulation.

Objects are collected in a hierarchy of SimGroups and can be searched for by name or by object id.

Persistence and Inspection

Objects in Torque can be saved to a script file using SimObject::save(). This basically dumps the current state of all the object's registered fields and dynamic fields, as well as, in the case of a SimGroup, all of that object's sub objects. GUIs and missions are examples of how the engine's editors save objects.

Objects' fields can also be modified in-game using the inspector, which a GUI window that shows the fields of an object and allows those fields to be changed and saved. Before new field values are to be saved to an object its onPreApply() method will be called, then the fields will be changed, then the object's onPostApply() method will be called.

Useful Console Commands

There are several console commands that are useful to get an idea of what's going on in the system:

trace(true);       // Turns on console trace output, trace(false); to disable it.
tree();            // Displays a graphical hierarchy and object inspector for
                   // all objects currently registered in the system.
object.dump();     // Dumps a list of all console commands and instance variables on an object.
set.listObjects(); // Lists all of the objects in a set.

Container Database

Container maintains a database on both client and server for objects positioned in the simulation. It supports a set of functions for quickly inserting, removing and moving objects in the world (Container::addObject, Container::removeObject, Container::checkBins), as well as query functions for line, box and polyhedron intersection tests (Container::castRay, Container::collideBox, Container::findObjects).