Return To Contents Page

Introduction to Templates

Torque X uses a template system to create new objects. A "template" is identical to a normal game object, except that a template object cannot be registered with the engine. Instead, one clones the template and registers the template object with the engine.

A Template Example

Suppose you have a game like Tank Buster, where the goal of the player is to blow up fuel tanks. There are going to be a lot of fuel tanks in the game. You need some way of configuring a basic fuel tank object, and then reproducing this object over and over again "cookie-cutter" style. In Torque X, the fuel tank object is configured to be a template. When you want to create a fuel tank, clone the template. The object returned by clone will be identical to the fuel tank template, except that it will not itself be a template. Since it is not a template, it can be registered with the engine. Once you have the cloned object, position it appropriately for your game, and then register it. Now you have a fuel tank, and the original fuel tank template remains available for future cloning. The following code adapted from TankBuster illustrates this process.

T2DSceneObject fuelTankTemplate = TorqueObjectDatabase.Instance.FindObject<T2DSceneObject>("FuelTank");
if (fuelTankTemplate != null)
{
    T2DSceneObject fuelTank = (T2DSceneObject)fuelTankTemplate.Clone();
    fuelTank.Position = new Vector2(50, -20);
    TorqueObjectDatabase.Instance.Register(fuelTank);
}

Note that we check to make sure the template is not null before we try cloning it. This is good practice, because the template may not exist. For example, the FuelTank template in Tank Buster is declared in its levelData.txscene file. This makes it easier for it to be intentionally (or accidentally) removed in TXB. If we did not check for null, the game would terminate when trying to clone the template. Another way to find a template object, which you will see in some places in the built in starter kits, looks like this:

// unsafe way to find a template object
T2DSceneObject fuelTankTemplate = (T2DSceneObject)TorqueObjectDatabase.Instance.FindObject("FuelTank");

This version works, but has the downside that if the template object is found but is not of the correct type for the cast, an exception will be thrown and the game will terminate. For this reason it is advised that you use the parameterized version of FindObject instead when looking up templates (and other objects).

How to Specify a Template

A template is defined the same as a normal object, except that its "IsTemplate" flag is true. Here is a simple, but somewhat pointless, template:

T2DSceneObject myTemplate = new T2DSceneObject();
myTemplate.Position = new Vector2(50, 50);
myTemplate.Name = "Position5050Template";
myTemplate.IsTemplate = true;

An object cloned from this template would have a position set to 50, 50, but it would have no components and all other fields of T2DSceneObject would have their default values. So you'd need a lot more configuration code before you would be able to do anything useful with the clone. The key here though, is that the only thing special about a template in its definition is that IsTemplate is true.

Return To Contents Page