To create a Torque X game, we first need to create a "project" for it. This is done in Visual Studio, so let's start that first. From the Start Menu, select: All Programs -> Microsoft XNA Game Studio 3.1 -> Microsoft Visual Studio 2008. Note: Version numbers may be different depending on what you have installed. For this tutorial, we are using XNA 3.1 and Visual Studio 2008.
In Visual Studio, use the menu to select File -> New -> New Project. This brings up the New Project window.
We want to create a simple Torque X game, so select the Starter Game 2D template (only single-click it to select it -- double-clicking will automatically create the project with the default name).
Then, in the text field for Name, enter HelloWorld.
If you want to create the project somewhere other than the default project folder, update the location.
Click the OK button to create the project. After the project is created, build the project by pressing the F5 or selecting Build > Build Solution from the menu to. This will compile game code and produce the myschema.txschema file, needed by Torque X Builder.
Now that our project is created, we can start Torque X Builder, the visual editor that works with the Torque X engine to help make designing your game easier. From the Start Menu, select: All Programs -> Torque X -> TXB.exe
If you see the startup screen, select Open. If you don't see the startup screen, select File -> Open Project.
In the "Open A Torque X Game Project" window, navigate to the folder of the project you created in Visual Studio. Go to the Game folder, and select the file Game.txproj, which is a TXB project file that was automatically created when you generated the project in Visual Studio with the StarterGame template, and click the Open button to open the project. There's not a whole lot going on in there yet, so let's add some art. Save the following file to your local drive and open it within TXB using the "Create New Material" button.
 |
This image is a PNG file, which lets us use transparency for the corners where we'd like to see whatever background is behind the image, rather than a background color hardcoded into the image. In Windows, dragging the image onto TXB like this automatically creates a Material. A Material is simply the image plus some other information that Torque X needs in order to render images when the game is running. Whenever you add a new image you are updating the project, so you need to save the project before it will work. From the menu, select File ->Save Project.
Whenever you update the TXB project file, Visual Studio needs to reload the file. Go back to compiler, and in the "File Modification Detected" popup, select Reload.
Just creating that material makes it possible to render the material, it doesn't actually put anything in the game scene to render. Let's do that next.
Go back to Torque X Builder. From the Create pane in TXB, from the Materials rollout, drag the worldMaterial into the center of the Scene View. This creates a static sprite that displays the material with our world image.
Now that we have something in our scene, let's save it to a scene file. From the menu, select File -> Save Scene As. Select the levelData.txscene file that's already there (which was created by default with the project), and click the Save button. In the popup that warns you that you're overwriting an existing file, answer Yes.
Now let's see our scene in action. Minimize TXB (so your computer's video card doesn't have to work to render both TXB and the game we're going to start), and go over to Visual Studio. From the menu, select Debug -> Start Debugging. This runs the game, and we can see our lonely planet.
When you're finished observing the game in action, close it by either clicking on the "X" in the upper right corner or by using the Visual Studio menu to do Debug -> Stop Debugging.
Right now, there's not a lot going on with this game. Let's change that by adding some player input. Go back to TXB. Select the world sprite in the Scene View. Now switch to the Edit pane.
Expand out the Components rollout. Components are "chunks of functionality" that you can attach to an object in Torque X. There are already some components attached to the object by default, but we want to add a new component. In the selection box, choose MovementComponent and click the green "+" button. This adds a component that comes with the StarterGame project template, which makes an object move based on keyboard input (WASD or arrow keys) or an XBOX 360 Controller (left analog stick).
Let's see this movement component in action. With the menu, choose File -> Save Scene. Now minimize TXB, go to the compiler, and use the menu to select Debug -> Start Debugging.
Now the world can move around, but it's obviously quite lonely. More than anything else, it wants someone to say hello to it. Let's create a character that can wave hello to the world. Start by dragging this image from your browser onto TXB or openning it locally with the "Create New Material" button:
 |
As you can see, this image is made up of different frames of animation. Let's tell TXB about that. Go to TXB, and the Create pane, and the Materials rollout. Double-click on the guyMaterial. This brings up the Material Builder window.
Set the Image Mode to "Cell". This sets the material as an animation material, and gives us some more choices which we can use to set it up.
For Cell Count X, enter 4. For Cell Count Y, enter 3.
Click the Save button.
Now the material can be used as the basis for an animation, but we need more than the frames to make an animation, we need to decide which frames to use in which order. Let's do that now. Click the "Create a new Animation" button.
This brings up the "Select Material" window. We've only got one choice here, so it's an easy choice to make: select guyMaterial from the list, and then click the Select button. This brings us to the Animation Builder window.
You create the animation by dragging the frames from the bottom of the window into the sequence at the top. The top row of frames has the guy moving his foot a little bit. Let's use the four frames from the top row to create an animation.
Start by dragging the top left frame into the sequence. Then drag the second, third, and fourth frames into the sequence. Now our animation has a guy that's lifting his foot up, but in order to actually tap his foot, he'll need to bring it back down again. To do that we can just use the same frames in reverse! Drag the third, then the second, then the first frame into the sequence.
Now we have some awesome foot-tapping action. But it's going a little fast, so set the Frames Per Second to 15.
In the Name textbox, change the name to idleAnimation. Click the Save button.
Now you have a new Animation in the Create pane. Drag it into the Scene View to create a new animated sprite.
Use the menu to do File -> Save Project and File -> Save Scene. Minimize TXB, go over to Visual Studio. In the popup, reload the project. Then use the menu to do Debug -> Start Debugging.
Well, now there's a guy in there, but he's not very friendly. Where's that hello that the world has been waiting for? Let's make some more animations that we can use to wave to the world. Go back to TXB, and click the "Create a new Animation" button.
Select guyMaterial again, and click the Select button.
We want to create an animation for the guy to raise his hand, so add the four frames from the second row to the animation.
Set the Frames Per Second to 15.
Also, click on the Cycle Animation checkbox to clear the checkmark out of there. It doesn't make sense for this animation to repeat.
Set the Name to raiseAnimation, and click the Save button.
Let's make an animation for the guy to lower his hand, too. Click the "Create a new Animation" button. Select guyMaterial.
Now add the frames from the second row, but in reverse order.
Set the Frames Per Second to 15, and clear the Cycle Animation checkbox. Set the Name to lowerAnimation and click the Save button.
Now, let's make a waving animation. Click the "Create a new Animation" button, and select guyMaterial again.
This time, add the last image from the second row, then the four images in the bottom row, and then add the same frames in reverse to complete the wave (i.e. if the frames were numbered from 1 at the upper left, you would add frames 8, 9, 10, 11, 12, 11, 10, 9, 8 in this animation).
Set the Frames Per Second to 15.
Set the Name to wavingAnimation and click the Save button.
Now we have multiple animations, but how do we get our guy to switch between them so he can wave when the world is close, but not when the world is far away? That's the kind of customized behavior that you wouldn't expect to be part of a game engine, but we can write some custom code to do it.
Run Visual Studio. From the menu, select Project -> Add New Item. In the popup box that comes up, select the T2DComponent template and enter WavingComponent.cs for Name. Click the Add button.
This component we're creating is going to need some variables to store data, so we need to declare them. In order to keep the code nicely organized, the best place to do that is in the "Private, protected, internal fields" region. Scroll down until you can see those words, and click on the "+" sign to the left to expand that region out so we can type into it.
Go to the end of the line that says "#region Private, protected, internal fields" and hit return a few times, to create some blank space before the line that says "#endregion". Now, in the blank space you just created, type this code to declare some variables:
T2DAnimationData _idle;
T2DAnimationData _raise;
T2DAnimationData _lower;
T2DAnimationData _wave;
T2DSceneObject _target;
float _range;
C# requires you to declare your variables with types. The T2DAnimationData type is the kind of variable that can store those animations we created over in TXB. The T2DSceneObject type is the kind of variable that can store any kind of object that we put in our scene, and in this case we'll use our _target variable to point to the world sprite, so we know who we're trying to wave to. The last variable, _range, is a floating-point variable (i.e. it can have decimal places) that we'll use to determine if we want to wave or not: if the target is close we'll wave, but if it's far away we won't.
Having variables is important, but in order to do anything with them we'll need to be able to assign values to them. We could use C# code to assign the values, but one of the powerful features of Torque X is that you can use the C# concept of properties to expose tweakable control parameters on your components to the TXB editor. Let's create some properties so we can set our variables in TXB.
Expand out the "Public properties, operators, constants, and enums" region. Before the line with #endregion, type in this code:
public T2DAnimationData Idle
{
get { return _idle; }
set { _idle = value; }
}
public T2DAnimationData Raise
{
get { return _raise; }
set { _raise = value; }
}
public T2DAnimationData Lower
{
get { return _lower; }
set { _lower = value; }
}
public T2DAnimationData Wave
{
get { return _wave; }
set { _wave = value; }
}
public T2DSceneObject Target
{
get { return _target; }
set { _target = value; }
}
public float Range
{
get { return _range; }
set { _range = value; }
}
From the menu, select Build -> Build Solution.
Go over to TXB. There should be a popup that is informing you that the component definitions have changed (because we just added a new one). Click OK.
Select your foot-tapping animated sprite in the Scene View, and go to the Edit pane.
In the Components rollout, select WavingComponent and click the green "+" button to add it to the object. Scroll down, and you can see the new component we created, along with those public properties we set up.
Now let's put values in those properties. For Idle, select idleAnimation.
For Raise, select raiseAnimation.
For Lower, select lowerAnimation.
For Wave, select wavingAnimation.
We'd like to be able to set Target to our world, but if you try it you'll see we can't set it to anything useful yet. In order to do that, we'll need to give our world object a name. Select the world sprite. Find the Scripting rollout in the Edit pane, and expand it out. In the Name field, enter "world".
Select the animated guy again, and go back to the WavingComponent rollout. Now you can set Target to "world"!
Enter 15 in Range.
Then do File -> Save Scene.
So setting those properties in TXB is useful, but our component doesn't really do anything with them yet. Let's fix that. We'll write some code that will let us switch between animations based on the distance from the target. Go to Visual Studio, and expand out the "Public methods" region. Before the #endregion line, type in this code:
public void AnimationRunner()
{
T2DAnimatedSprite anim = SceneObject as T2DAnimatedSprite;
float distance = Vector2.Distance(SceneObject.Position, _target.Position);
This code is the beginning of a definition of a new method. We're going to use this method to figure out which animation we should be playing, and start playing that animation. The first thing we do is declare the variable anim, which we've defined as a T2DAnimatedSprite which will let us access all of the animated sprite functionality which is only defined for that type of object. Then we assign into it from the SceneObject property, which refers to whatever object this component is attached to (in our case, the little guy). This will let us use the animation functionality on the object we're attached to, which is exactly what we'll need pretty soon. The next thing we do is calculate the distance from our object to the target object. We can use that distance, and the range we set earlier in TXB, to decide if we want to wave or not. To do that, type in this code right after the code you just entered:
if (distance <= _range)
{
// target is nearby, wave, wave!
if ((anim.AnimationData == _idle) || (anim.AnimationData == _lower))
{
anim.PlayAnimation(_raise);
}
else
{
anim.PlayAnimation(_wave);
}
}
The first "if" statement, as the comment indicates, decides whether we should be waving or not. If we do want to wave, we need to account for the fact that the guy may need to raise his hand before he can start waving. Now type in this code, right after the stuff you just added:
else
{
// target is far away, just stand idle
if ((anim.AnimationData == _wave) || (anim.AnimationData == _raise))
{
anim.PlayAnimation(_lower);
}
else
{
anim.PlayAnimation(_idle);
}
}
}
This takes care of the situation where we're not close enough to wave (i.e. the target is far away and we don't want to wave). Similarly to how we had to run the "raise" animation before we could do the "wave" animation, we have to account for the fact that the guy has to lower his hand when he stops waving and wants to just stand around.
So that gives us a method that lets us decide which animation to run, but how do we make that method get called? We can use the OnAnimationEnd property. This is a property of T2DAnimatedSprite objects that let you specify a method to be called whenever an animation finishes. We'll set it to the AnimationRunner method that we just created, and that way whenever one animation finishes, we'll decide which animation to play next. Perfect! Let's set that up. Expand out the "Private, protected, internal methods" region.
Find the _OnRegister method, and enter this code right after the line that says "//todo: perform initialization for the component":
T2DAnimatedSprite anim = SceneObject as T2DAnimatedSprite;
anim.OnAnimationEnd = this.AnimationRunner;
As before, we set up a variable so we can access the T2DAnimatedSprite functionality, and then we assign the method that we defined into it. We're specifying the method as this.AnimationRunner because we want the method to be called on this component object.
Let's save the changes we've made to this file. Use the menu to do File -> Save All.
Now, the OnAnimationEnd property is cool, but it will only work on animations that actually end. Remember our foot-tapping and waving animations? They're set to cycle infinitely, so they'll never actually end. Let's fix that. Go back to TXB, and in the Create pane, double-click on the idleAnimation in the Animations rollout.
This brings the Animation Builder window back up. Clear the checkmark out of the Cycle Animation checkbox, and click the Save button.
Now double-click the wavingAnimation. Clear the checkmark out of its Cycle Animation checkbox, and click the Save button.
Use the menu do to File -> Save Scene. Minimize TXB, and open Visual Studio. From the menu, select Debug -> Start Debugging. Now, when you move the world close enough, the guy will wave hello, and he'll stop waving when you move away. Now that someone's saying hello, the world won't have to feel lonely anymore.
We want your feedback! Please follow this link to take a short survey about this tutorial. Telling us what you think about our tutorials (good and bad) helps us make our tutorials better. We need to know what we're doing right and what we're doing wrong, and we can't do that without your help!