Version 0.1 – June 13, 2007

This is a very rough guide/outline that I put together for my personal use to help me understand TGBX better and faster – you may or may not find this useful . I don’t claim to have come up with all of this – most, if not all of this material, is derived from:

• TGBX Documentation
• Torque X User’s Guide
• (the often overlooked but very useful) Torque X API.chm
• Microsoft webcasts
• GarageGames forums
• XNA forums

This document assumes knowledge of the contents of the first two sources, and actually depends heavily on them . It’s basically just the Blaster/Microbes tutorials minus specifics. I thought that it might be helpful to lay out the things described there more generally.

I’d love to hear what you think about this document – feel free to leave a comment .

Thank you so much to GarageGames and Microsoft for this amazing product, and to the GarageGames and XNA communities for all the help that you continue to give!

How To Use This Document

Personally, I like everything on one big page, and if there’s anything I need, I just hit Ctrl+F from within Firefox then type in the keyword I’m looking for, then press Ctrl+G as needed. Very primitive, but it works for me .

GUI Matters

First Steps

1. Make a new project using the StarterGame template in Visual C# Express, and build the solution.
2. Start TGBX and load StarterGame.txproj.
3. Save the scene as sceneNameHere.txscene.
4. Materials may be imported simply by dragging images into TGBX.

Setting-up Animated Sprites

1. Click on the Animation check box.
2. Adjust the cell fields as appropriate.
3. Click Create a new Animation.
4. Click Add all frames from the image (green button)
5. Change the Cycle Animation checkbox as appropriate.
6. Adjust the Frames Per Second.
7. Save the animation.

Defining Object Types

1. Make sure that no objects are selected in the scene.
2. Go to the Edit Pane‘s Scene Data tab.
3. Type a name in the Object Types text box, then click the green button to make it register.

Defining Templates

General Directions

1. From the Create pane, drag the material for the template into the scene (may be outside the camera area if you don’t want it to appear immediately at the start of the game).
2. You may manipulate the material as needed using the Edit Pane‘s Scene Object tab.
3. Give the template a name using the Scripting tab of the Edit pane.
4. You may mark the template using one of the object types you have defined.
5. Check the Template box in the Scripting tab.
6. You may change the template’s collision detection polygon or its world limits.
7. If appropriate, enable/disable Pool With Components
8. You may add/adjust the components from the Edit pane. Items of particular interest:
   • WorldLimitResolveCollision in T2DWorldLimitComponent
   • CollidesWith in T2DCollisionComponent

For animations

You may want to check the Remove On Finished checkbox.

C# Matters

In Game.cs…

…you may want to add the following piece of code:

static public Game GameInstance
{
	get { return _myGame; }
}

Putting Scene Objects in Variables

1. In the region Private, protected, internal fields, add:

   T2DSceneObject _gameObject;

2. In the region Public properties, operators, constants, and enums, add:

   public T2DSceneObject GameObject
   {
   	get { return _gameObject; }
   	set { _gameObject = value; }
   }
   

3. Typically, one would access _gameObject from a method within the region Public Methods, whose contents are typically called from the Private, protected, internal methods region’s BeginRun method, where, VERY simply speaking, game code execution starts. Usage of _gameObject would probably work like this:

   public void SomePublicMethod()
   {
   	// look up the template for the object;
   	// here, SceneObjectTemplate would correspond to the name we gave to the template earlier in TGBX
   	T2DSceneObject sceneObjectTemplate = TorqueObjectDatabase.Instance.FindObject("SceneObjectTemplate");
   
   	if (sceneObjectTemplate != null)
   	{
   		// clone the template to create the object
   		_gameObject = (T2DSceneObject)sceneObjectTemplate.Clone(); 
   
   		// process _gameObject further here...
   
   		// register our object with the TorqueObjectDatabase
   		TorqueObjectDatabase.Instance.Register(_gameObject);
   	}
   }
   

   Alternatively, one can also write (NOT TESTED YET and COULD BE INCORRECT):

   public void SomePublicMethod()
   {
   	// clone the template to create the object
   	_gameObject = TorqueObjectDatabase.Instance.CloneObject("sceneObjectTemplate");
   
   	// process _gameObject further here...
   
   	// register our object with the TorqueObjectDatabase
   	TorqueObjectDatabase.Instance.Register(_gameObject);
   }
   

   Note that sceneObjectTemplate.Clone() returns an Object object, so it needs a cast, while TorqueObjectDatabase.Instance.CloneObject returns a T2DSceneObject.

Manipulating Scene Objects from Code

For this, the Torque X API.chm help file is your best source of information. Basically, this will allow you to do in code the changes you make to scene objects within the TGBX editor.

Setting a scene object’s position

Within a method (maybe within // process _gameObject further here...),

_gameObject.Position = new Microsoft.Xna.Framework.Vector2(desiredX, desiredY);

or

_gameObject.Position = SceneObject.Position;

where SceneObject refers to the scene object to which the component is attached to.

Setting a scene object’s layer

_gameObject.Layer = SceneObject.Layer + n;	// n an integer

Setting a scene object’s rotation

_gameObject.Rotation = 180.0f;

Enabling/disabling collisions

_gameObject.CollisionsEnabled = true;

T2DCollisionComponent

_gameObject.Collision.CollidesWith = TorqueObjectDatabase.Instance.GetObjectType("objectType");
_gameObject.Collision.ResolveCollision = T2DPhysicsComponent.KillCollision;

T2DPhysicsComponent

_gameObject.Physics.Velocity = new Vector2(0.0f, -80.0f);
_gameObject.Physics.VelocityY = TorqueUtil.GetRandomFloat(5.0f, 15.0f);

Loading Levels

Within the BeginRun method in the region Private, protected, internal methods in Game.cs:

SceneLoader.Load(@"data\levels\sceneNameHere.txscene");

This line may be followed by Public Methods that initialize the level (probably concerning Scene Objects).

Adding Components

1. Add a new T2DComponent called ComponentNameHere.cs from Game Studio Express.
2. Add fields such as float _fieldName; relevant to the component in the region Private, protected, internal fields.
3. Add methods in the region Private, protected, internal methods.
4. If you want your component to accept input, you may want to add code similar to the following in the Private, protected, internal methods region, in the _OnRegister method, before the return true statement:

   	InputMap inputMap = PlayerManager.Instance.GetPlayer(0).InputMap; 
   
   	int gamepadId = InputManager.Instance.FindDevice("gamepad0");
   
   	if (gamepadId >= 0)
   	{
   		inputMap.BindMove(gamepadId, (int)XGamePadDevice.GamePadObjects.A, MoveMapTypes.Button, 0);
   	}
   
   	int keyboardId = InputManager.Instance.FindDevice("keyboard");
   
   	if (keyboardId >= 0)
   	{
   		inputMap.BindMove(keyboardId, (int)Keys.Space, MoveMapTypes.Button, 0);
   	} 
   
   	// tell the engine to call our ProcessTick method every clock tick.
   	ProcessList.Instance.AddTickCallback(Owner, this);
   

   Again, I highly recommend that you refer to the Torque X API.chm help file – it will really help in understanding the inputMap.BindMove method.

5. To make the game to actually react to the user input, you will need to add the following to the ProcessTick method in the Public Methods region:

   	if (move != null && move.Buttons[0].Pushed == true)
   	{
   		_React();
   	}
   

6. We can make properties for the fields defined earlier, and make them editable in TGBX using code similar to the following within the Public properties, operators, constants, and enums region:

   	[TorqueXmlSchemaType(DefaultValue="15")]
   	public float FieldName
   	{
   		get { return _fieldName; }
   		set { _fieldName = value; }
   	} 
   
   	[TorqueXmlSchemaType(DefaultValue="8")]
   	public float AnotherField
   	{
   		get { return _anotherField; }
   		set { _anotherField = value; }
   	}
   

7. In order to make templates using this component clonable, we will need to modify the CopyTo method in the Public Methods region as follows:

   	public override void CopyTo(TorqueComponent obj)
   	{
   		base.CopyTo(obj);
   
   		ComponentNameHere obj2 = (ComponentNameHere)obj;
   
   		obj2.FieldName = FieldName;
   		obj2.AnotherField = AnotherField;
   	}
   

   A more complete discussion on this matter is available in the Torque X Forums.

Working Within Components

1. To access public properties defined in Game.cs from within a component, you may use Game.GameInstance. For example, if the T2DSceneObject GameObject property is defined in Game.cs, you may use the following code:

   float GameObjectX = Game.GameInstance.GameObject.Position.X;
   

2. To access the scene object to which the component is attached to, you may use SceneObject.