Your First Bot

Once you've created a new bot you'll have a very basic class with just a constructor and an overridden ProcessActions() method.

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using UT3Bots;
using UT3Bots.UTItems;
using System.Threading;
using UT3Bots.Communications;


namespace UT3UserBot
{
    public class MyBot : UTBot
    {

        //Constructor for your bot
        public MyBot() : base ("174.133.254.34", "Sitting Duck", BotMesh.Harbinger, BotColor.Red)
        {
        }


        //Method to control the bot once it has connected to the server
        protected override void ProcessActions()
        {
            //Add code here to perform some actions at specific intevals
        }
    }
}

VB

Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Text

Imports UT3Bots
Imports UT3Bots.UTItems
Imports System.Threading
Imports UT3Bots.Communications


Namespace UT3UserBot
    Public Class MyBot
        Inherits UTBot

        'Constructor for your bot
        Public Sub New()
            MyBase.New("174.133.254.34", "Sitting Duck", BotMesh.Harbinger, BotColor.Red)
        End Sub


        'Method to control the bot once it has connected to the server
        Protected Overloads Overrides Sub ProcessActions()
            'Add code here to perform some actions at specific intevals
        End Sub
    End Class
End Namespace

Setting Up Your Bot

The first thing you need to do for your bot is configure it with a look and feel, and then actually connect to the server and get in the game. This is pretty straightforward, all you need to do is alter the parameters that are getting sent up to the base bot class in the constructor.

• Server IPAddress - The first parameter is the IPAddress of the server to connect to. By default this points to the UT3Bots server we have running on the internet (ut.utbots.com), you'll need to alter this to point to the server you need to connect to.
• Name – The name of your bot will be seen on the Visualizer and in game.
• Bot Mesh – This is the appearance of your bot on the server.
• Bot Color – This is the color of your bot.

Now you are ready to join a UT3 game.

Pressing F5 will build and run your bot. The bot project will load up a little console application which provides info about what your bot is doing.

Bot's First Sight

Now that we have a bot in the game we need to make it actually do something. The first thing we are going to make it do is move to a UTNavPoint. This is a location in the game which might hold something interesting. A series of UTNavPoints provide a path through the level to interesting items. A bot can travel around a game level by moving from one UTNavPoint to another.

Within the game framework (UT3RemoteBot.dll), an instance of the UTVector class can be used to express the actual location of something. The location of a UTNavPoint is given by its Location property, which is given as a UTVector value.

Our bot needs to have a way of keeping track of where it is going so in the UT3UserBot class create a new private UTVector called destinationLocation

C#

private UTVector destinationLocation;

VB

Private destinationLocation As UTVector

We want our bot to head towards the first navpoint that it “sees”. To do this we place the following code into the ProcessActions() method.

C#

this.destinationLocation = this.GameState.NavPointsVisible[0].Location;

VB

Me.destinationLocation = Me.GameState.NavPointsVisible(0).Location

The GameState property of our bot contains information on the current state of the game. NavPointsVisible is a list of references to UTNavPoint instances which refer to all of the UTNavPoints a bot can currently see. The above code simply takes the UTVector at position 0 (the first navigation point your bot can see) and sets destinationLocation to refer to it.

So at this point the bot has identified the location it wants to move towards, now we have to make it move in that direction.

Bot's First Steps

Now we are going to make our bot move to the destination it has selected. Place the following code into the ProcessActions() method just below the code written in the previous example.

C#

this.Commands.RunTo(this.destinationLocation);

VB

Me.Commands.RunTo(Me.destinationLocation)

The Commands property provides a set of methods which are the commands that your program can give to the bot. There are a wide range of commands, some of which are listed below. For full details you should investigate the API reference.

• Jump() - Jumps in the air
• RotateBy() - Rotates by a specific number of degrees
• RunTo() - Runs to a specific location
• StartFiring() - Attacks a target or location
• StopFiring() - Stops the bot from shooting
• StrafeTo() - Strafes to a specific location while looking at another

The RunTo() command is provided with a destination location. When this method is called your bot will start running towards the destination.

If you execute this program you will see your bot start running towards a navigation point.

Bot's First Shot

For the purpose of this example we will next make our bot shoot at the location it is running towards, it is recommended that you change this when creating your own implementation as shooting at an empty UTNavPoint is unlikely to get you many frags.

Place the following code into the ProcessActions() method just below the code written in the previous example.

C#

this.Commands.StartFiring(this.destinationLocation, false);

VB

Me.Commands.StartFiring(Me.destinationLocation, false)

If you execute the program you will see that your bot now shoots at the location as it runs towards it. It will continue running and shooting until you call a method to instruct it to stop, or it runs out of ammo!

Place the following code into the ProcessActions() method just below the code written in the previous step.

C#

this.Commands.StopFiring();

VB

Me.Commands.StopFiring()

Your bot will now stop shooting.

So you now know how to get your bot to do something in the game. Running around and shooting things is as easy as using the GameState property to access what your bot can see, and the Commands property to call methods that perform actions.

Bot's First Reaction

Now we are going to make the bot react to things that happen in the game. This is done by subscribing to any of the events that the bot exposes through its Events property. We normally want to subscribe to the game events as soon as the bot starts, so that we get all the juicy information that we can use to make a clever bot. You can do this by attaching an event handler to an event in the constructor for your bot.

In this example we will subscribe to the OnSpawned event which is trigged whenever the bot spawns in the game, whether this is the first time, or after it has died.

Place the following code into the constructor of the MyBot class.

C#

this.Events.OnSpawned += new EventHandler<BotSpawnedEventArgs>(Events_OnSpawned);

VB

AddHandler Me.Events.OnSpawned, AddressOf Events_OnSpawned

You also need to add a new method to the class that will be called when the bot spawns.

Place the following method code into the MyBot class.

C#

void Events_OnSpawned(object sender, BotSpawnedEventArgs e)
{
    this.Commands.PerformEmote(Emote.PelvicThrust);
} 

VB

Private Sub Events_OnSpawned(ByVal sender As Object, ByVal e As BotSpawnedEventArgs)
    Me.Commands.PerformEmote(Emote.PelvicThrust)
End Sub

Your bot will now start performing some fetching pelvic thrusts whenever it spawns in the game. This won't actually help you get any extra frags, but maybe it'll start a new craze!

There are many different events you can attach handlers to which will allow you to change your bot behavior to react to different circumstances. For full details you should investigate the API reference or check out Visual Studio's intellisense.

Viewing Your Bot In Action

You can easily find out what your bot is up to by using the special Silverlight 2 visualizer we have created. When you open the visualizer web page in your browser, you can automatically see the status of the server running the Bot game type and get a bird's eye view of the game in progress. You can see the waypoints which are marked by green dots and the active players which have their name next to moving circles with a line indicating which way they are facing. From here you can view the game and see what your bot is doing as shown in the visualizer screenshot.

What To Do Next

Now that you have got your bot into the game and made it move around a bit you can start thinking about making it into a decent player of the game. Take a look at the other members of the GameMap class so that your bot can look for weapons and health packs and move towards them. Then take a look at the members of the GameState class for the information that your bot is given about the game around it.

One thing you will need to add is some way that your bot can be in a particular state at any given time. Sensible states might be "Roaming", "Hunting", "Idle", "Recovering", etc. Depending on the state your bot is in it will do different things each time ProcessActions is called.

If it is in the roaming state, for example, it will be looking for a navigation point. If it is in the hunting state it will be chasing other bots. If it is in the recovering state it will be avoiding other bots and looking for a health pack, and so on. You can keep track of the state of your bot by creating an enumerated type with the different values. Then your ProcessActions method can contain a switch statement which makes it behave differently, depending on what it is doing.

A state machine is just one way you could program your AI, you could make a sophisticated bot that had a way of determining if a result had a positive or negative consequence and then have the bot perform more actions that had a positive consequence. Essentially a learning bot, be careful though if your bot takes too long executing ProcessActions it will get out of touch with the game as messages will sit on the queue unprocessed waiting for your code to finish.

Conclusion

With this quick getting started guide you should be able to go about creating your own UT3 Deathmatch player. There are also some very handy hints in the FAQ below about getting your bot on the road to stardom.

If you're feeling particularly brave join our project on CodePlex at http://www.codeplex.com/UT3Bots and help pitch in with improving the bot client, the visualizer, or even the server mutator.

Happy Fraggin'!

Download: http://codeplex.com/sammythesnake
Software: Visual C# Express Editions, XNA Game Studios 3.0
Difficulty: Intermediate
Time Required: 8 hours
Cost: Free

Artwork courtesy of George Clingerman of XNADevelopment.com
Side note: XNA is c# only

In the exciting world of XNA Game Studio, the new big thing is the XNA Game Studio 3.0 Beta. This beta allows developers to glimpse what will be coming with the full release of XNA Game Studio 3.0. One of the largest new features coming with XNA Game Studio 3.0 is the new ability to create games for Microsoft's Zune media device. What we're going to cover today is how to create a full game for the Zune, specifically a clone of the classic “Snake” game.

To begin you need to make sure you are set up to start working on Zune games. For all the details and instructions you will need for this step, please visit http://creators.xna.com/en-us/3.0beta_mainpage. Once you have read and completed steps one and two, continue on with this tutorial.

Welcome back! Now that you're all set up with XNA Game Studio 3.0 Beta, we can start working on our game. Since we want to test our game as we go forward, we're actually going to create the game as a Windows game first and then simply convert it to be a Zune project when we are finished. First open up Visual Studio 2008 or Visual C# 2008 Express and create a new Windows project. Let's call it “SammyTheSnake”. Choose the location to save the project and hit Ok.

Now that we have the project created let's start out first by adding in the content for our game. George Clingerman of XNADevelopment.com was nice enough to create some pretty graphics for this tutorial so those are the ones we are going to add to the project. In Visual Studio you will have a panel called the Solution Explorer which will show you all of the files in your project. In that window you want to find the Content node of your project. Right click on the Content node and choose Add->New Folder. Name this new folder “Fonts”. Then add a second folder called “Sprites”. At this point your Solution Explorer should look like what is to your right:

Let's continue by adding our content files. The easiest way to add the sprites to our project is to simply drag and drop them in from the folder. Another method is to right click on the “Sprites” folder, select Add->Existing Item. Then you can navigate to the directory where the graphics are, select them, and click Ok. When completed you will see all five images are copied into the Sprites directory:

Next we'll create the three fonts that we will be using for the game. To create a font, right click on the “Fonts” folder and select Add->New Item. In the pop up window you will see an item called a “Sprite Font”. Select that item, name your file “MiniFont.spritefont”, and then press Ok. When created it will open up in Visual Studio. The .spritefont file is simply an XML document describing which font you want to use. For our purposes there are only two nodes we need to change. First find the node that looks like this:

<FontName>MiniFont</FontName>

The FontName node specifies which font we wish to use. Let's change our font to Arial:

<FontName>Arial</FontName>

Next we need to change the size of the font. Let's find the Size node which, by default, is set to 14:

<Size>14</Size>

And let's change our font to size 10:

<Size>10</Size>

Now that you know how to create fonts, create two more fonts: “MediumFont.spritefont” and “TitleFont.spritefont”. Both fonts should use the Arial font. MediumFont should be size 14 (the default value) and TitleFont should be size 18.

Now you have all the content our game needs. Let's take a look at the Solution Explorer one last time to make sure we have all the files in the correct locations:

Now that all of the content is in place, we can begin working on the game. Let's start writing that code!

To begin we want to make sure our Windows game looks just like the Zune version will. Since the Zune screen has a resolution of 240 pixels by 320 pixels, we want to make our Windows game run in a window set at 240x320. To do this we just need to add two lines of code to our Game1 class's constructor:

public Game1()
{
    graphics = new GraphicsDeviceManager(this);
    Content.RootDirectory = "Content";

    graphics.PreferredBackBufferWidth = 240;
    graphics.PreferredBackBufferHeight = 320;
}

The next thing to consider is our game's flow. Since we are making a simple game, we are only ever going to have three states in which the game can be in as illustrated by this diagram:

From the diagram we see that our game will have a title screen, some game play, and a game over screen. The arrows represent the changes in game state. From the title screen we can only progress to the in-game screen. From the in-game screen we can either quit, going back to the title screen, or we can finish the game and move to the game over screen. From the game over screen we then return to the title screen and the process repeats until the user quits.

Now that we have an idea of how our game will work we will start by creating the framework that will manage our game's state and make sure that we are executing the appropriate code based on the state of the game. First we'll create a new enumeration type to represent the three states of our game. In the Game1.cs file right above the declaration for the Game class, add this new enumeration:

public enum GameState
{
    Title,
    InGame,
    GameOver
}

Now in the actual Game1 class, we need to add a variable to hold the game's state:

private GameState state = GameState.Title;

Now we need to create some new methods which will be used to handle updating and drawing our various states. First let's add three new methods to our Game1 class:

private void UpdateTitleScreen()
{ }

private void UpdateInGame(GameTime gameTime)
{ }

private void UpdateGameOver()
{ }

From the names you can probably see that we have one for each of our three game states. Our UpdateInGame method takes in the GameTime as a parameter because it is used for moving our snake around. The other two game states don't need that value, so they have no parameters. Now let's make some changes to the Update method to handle calling each of these methods based on the state of our game:

protected override void Update(GameTime gameTime)
{
    if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
        this.Exit();

    if (state == GameState.Title)
        UpdateTitleScreen();
    else if (state == GameState.InGame)
        UpdateInGame(gameTime);
    else if (state == GameState.GameOver)
        UpdateGameOver();

    base.Update(gameTime);
}

Now we'll repeat those steps to make three methods for rendering each state and updating the Draw method to call each of them as appropriate. While we're at it, we're also going to change the background from the default of CornflowerBlue to Gray to make it a little easier on the eyes with the white text we're going to add later:

private void DrawTitleScreen()
{ }

private void DrawInGame()
{ }

private void DrawGameOver()
{ }

protected override void Draw(GameTime gameTime)
{
    graphics.GraphicsDevice.Clear(Color.Gray);

    if (state == GameState.Title)
        DrawTitleScreen();
    else if (state == GameState.InGame)
        DrawInGame();
    else if (state == GameState.GameOver)
        DrawGameOver();

    base.Draw(gameTime);
}

With that our game now has a fully functioning state system. Of course our game only ever has one state since we don't currently change it, and none of the game states do anything, but the functionality is there. Let's move on to create the code that will power the title screen.

First we need to add a few strings to our game which will be used on the title screen. Towards the top of your Game1 class, add these string constants:

private const string gameTitle = "Sammy the Snake!";
private const string playInstructions = "Press Play to Begin";
private const string quitInsructions = "Press Back to Quit";

Now we need to add a few variables to the Game1 class to hold our fonts which we'll be using to render these strings:

private SpriteFont titleFont;
private SpriteFont mediumFont;
private SpriteFont miniFont;

Next we'll go to our LoadContent method and add in the code that will load those .spritefont files we created earlier and store them in these three variables:

protected override void LoadContent()
{
    spriteBatch = new SpriteBatch(GraphicsDevice);
    titleFont = Content.Load<SpriteFont>("Fonts/TitleFont");
    mediumFont = Content.Load<SpriteFont>("Fonts/MediumFont");
    miniFont = Content.Load<SpriteFont>("Fonts/MiniFont");
}

After that we also need to add two more variables. The first will store the current frame's input state. The second will store the previous frame's input state. By storing these two values, we will be able to test for when a button gets pressed by verifying that the button was down the frame before and is pressed in the current frame.

private GamePadState gamePadState;
private GamePadState lastGamePadState;

Now let's go ahead and make a method which we'll use to test for new button presses for us. We'll take a parameter for which button to test and then check for that button being down in gamePadState but up in lastGamePadState.

private bool IsNewButtonPress(Buttons button)
{
    return (gamePadState.IsButtonDown(button) && lastGamePadState.IsButtonUp(button));
}

We'll go ahead, now, and modify the game's Update method to handle updating those GamePadState variables we created above. We get the current state right away and then, at the end of the Update method, we store the current state in our last state variable for next frame. We also want to remove the default code in there for exiting when the Back button is pressed because we will handle this in our UpdateTitleScreen method:

protected override void Update(GameTime gameTime)
{
    gamePadState = GamePad.GetState(PlayerIndex.One);

    if (state == GameState.Title)
        UpdateTitleScreen();
    else if (state == GameState.InGame)
        UpdateInGame(gameTime);
    else if (state == GameState.GameOver)
        UpdateGameOver();

    lastGamePadState = gamePadState;

    base.Update(gameTime);
}

With that in place we can move on to filling in our UpdateTitleScreen method. For our simple game, we're going to simply detect the Play/Pause button to start the game and the Back button to exit. These buttons map to the GamePadState's B and Back buttons, respectively.

private void UpdateTitleScreen()
{
    if (IsNewButtonPress(Buttons.Back))
        Exit();

    if (IsNewButtonPress(Buttons.B))
    { }
}

For now we'll leave the inside of our second if statement empty because we have not implemented the in-game game state at this point.

Let's now move on to rendering our title screen. We know we are going to have to render three different strings to the screen, so what we're going to do first is write a helper method that will help us write text centered on a point. This will make it easier for us so that we don't have to try and calculate where to draw each string individually; we can simply use this one method everywhere we need to draw text.

private void DrawText(SpriteFont font, string text, Vector2 position)
{
    Vector2 halfSize = font.MeasureString(text) / 2f;
    position = position - halfSize;

    position.X = (int)position.X;
    position.Y = (int)position.Y;

    spriteBatch.Begin();
    spriteBatch.DrawString(
        font,
        text,
        position, 
        Color.White);
    spriteBatch.End();
}

This is our first complex code so we're going to take a look at it line by line. The method itself takes in three parameters: the SpriteFont to use for rendering, the text we want to render, and the point at which we want the text centered.

First we use the font's MeasureString method to calculate how big the text will be (in pixels) if rendered with that font. We then divide this size by two and subtract it from the position. Why do we do all of this? In the XNA framework (and most 2D graphics APIs) positions of objects are specified using the top-left corner of the object. So by getting half of the size of the object and offsetting the position by it, we are able to set the center point and know that the text will be positioned properly.

Once we have offset the position, we then cast each of the components to integers. We do this to avoid unnecessary blurring of our text. Since all text is rendered as whole pixels (because there's no such thing as a fractional pixel), having a position that is not an integer value will cause the device to try and filter the text to get it to look right, or simply render it incorrectly. So when drawing in 2D, it's always best to cast your positions to integers before using them to render.

Lastly our method uses a simple SpriteBatch routine to draw the text at the desired position using the desired font using the White color.

With that helper method out of the way, we can add three simple lines to the DrawTitleScreen method to draw our title screen:

private void DrawTitleScreen()
{
    DrawText(titleFont, gameTitle, new Vector2(120f, 25f));
    DrawText(mediumFont, playInstructions, new Vector2(120f, 200f));
    DrawText(mediumFont, quitInsructions, new Vector2(120f, 225f));
}

Now if you run your game, you should see a window like this:

If you have an Xbox 360 controller hooked to your computer, you could press the Back button to quit, but otherwise you can simply use the close button of the window to exit the game.

From this point we're going to start working on the gameplay. I am only going to be showing GamePad controls for this (since we are targeting the Zune), so if you don't have an Xbox 360 controller connected to your PC, you are either going to have to deploy the game to the Zune each time you want to test or implement keyboard controls. You can skip down to the end of this tutorial where we convert the project to be a Zune game or use other references for that process.

Next we need to add in the game play code itself. Our game is rather simple. At any given time our game will have a single orange on screen, the snake, and a display of the number of oranges consumed. We're going to start with the orange, then handle the snake, and finally the scoring system.

To begin any of our rendering we need to get setup with a system for easily rendering our game. Since the whole game is grid based, we are going to make a class whose only purpose is to handle rendering a sprite at a given point using grid coordinates. We'll start by creating a new static class called Grid:

public static class Grid
{ }

Next we will define a few constants. The first sets the size of each grid cell. The second is one half of the grid cell size. We will be using a 16x16 pixel area for our grids. This number has been chosen because both 240 and 320 are even divisible by it, thus giving us a perfect grid for the resolution. We then have values to represent the largest row and column values in our grid:

Next we'll define a method called PointToVector2. The whole purpose of this method will be to take a Point value representing cell coordinates and converting them into the pixel coordinates needed to render a sprite. To do this we simply multiply the point's coordinates by the scale and add in the half scale value. We add the half scale so that the resulting Vector2 is at the center of the cell. As I said before you always want to convert to integer based coordinates, but since the Point only contains integer values, and all our constants are integers, we don't need to explicitly cast the values to ints:

public static Vector2 PointToVector2(Point p)
{
    return new Vector2(
        p.X * Scale + HalfScale,
        p.Y * Scale + HalfScale);
}

The only other method we're going to add to our Grid class is the DrawSprite method. DrawSprite will handle rendering a given texture at a specific point with a given angle of rotation.

public static void DrawSprite(
    SpriteBatch spriteBatch, 
    Texture2D texture, 
    Point point, 
    float rotation)
{
    float spriteSize = (float)Math.Max(texture.Width, texture.Height);
    Vector2 origin = new Vector2(texture.Width / 2f, texture.Height / 2f);
    spriteBatch.Draw(
        texture,
        PointToVector2(point),
        null,
        Color.White,
        rotation,
        origin,
        Scale / spriteSize,
        SpriteEffects.None,
        0);
} 

Let's walk through what this method is doing so that we're all clear as to how it works. We first calculate the largest dimension of the texture given to us. We do this so we know how much to scale the sprite to make it fit into a single cell of the grid. Then we compute the origin we'll use for rendering. I'll explain the origin below as we go through the parameters of our Draw call.

Next we make a large call to spriteBatch.Draw, where we have lots of variables going in. Let's just explain each one briefly:

• texture – This represents the texture object we want to draw.
• PointToVector2(point) – Here we leverage the Grid.PointToVector2 method we wrote before to convert our grid coordinate to pixel coordinates.
• null – This parameter represents the source rectangle used to render. The source rectangle is used to specify a subsection of the area of the texture to use for rendering. Since we want to draw the entire texture, we use null here.
• Color.White – Using white here simply causes the sprite batch to render the texture with no color modifications.
• rotation – The rotation (specified in radians) instructs the sprite batch to rotate the texture as desired.
• origin – Here we use the origin value we calculated earlier. This value specifies how to place, rotate, and scale the texture. What we've done is specified the pixel value of the center of our sprites. The sprites created for us are 32x32 pixels making their center point 16x16. Rather than hard coding in that value, we simply divide the width and height by two. By using the center of the texture, our sprite will be positioned such that the second parameter tells the sprite batch where we want the center of our texture. It also means that the sprite will be rotated and scaled about its center.
• Scale / spriteSize – Here we use our grid's Scale value and divide it by the size of the sprite. This will cause sprite batch to scale the texture so that it fits completely within a single grid cell.
• SpriteEffects.None – SpriteEffects are used for flipping the texture over the horizontal axis, vertical axis, or both. We don't want to flip the texture, so we specify none.
• 0 – The last parameter is the layer depth. This can be used to specify the order in which sprites drawn in the same batch are layered when rendered with zero being the topmost drawn sprites and one being the bottom most drawn sprites. We just use zero here because we will be handling the rendering order by hand so that sprites we want lower will be drawn first. In addition we will rarely ever have overlapping sprites, so ordering is hardly an issue for us.

With the Grid class complete, we can move on to create the Orange class:

public class Orange
{
    Position = new Point(Grid.MaxColumn / 2, Grid.MaxRow / 2);
}

Now let's think about what data our orange will need. The two obvious ones are a position and the texture. But we also need a third value: a random number generator which will be used to place the orange in a random place on the screen:

public Point Position;
private Texture2D texture;
private Random rand = new Random();

Now we're going to add three short methods to our Orange class that will handle just about all the functionality we will need for this game:

public void Reposition()
{
    Position = new Point(rand.Next(Grid.MaxColumn), rand.Next(Grid.MaxRow));
}

public void Load(ContentManager content)
{
    texture = content.Load<Texture2D>("Sprites/Orange");
}

public void Draw(SpriteBatch spriteBatch)
{
    spriteBatch.Begin();
    Grid.DrawSprite(spriteBatch, texture, Position, 0f);
    spriteBatch.End();
}

Our Reposition method is what will generate a random location in our grid at which the orange will be placed. The Load method requires a ContentManager instance and handles loading our orange texture from file. Lastly the Draw method takes in a SpriteBatch instance and handles rendering the orange using our Grid class's DrawSprite method.

Before continuing on, let's give this class a try to make sure it works like we think it should. First let's head to the Game1 class and add a new variable for the orange. We'll also set our starting game state to the InGame playing state:

private Orange orange = new Orange();
private GameState state = GameState.InGame;

Then we need to make sure call the orange's Load method in our LoadContent method:

protected override void LoadContent()
{
    spriteBatch = new SpriteBatch(GraphicsDevice);
    titleFont = Content.Load<SpriteFont>("Fonts/TitleFont");
    mediumFont = Content.Load<SpriteFont>("Fonts/MediumFont");
    miniFont = Content.Load<SpriteFont>("Fonts/MiniFont");

    orange.Load(Content);
}

Next we'll go to our UpdateInGame method and add in some code that will call the orange's Reposition method every second:

private void UpdateInGame(GameTime gameTime)
{
    if (gameTime.TotalGameTime.Milliseconds % 1000 == 0)
        orange.Reposition();
}

Lastly we'll add to the DrawInGame method so that it call's the orange's Draw method:

private void DrawInGame()
{
    orange.Draw(spriteBatch);
}

Build and run the game. You should see the same gray window with a single orange drawn. Every second the orange will move to a new grid location on the screen.

Now we will be creating our Snake class:

public class Snake
{ }

The Snake class is a bit more complex. Logically let's lay out what data the class will need:

• A list of points for each segment of the body.
• The four textures (head, straight body piece, angled body piece, and tail) with which we will render the snake
• A value indicating how fast the snake should be moving.
• A value indicating the snake's current direction and the direction he will be moving next.
• A value indicating whether or not to extend the snake's length the next time it moves.
• A timer value so that we can control how often the snake moves from grid cell to grid cell.

A good amount of data for something that seems rather simple. We'll start by creating an enumeration for those direction values we are going to need:

public enum Direction
{
    Up,
    Down,
    Left,
    Right
}

Next we'll go ahead and add all the variables to our Snake class itself:

public const float MoveSpeed = .2f; 
private float moveTimer;
private Texture2D head, straight, angle, tail;
private List<Point> bodyPoints = new List<Point>();
private Direction currentDirection = Direction.Right;
private Direction nextDirection = Direction.Right;
private bool extending;

Everything here should be rather self explanatory. The MoveSpeed represents the number of seconds before the snake proceeds to the next grid cell and the moveTimer will be used to count up to this value. We then have our four textures, a list for the body points, and two values for the current and next direction. Lastly our bool value to tell us whether the snake should extend the next time it moves.

Now we're going to add a new method called Reset which will be called from the Snake's constructor. Reset is responsible for placing our Snake it its starting position in the game.

public Snake()
{
    Reset();
}

public void Reset()
{
    bodyPoints.Clear();

    bodyPoints.Add(new Point(2, 0));
    bodyPoints.Add(new Point(1, 0));
    bodyPoints.Add(new Point(0, 0));

    currentDirection = Direction.Right;
    nextDirection = Direction.Right;
}

In the Reset method, first we make sure to clear out the list of points for the snake's body. Next we add three points to the body. The first point sets the position of the head, followed by a single body piece, and lastly the tail. To finish we also make sure to reset both the current and next direction values to Right so that the snake begins by heading to the right.

Next we'll make a Load method which, like the Orange class, handles loading in the textures needed to render the snake:

public void Load(ContentManager content)
{
    head = content.Load<Texture2D>("Sprites/Head");
    straight = content.Load<Texture2D>("Sprites/Straight");
    angle = content.Load<Texture2D>("Sprites/Angle");
    tail = content.Load<Texture2D>("Sprites/Tail");
}

Continuing on we're going to implement the rendering for the snake. This is the most complex part of this entire game, but we'll take it one step at a time to make sure each line of code is explained. First let's add the five methods we'll be using:

public void Draw(SpriteBatch spriteBatch)
{
    spriteBatch.Begin();

    for (int i = 1; i < bodyPoints.Count - 1; i++)
    {
        DrawBody(
            spriteBatch, 
            bodyPoints[i], 
            bodyPoints[i - 1], 
            bodyPoints[i + 1]);
    }

    DrawTail(spriteBatch);
    DrawHead(spriteBatch);
    spriteBatch.End();
}

private void DrawHead(SpriteBatch spriteBatch) { }
private void DrawTail(SpriteBatch spriteBatch) { }
private bool IsAnglePiece(Point current, Point last, Point next) { }
private void DrawBody(SpriteBatch spriteBatch, Point current, Point last, Point next) { }
private float GetAngleRotation(Point current, Point last, Point next) { }

We can see that we have broken the rendering up into multiple methods to make the code a bit more organized. We have the main Draw method which will be used by our Game1 class to handle drawing the snake. The method has a single SpriteBatch instance for a parameter.

Then we loop through the bodyPoints list starting on the second item and going up to the second to last item. We intentionally do not use the first or last points because those represent the head and tail, respectively.

After we draw the body, we then draw the tail and head. The order in which we call these methods will affect the graphics to a small degree. The important part is drawing the head last. By doing this we ensure that even when the head and a body piece overlap (for instance, when the snake runs into itself) the head will be drawn on top of the body part.

Next we'll go ahead and fill in the DrawHead method:

private void DrawHead(SpriteBatch spriteBatch)
{
    Point headPoint = bodyPoints[0];
    Point nextBody = bodyPoints[1];

    float rotation;
    if (headPoint.Y == nextBody.Y - 1)
    {
        rotation = -MathHelper.PiOver2;
    }
    else if (headPoint.Y == nextBody.Y + 1)
    {
        rotation = MathHelper.PiOver2;
    }
    else if (headPoint.X == nextBody.X - 1)
    {
        rotation = MathHelper.Pi;
    }
    else
    {
        rotation = 0f;
    }

    Grid.DrawSprite(spriteBatch, head, headPoint, rotation);
}

While this looks really complex, it's rather simply once you look at it. First we get out the position of the head and then the first body point after that. What we then do is compare those points to figure out what angle to use when rendering the head. Finally we just use the Grid.DrawSprite method to render the head to the screen.

Now we'll fill in the DrawTail method. This method is almost identical to the DrawHead method so there really is no explanation needed:

private void DrawTail(SpriteBatch spriteBatch)
{
    Point tailPoint = bodyPoints[bodyPoints.Count - 1];
    Point lastBody = bodyPoints[bodyPoints.Count - 2];

    float rotation;
    if (tailPoint.Y == lastBody.Y - 1)
    {
        rotation = MathHelper.PiOver2;
    }
    else if (tailPoint.Y == lastBody.Y + 1)
    {
        rotation = -MathHelper.PiOver2;
    }
    else if (tailPoint.X == lastBody.X + 1)
    {
        rotation = MathHelper.Pi;
    }
    else
    {
        rotation = 0f;
    }

    Grid.DrawSprite(spriteBatch, tail, tailPoint, rotation);
}

We'll tackle the IsAnglePiece method next. This method is used by the DrawBody method to determine if a given point should be drawn with the angled body piece or the straight body piece. To do this we compare the positions of the current body piece, the previous body piece, and the next body piece to determine if they make up a right angle or not:

private bool IsAnglePiece(Point current, Point last, Point next)
{
    return (current.X == last.X && current.X != next.X && current.Y != last.Y) ||
           (current.X == next.X && current.X != last.X && current.Y != next.Y);
}

With that completed we can fill in the DrawBody method. This method is also pretty simple:

private void DrawBody(SpriteBatch spriteBatch, Point current, Point last, Point next)
{
    if (IsAnglePiece(current, last, next))
    {
        Grid.DrawSprite(
            spriteBatch, 
            angle, 
            current, 
            GetAngleRotation(current, last, next));
    }
    else if (current.X != last.X)
    {
        Grid.DrawSprite(
            spriteBatch, 
            straight, 
            current, 
            0f);
    }
    else if (current.Y != last.Y)
    {
        Grid.DrawSprite(
            spriteBatch, 
            straight, 
            current, 
            MathHelper.PiOver2);
    }
}

First we check to see if the three points comprise and angle. If they do we use the Grid.DrawSprite method to render the angle texture at the current position. For the angle we utilize the GetAngleRotation method which we will be filling in later.

If we don't have an angle piece, we then figure out whether the body piece is horizontal or vertical and use that to render the straight body piece with either zero or PiOver2 as the angle.

Finally we come to the GetAngleRotation method. This method takes three Points and determines the angle at which the sprite must be drawn in order to connect the three body pieces. Here's the code for this method:

private float GetAngleRotation(Point current, Point last, Point next)
{
    Point negPiOver2 = new Point(next.X + 1, last.Y - 1);
    Point negPiOver22 = new Point(last.X + 1, next.Y - 1);

    Point pi = new Point(next.X - 1, last.Y - 1);
    Point pi2 = new Point(last.X - 1, next.Y - 1);

    Point piOver2 = new Point(next.X - 1, last.Y + 1);
    Point piOver22 = new Point(last.X - 1, next.Y + 1);

    if (current == negPiOver2 || current == negPiOver22)
    {
        return -MathHelper.PiOver2;
    }
    else if (current == pi || current == pi2)
    {
        return MathHelper.Pi;
    }
    else if (current == piOver2 || current == piOver22)
    {
        return MathHelper.PiOver2;
    }
    else
    {
        return 0f;
    }
}

The method begins by calculating a set of Points. Each pair of points represents one of the combinations that will result in a particular angle. This can take a little bit to wrap your head around, so if you have trouble visualizing it, I'd recommend grabbing (or making) some grid paper and drawing the points out so you can see how they all fall into place.

We then go through and compare the current point to each set of our values. If any match up, we return that value. If none match, we don't have any rotation to apply to the sprite.

That completes the snake's rendering system. It was a pretty big hill to take, but with it behind us we can feel good knowing that the rest of the code will be quite a bit simpler. Before we move on, let's head back to the Game1 class to test out our new class and make sure it works.

First we'll add a new variable for the snake:

private Snake snake = new Snake();

Next we head to the LoadContent method and make sure we call the snake's Load method:

snake.Load(Content);

Lastly for this test we'll just add a call to the snake's Draw method in our DrawInGame method:

private void DrawInGame()
{
    orange.Draw(spriteBatch);
    snake.Draw(spriteBatch);
}

Go ahead and run the game now and you should see the little snake in the top-left corner of the screen along with the orange that we added earlier:

There is already one issue with our game. The orange, as it keeps repositioning, occasionally will position itself underneath the snake. We want to avoid this at all costs. To accomplish this we need to add a new method to the Snake class called IsBodyOnPoint which will tell us whether a given grid cell is occupied by one of the snake's body parts. To do this we simply leverage the list's Contains method:

public bool IsBodyOnPoint(Point p)
{
    return bodyPoints.Contains(p);
}

Next we will modify the Orange class's Reposition method to take in a snake instance and use this to make sure we generate a random point not occupied by the snake:

public void Reposition(Snake snake)
{
    do
    {
        Position = new Point(rand.Next(Grid.MaxColumn), rand.Next(Grid.MaxRow));
    } while (snake.IsBodyOnPoint(Position));
}

By using the do-while loop, we ensure that we will run that code at least once. Then if the position is found to be occupied by the snake, the code will continue looping until an unoccupied space has been found.

Let's go ahead and update our code found in the Game1 UpdateInGame method to match this new method signature:

private void UpdateInGame(GameTime gameTime)
{
    if (gameTime.TotalGameTime.Milliseconds % 1000 == 0)
        orange.Reposition(snake);
}

Now if you run the game, you'll notice the orange will never, ever position itself underneath of the snake. We now have enough of the core to begin working on making the snake move around. Let's head to the Snake class and add a few new methods:

public void Update(GameTime gameTime)
{ }

private void HandleInput()
{ }

private void MoveSnake()
{ }

These three methods will handle all of our update code for the snake. First we'll start by filling in the main Update method:

public void Update(GameTime gameTime)
{
    HandleInput();

    moveTimer += (float)gameTime.ElapsedGameTime.TotalSeconds;

    if (moveTimer < MoveSpeed)
    {
        return;
    }

    moveTimer = 0f;
    currentDirection = nextDirection;
    MoveSnake();
}

The first thing our method does is call the HandleInput. Next we add the elapsed time in seconds to our moveTimer variable. Then we see if the moveTimer is less than the MoveSpeed value. If moveTimer is less than the MoveSpeed we know that enough time has not elapsed so we call ‘return' to exit out of our update method. If moveTimer has exceeded the MoveSpeed value, we proceed on with updating. The next thing we do is reset the moveTimer. Then we assign the nextDirection as our currentDirection and call the MoveSnake method.

We'll continue by filling in the HandleInput method:

private void HandleInput()
{
    GamePadState gps = GamePad.GetState(PlayerIndex.One);

    if (gps.IsButtonDown(Buttons.DPadDown) && currentDirection != Direction.Up)
    {
        nextDirection = Direction.Down;
    }
    if (gps.IsButtonDown(Buttons.DPadUp) && currentDirection != Direction.Down)
    {
        nextDirection = Direction.Up;
    }
    if (gps.IsButtonDown(Buttons.DPadLeft) && currentDirection != Direction.Right)
    {
        nextDirection = Direction.Left;
    }
    if (gps.IsButtonDown(Buttons.DPadRight) && currentDirection != Direction.Left)
    {
        nextDirection = Direction.Right;
    }
}

All we are doing here is finding out which DPad direction is down and using that for the next direction. We also check to make sure that the next direction is not the direct opposite of the current direction. Pretty simple.

Next is the MoveSnake method. This method takes care of two things for us. First it handles updating all the body points in the snake to move him around the grid. The second thing it handles is inserting new body pieces as requested. Let's take a look at the code:

 private void MoveSnake()
{
    Point p1 = bodyPoints[0];
    switch (currentDirection)
    {
        case Direction.Up:
            bodyPoints[0] = new Point(p1.X, p1.Y - 1);
            break;
        case Direction.Down:
            bodyPoints[0] = new Point(p1.X, p1.Y + 1);
            break;
        case Direction.Left:
            bodyPoints[0] = new Point(p1.X - 1, p1.Y);
            break;
        case Direction.Right:
            bodyPoints[0] = new Point(p1.X + 1, p1.Y);
            break;
    }
    if (extending)
    {
        bodyPoints.Insert(1, p1);
        extending = false;
        return;
    }
    for (int i = 1; i < bodyPoints.Count; i++)
    {
        Point p2 = bodyPoints[i];
        bodyPoints[i] = p1;
        p1 = p2;
    }
}

Going through this little by little, what we first do is get the position of the head to store that for the next body part. We then use the currentDirection value to move the head to the next position it should be at.

Following that we see if we need to add in a new body piece. If we need to, we simply insert the point the head used to be at into the list behind the head and exit the method since we have filled the gap left by moving our head.

If we did not extend, we then loop through all remaining body parts (including the tail) and update them by moving them to position of the body part in front of them.

We'll follow this up by again testing our code to make sure it all works. Head back to the Game1 class and update the UpdateInGame method to call the snake's Update method:

private void UpdateInGame(GameTime gameTime)
{
    if (gameTime.TotalGameTime.Milliseconds % 1000 == 0)
        orange.Reposition(snake);
    snake.Update(gameTime);
}

Now when you run the game your snake will take off towards the right. You can now use the DPad of your Xbox 360 controller (or Zune if you have deployed it there) to direct the snake around.

At this point we have all the ground work in place. Let's go ahead and make our gameplay actually goal oriented. First let's increase functionality that lets our snake eat the oranges. For us to do this, we need to be able to see if the snake's head is in the same grid cell as the orange. Our orange already has a position value, so we just need to add a method to see if the snake's head is at that position. We'll add the following method now to our Snake class:

public bool IsHeadAtPosition(Point position)
{
    return (bodyPoints[0] == position);
}

All this method does is compare the first point in our array to the position given and return if the two values are the same. With this in place, let's fix up the UpdateInGame method to only reposition the orange when the snake eats it:

private void UpdateInGame(GameTime gameTime)
{
    snake.Update(gameTime);

    if (snake.IsHeadAtPosition(orange.Position))
        orange.Reposition(snake);
}

Our orange is now updated appropriately so that it only repositions itself if eaten by the snake. However our snake still doesn't actually grow like he should. So we'll add another method to the Snake class that tells our snake to extend itself:

public void Extend()
{
    extending = true;
}

We can now add this to our UpdateInGame method so that when the snake eats the orange, not only does the orange reposition itself, but the snake will also grow the next time it moves:

private void UpdateInGame(GameTime gameTime)
{
    snake.Update(gameTime);

    if (snake.IsHeadAtPosition(orange.Position))
    {
        orange.Reposition(snake);
        snake.Extend();
    }
}

Now we're making some progress. We still have a big problem: there's no way to lose. In the original game of Snake you would lose by either crashing into the wall of the window or by making the snake crash into itself. We can address both of these cases by adding two methods to the Snake class:

public bool IsLooped()
{
    for (int i = 1; i < bodyPoints.Count; i++)
        if (IsHeadAtPosition(bodyPoints[i]))
            return true;

    return false;
}

public bool IsHeadOffScreen()
{
    Point h = bodyPoints[0];
    return (h.X < 0 || h.Y < 0 || h.X >= Grid.MaxColumn || h.Y >= Grid.MaxRow);
}

The first method, IsLooped, tests all body pieces against the head to see if the head is on the same space as them. The second method, IsHeadOffScreen, checks to see if the head is out of the valid grid locations. Let's head back to the UpdateInGame method and add in these tests:

private void UpdateInGame(GameTime gameTime)
{
    snake.Update(gameTime);

    if (snake.IsHeadAtPosition(orange.Position))
    {
        orange.Reposition(snake);
        snake.Extend();
    }

    if (snake.IsLooped())
        state = GameState.GameOver;

    if (snake.IsHeadOffScreen())
        state = GameState.GameOver;
}

We now have the ability to lose the game which brings us very close to having a completed game. Let's now add some code to the start of the UpdateInGame method to let the user exit back to the title screen by pressing the Back button.

private void UpdateInGame(GameTime gameTime)
{
    if (IsNewButtonPress(Buttons.Back))
        state = GameState.Title;

    snake.Update(gameTime);

    if (snake.IsHeadAtPosition(orange.Position))
    {
        orange.Reposition(snake);
        snake.Extend();
    }

    if (snake.IsLooped())
        state = GameState.GameOver;

    if (snake.IsHeadOffScreen())
        state = GameState.GameOver;
}

We are just about done with all of the code for the UpdateInGame method. Let's finish up by adding the ability to count the oranges that have been eaten. First we need to add a new integer variable to the Game1 class to hold the score:

private int score;

We now just increment the score every time the snake eats and orange. Inside of our UpdateInGame method, update the code for the snake eating the orange to look like this:

if (snake.IsHeadAtPosition(orange.Position))
{
    orange.Reposition(snake);
    snake.Extend();
    score++;
}

We can now focus on finishing the drawing for the DrawInGame. All we need to do is display the current score on the screen. We'll start by adding a new string constant to the Game1 class:

private const string scoreFormat = "Oranges Eaten: {0}";

The “{0}” in there, if you haven't worked with format strings before, is a placeholder that specifies where we want to insert our score.

Now let's head down to the DrawInGame method and add in the code to draw the score to our screen:

private void DrawInGame()
{
    orange.Draw(spriteBatch);
    snake.Draw(spriteBatch);
    DrawText(miniFont, string.Format(scoreFormat, score), new Vector2(120f, 5f));
}

We can run the game and now see how well we're doing:

We can now quickly fill in both the UpdateGameOver and DrawGameOver screens to simply display the results of the game and await input to return to the title screen. First we'll add two more string constants to the game:

private const string gameOver = "Game Over!";
private const string gameOverInstructions = "Press Play to Continue";

And then we can fill in the code for our two methods:

private void UpdateGameOver()
{
    if (IsNewButtonPress(Buttons.B))
        state = GameState.Title;
}

private void DrawGameOver()
{
    orange.Draw(spriteBatch);
    snake.Draw(spriteBatch);

    DrawText(titleFont, gameOver, new Vector2(120f, 25f));
    DrawText(mediumFont, string.Format(scoreFormat, score), new Vector2(120f, 200f));
    DrawText(mediumFont, gameOverInstructions, new Vector2(120f, 225f));
}

You can see that we not only draw text in our state, but we also draw the orange and snake. This lets the user see where things were when the game ended and is a nice touch to add to the game.

The last thing we add is the code to make sure that the UpdateTitleScreen method makes sure to reset the snake, orange, and score when the user starts a new game:

private void UpdateTitleScreen()
{
    if (IsNewButtonPress(Buttons.Back))
        Exit();

    if (IsNewButtonPress(Buttons.B))
    {
        snake.Reset();
        score = 0;
        orange.Reposition(snake);
        state = GameState.InGame;
    }
}

And lastly we make sure the initial state is set to the title screen:

private GameState state = GameState.Title;

With that your game is complete! You now have a fully functional Snake clone. “But what about the Zune?”, you ask. Let's take care of that right now.

XNA Game Studio has always aimed to be a cross-platform tool and the new Zune support is no exception. Getting our project onto a Zune is literally just a matter of clicks. First right click on your game project in the Solution Explorer and choose the Create Copy of Project for Zune menu item. When completed you will have a complete duplicate project that targets the Zune platform. The Solution Explorer should now look like this:

Next we need to build and deploy the game to the Zune. This process is also rather simple. If you went through the tutorial on the download instructions page, this will already be familiar to you. If not, we'll cover the whole process here.

Head up to the Tools menu and choose the Launch XNA Game Studio Device Center option. You will be presented with a window that looks like this:

Click on the Add Device button and you will see the following dialog:

We want to add a Zune, so click on the Zune button. You should see your Zune appear in the window now:

Note: If your Zune did not appear in the window,make sure you have the latest Zune firmware on your device and that the Zune Player application is closed.

From here select your Zune and press the Next button. After a brief moment you will see the success screen:

Press the Finish button and then close the XNA Game Studio Device Center.

Now click on the Zune project you created earlier and go up to the Build menu and click on Deploy Zune Copy of SammyTheSnake to begin deploying the game to your Zune.

You should see the Zune screen update to show that the game is deploying. Once the text on the screen changes to ”connected” or “waiting for computer”, your game has been completely deployed.

To get to the game on your Zune, simply press the center button to exit XNA Game Studio Connect. Next navigate in your main menu to find the Games option. Inside of there will you will see your newly deployed game. Simply click Play and away you go. Enjoy the new snake game and good luck on your adventures of Zune game development with XNA Game Studio.

In this article I'll take you along for the ride as I attack the learning curve required to create a fun, interactive application using both the Microsoft Windows Presentation Foundation (WPF) and the Windows Communication Foundation (WCF). Afterwards, you'll have a flexible trivia client/server game ready to play by yourself or against friends, coworkers and your local know-it-all.  And in honor of Halloween, I've included three games of horror movie trivia.

Steve Holstad The Bright Lights Difficulty: Advanced Time Required: 6-10 hours Cost: Free Software: Visual Studio Express, 2005, 2008 Beta 2 Microsoft .NET Framework 3.0 Hardware: Download: Download Source

What can YeahTrivia do for me?

Glad you asked. This project started when I decided I wanted to dive headfirst into learning WPF and WCF, without hacking through countless Hello World examples.  And I wanted something fun that I could improve over time as my skills developed in these new technologies.  In this article I'll take you along for the ride as I attack the learning curve required to create a fun, interactive application using both the Microsoft Windows Presentation Foundation (WPF) and the Windows Communication Foundation (WCF). Afterwards, you'll have a flexible trivia client/server game ready to play by yourself or against friends, coworkers and your local know-it-all.  And in honor of Halloween, I've included three games of horror movie trivia.

In case you were wondering, the "YeahTrivia" name honors my new bride & her favorite prefix.  Think of it as YeeeeaaaaahhTrivia!

Basic Setup

This demo project was built using Visual Studio 2008 Beta 2, and is based on the Microsoft .NET Framework version 3.0.  The game is fed by a small windows app that acts as a game server, providing game selection, user registration, question loading, response times, chat messaging and scorekeeping.  The server loads a game by reading a predefined XML format, which we will look at a bit later.  This dynamic load lets anyone create their own flavor of trivia game, with any number of questions.

The server app exposes one WCF endpoint, a wsDualHttpBinding channel that supports duplex (two-way) communication between the server and any number of game clients.  Clients attach themselves to this endpoint and provide a callback address to the server.  The server saves an instance of this callback channel and uses each client's instance to contact the clients en masse during general game flow.  Enough talk, here's how to build one yourself.

Trivia Common and WCF Service Interfaces

The TriviaCommon project provides both the server and client projects access to shared objects.  To keep things simple the Common project only contains two classes:

Constants.cs defines the AnswerItem enumeration, which gives easy access to the five answer options (None, A, B, C, D), and the QuestionItem struct.  This structure is delivered to the client and contains question text, answer text, and the correct answer object of type AnswerItem.  Notice that objects being directly passed over the wire need to be marked with the [DataContract] attribute.

The second class, Interfaces.cs is where our WCF fun begins.  Take a look:

using System;
using System.Collections.Generic;
using System.ServiceModel;
using System.Text;

namespace Trivia.Common
{
    #region Interfaces

    #region Service Interface

    /// <summary>
    /// Interface that defines Trivia service contract.
    /// </summary>
    [ServiceContract(CallbackContract = typeof(ITriviaCallback))]
    public interface ITrivia
    {
        [OperationContract(IsOneWay = true)]
        void RegisterUser(string userName);

        [OperationContract(IsOneWay = true)]
        void AcceptAnswer(string userName, string answerValue);

        [OperationContract(IsOneWay = true)]
        void ChatPublish(string userName, string message);
    }

    #endregion Service Interface

    #region Client Callback Interface

    /// <summary>
    /// Interface that defines Trivia client callback contract.
    /// </summary>
    public interface ITriviaCallback
    {        
        [OperationContract(IsOneWay = true)]
        void OnGameStart(int questionCount);

        [OperationContract(IsOneWay = true)]
        void OnGameEnd();

        [OperationContract(IsOneWay = true)]
        void OnUserRegistered(string userName);

        [OperationContract(IsOneWay = true)]
        void OnPublishChat(string userName, string chatMessage);

        [OperationContract(IsOneWay = true)]
        void OnQuestionLoad(int questionIndex, QuestionItem questionItem);

        [OperationContract(IsOneWay = true)]
        void OnQuestionEnd();

        [OperationContract(IsOneWay = true)]
        void OnQuestionStatusUpdate(Int64 questionTimeRemaining);

        [OperationContract(IsOneWay = true)]
        void OnScoreboardUpdate(Dictionary<string, Int64> scoreboard);

        [OperationContract(IsOneWay = true)]
        void OnGameServerStopped();
    }

    #endregion Client Callback Interface

    #endregion Interfaces
}

VB:

Imports System
Imports System.Collections.Generic
Imports System.ServiceModel
Imports System.Text

Namespace Trivia.Common

#Region "Interfaces"

#Region "Service Interface"
    
    ''' <summary>
    ''' Interface that defines Trivia service contract.
    ''' </summary>
    <ServiceContract(CallbackContract:=GetType(ITriviaCallback))> _
    Public Interface ITrivia
        <OperationContract(IsOneWay:=True)> _
        Sub RegisterUser(ByVal userName As String)

        <OperationContract(IsOneWay:=True)> _
        Sub AcceptAnswer(ByVal userName As String, ByVal answerValue As String)

        <OperationContract(IsOneWay:=True)> _
        Sub ChatPublish(ByVal userName As String, ByVal message As String)
    End Interface
        
#End Region

#Region "Client Callback Interface"

    ''' <summary>
    ''' Interface that defines Trivia client callback contract.
    ''' </summary>
    ''' <remarks></remarks>
    Public Interface ITriviaCallback
        <OperationContract(IsOneWay:=True)> _
      Sub OnGameStart(ByVal questionCount As Integer)

        <OperationContract(IsOneWay:=True)> _
        Sub OnGameEnd()

        <OperationContract(IsOneWay:=True)> _
        Sub OnUserRegistered(ByVal userName As String)

        <OperationContract(IsOneWay:=True)> _
        Sub OnPublishChat(ByVal userName As String, ByVal chatMessage As String)

        <OperationContract(IsOneWay:=True)> _
        Sub OnQuestionLoad(ByVal questionIndex As Integer, ByVal questionItem As QuestionItem)

        <OperationContract(IsOneWay:=True)> _
        Sub OnQuestionEnd()

        <OperationContract(IsOneWay:=True)> _
        Sub OnQuestionStatusUpdate(ByVal questionTimeRemaining As Long)

        <OperationContract(IsOneWay:=True)> _
        Sub OnScoreboardUpdate(ByVal scoreboard As Dictionary(Of String, Long))

        <OperationContract(IsOneWay:=True)> _
        Sub OnGameServerStopped()

    End Interface

#End Region

#End Region

End Namespace

A few items of interest here.  Notice we're importing the System.ServiceModel namespace.  This is the key assembly when using WCF, so don't forget to add a reference to your project.  The first interface, ITrivia, defines the operations the server is required to implement, which handle basic user actions: Register a team, accept an answer and accept a chat message.  Easy.

The second interface, cleverly named ITriviaCallback, lays out the callback contract a client must fulfill in order to play nicely with our server.  The operations listed here describe events the server will publish.  These aren't actual events, but the naming convention "OnX..." helps you remember that these are server published activities.

Notice that the [OperationContract] attribute notifies WCF that each method is part of a service contract.  The IsOneWay flag gives us "fire-and-forget" behavior (the app shouldn't wait around for a response).  So now that the common objects are ready, let's move on to...

Building the Trivia Server

The YeahTrivia Server is a simple utility app, but don't let the plain looks fool you; I thought about calling this the BrainStumper Pumper, but this is a family site.  This app lets a user (anyone acting as game admin) start the service, select the desired game, await team registrations, and then start the game.  If this were to become a larger scale project, I would make this an IIS hosted service that manages multiple games and provides more autonomy.  Until those sports bar royalty checks start rolling in, however, a utility app will do just fine.

The only form, GameServerDashboard, simply provides user interaction with the GameServer class.  On startup, the form inits an instance of GameServer and tells it to start the service.  It also loads all trivia question sets from the Games directory, and displays them in the list.

GameServer is the brain behind YeahTrivia. The attributes below set up the GameServer for action:

C#:

[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant
        ,InstanceContextMode = InstanceContextMode.Single)]
    public class GameServer : ITrivia

VB:

<ServiceBehavior(ConcurrencyMode:=ConcurrencyMode.Reentrant, InstanceContextMode:=InstanceContextMode.Single)> _
    Public Class GameServer
        Implements ITrivia

ConcurrencyMode.Reentrant prevents deadlocks between the apps by stating that while this service is single-threaded, callbacks are allowed to invoke new operations.

InstanceContextMode.Single sets the service as a singleton, so that all messages are delivered to the same object instance.

These are advanced topics if you're new to WCF, so I'll include some links at the end that helped clarify some of this for me.  Let's keep moving forward by looking at a few activities of the game server:

Start the Service:  Passes in the configured base address as a Uri, inits and opens a new ServiceHost.

C#:

public void StartService()
{
   // Set base address and open service host
   Uri baseAddress = new Uri(ConfigurationManager.AppSettings[CONFIG_KEY_BASEURI]);
   _serviceHost = new ServiceHost(new GameServer(), baseAddress);
   _serviceHost.Open();
}

VB:

  Public Sub StartService()
     'Set base address and open service host
     Dim baseAddress As New Uri(ConfigurationManager.AppSettings(CONFIG_KEY_BASEURI))
     _serviceHost = New ServiceHost(New GameServer(), baseAddress)
     _serviceHost.Open()
  End Sub

Register a new team: Saves off the callback, adds it to the callback collection and scoreboard containers, notifies the user of a successful registration, and notifies all game clients of the new team.

C#:

 public void RegisterUser(string userName)
 {
     _currentCallback = OperationContext.Current.GetCallbackChannel<ITriviaCallback>();

     // Store callback
     if (!_callbacks.ContainsKey(userName))
     {
         _callbacks.Add(userName, _currentCallback);
         _scoreboard.Add(userName, 0);

         // Notify user of registration
         _currentCallback.OnUserRegistered(userName);

         // Notify clients of new user
         foreach (string userKey in _callbacks.Keys)
         {
            _currentCallback = _callbacks[userKey];
            _currentCallback.OnPublishChat(GAME_USERKEY, string.Format(FORMAT_USER_REGISTERED, userName));
         }                
     }
     else
     {
         // User already registered, throw exception
         throw new Exception(ERROR_USER_ALREADY_EXISTS);
     }
 }

VB:

Public Sub RegisterUser(ByVal userName As String) Implements ITrivia.RegisterUser
   _currentCallback = OperationContext.Current.GetCallbackChannel(Of ITriviaCallback)()

   'Store callback
   If Not _callbacks.ContainsKey(userName) Then
      _callbacks.Add(userName, _currentCallback)
      _scoreboard.Add(userName, 0)

      'Notify user of registration
      _currentCallback.OnUserRegistered(userName)

      'Notify clients of new user
      For Each userKey As String In _callbacks.Keys
         _currentCallback = _callbacks(userKey)
         _currentCallback.OnPublishChat(GAME_USERKEY, String.Format(FORMAT_USER_REGISTERED, userName))
      Next
   Else
      'User already registered, throw exception
      Throw New Exception(ERROR_USER_ALREADY_EXISTS)
   End If
End Sub

You can start to see how the server is able to handle incoming calls and process them back to the clients using the duplex channel.  I'll leave the rest of the server actions for you to examine on your own.

Building the Game Client (WCF)

Address, Binding, Contract.  These are the ABC's of WCF.  The client's app.config file handles connecting to the service and specifying the channel and contract used to interact with it.  Examine the client portion of the client .config:

<client>
   <endpoint address="http://localhost:8088/Trivia" binding="wsDualHttpBinding"
      bindingConfiguration="WSDualHttpBinding_ITrivia" contract="Trivia.Common.ITrivia"
      name="WSDualHttpBinding_ITrivia">
   </endpoint>
</client>

The address points to the exposed service endpoint.  The binding sets the channel as "wsDualHttpBinding" (our http duplex channel).  The bindingConfiguration attribute is an optional pointer to another group of configurations for the binding, and finally, the contract sets the interface with which our client will be interacting.

Next it's time to generate a proxy class.  Memorize this: Svcutil.exe is your friend.  The client needs a proxy class that it can use to interact with the service model.  The utility is a bit tricky at first, because of the wealth of optional flags, but stick with it, it's better than coding the proxy class by hand!  You can generate your client code by starting the service and running a command line similar to this:

svcutil /language:cs /out:ServerProxy.cs http://localhost:8088/Trivia

Add the generated class to the client project and you can begin to interact with the service.  The svcutil is available as part of the Windows SDK.  Check out the referenced site below for more information on this handy utility.

Building the Game Client (WPF)

Building the WPF portion of the client app was really a learning experience, and it will be the priority for me to improve in a later version.  Learning to program in XAML markup can seem daunting, and it requires a large paradigm shift on your part in order to grasp the new concepts.  Microsoft Expression is powerful tool for XAML work, but this time I coded all of the XAML by hand in order to fully see what was taking place inside.

A deep discussion of WPF is beyond the scope of this article, but take a look at the example code to get an idea of the layout.  An excellent book to start with is WPF Unleashed by Adam Nathan.  An easy read (for a programming book), and solid examples to get you rolling.

I've set up the client using a instance of the Window class, which is shown below:

<Window x:Class="Trivia.Client.GameClient"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="YeahTrivia" MinHeight="620" MinWidth="620" 
    WindowStartupLocation="CenterScreen" WindowState="Normal"  Style="{DynamicResource MainWindowStyle}"
    Background="{DynamicResource MainWindowBackgroundBrush}">

The window class sets up the outermost container of the app, and includes two default namespaces.  I've also set a few other properties here: a min height and width, window startup location & state, and two styling attributes set by dynamic resources.

Resources are a great way to further separate form & function, allowing a programmer to handle the behavior of an app, while a designer can work simultaneously on the look, all without stepping on too many toes.  As a 2.0 task for this project, I would remove all inline styling and move them into resource dictionaries.  A dictionary contains styles and control templates (a skin) that can be loaded & switched at runtime.

ResourceDictionaries are linked to your XAML in the App.Xaml file.  Once you've set up the reference, the example above show how to reference the current dictionary:  The Background and Style properties are set as dynamic resources by naming the Keys specified in the ResourceDictionary (DefaultResources.xaml):

<LinearGradientBrush x:Key="MainWindowBackgroundBrush" StartPoint=".45,.45" EndPoint=".55,.55" SpreadMethod="Reflect">
   <GradientStop Offset="0" Color="DodgerBlue"/>
   <GradientStop Offset=".8" Color="DarkSlateBlue"/>
</LinearGradientBrush>

<Style TargetType="{x:Type Window}" x:Key="MainWindowStyle">
   <Setter Property="FontFamily" Value="Trebuchet MS"/>
</Style>

Not quite as easy as CSS, but for a Forms project, it's a nice feature.  The sample ResourceDictionary includes a button control template for all of my buttons, based on Rob Eisenberg's excellent article (link below).

One other interesting feature to point out: Take a look at the code-behind class MarshalToUIThread method, which accepts a SendOrPostCallback parameter.  This is where the client is transferring actions from the sync thread back to the UI thread.  In each interface method implementation (OnX..), you can see how I wrap any UI-directed code and assign it to the postCallback field.  Passing this to the MarshalToUIThread method simply issues a SynchronizationContext.Post call, and the UI thread executes as expected.

Creating a New Trivia Game (XML)

New trivia games can be added at any time using the simple XML format shown here.  After installing the server application, simply drop the new .XML file into the Games directory ([Server Install Location]\Yeah Trivia Server\Games).  This demo comes pre-loaded with Geek Trivia, and a special Halloween Trivia version in case you're feeling festive.

<TriviaQuestionDataSet xmlns="http://tempuri.org/TriviaQuestionDataSet.xsd">
  <TriviaQuestion>
    <QuestionText>Name the highest grossing Monty Python creation.</QuestionText>
    <AnswerTextA>A) Holy Grail</AnswerTextA>
    <AnswerTextB>B) The Life of Brian</AnswerTextB>
    <AnswerTextC>C) Shrubbery</AnswerTextC>
    <AnswerTextD>D) The Meaning of Life</AnswerTextD>
    <CorrectAnswerKey>A</CorrectAnswerKey>
  </TriviaQuestion>
  <TriviaQuestion>
    <QuestionText>Ferris Bueller's best friend was _________.</QuestionText>
    <AnswerTextA>A) Sloane Peterson</AnswerTextA>
    <AnswerTextB>B) Edward R. Rooney</AnswerTextB>
    <AnswerTextC>C) Charlie Sheen</AnswerTextC>
    <AnswerTextD>D) Cameron Frye</AnswerTextD>
    <CorrectAnswerKey>D</CorrectAnswerKey>
  </TriviaQuestion>
</TriviaQuestionDataSet>

It's Time to Play YeahTrivia

Install both the Server and Client applications.  First, fire up the server, and then start your game client(s).  Once everyone has registered a team, select your game and hit "Start Game".    You're off...

Game Over

So there you have it.  We've seen how WCF manages communication between objects, extracting complicated service protocols away from your code.  And just a small subset of the WPF functionality has shown us how quickly a rich, XAML-based UI can come together.  And maybe, just maybe, you've learned why a CD is 74 minutes long... but I'm not telling.

I challenge you to improve on this initial version of YeahTrivia:  Crack open the XAML and add animations, images, video, music & more.  Create a self-maintaining server to run multiple games at once.  Add a High Score storage system.  Extend the WCF settings to enable other communication channels.  Add a new skin. Create new question files to share with us.  Whatever you do, have fun and go nuts.  YeahCoding4Fun.

Download source files

Download compiled demo (C# and VB)

About The Author

Steve Holstad works as a software consultant for Clarity Consulting in Chicago.  He blogs at The Bright Lights, and is available via email at sholstad@claritycon.com

References

wcf.netfx3.com/
wpf.netfx3.com/
Generating a client proxy class
ConcurrencyMode
SvcUtil.exe Tutorial
Rob Eisenberg's WPF control template

Special thanks to Bryan Dougherty for the WCF jumpstart, Kevin Marshall for the Halloween Trivia and Jay Garmon, creator of TechRepublic's Geek Trivia.

	In this article, I will discuss how I have built a 2 player 8-Ball game in Silverlight (play here). I will explain how I used the Expression tools to design the graphics and various .NET techniques to enable user control and game animation.
Justin Petersen Coding4Fun at Clarity Difficulty: Intermediate Time Required: 6-10 hours Cost: Free Software: Visual Studio 2008 Beta 2, Silverlight 1.1 Alpha Refresh, Expression Design, Expression Blend 2 Preview Hardware: Download: Download

In this article, I will discuss how I have built a 2 player 8-Ball game in Silverlight (play here). I will explain how I used the Expression tools to design the graphics and various .NET techniques to enable user control and game animation. 

The following components must be implemented to complete this game:

1. Graphics (pool table, pool ball, and pool stick)
2. Vector animation and collision physics
3. User interaction 
4. Game state and control

Before I continue, I'd like to point out that I did not originate all of the code and XAML for this solution. I came up with the idea of creating a Silverlight 8-Ball game after stumbling upon a 2-D “bouncing bubble” animation here: http://www.bubblemark.com/ created by Alexey Gavrilov. 

The original intent for this solution was to compare the performance of the bouncing bubbles across various platforms.  I found this very useful, but was personally interested in making something fun and interactive out of it. 

Getting Started

Prerequisites

The following tools were used to implement this solution:

• Visual Studio 2008 Beta 2
• Silverlight 1.1 Alpha Refresh 
• Expression Design
• Expression Blend

Learning more about game development

If you'd like to learn more about game development, I found a number Coding4Fun posts under Gaming helpful.  In particular, the 2D Game Primer by "ZMan" gives a good overview of the basics (e.g. GameLoop, Sprites, etc.)

Graphics

I am not much of a graphic designer.  In fact, I've spent the majority of my career designing and implementing line of business apps for enterprise customers (typically not a very graphically intensive task).  So I believe it is a decent testament to the effectiveness of the Microsoft Expression suite that I could, in short order, create the graphics for this game. 

I used Expression Design to build the graphics of the pool table.  Modeling my design after the standard dimension of a 9 foot billiards table, I drew the main structure as a rectangle with rounded corners.  I drew a smaller green rectangle centered over it for the playing surface (of course following standard dimensions).  Next, I created 6 black circles placed one level behind the playing surface to give the impression of pockets.  Lastly, I added the wood texture to the outside rectangle (which was super easy as there is a set of wood textures available by default), and drew a simple rounded rectangle beneath the table to serve as a status bar. 

I also created the graphics for my pool stick using Expression Design.  This consisted of a few tapered polygons and 2 half circles for the butt and tip.

After exporting the associated XAML, I imported each element into my project.  From here, I could view and refine the design through a scaled down visual editor or the associated XAML.

Lastly, I inspected the XAML markup for the pool ball I reused from Alexey's Bubblemark solution.  I needed to understand the properties of this object so that I could modify the color of the balls later on.

Vector Animation and Collision Physics

The root of Silverlight8Ball is a Storyboard (x:Name=”GameLoop”) that acts as a triggering mechanism for determining ball velocity, direction, and redirection due to collision. Whereas some Storyboards are implemented with predetermined paths and timelines directly in XAML, the action taken at each tick must be determined dynamically in this game. So we simply set the duration to 00:00:0, and handle the Completed event to trigger our positioning logic. This design effectively creates what game developers call a “Game Loop” that triggers continuous processing to determine application state.

The resulting “GameLoop_Completedhandler” becomes the root processing agent for all of the game's ball movement logic.  

C#

   1: void GameLoop_Completed(object sender, EventArgs e)

   2: {

   3:     switch (m_ActionState)

   4:     {

   5:         case m_ActionStates.BallsMoving:

   6:  

   7:             // prep

   8:             List<Ball> removeList = new List<Ball>();

   9:             bool someBallsAreMoving = false;

  10:  

  11:             // move each ball

  12:             foreach (Ball ball in m_GameBalls)

  13:             {

  14:                 ball.Move();

  15:                 if (ball.InPocket) removeList.Add(ball);

  16:                 else if (ball.IsMoving) someBallsAreMoving = true;

  17:             }

  18:  

  19:             // store balls sunk on shot and update ui 

  20:             foreach (Ball ball in removeList)

  21:             {

  22:                 sunkBalls.Add(ball);

  23:                 RemoveBall(ball);

  24:             }

  25:  

  26:             if (someBallsAreMoving)

  27:             {

  28:                 // update vectors for ball collisions

  29:                 for (int i = 0; i < m_GameBalls.Count; i++)

  30:                 {

  31:                     for (int j = i + 1; j < m_GameBalls.Count; j++)

  32:                     {

  33:                         m_GameBalls[i].DoCollide(m_GameBalls[j]);

  34:                     }

  35:                 }

  36:             }

  37:             else

  38:             {

  39:                 // determine shot results

  40:                 ShotResults results = EvaluateShot();

  41:  

  42:                 // apply state and ui changes

  43:                 UpdateGameState(results);

  44:             }

  45:  

  46:             break;

  47:     }

  48:  

  49:     // restart the storyboard

  50:     if (m_IsRunning)

  51:     {

  52:         GameLoop.Begin();

  53:     }

  54:  

  55: }

VB

   1: Private Sub GameLoop_Completed(ByVal sender As Object, ByVal e As EventArgs)

   2:  

   3:     Select Case m_ActionState

   4:  

   5:         Case m_ActionStates.BallsMoving

   6:  

   7:             ' prep

   8:             Dim removeList As List(Of Ball) = New List(Of Ball)()

   9:             Dim someBallsAreMoving As Boolean = False

  10:  

  11:             ' move each ball

  12:             For Each ball As Ball In m_GameBalls

  13:                 ball.Move()

  14:                 If ball.InPocket Then

  15:                     removeList.Add(ball)

  16:                 ElseIf ball.IsMoving Then

  17:                     someBallsAreMoving = True

  18:                 End If

  19:             Next ball

  20:  

  21:             ' store balls sunk on shot and update ui 

  22:             For Each ball As Ball In removeList

  23:                 sunkBalls.Add(ball)

  24:                 RemoveBall(ball)

  25:             Next ball

  26:  

  27:             If someBallsAreMoving Then

  28:                 ' update vectors for ball collisions

  29:                 For i As Integer = 0 To m_GameBalls.Count - 1

  30:                     For j As Integer = i + 1 To m_GameBalls.Count - 1

  31:                         m_GameBalls(i).DoCollide(m_GameBalls(j))

  32:                     Next j

  33:                 Next i

  34:             Else

  35:                 ' determine shot results

  36:                 Dim results As ShotResults = EvaluateShot()

  37:  

  38:                 ' apply state and ui changes

  39:                 UpdateGameState(results)

  40:             End If

  41:  

  42:     End Select

  43:  

  44:     ' restart the storyboard

  45:     If m_IsRunning Then

  46:         GameLoop.Begin()

  47:     End If

  48:  

  49: End Sub

The above code snippets demonstrate the full functionality of our GameLoop.  However, the primary animation and collision logic are handled by "ball.Move();" and "m_GameBalls[i].DoCollide(m_GameBalls[j]);" lines (in C# example).  The Move() function of each ball applies its current vector (i.e. x and y "velocities") to determine its next position and updates the ball's UI element coordinates.  Once the ball is advanced, the DoCollide function checks if two balls have collided.  If so, their vectors are adjusted accordingly.

C#

   1: public bool DoCollide(Ball b)

   2: {

   3:     // calculate some vectors 

   4:     double dx = this._x - b._x;

   5:     double dy = this._y - b._y;

   6:     double dvx = this._vx - b._vx;

   7:     double dvy = this._vy - b._vy;

   8:     double distance2 = dx * dx + dy * dy;

   9:     

  10:     if (Math.Abs(dx) > this._d || Math.Abs(dy) > this._d)

  11:         return false;

  12:     if (distance2 > this._d2)

  13:         return false;

  14:  

  15:     // make absolutely elastic collision

  16:     double mag = dvx * dx + dvy * dy;

  17:  

  18:     // test that balls move towards each other    

  19:     if (mag > 0)

  20:         return false;

  21:  

  22:     mag /= distance2;

  23:  

  24:     double delta_vx = dx * mag;

  25:     double delta_vy = dy * mag;

  26:  

  27:     this._vx -= delta_vx;

  28:     this._vy -= delta_vy;

  29:  

  30:     b._vx += delta_vx;

  31:     b._vy += delta_vy;

  32:  

  33:     return true;

  34: }

VB

   1: Public Function DoCollide(ByVal b As Ball) As Boolean

   2:     ' calculate some vectors 

   3:     Dim dx As Double = Me._x - b._x

   4:     Dim dy As Double = Me._y - b._y

   5:     Dim dvx As Double = Me._vx - b._vx

   6:     Dim dvy As Double = Me._vy - b._vy

   7:     Dim distance2 As Double = dx * dx + dy * dy

   8:  

   9:     If Math.Abs(dx) > Me._d OrElse Math.Abs(dy) > Me._d Then

  10:         Return False

  11:     End If

  12:     If distance2 > Me._d2 Then

  13:         Return False

  14:     End If

  15:  

  16:     ' make absolutely elastic collision

  17:     Dim mag As Double = dvx * dx + dvy * dy

  18:  

  19:     ' test that balls move towards each other    

  20:     If mag > 0 Then

  21:         Return False

  22:     End If

  23:  

  24:     mag /= distance2

  25:  

  26:     Dim delta_vx As Double = dx * mag

  27:     Dim delta_vy As Double = dy * mag

  28:  

  29:     Me._vx -= delta_vx

  30:     Me._vy -= delta_vy

  31:  

  32:     b._vx += delta_vx

  33:     b._vy += delta_vy

  34:  

  35:     Return True

  36: End Function

User Interaction 

While the GameLoop Storyboard does a good job at managing ball movement, I didn't think it was the best option for handling pool stick and q-ball control.  During times of user control (stick aiming and q-ball "ball in hand"), I chose to use mouse movement and click events to determine object position and angle.  I created my own enumeration to manage switching between ball movement and user control states.  The rest involves some simple statistics and Silverlight XAML transformations.

Pool Stick Aiming and Ball-In-Hand

During a scratch, the MouseMove event allows the affect of moving the q-ball for placement.  During aiming, it allows the user to rotate the poolstick around the q-ball.

C#

   1: void Page_MouseMove(object sender, MouseEventArgs e)

   2: {

   3:  

   4:     m_MousePoint = e.GetPosition(this);

   5:  

   6:     switch (m_ActionState)

   7:     {

   8:         case m_ActionStates.Scratch:

   9:             m_QBall.MoveAbsolute(m_MousePoint.X, m_MousePoint.Y);

  10:             break;

  11:         case m_ActionStates.Aiming:

  12:             m_PoolStick.Rotate(m_MousePoint.X, m_MousePoint.Y, m_QBall.BallCenterX, m_QBall.BallCenterY);

  13:             break;

  14:     }      

  15:     

  16: }

VB

   1: Private Sub Page_MouseMove(ByVal sender As Object, ByVal e As MouseEventArgs)

   2:  

   3:     m_MousePoint = e.GetPosition(Me)

   4:  

   5:     Select Case m_ActionState

   6:         Case m_ActionStates.Scratch

   7:             m_QBall.MoveAbsolute(m_MousePoint.X, m_MousePoint.Y)

   8:         Case m_ActionStates.Aiming

   9:             m_PoolStick.Rotate(m_MousePoint.X, m_MousePoint.Y, m_QBall.BallCenterX, m_QBall.BallCenterY)

  10:     End Select

  11:  

  12: End Sub

The RotateTransform Rocks

The Silverlight RotateTranform is very powerful in this case.  It allows me to simply rotate the pool stick object around a center point (the center of the q-ball) using a relative angle between the mouse point and the ball. 

C#

   1: public void Rotate (double mouseX, double mouseY, double ballX, double ballY)

   2: {

   3:     double vx = ballX - mouseX;

   4:     double vy = ballY - mouseY;

   5:     

   6:     radians = Math.Atan2(vy, vx);

   7:     double angle = radians * (180/Math.PI);

   8:     

   9:     rootCanvas.RenderTransform = new RotateTransform 

  10:     { 

  11:         CenterX = Model.stickBuffer, 

  12:         CenterY = Model.stickHeight/2, 

  13:         Angle = angle 

  14:     };

  15:  

  16: }

VB

   1: Public Sub Rotate(ByVal mouseX As Double, ByVal mouseY As Double, ByVal ballX As Double, ByVal ballY As Double)

   2:     Dim vx As Double = ballX - mouseX

   3:     Dim vy As Double = ballY - mouseY

   4:  

   5:     radians = Math.Atan2(vy, vx)

   6:     Dim angle As Double = radians * (180 / Math.PI)

   7:  

   8:     Dim transform As RotateTransform = New RotateTransform()

   9:     transform.CenterX = Model.stickBuffer

  10:     transform.CenterY = Model.stickHeight / 2

  11:     transform.Angle = angle

  12:  

  13:     rootCanvas.RenderTransform = transform

  14:  

  15: End Sub

Power Control and Q-Ball Placement

Based on the ActionState, the mouse up and mouse down events manage user interaction during power adjustment and q-ball placement.

C#

   1: void Page_MouseLeftButtonUp(object sender, MouseEventArgs e)

   2: {

   3:     if (this.m_ActionState == m_ActionStates.AdjustingPower)

   4:     {

   5:         m_QBall.Strike(m_PoolStick.power, m_PoolStick.radians);

   6:  

   7:         m_PoolStick.StopPowerMovement();

   8:         this.Children.Remove(m_PoolStick);

   9:         this.m_ActionState = m_ActionStates.BallsMoving;

  10:     }

  11: }

  12:  

  13: void Page_MouseLeftButtonDown(object sender, MouseEventArgs e)

  14: {

  15:     switch (m_ActionState)

  16:     {

  17:         case m_ActionStates.Aiming:

  18:             m_PoolStick.StartPowerMovement();

  19:             this.m_ActionState = m_ActionStates.AdjustingPower;

  20:             break;

  21:         case m_ActionStates.Scratch:

  22:             ResetPoolStick();

  23:             m_ActionState = m_ActionStates.Aiming;

  24:             break;

  25:     }

  26: }

VB

   1: Private Sub Page_MouseLeftButtonUp(ByVal sender As Object, ByVal e As MouseEventArgs)

   2:     If Me.m_ActionState = m_ActionStates.AdjustingPower Then

   3:         m_QBall.Strike(m_PoolStick.power, m_PoolStick.radians)

   4:  

   5:         m_PoolStick.StopPowerMovement()

   6:         Me.Children.Remove(m_PoolStick)

   7:         Me.m_ActionState = m_ActionStates.BallsMoving

   8:     End If

   9: End Sub

  10:  

  11: Private Sub Page_MouseLeftButtonDown(ByVal sender As Object, ByVal e As MouseEventArgs)

  12:     Select Case m_ActionState

  13:         Case m_ActionStates.Aiming

  14:             m_PoolStick.StartPowerMovement()

  15:             Me.m_ActionState = m_ActionStates.AdjustingPower

  16:         Case m_ActionStates.Scratch

  17:             ResetPoolStick()

  18:             m_ActionState = m_ActionStates.Aiming

  19:     End Select

  20: End Sub

Game State and Control

The final component to this application is the "business rules" behind the game.  A game of 8-Ball is governed by the results of each player's shot.  Whether that shot ends the game or whose shot it is next is based on what balls are sunk. 

I created another enumeration for ShotResults which defines each potential outcome: GoAgain, NextPlayer, Scratch, ScratchOnEight, PrematureEightBall, and Win. 

C#

   1: private void UpdateGameState(ShotResults results)

   2: {

   3:     string resultText = "";

   4:     

   5:     switch (results)

   6:     {

   7:         // update game states

   8:         case ShotResults.PrematureEightBall:

   9:         case ShotResults.ScratchOnEight:

  10:             resultText = ProcessGameEnd(false, results);

  11:             m_ActionState = m_ActionStates.GameOver;

  12:             break;

  13:         case ShotResults.NextPlayer:

  14:             resultText = "Player looses turn";

  15:             ChangeCurrentPlayer();

  16:             ResetPoolStick();

  17:             m_ActionState = m_ActionStates.Aiming;

  18:             break;

  19:         case ShotResults.GoAgain:

  20:             resultText = "Nice job. Go again.";

  21:             ResetPoolStick();

  22:             m_ActionState = m_ActionStates.Aiming;

  23:             break;

  24:         case ShotResults.Scratch:

  25:             resultText = "Scratch. Player looses turn.";

  26:             ChangeCurrentPlayer();

  27:             AddBall(m_QBall);

  28:             m_ActionState = m_ActionStates.Scratch;

  29:             break;

  30:         case ShotResults.Win:

  31:             resultText = ProcessGameEnd(true, results);

  32:             m_ActionState = m_ActionStates.GameOver;

  33:             break;

  34:     }

  35:  

  36:     sunkBalls.Clear();

  37:  

  38:     this.Text_Status.Text = resultText;

  39: }

VB

   1: Private Sub UpdateGameState(ByVal results As ShotResults)

   2:     Dim resultText As String = ""

   3:  

   4:     Select Case results

   5:         ' update game states

   6:         Case ShotResults.PrematureEightBall, ShotResults.ScratchOnEight

   7:             resultText = ProcessGameEnd(False, results)

   8:             m_ActionState = m_ActionStates.GameOver

   9:         Case ShotResults.NextPlayer

  10:             resultText = "Player looses turn"

  11:             ChangeCurrentPlayer()

  12:             ResetPoolStick()

  13:             m_ActionState = m_ActionStates.Aiming

  14:         Case ShotResults.GoAgain

  15:             resultText = "Nice job. Go again."

  16:             ResetPoolStick()

  17:             m_ActionState = m_ActionStates.Aiming

  18:         Case ShotResults.Scratch

  19:             resultText = "Scratch. Player looses turn."

  20:             ChangeCurrentPlayer()

  21:             AddBall(m_QBall)

  22:             m_ActionState = m_ActionStates.Scratch

  23:         Case ShotResults.Win

  24:             resultText = ProcessGameEnd(True, results)

  25:             m_ActionState = m_ActionStates.GameOver

  26:     End Select

  27:  

  28:     sunkBalls.Clear()

  29:  

  30:     Me.Text_Status.Text = resultText

  31: End Sub

Conclusion

This was a fun and educational exercise for me (always a good combination).  I learned enough about graphics design to at least fear it less, especially with the use of the Expression suite.  It also opened my perspective of Silverlight to understand how it will empower us to implement more rich interactive applications.  The most interesting part for me, however, was the change in perspective I had to take in implementing an "always on" game.  As simple as a game of 8-ball is, it definitely required an adjustment in thinking from the event-driven model of programming I'm accustomed to using in my every day work. 

If you have any questions about this solution or have suggestions for improvement, feel free to contact me at jpetersen@claritycon.com

Back in October one of my co-workers at Clarity, Kevin Marshall, wrote an article about how he modified the foosball table in our employee lounge to allow us to track game results and individual player statistics (see article here). Statistics are the basis for bragging rights, and at a competitive software development company, we're big on bragging rights. Following in the tradition of the foosball, we next set out to make similar capabilities to track scoring and statistics for our recreational dart board. We ended up building a WPF-enabled windows form-based application to use as our virtual scoreboard, attached it to a touch screen monitor, and hooked it up to a database to track statistics. This article will show how we went about building a Cricket scoreboard application. 

Since the application makes heavy use of animations, a video works better to convey some of the features.  You can view a video of the dart board application in action here.

Windows Presentation Foundation

Windows Presentation Foundation (WPF) is Microsoft's next generation framework for building rich user experiences for both forms-based and web-based applications. At the core of WPF is the Extensible Application Markup Language (XAML – pronounced “Zamel”) which allows developers to lay out a user interface using XML in a hierarchical tree structure. If you're not familiar with WPF, you may want to stop reading this article and first read an overview of WPF on MSDN. This article assumes you have a basic understanding of the concepts of WPF. I built the application in this article using the November 2006 CTP of the Visual Studio 2005 extensions for .NET Framework 3.0. Make sure you install the .NET 3.0 runtime prior to installing the Visual Studio extensions.

Laying out the main form

In support of WPF, Microsoft has released a slew of tools that make writing WPF applications easier. Expression Studio is a suite of tools that Microsoft market's towards “creative designers”, but these tools are equally important for developers, especially with the WPF framework's designer glitches in the current release. In many cases you cannot use the designers built into Visual Studio. For example, if your forms use controls that you create, you will not be able to open your XAML file in the visual designer in Visual Studio. To get around this, you can use Expression Blend to open your Visual Studio project and view your form (Expression Blend can natively open Visual Studio project and solution files).

Figure 1: Microsoft Expression Blend XAML editor

Expression Blend is great for editing XAML and creating Storyboard (animations) but it is important to note that the tool is not a code editor.  You cannot edit the .NET code behind files or even HTML or Javascript files from within Expression Blend.  However, there is nice integration with Visual Studio .NET - opening a code file from within Expression Blend will automatically kick off an instance of Visual Studio, open your solution, and present you with the source file to edit.

Our application contains just a few screens - the main dartboard form, plus a couple forms used to manage the players in the game and view statistics. Our scoreboard application will be run in a kiosk and use a touch screen monitor as the main interface. The idea is that a player throws the dart, and then touches the appropriate section of the screen to indicate where the dart landed. The scoreboard then tracks the score and statistics based on the accumulated data.
To create the main form I started with a vector image of a dartboard and used Expression Design to export the image to XAML. The vector image consists of paths for each individual component so the resulting XAML will contain the details for each path. Below is a sample snippet from a one of the Path elements in the scoreboard's XAML. Each individual Path element makes up a second of the image.

<Path x:Name="Path" Width="93.8075" Height="113.784" Canvas.Left="120.154" Canvas.Top="641.654" Stretch="Fill" Fill="#FFFF1A00" Data="F1 M... />

Once I have the XAML representation of the board, I can rename the individual Path elements and make them “clickable” by simply adding the appropriate attributes to each Path element, and then writing the event handler in the code behind file. In this case, I added the OnLeftMouseUp attribute to each Path element which would be raised for each section whenever the player clicks on the board.

<Path x:Name="Double16" MouseLeftButtonUp="Double16Click" Width="93.8075" Height="113.784" Canvas.Left="120.154" Canvas.Top="641.654" Stretch="Fill" Fill="#FFFF1A00" Data="F1 M... />

In the example Path above – the Double16 – the resulting code behind that would handle the event looks like this:

C#

        void Double16Click(object sender, EventArgs e)
        {
            OnDartThrown(Darts.Dart16, 2);
        }

VB

        Private Sub Double16Click(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
            OnDartThrown(Data.Darts.Dart16, 2)
        End Sub

The OnDartThrown method simply performs a swtich on the Dart enum and performs the appropriate animation followed by notifying the game class to record the score.

Scoring and Rules

Since we envision using this framework to support multiple dart games, we created a BaseGame class and derived a CricketGame class from BaseGame. Our scoreboard has a member variable of type BaseGame that is set to an instance of the current game type (note: we didn't implement multiple game types yet –that could be done by adding an additional screen to choose the type of game to play – so for this version all games are of type Cricket). Our BaseGame has a virtual method called UpdateGame that is called after every dart is thrown. This gives the game class a change to update any game data, player scores, statitistics, or other state as required. Since our game is Cricket, CricketGame class manages the scoring rules specific to Cricket, such as maintaining open/close state of each target number:

C#

   if (lastDartThrown != Darts.DartOutOfBounds)
   {
       score = UpdateScores(lastDartThrown, numberThrown);
       UpdateClosedStatus(lastDartThrown);
   }

   List<int> dartMarks = _players[_currentPlayerIndex].MarkDart(lastDartThrown, numberThrown);
   _dartHistory.Push(new DartHistoryItem(score, lastDartThrown, numberThrown,wasClosed, _currentPlayerIndex, _round, dartMarks));

VB

        If lastDartThrown <> Darts.DartOutOfBounds Then
            score = UpdateScores(lastDartThrown, numberThrown)
            UpdateClosedStatus(lastDartThrown)
        End If

        Dim dartMarks As List(Of Integer) = _players(_currentPlayerIndex).MarkDart(lastDartThrown, numberThrown)
        _dartHistory.Push(New DartHistoryItem(score, lastDartThrown, numberThrown, _
        wasClosed, _currentPlayerIndex, _round, dartMarks))

Setting up the animations

One of the key new capabilities WPF gives to developers is a way to add animations to their applications. For the dartboard framework, we wanted to add animations after each scoring throw. To give us a good variety, we played around with several different types of animations as part of the storyboards in our application.  For the dartboard scoreboard we built custom animations for various events that occur during the game – scoring throws, transitions between the scoreboard and the settings screens, and transitions between rounds during the game. We implemented our animations in .Net and referenced the .Net classes from within the XAML by adding a namespace declaration in the root node of our scoreboard XAML file. Referencing .Net code from within XAML (and also referencing XAML-defined elements from within .Net) is an important concept to understand when writing complex WPF applications.

<UserControl
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:uc="clr-namespace:DartScoreboard.GUI.Controls" 
    xmlns:CustomAnimations="clr-namespace:DartScoreboard.Animations" .../>

With the namespace for our custom animations declared, we can reference them via storyboards in the XAML. For example, the XAML below is a storyboard that refers to our BounceDoubleAnimation.

      <Storyboard x:Key="roundChangedAnimation" SpeedRatio="2.0">               
              <CustomAnimations:BounceDoubleAnimation
                    From="-500" To="0" Duration="0:0:5" EdgeBehavior="EaseOut" 
            Storyboard.TargetName="roundChangedBounce" 
            Storyboard.TargetProperty="(TranslateTransform.Y)"/>
      </StoryBoard>

This animation is used during the transition from one round to the next, and results in the text bouncing as it moves from the top of the screen to the bottom.

DependencyProperties

One of the steps in implementing the animation in a .Net code-behind class is to define DependencyProperties. DependencyProperties are special types of properties that can be used by WPF to perform things like data binding, animations, inheritance, and styling. It is DependencyProperties, for example, that allow the WPF runtime to render the styling of a child element based on where it is nested in the XAML tree.  For our custom animations, any properties we want to add to our classes that affect or control the animation behavior must be defined as DependencyProperties.  For example, our BounceDoubleAnimation has a property called EdgeBehavior that controls whether the animation starts on the screen and moves off the screen (EdgeOut) or starts off the screen and moves onto the screen (EdgeIn).  We define this as a DependencyProperty below.

Creating a DependencyProperty in your code required two steps: First, you need to register the property with WPF. Second, you need to define property Get and Set methods that call the special GetValue and SetValue functions used to read and write DependencyProperties. The example below shows how to register the “EdgeBehavior” DependencyProperty used by the BounceDoubleAnimation:

C#

        public static readonly DependencyProperty EdgeBehaviorProperty =
            DependencyProperty.Register("EdgeBehavior",
                typeof(EdgeBehaviorEnum),
                typeof(BounceDoubleAnimation),
                new PropertyMetadata(EdgeBehaviorEnum.EaseInOut));

VB

        Public Shared EdgeBehaviorProperty As DependencyProperty = _
            DependencyProperty.Register("EdgeBehavior", _
                GetType(EdgeBehaviorEnum), _
                GetType(BounceDoubleAnimation), _
                New PropertyMetadata(EdgeBehaviorEnum.EaseInOut))

This snippet below shows how to create the property Get and Set methods for a DependencyProperty. Notice the calls to the GetValue and SetValue methods. 

C#

        /// <summary>
        /// Specifies which side of the transition gets the "bounce" effect.
        /// </summary>
        public EdgeBehaviorEnum EdgeBehavior
        {
            get
            {
                return (EdgeBehaviorEnum)GetValue(EdgeBehaviorProperty);
            }
            set
            {
                SetValue(EdgeBehaviorProperty, value);
            }
        }

VB

        Public Property EdgeBehavior() As EdgeBehaviorEnum
            Get
                Return CType(GetValue(EdgeBehaviorProperty), EdgeBehaviorEnum)
            End Get
            Set(ByVal Value As EdgeBehaviorEnum)
                SetValue(EdgeBehaviorProperty, Value)
            End Set
        End Property

Invoking Animations from managed code

Like most things in WPF, animations can be defined declaratively in the XAML, or via managed code.  Similarly, they can be triggered from within the XAML, or dynmaically from .NET.  In this case, we've defined the animations in Storyboard elements in the XAML, but we'll call them from .NET (for example, as a result of a dart being thrown).  It is easy to get a reference to a Storyboard and invoke methods against the managed Storyboard class: 

C#

        private void AnimateDoubleBull()
        {
            Storyboard doubleBullAnimation = (Storyboard)FindResource("doubleBullAnimation");
            doubleBullAnimation.Begin(this);
        }

VB

        Private Sub AnimateDoubleBull()
            Dim doubleBullAnimation As Storyboard = CType(FindResource("doubleBullAnimation"), Storyboard)
            doubleBullAnimation.Begin(Me)
        End Sub

Putting it all together

While all the WPF related features were fun to build, the real purpose of the framework is to track statistics. For our purposes we will track the typical win/loss record, plus player efficiency, which is the ratio of darts thrown to scoring throws. Since a “scoring throw” has a different meaning depending on what game is being played, we write the code to handle scoring in the derived BaseCricket class. For example, for Cricket we define a scoring throw as any throw that hits a 15 or higher, or a bullseye. We store this per player in a simple database and then compile statistics on the most efficient players. This isn't perfect of course but it works well for what we wanted. With a little work (and some interruption to the game's flow), you could compile statistics on a per target level to answer questions like who is the best at hitting the triple 20.

With the game framework coded and looking good we next looked to find a good place to position the touch screen monitor. We wanted a place that was convenient to the thrower, but yet not in the way. At first we mounted the monitor on the wall adjacent to the thrower. This worked well but we didn't have a good place to put the PC. We eventually ended up building a kiosk to house the PC with an angled top containing the touch screen monitor.

This made the whole presentation seem a little nicer and with the addition of some color and a couple Clarity logos it could make a great conversation piece when it comes to recruiting.

Welcome to part 2 of the introduction to XNA series. Last time we converted the TinyTennis sample to use the XNA framework for rendering and keyboard input. However at the time that article was written deployment was not available on the Xbox 360. In this article you will make additional changes to the project to enable the game to be deployed and played on your Xbox 360.

Before you go any further I need to explain how XNA works on the Xbox 360. Microsoft created a version of the .Net compact framework that runs on the Xbox 360, as well as Xbox versions of the XNA assemblies. To get these assemblies onto your Xbox 360 and enable deployment of XNA framework requires that you join the Creators Club which has a cost associated. The changes you will make for this article will work on the PC too, but you will not be able to play on the Xbox 360 without this. Microsoft have provided a video to help you get this installed: Getting Started with the XNA Creators Club

Some people have asked why I am using such a simple game for these articles. My reasoning is that I do not want to introduce many new things at the same time. TinyTennis is a very simple game and the GDI version has been on MSDN for a long time now and is well documented so I do not need much explanation. Future articles will use more advanced code such as the SpaceWar starter kit.

Errata for part 1

Firstly an update to part 1. In the rush to get the article out at launch date I converted all the GDI PointF structs into XNA Point structs. This meant that everything was stored as integers rather than floating point values. The rounding is not noticeable in a game this simple, but it was incorrect. The correct thing to do was convert to XNA Vector2 structs and this has been corrected in the article and the code for part 1.

Making it work with Gamepads

Those of you with an Xbox 360 will notice that there is no keyboard so controlling the paddles will be a problem. In fact the Xbox 360 does support a standard USB keyboard if you plug one in, its just that very few games look for this input device so there is little point in coding for it and certainly no point in mandating it. All Xbox 360 games of course work with the gamepads and TinyTennis will be no exception.

Xbox 360 gamepads work on the PC as well as on the Xbox. If you have wired controllers you can just plug them in to a vacant USB port and let Windows download the drivers. If you have wireless controllers then you need to buy the wireless controller adapter for windows. Note that the charging pack looks like it has a USB connection but that is purely to take electricity to charge the controller - it won't allow you to use the controller on Windows. In addition since the XNA framework only supports the XInput API you can ONLY use controllers that support this API. In general right now this is Xbox 360 controllers. Any older controllers rely on the DirectInput API which is not available in the XNA framework.

Reading the gamepad is as simple as reading the keyboard in XNA. You simple get the current state of a particular gamepad using the PlayerIndex enumeration (one, two, three or four corresponding to the players) and then read strongly named properties from the gamepad.

Firstly you need to know which player controls each bat so add a PlayerIndex field to bat.cs and modify the constructor to take a PlayerIndex:

private PlayerIndex _playerIndex;

public Bat(int x, Keys up, Keys down, float minPosition, float maxPosition, PlayerIndex playerIndex)
    : base()
{
    initialize(x, minPosition, maxPosition);

    //Keys to control this sprite 
    _upKey = up;
    _downKey = down;

    _playerIndex = playerIndex;
    _isHuman = true;
}

When the bat is created in the constructor of TinyTennis.cs you need to pass in the correct PlayerIndex for each bat (note player 2 is the commented out line)

//Create the bat Sprites - they need the keyboard controls and the gameplay area limits
_player1 = new Bat(30, Keys.Q, Keys.A, 0, Window.ClientBounds.Height, PlayerIndex.One);

//use this line for a second human player
//_player2 = new Bat(Window.ClientBounds.Width - 30 - Bat.Width, Keys.P, Keys.L, 0, Window.ClientBounds.Height, PlayerIndex.Two);

Finally change the humanMove function in bat.cs to read the gamepad state for the correct gamepad.

private void humanMove()
{
    KeyboardState keyState = Keyboard.GetState();
    GamePadState padState = GamePad.GetState(_playerIndex);

    double velocity = 0.0;
    //Set the velocity of the sprite based on which keys are pressed
    if (keyState.IsKeyDown(_upKey) || padState.DPad.Up == ButtonState.Pressed)
    {
        velocity += -_speed;
    }
    if (keyState.IsKeyDown(_downKey) || padState.DPad.Down == ButtonState.Pressed)
    {
        velocity += _speed;
    }
    Velocity.Y = (int)velocity;
}

Replacing Windows Sound with XACT

TinyTennis only has one sound for when the ball bounces. The code currently uses the SoundPlayer class from System.Media. Unfortunately System.Media is one of the assemblies which is not availalbe in the version of the .Net framework on the Xbox 360. The only audio API available on the Xbox is called XACT and its exposed in the Microsoft.Xna.Framework.Audio namespace in the XNA framework.

In addition to being the name of the API, XACT also contains a fairly complex sound management tool. In AAA titles the sound guy on the team uses XACT to create a bank of sounds that the programmer can simply play by referring to a 'cue'. The idea behind it is to separate the work the audio guy does away from the programmer in the same way as a 3D modeling tool allows an artist to work away from the programmer. If this sounds too complex just to play the bounce sound then you are right - XACT is overkill for this. But its the only way to play sounds at the moment, and thankfully you do not need to learn very much XACT to be able to play a WAV file.

Start by running the XACT tool from the start menu. Note that you MUST use the version of XACT that ships with XNA Game Studio Express and not one that you may find in a DirectX SDK. The file formats for XACT projects changes almost every SDK release and the XNA framework only understands the one it was shipped with. Also note that if you are running on Vista you should follow the instructions on Dave's blog to get it to work, and also set it to run as Admin. A future release of XNA Game Studio Express will make everything compatible with Vista.

You will see the XACT window:

For TinyTennis you do not need to understand most of this. However there are 2 concepts you need to grasp:

1. Wavebank: This contains the raw sound files
2. Soundbank: This contains the 'cues' that you, as the programmer, will play.

In the case of TinyTennis the 'cue' will just play the raw sound file but XACT gives an audio engineer a lot more flexibility than that such as merging multiple sound files, changing the pitch and volume and applying reverb effects.

Create a new wavebank and soundbank by right clicking and selecting New

You will now see the wavebank and the soundbank windows appear. Add the beep.wav from the project directory by right clicking the wavebank window and selecting Insert Wave Files. In Windows XP you can drag and drop from Windows Explorer into the wavebank window.

Then drag the beep from the wave bank window into the top half of the sound bank window (the Sound Name section). Then drag the 'beep' sound into the lower half of the sound bank window (the Cue Name) section. You will end up with something that looks like this:

What you have done is created an XACT cue that plays a sound which just contains a single wave file.

Now save the XACT project as TinyTennis.xap in the project folder.

XNA Game Studio Express understands .xap files and will compile correct Windows or Xbox 360 versions when the project is compiled. So the only remaining thing to do is add the .xap to the project. Simple browse and add. Since the .xap file knows which .wav files are required you do not need to explicitly reference beep.wav any more so it can be 'excluded from project' (Do not use 'delete' as that will actually remove the file from disc and the .xap file references it).

Playing the sound is a little more complex that the 2 lines of code required with the SoundPlayer class but its much more flexible. For a start you can have more than one sound playing at a time which is not possible with SoundPlayer.

The XACT sound engine needs to be initialized when the game starts up so add the following declarations to TinyTennis.cs (note this was called Game1.cs in part1 - I have renamed it for obvious reasons)

private static AudioEngine engine;
private static WaveBank wavebank;
public static SoundBank soundbank;

and then initialize the engine inside the Initialize() function

protected override void Initialize()
{
    engine = new AudioEngine(@"tinytennis.xgs");
    wavebank = new WaveBank(engine, @"wave bank.xwb");
    soundbank = new SoundBank(engine, @"sound bank.xsb");

In ball.cs you can remove the using statement for System.Media and add in Microsoft.Xna.Framework.Audio. Then remove all of the places that _beep and SoundPlayer are used.

To play the sound using XACT is a single line replacement inside PlayBounceSound()

private void playBounceSound()
{
    TinyTennis.soundbank.PlayCue("beep");
}

 Compile and run and after all of that hard work you should be back exactly where you started, with the ball playing a beep sound when it bounces.

Running TinyTennis on the Xbox 360

Game Studio Express requires you to have separate projects for Windows and Xbox 360 development. For almost all XNA framework projects the source code is identical between the two versions - any slight differences can be handled using #if XBOX - so maintaining 2 code trees is almost always more trouble than it is worth. The easiest way to get round this is to create both projects in the same directory so that they can share files in a simple manner. You will still have to remember to add a file to both projects when you make a new file but that is a simple drag and drop operation.

Firstly create an empty Xbox 360 Game project somewhere on your hard drive - its a temporary location so anywhere will do. Then using windows explorer copy the .csproj file into the TinyTennisXNA folder and add it to your solution as a second project. It will complain about the source files that are missing but that doesn't matter as we will add our own.

Rename the project to TinyTennis360, remove Game1.cs and then drag and drop all the files from TinyTennisXNA into TinyTennis360 - from within the solution explorer. Even though the files are in the same directory they will get added to the new project. Now if you modify bat.cs in one project it automatically gets updated in the other project too. The only thing you have to do to keep in sync is remember to drag and drop any new files if you add them to one of the projects.

Now when you compile it will compile both projects. If you only want to compile the windows or the Xbox one you can select it from the platform drop down on the men bar

Also remember that now you have 2 projects you need to remember to set the right one to be the startup project by right clicking the project file. You will get confused when it tries to run the Xbox project and deploy when you really wanted to debug the windows one.

Now that everything compiles its time to deploy it to the Xbox. Rather than explain how to do it in words and pictures I recommend you take a look at the second half of the Getting Started with the XNA Creators Club video. If you fast forward to 6:02 you can see a demo of how to create the connection between Game Studio Express and your 360 and how to put your Xbox in receive mode. Once that is done you just hit f5 in Game Studio Express and the game will be deployed and run. Depending on what screen resolution you have set on your Xbox the paddles may not appear in the expected place, but the game is still playable. To quit the game on the Xbox 360 press the 'back' button on gamepad 1.

Next time I will cover some additional features for the Xbox version and add the scores back in.

The ZMan runs the #1 Managed DirectX & XNA community website http://www.TheZBuffer.com. If you have a question for the ZMan that you would like to se answered in a future column then send it to zman@thezbuffer.com.

Copyright © 2007 ZBuffer Games, LLC

Have you ever played a first person shooter? Then you've probably played against computer controlled players known as "bots" which are computer programs designed with artificial intelligence. Up until now the only way to do create your own bot for a game like Unreal Tournament was to learn a bunch of C++ and complicated AI routines. Of course, what you really want to do is code up your bot using C# or VB and Visual Studio Express.

Andy Sterland (Program Manager, Microsoft),James Lissiak, and Tom Randell Difficulty: Intermediate Time Required: Less than 1 hour Cost: Less Than $50 Software: Visual Basic or Visual C# Express Editions required, optionally install client and server piece: optional install of Unreal Tournament Game of the Year Edition client, optional Unreal Tournament Server Software Hardware: None Download: Download

Unreal Tournament "Bots"

Have you ever played a first person shooter? Then you've probably played against computer controlled players known as "bots" which are computer programs designed with artificial intelligence. Up until now the only way to do create your own bot for a game like Unreal Tournament was to learn a bunch of C++ and complicated AI routines. Of course, what you really want to do is code up your bot using C# or VB and Visual Studio Express.

For this project, we created:

• VB and C# project templates to simplify setup/installation of the necessary components for Visual Studio Express
• A "Bot API mutator" (custom level) which runs on the server that can accept .NET bots
• A "visualizer" (custom Windows Form app) which provides a visual representation of a map so you can watch players play against each other

This project uses the code based on the Mutator for Unreal Tournament at http://www.planetunreal.com/gamebots/, but instead creates a .NET wrapper you to code your own "bots" in any .NET language. If you have ever wanted to write software which will take control of a player in Unreal Tournament and duke it out with other killer classes, then read on to find out how to do it.

Getting Started

Installing the Game (optional)
Installing the Game is *not* required as your bots can run on any of the supported remote servers. That being said, if you want to play against your own AI, you can configure your PC to be both a client (with you playing) and a server. You'll find full instructions on server configuration below, but to get Unreal Tournament Game of the Year Edition, you can order it from Amazon.com or download the shareware version ($19.99 for purchase) from Tucows. After installing, make sure to apply the patch up to version v436.

Configuring the Server (optional)
Your bot can only connect to servers running the “Bot API” mutator meaning you can either run a server locally or join a public server. If you want to run a server, Epic Games distributes the server version of Unreal Tournament for free at:  http://www.fileshack.com/file.x?fid=300. You can find step-by-step server setup instructions here. If you have a server of your own that is open to all feel free to add it to that list so that other bots from around the world can come round and visit you. Alternatively you can join one of the public servers listed at http://www.net.dcs.hull.ac.uk/utbot/ServerList.aspx without the hassle of configuring your own server and the benefit of seeing your AI bot play against other AI bots anywhere in the world.

Configuring Visual Studio Express
To simplify configuring Visual Studio Express, we've created project templates for VB and C#. You can download the appropriate:

• Visual Basic Project Template
• Visual C# Project Template

http://www.net.dcs.hull.ac.uk/utbot/Files/CS+UT+Remote+Bots.vsi (C#) http://www.net.dcs.hull.ac.uk/utbot/Files/VB+UT+Remote+Bots.vsi (VB)

Double click on your download to install it and when you next load up Express you should see a “UT Bots” Starter Kit in the new project window.

Configuring the Visualiser (optional)
To configure the visualiser, simply run UTBotsVisualiser.exe and enter the IP address for the running game.

Creating Unreal Tournament Bots

How your Bot works
You create your bot as a program running on your PC. The PC is connected by the network to the server which needs to be running the “Bot API” mutator. Twice per second the server makes a call to your bot's PerformActions() method, which is a member of the RemoteUserBot class. The server will also call methods in your bot when events happen in game, such as your bot hitting a wall or hearing a noise.

Performing Actions
You put code into the PerformActions method to give your bot its distinctive personality.

Your aim is to produce a bot that is aware of its own current state and that of the surroundings, reacting in a sensible manner. This may sound complicated, however, thanks to the methods and properties provided in the Getting Started pack, it is incredibly simple.

Game Messages
Although the majority of your code will be executed during the call to PerformActions() your bot also receives messages from the server whenever a certain ‘event' occurs.

For the purpose of clarity when we refer to an event we are not talking about an event of the .NET event-delegate type; in the context of your bot an event could be walking into a wall or hearing a noise.

It is also possible to override the behaviour of the methods which receive the messages passed in by the server so that your bot can respond sensibly to them. For example, you can override the AnotherBotDied method to keep a scoreboard of who's winning and losing in the game. For full details on these methods please check the API reference.

The creation of a working bot
The following examples have been provided as a basic starting point for developing your own working bot. Please note these examples are by no means the best way to do things; it is up to you to optimize your bot to make the best fragger.

Creating your Bot
After installing the Project Template from the Getting Started section, open up Visual Studio Express and select File...New Project... and select the "UT Remote Bot" template.

Solution Explorer View

Here you'll see the solution explorer view of the UT Remote Bots which contains a number of files for the project. In essence, the UT RemoteBot project is nothing more than a console application that sends and receives commands at a specific interval

• Starter file- The basic template that describes the Remote UserBot and the server
• RemoteUserBot file - Where you will code all of the work
• UTRemoteBot.dll - The class library that contains the wrapper code for Unreal Tournament Functions
• UTBotsVisualiser.exe - The visualiser tool mentioned previously
• UT Bots - Guide.htm - An HTML getting started guide

Starter File
The Starter file is a console application that creates an instance of the RemoteUserBot class. You can customize it by providing a name for your bot, currently "UserBot", a "skin" for your bot which will display how your bot appears (ex: mercenary vs alien), the bot color (for teams), and the server to connect to. If you are self-hosting, you should set the server value to: "127.0.0.1"

Visual Basic

Imports UTRemoteBot

Module Starter
    '''<summary>
    ''' The main entry point for this bot. 
    '''Creates a new instance of your bot which will connect to the server and begin to play
    '''</summary>
    Sub Main()
        Dim b As RemoteUserBot = New RemoteUserBot("UserBot", BotSkin.Blake, BotColour.None, "classroom.dcs.hull.ac.uk")
        Console.WriteLine(" (Press Enter To Disconnect)" & Microsoft.VisualBasic.Chr(10) & "")
        Console.Read()
        b.DisconnectFromServer()
        Console.Read()
    End Sub

End Module

Visual C#

using System;

namespace UTRemoteBot
{

    public class Starter
    {

        /// <summary>
        /// The main entry point for this bot. 
        /// Creates a new instance of your bot which will connect to the server and begin to play
        /// </summary>
        [STAThread]
        public static void Main()
        {
            RemoteUserBot b = new RemoteUserBot("UserBot", BotSkin.Blake, BotColour.None, "classroom.dcs.hull.ac.uk");

            Console.WriteLine(" (Press Enter To Disconnect)\n");
            Console.Read();

            b.DisconnectFromServer();
            Console.Read();
        }

    }
}

If you run the program now you will find that your bot will appear in the game and stand waiting for instructions. The game framework is calling the PerformActions method in your bot at regular intervals, but because the method presently does nothing, your bot does not move.

The next thing we must do is change the content of this method to get control of our bot and make it move around in the game by adding code to the RemoteUserBot file. Opening up the RemoteUserBot file shows the code below where we will add whatever code we want to perform directly into the PerformActions() method.

RemoteUserBot Visual Basic

Imports System
Imports System.Collections.Generic
Imports UTRemoteBot


Public Class RemoteUserBot
    Inherits RemoteBot
    ''' <summary>
    ''' This methods creats an instance of your bot sets the UT options such as name, colour and 
    ''' skin and then connects to the specified server. Once connected PerformActions will be 
    ''' called every ~2 seconds and any in game events such as hitting a wall will call the appropiate
    ''' overriden method.
    ''' </summary>
    ''' <param name="aName">Name of your bot as it should appear in game</param>
    ''' <param name="skin">Skin that the bot should use in game</param>
    ''' <param name="colour">Colour of the bot in game</param>
    ''' <param name="server">The server which to connect either an IP address or a host name, it can only connect on the default port</param>
    ''' <remarks></remarks>
    Public Sub New(ByVal aName As String, ByVal skin As BotSkin, ByVal colour As BotColour, ByVal server As String)
        MyBase.New(aName, skin, colour, server)

    End Sub

    ''' <summary>
    ''' Method to control the bot once it has connected to the server
    ''' </summary>
    ''' <remarks></remarks>
    Protected Overloads Overrides Sub PerformActions()
        'Add code here to perform an action at a specific interval
    End Sub
End Class

RemoteUserBot Visual C#

using System;
using System.Collections.Generic;

namespace UTRemoteBot
{
    public class RemoteUserBot : RemoteBot
    {
        /// <summary>
        /// This methods creats an instance of your bot sets the UT options such as name, colour and 
        /// skin and then connects to the specified server. Once connected PerformActions will be 
        /// called every ~2 seconds and any in game events such as hitting a wall will call the appropiate
        /// overriden method.
        /// </summary>
        /// <param name="aName">Name of your bot as it should appear in game</param>
        /// <param name="skin">Skin that the bot should use in game</param>
        /// <param name="colour">Colour of the bot in game</param>
        /// <param name="server">The server which to connect either an IP address or a host name, it can only connect on the default port</param>
        /// <remarks></remarks>
        public RemoteUserBot(string aName, BotSkin skin, BotColour colour, string server)
            : base(aName, skin, colour, server)
        {
        }


        //Method to control the bot once it has connected to the server
        protected override void PerformActions()
        {
            //Add code here to perform an action at a specific interval

        }
    }
}

Bot's first sight
Now that we have a bot in the game we need to make it actually do something. The first thing we are going to make it do is move to a NavPoint. This is a location in the game which might hold something interesting. A series of NavPoints provides a path through the level to interesting items. A bot can travel around a game level by moving from one NavPoint to another.

Within the game framework (UTRemoteBot.dll), an instance of the UTVector class can be used to express the actual location of something. The location of a Navpoint is given by its Location property, which is given as a UTVector value.

Our bot needs to have a way of keeping track of where it is going so in the RemoteUserBot class create a new private UTVector called destinationLocation:

VB

Dim destinationLocation As UTVector

C#

private UTVector destinationLocation; 

We want our bot to head towards the first navpoint that it “sees”. To do this we place the following code into the PerformActions() method.

VB

Me.destinationLocation = Me.CurrentGameState.NavPointsVisible(0).Location

C#

this.destinationLocation = this.CurrentGameState.NavPointsVisible[0].Location; 

CurrentGameState property of our bot contains information on the current state of the game. NavPointsVisible is an array of references to UTVector instances which refer to all of the NavPoints a Bot can see. The above code simply takes the UTVector at position 0 (the first NavPoint your Bot can see) and sets destinationLocation to refer to it.

So at this point the bot has identified the location it wants to move towards, now we have to make it move in that direction.

Bot's first steps
Now we are going to make our bot move to the destination it has selected. Place the following code into the PerfomActions() method just below the code written in the previous example.

VB

Me.BotCommands.RunTo(Me.destinationLocation)

C#

this.BotCommands.RunTo(this.destinationLocation); 

BotCommands provides a set of methods which are the commands that your program can give to the bot. There are a wide range of commands, some of which are listed below. For full details you should investigate the API reference.

• ChangeWeapon() - Changes the current weapon
• Jump() - Jumps in the air
• RotateBy() - Rotates by a specific degree
• RunTo() - Runs to a specific location
• Shoot() - Attacks a target or location
• StopShooting() - Stops the bot from shooting
• StrafeTo() - Strafes to a specific location

The RunTo() command is provided with a destination location. When this method is called your bot will start running towards the destination.

If you execute this program you will see your bot start running towards a navpoint.

Bot's first shot
For the purpose of this example we will next make our bot shoot at the location it is running towards, it is recommended that you change this when creating your own implementation as shooting at an empty NavPoint is unlikely to get you many frags.

Place the following code into the PerfomActions() method just below the code written in the previous example.

VB

Me.BotCommands.Shoot(Me.destinationLocation, false)

C#

this.BotCommands.Shoot(this. destinationLocation, false); 

If you execute the program you will see that your bot now shoots at the location as it runs towards it. It will continue doing this until you call a method to instruct it to stop.

Place the following code into the PerfomActions() method just below the code written in the previous step. Your Bot will now stop shooting.

VB

Me.BotCommands.StopShooting

C#

this.BotCommands.StopShooting(); 

Viewing your bot in action
You can find out what your bot is up to we have provided a visualiser. This is a modified version of TclViz. When you run the Visualiser you can connect it to any server running the mutator and get a birds eye view of the game in progress by simply providing the IP address of the server. You can see the waypoints which are marked by pink dots and the active players which have their name next to a yellow dot and a line indicating which way they are facing. From here you can view the game and see what your bot is doing as shown in the visualizer screenshot.

What to do next
Now that you have got your bot into the game and made it move around a bit you can start thinking about making it into a decent player of the game. Take a look at the other members of the NavPoint class so that your bot can look for weapons and health pack and move towards them. Then take a look at the members of the CurrentGameState class for the information that your bot is given about the game around it.

One thing you will need to add is some way that your bot can be in a particular state at any given time. Sensible states might be “Roaming”, “Hunting”, “Idle”, “Recovering” etc. Depending on the state your bot is in it will do different things each time PerformActions is called.

If it is in the roaming state it will be looking for a nav point. If it is in the hunting state it will be chasing other bots. If it is in the recovering state it will be avoiding other bots and looking for a MediPac, and so on. You can keep track of the state of your bot by creating an enumerated type with the different values. Then your PerformActions method can contain a switch statement which makes it behave differently, depending on what it is doing.

A state machine is just one way you could program your AI, you could make a sophisticated bot that had a way of determining if a result had a positive or negative consequence and then have the bot perform more actions that had a positive consequence. Essentially a learning bot, be careful though if your bot takes too long executing PerformActions it will get out of touch with the game as messages will sit on the queue unprocessed waiting for your code to finish.

There are also some very handy hints in the FAQ below about getting your bot on the road to stardom.

Conclusion
With this you should be able to go about creating your own deathmatch player. If you have any questions which are not answered in the FAQ below feel free to use the forum on the site (http://www.net.dcs.hull.ac.uk/utbot/ ).

If you're feeling particularly brave join our project on CodePlex at http://www.codeplex.com/Wiki/View.aspx?ProjectName=UTBots and help pitch in with improving the client.

Frequently Asked Questions

Do I need Unreal Tournament to use this stuff?
No, you can create bots and have them connect to any bot server and use the visualiser to get an idea of what's going on. Of course it isn't as pretty as UT! You can also run the server without owning a copy as Epic distribute a free server side runtime which you can get from http://www.fileshack.com/file.x?fid=300 .

My bot won't move! What did I do wrong?
This could be due to incorrect programming logic, please double check your code. You may also have left a Break Point within Visual Studio, if this is reached while watching your bot via Unreal Tournament your bot will appear to freeze until your program continues.

My bot keeps getting stuck when it runs into a wall. How can I stop this?

Try overriding the HitWall() method, an example of how to do this would be:
VB

Protected Overrides Sub HitWall(ByVal locationOfBot As UTVector, ByVal normalOfCollision As UTVector)
  Me.BotCommands.RotateBy(90)
End Sub

C#

protected override void HitWall(UTVector locationOfBot, UTVector normalOfCollision)
{
  this.BotCommands.RotateBy(90);
}

This method will be called when your bot hits the wall. The code above will simply rotate the bot by ninety degrees when it hits a wall.

What events can my bot react to?
You can try overriding any of the following methods:

• AnotherBotDied()
• BumpedActor()
• HitLedge()
• HeardNoise()
• HeardPickup()
• HitWall()
• IncomingProjectile()
• NewGlobalChatMessage()
• PathReceieved()
• PickedUpItem()
• ShotAnotherBot()
• TookDamage()
• WasKilled()

My Bot seems a little slower than the other Bots! How do I make it faster?
Try improving your Bot's logic to optimize the speed.

The more quickly the PerformActions() method completes the more time your bot has to react in the game.

My Bot is nearly dead! How do I get it to collect some health?
A simple idea would be to just run your bot around the level, checking the CurrentGameState.ItemsVisible list to see if your bot can see a Health item and if it can, get it to run to that location to collect it.

Another idea would be to use the GetNearestItem() method inside the LevelMap class to find the location of the closest MediPack. Then you can call the GetPathTo() method from the BotCommands class to ask for an array of UTNavPoints to get to that health box. Once you have received this path, you can just get your bot to run to each point in turn until it reaches the health.

The following example shows you how you could do this:

VB

Dim pathToRun() As UTNavPoint
Dim index As Integer = 0

    
    Protected Overrides Sub PerformActions()
        'Check to see if we have a path to run already
        If (Not (Me.pathToRun) Is Nothing) Then
            'Run to this point on the path
            Me.BotCommands.RunTo(Me.pathToRun(index))
            'Check to see if our bot is near to the point we are running to
            If Me.Self.IsCloseTo(Me.pathToRun(index)) Then
                'Move our index to the next point in the path array
                index = (index + 1)
                If (index >= Me.pathToRun.Length) Then
                    'The index has reached the end of the path.
                    Me.pathToRun = Nothing
                End If
            Else
                'We don't have a path so find the nearest health box
                Dim box As UTObject = Me.LevelMap.GetNearestItem(HealthType.MediBox)
                'Ask for a path to that box
                Me.BotCommands.GetPathTo("Looking for health", box)
            End If
        End If
        'Override this method to collect the result back from GetPathTo()
        Dim PathReceieved As System.Void
        string
        requestID
        Dim path() As UTNavPoint
        If (requestID = "Looking for health") Then
            'The server has sent us a path so store it in our variable
            Me.pathToRun = path
        End If
    End Sub

C#

//Some variables to store our data
UTNavPoint[] pathToRun;
int index = 0; 

protected override void PerformActions()
{
  //Check to see if we have a path to run already
  if (this.pathToRun != null)
  {
     //Run to this point on the path
     this.BotCommands.RunTo(this.pathToRun[index]); 

  //Check to see if our bot is near to the point we are running to
  if (this.Self.IsCloseTo(this.pathToRun[index]))
  {
    //Move our index to the next point in the path array
    index++;
    if (index >= this.pathToRun.Length)
    {

      //The index has reached the end of the path.
      this.pathToRun = null;
    }
  }
  else
  {
    //We don't have a path so find the nearest health box
    UTObject box = this.LevelMap.GetNearestItem(HealthType.MediBox); //Ask for a path to that box
    this.BotCommands.GetPathTo("Looking for health", box);
  }
} 

//Override this method to collect the result back from GetPathTo()
protected override void PathReceieved(string requestID, UTNavPoint[] path)
{
  if (requestID == "Looking for health")
  {
    //The server has sent us a path so store it in our variable
    this.pathToRun = path;
  }
} 

Some of the methods want me to provide a HealthType, AmmoType, etc as a parameter. Where can I find these?
These types are Enumerators which have been used to make coding your bot easier. They are all located inside the UTRemoteBot namespace so to use them you need only type in the appropriate name and IntelliSense should fill in the rest.

For example typing WeaponType. Would fill the Intellisense with the different types of weapons in UT so you could then pass these to the LevelMap.GetNearestItem() method.

These types can all be sent as parameters to various methods in the BotCommands class:

• AmmoType – A list of all the types of ammo for weapons in the game
• ArmourType – A list of all the types of armour in the game
• HealthType – A list of the different types of health items in the game
• WeaponType – A list of the different types of weapon in the game

The following types can be sent as parameters to your bot's constructor in the Starter file:

• BotColour – A list of the 5 different colours to use when customising your bot in the Starter file
• BotSkin – A list of the skins that you can give your bot when customising it in the Starter file
• OutputType – The level of output you want to be written to the console when developing your bot

How do I shoot at another player?

All you need do is check the CurrentGameState.PlayersVisible list for any players visible. You would then call the BotCommands.Shoot() passing in one of the Bots from the list and a bool which if set to true your bot will use the secondary fire mode on the current weapon if set to false your bot will use the primary fire mode.

GetPathTo doesn't seem to work
For reasons best known to code pixies GetPathTo doesn't always return a valid navigation path. In some cases it might even return nothing. The root cause of this problems lies deep within the Unreal Tournament path finding routines. It seems that in certain circumstances, for instance just after an item has been collected, the game just can't find a path. We strongly recommend that your bot doesn't rely too heavily on this method and only uses it occasionally with plenty of error checking!

Where do I connect to?
You can find a list of servers here: http://www.net.dcs.hull.ac.uk/utbot/ServerList.aspx  or you can run your own instructions for which can be found here: http://www.net.dcs.hull.ac.uk/utbot/ServerSetup.aspx

I want to run my own server
Great! Instructions and files can be found at: http://www.net.dcs.hull.ac.uk/utbot/ServerSetup.aspx

If your server is public and you don't mind strangers you can add it to the list here: http://www.net.dcs.hull.ac.uk/utbot/ServerList.aspx

Is Unreal Tournament Game of the Year Edition the only supported UT version?
Yes, although we are looking to add support for Unreal Tournament 2007 when it is released. Check the CodePlex Unreal Tournament Bots project for more information

December 11th... a day that we all hope will go down in history as the start of a new generation of hobbyist game developers. Today XNA Game Studio Express launches. It's not the first platform to allow home developers access to console development but its is the first one to be fully sanctioned and supported and running on a retail console.

So where do you start? XNA Game Studio Express is going to interest people who have no game development experience at all so starting with some simple games is a good idea. You may have seen the 3 games I did for MSDN for their Upgrade Your Game promotion - Tiny Tennis, Space Blitz and Crusader. For this series of articles I will walk you through simple XNA applications using as much code from these starter kits as possible. The original tutorials and screencasts will walk you through the game logic and these articles will add in the XNA know how.

Firstly a couple of points:

1. Even The ZMan didn't have access to the retail XBox 360 release before today so for the first part I will only cover the PC. Watch for part 2 to add in the things needed to run on the 360 and go into more detail.
2. XNA only supports Visual C# Express so although the original games were in Visual Basic, this series will be only in C#
3. You need to ensure you have C# Express and XNA Game Studio Express installed. If you have problems installing or running then ask in the XNA Game Studio Express Forum.

Making a new XNA game

Installing XNA Game Studio Express adds several new project types to C# Express:

The SpaceWar projects are complete games for the xbox and the windows platforms - they have all the source code, graphics and sound and Microsoft absolutely want you to use this to make your own games as well as learn about making simple 2d and 3d games.

The Windows Game and Xbox Game projects are for writing games on those 2 platforms and the Game Library projects are for making reusable components that are easy to use within the XNA game projects.

For this tutorial start with the Windows Game project. Once you have selected it you can immediately run the project and see a wonderful cornflower blue, blank screen. (It is widely speculated that cornflower blue is Tom Miller's favorite color).

Now we need to add the project files from the Tiny Tennis sample. Select Add Files by right clicking the project and then browse to the Tiny Tennis solution and add the following files:

Converting the Game

There are going to be a LOT of errors right now because Tiny Tennis relies heavily on Windows.Forms and System.Drawing neither of which are available when writing an XNA application that you eventually want to run on the Xbox 360 because the Xbox 360 does not support those libraries. So initially there are several big changes to make.

Game1.cs is the main XNA game file. It contains the initializer for the game as well as several methods that are called automatically for the game. If you have been through the tutorials for the Express games you will see that the games are designed to be continually updated. As fast as possible the keyboard is read, the positions are updated and the screen is redrawn. This is exactly the same method used in XNA so it is very simple for us to use the same logic.

You need to copy sections of code from the tennis.cs file into the game1.cs.

Firstly the declarations:

Then the constructor which goes into the end of the Game1 constructor.

The TinyTennis_Paint code gets moved into the Draw method in Game1.cs. The Draw method is continually called by the XNA Game class and this is where you should draw your graphics.

Notice that I have not copied across any of the timer/stopwatch code. XNA provides its own timer logic so that is not needed. Since XNA does not support Windows forms, it does not support KeyUp and KeyDown events so the code for those is of no use to us. You can now remove TinyTennis.cs from the project.

Now to fix up the errors. If you hit compile and walk through them one by one you will fix them in the following order:

• The first thing to do is remove all the 'using' statements that mention Windows.Forms and System.Drawing. If you try to compile these will be the first errors on the list.
• PointF in System.Drawing is replaced by Vector2 in Microsoft.XNA.Framework. If you change the type to Vector2 you can use the intellisense feature of C# express to add in the new using statement.
   
• There is no SizeF type in XNA. Since it is just a pair of values you can reuse Vector2 type so change SizeF to Vector2. Change the Width property to X and the Height
• Color in System.Drawing is replaced by Color in Microsoft.XNA.Framework. For most of these errors you just need to add the correct using statement with intellisense.
• In TinyTennis I used windows controls to do the rendering. Since this is not possible in XNA all references to the Control type need to be removed
  • in ball.cs and bat.cs remove the parameters in the constructor that refer to Control
  • ControlSprite is a wrapper around Sprite that draws using windows controls. Since we no longer have windows controls we can remove ControlSprite from the project and just use the Sprite implementation
  • Now that ControlSprite is missing Ball and Bat should be changed to inherit directly from Sprite
  • In game1.cs remove the Control parameters from the new Bat() and new Ball() lines in the constructor
• Keys is now found in Microsoft.Xna.Framework.Input so needs the correct using statement
• ClientSize from Windows.Forms becomes Window.ClientBounds from Microsoft.Xna.Framework
• In the WindowsForms version of TinyTennis I tracked the game time myself. This code is redundant in XNA and is removed because the Game class passes in gametime to the Draw() function. So replace the elapsedTime property with gameTime.ElapsedGameTime.TotalSeconds and the gameTime parameter with gameTime.TotalGameTime.TotalSeconds
  
  //Perform any animation
  _player1.Update(gameTime.TotalGameTime.TotalSeconds, gameTime.ElapsedGameTime.TotalSeconds);
  _player2.Update(gameTime.TotalGameTime.TotalSeconds, gameTime.ElapsedGameTime.TotalSeconds);
  _ball.Update(gameTime.TotalGameTime.TotalSeconds, gameTime.ElapsedGameTime.TotalSeconds);
• There is no easy way to draw text to the screen in XNA. So for this article I am simply going to avoid the subject until there is time to go into it in more detail. Comment out the lines that display the score. You can use the ctrl-K-C keypress to easily to this. ctrl-K-U reverses it
  
  //Draw the scores
  //player1Score.Text = gameState.Player1Score.ToString();
  //player1Score.Refresh();
  //player2Score.Text = gameState.Player2Score.ToString();
  //player2Score.Refresh();
• Since the Point type uses integers in XNA there are some parameters to change to int from float and the calculations need to have their results cast into (int). For example:
  
  public virtual void Update(double gameTime, double elapsedTime)
  {
      //Move the sprite based on the velocity
      Location.X += (int)(Velocity.X * (float)elapsedTime);
      Location.Y += (int)(Velocity.Y * (float)elapsedTime);
  }

So you should now have a project that compiles. However when it runs you will see a runtime error about a missing sound file - copy the WAV file from the original project and add it to the project and set the properties to copy the file to the output directory. Now the project should compile and run but nothing will appear on the screen. This is to be expected since the previous version used windows forms to do the rendering.

Using XNA to Render

The simplest way to draw anything in XNA is using the SpriteBatch class. This uses your graphics card to draw 2d rectangular areas on the screen. Since Tiny Tennis uses rectangles this is perfect. The SpriteBatch allows you to set the location and size of the rectangle - however it expects a graphic file to be used as the thing to draw. For TinyTennis a graphic file which is all white will work perfectly. I created a small graphic file using Windows Paint and added it to the project.

If you look at the file properties after you add the bitmap you will see another addition that XNA Game Studio Express adds. Image files are now a recognized project item. This is what you may have heard of as the content pipeline. It allows game content to be created and checked at compile time and the content to be treated as part of the game rather than some external files.

For the most part you don't need to change or even look at the properties window. Make a note of the Asset name - this is how you will be able to refer to it in code. It defaults to the name of the file without the type extension.

Rendering involves 2 steps - loading the graphic and then using it to draw.

Loading the graphic is done in the Game1.cs class. Using the already declared reference to the content pipeline it requires a simple declaration:

  and a single line of code in the LoadGraphicsContent function:

To draw the sprite you need a sprite batch object for this simple application its easiest to just create a single SpriteBatch and make it static so that the bats and balls can share it.

And create it in the initialize function.

Drawing with SpriteBatch has many overloads - however to draw a rectangle uses the simplest overload which simple stretches the white pixel to a rectangle of the required size and color in sprite.cs

Now if you run the game you will see the bats and balls on the screen. The final thing is to add the new keyboard code. Since there is no events in XNA you need to simply check each time around the game loop if the key is up or down, Just like everything else in XNA this is a few simple lines of code. Replace the humanMove() function in bat.cs with the following:

private void humanMove()
{    

KeyboardState keyState = Keyboard.GetState();
double velocity = 0.0;    
//Set the velocity of the sprite based on which keys are pressed    
if (keyState.IsKeyDown(_upKey))    
{         velocity += -_speed;     }    

if (keyState.IsKeyDown(_downKey))    
{         velocity += _speed;     }  
 
Velocity.Y = (int)velocity;

}

Now you can play the game. The keys Q and A control the bat on the left and the bat on the right uses some rudimentary AI.

Running on the Xbox

As I mentioned earlier running on the Xbox is something I will cover in the next article. But I'm sure you want to try so here are some pointers:

• There is no keyboard on the xbox so you will need to replace the key press code with reading the xbox controller instead
• Sound on the xbox is done using XACT so the SoundPlayer class is not available. You need to create an XACT project and add the .wav file to that

Take a look at the SpaceWar sample for examples of ow to do both of these things - or just wait till next week.

The code in this article uses Visual C# 2005 Express Edition and the October 2005 DirectX SDK

The ZMan is here to solve your XNA Game Studio Express and Managed DirectX programming problems. If you have a question for the ZMan then send it to zman@thezbuffer.com.

Credits:

Thanks to

• Carlos Aguilar for the code colorizer

Copyright © 2006 TheZBuffer.com

The ZMan runs the #1 Managed DirectX community website http://www.thezbuffer.com.

Introduction

I've always loved mobile technology and I wanted to try my hand at mobile development. So a little ways back I bought a Smartphone, the Motorola MPX220, which runs the Windows Mobile 2003 OS. I hope to upgrade to a new Smartphone soon, so this article will discuss building an application targeting the Windows Mobile 5.0 Smartphone platform.

When deciding what to do, I thought of a variety of useful applications I could build. Then I decided that making a game would be more fun. I settled on a classic: Pac-Man.

Figure 1: Pac-Man running on Windows Mobile 5.0 Smartphone Emulator

Getting Started

Before diving into code, I thought I'd mention some of the pieces involved in developing for the Smartphone.

Development Environment

In order to create applications for the Windows Mobile 5.0 Smartphone platform, the following applications need to be installed:

• Visual Studio .NET 2005 Professional Edition
  
  
• Windows Mobile 5.0 Smartphone SDK
  
  
• ActiveSync Version 4.1.0

New Project

Once the development environment is set up, the new Mobile 5.0 Smartphone templates appear under the New Project dialog in Visual Studio.

Figure 2: New Project dialog in Visual Studio (click image to zoom)

Note that you choose which version of the Compact Framework you are targeting when you select the project template. Those targeting CF1.0 have 1.0 after the name, while the others target the 2.0 Framework.

Development, in general, feels just like development of any WinForm application. You do need to keep in mind, however, that some functionality supported by the standard .NET Framework is not supported by the Compact Framework. For more on support for classes you can look in the MSDN Library.

The Emulator

While developing, you don't have to deploy your application to an actual phone when you want to test. Instead, a built-in emulator, as seen in the Figure 1, is available. With the click of a button, you can deploy to the emulator and test your application with full debugging capability, just like you would a WinForm application. The behavior and speed of the emulator seemed to provide a reasonable indication of how the application would perform on an actual phone.

Development

Instead of rushing in and trying to crank out the code for Pac-Man, I took a more structured approach. With a few proof of concepts under my belt, I decided to build a framework that would provide the common building blocks needed to create 2-D games for a Smartphone. I tried to focus on the following functionality as goals:

• A game board that controls efficient painting and game flow
  
  
• A basis for defining game characters supported by the game board
  
  
• Built-in support for common interactions between characters

A basic litmus test for success would be whether someone (like you) could use this framework to build a classic 2-D video game, like Frogger, by only writing the new code managing interactions between the characters specific to the game.

The remainder of the article will highlight a few of the key concepts I built into the framework.

Sprites

The Sprite class provides the basis for all characters in the game. In Pac-Man, this includes ghosts, dots, walls, and Pac-Man himself. The class is abstract, forcing all derived classes to implement two methods:

public abstract void Update();
public abstract void Draw(Graphics gameSurface);

Not surprisingly, they expect the derived class to update their state and draw themselves to the game board, respectively. Methods are provided for getting the instance of the GameBoard the Sprite has been added to, and detecting collisions between one Sprite and a list of other Sprites. In addition, a Sprite instance is expected to manage several state properties:

• ID—must be unique per GameBoard
  
  
• Bounds—a rectangle that defines the perimeter of the object. A future version could use a Region or other construct to more accurately track the area taken up by the Sprite. This property is used for collision detection and drawing.
  
  
• Invalid—a boolean that tells the GameBoard whether a Sprite needs to be redrawn
  
  
• Visible—a boolean that determines whether a Sprite should be drawn or not

GameBoard

The GameBoard class controls the flow of the game. It derives from System.Windows.Forms.Form, and like the Sprite class, it is not creatable. This inheritance structure allows the developer to handle any Form events needed for his game. Below is an example in which the Pac-Man application's GameBoard class listens to user input by overriding the OnKeyDown method.

protected override void OnKeyDown(KeyEventArgs e)
{
    _KeyPressed = true;
    base.OnKeyDown (e);
    if(e.KeyCode == Keys.Right || e.KeyCode == Keys.Left || e.KeyCode == Keys.Up || e.KeyCode == Keys.Down)
    {
        switch(e.KeyCode)
        {
            case Keys.Right:
            {
                _Pacman.MovementDirection = MovementDirections.Right;
                break;
            }
            case Keys.Left:
            {
                _Pacman.MovementDirection = MovementDirections.Left;
                break;
            }
            case Keys.Down:
            {
                _Pacman.MovementDirection = MovementDirections.Down;
                break;
            }
            case Keys.Up:
            {
                _Pacman.MovementDirection = MovementDirections.Up;
                break;
            }
        }
    }
}

Each game application needs to create its own game board class that derives from GameBoard. All character Sprites should then be created and added to the GameBoard's list of Sprites. Then, after the GameBoard loads, a Timer is used to call the Update and Draw methods on Sprites as mentioned above.

Painting

So how exactly does the drawing of the Sprites work? From a Sprite's perspective, it's simple. All a Sprite needs to know is how to draw itself. A Dot Sprite for example, simply draws a rectangle to the game board graphics object.

public override void Draw(Graphics gameBoard)
{
    if(!_IsEaten)
    {
        gameBoard.FillRectangle(new SolidBrush(Color.LightBlue), _Bounds);
    }
}

The Draw methods for Pac-Man and Ghost Sprites are more complicated and draw one of a series of bitmap images to the game board. The changing images, along with updated Bounds create animation. When drawn, a color is chosen (magenta in the Figure 3 below) to indicate portions of the image that should be treated as transparent.

Figure 3: Ghost Sprite image enlarged

The GameBoard class makes the screen painting as efficient as possible. It overrides the Form OnPaint and OnPaintBackground methods since it controls all the updating of the screen. The OnPaint method makes sure that only the portions of the screen that have changed get repainted. In addition, it uses a back buffer to minimize any flicker.

protected override void OnPaint(PaintEventArgs e)
{
    if(_BackBuffer == null) 
    { 
        return;
    }

    Graphics g = Graphics.FromImage(_BackBuffer);

    ArrayList changedSprites = new ArrayList();
    // blank out any invalid Sprites previous position in the back buffer
    foreach(Sprite sprite in _SpritesByZIndex)
    {
        if(sprite.Invalid)
        {
            g.FillRectangle(new SolidBrush(_BackgroundColor), sprite.PreviousBounds);
            changedSprites.Add(sprite);
        }
    }

    // now draw them to the back buffer
    foreach(Sprite sprite in changedSprites)
    {
        if(sprite.Visible)
        {
            sprite.Draw(g);
        }
    }

    if(_FullRepaint)
    {
        // draw the entire back buffer 
        e.Graphics.DrawImage(_BackBuffer, 0, 0);
        _FullRepaint = false;

        foreach(Sprite sprite in _SpritesByZIndex)
        {
            // reset Invalid flag
            sprite.Invalid = false;
        }
    }
    else
    {
        // only draw the parts that have changed
        foreach(Sprite sprite in changedSprites)
        {
            e.Graphics.DrawImage(_BackBuffer, sprite.Bounds, sprite.Bounds, GraphicsUnit.Pixel);
            e.Graphics.DrawImage(_BackBuffer, sprite.PreviousBounds, sprite.PreviousBounds, GraphicsUnit.Pixel);

            // reset Invalid flag
            sprite.Invalid = false;
        }
    }
}

Mobile Development Considerations

As I've said, from a coding perspective, developing mobile applications in .NET is very similar to building standard WinForm apps. However, this little project did bring to light a number of things you have to keep in mind with mobile applications, most centering around the word "small".

The most obvious consideration is that the device has a small screen. That means you have to design a user interface that is easy to use within the minimal real estate. That tends to translate into keeping things simple. One other screen consideration is that from phone to phone, screen size and resolution may change. I didn't address that with my first cut of Pac-Man, but it's on the list. In my testing I targeted a lower resolution that would work on my phone.

With any type of application, but especially with a game, you have to think about how a user will interact with the small keys of his phone, possibly using no more that a thumb! I consciously made controlling Pac-Man a little different than the typical arcade feel to make up for some of the clumsiness of using the phone's directional pad. That change has received mixed reviews from the people who have tried it out. That's what testing is for, though, right?

The other "small" consideration is the phone's horsepower. While a Smartphone blows away my old Tandy 64K Color Computer, the computer I started playing games on, I definitely found myself needing to tweak the code for performance. I was sure ahead of time that highly efficient painting logic would be necessary. I was surprised, however, to find that the code that prepares the possible travel paths for ghosts takes a considerable amount of time to crunch. For that reason, I made sure that this logic is only processed the first time the splash screen is displayed. It is then cached for later reuse.

Conclusion

So there it is...well, the first version, at least. I plan to periodically update the game making it more efficient and more fun—smarter ghosts for starters. Maybe I'll even eat my own dog food and try building Frogger to see if that little framework I put together holds water. I really want to add a feature to report high scores to a web site. What's a game with out a little healthy competition, right?

I recently started a blog about this and other topics related to software development on my company's blog site. The code and compiled game for the all platforms will be available there, too. Feel free to check for updates and post any feedback you may have.

Welcome to the eighth article on beginning game development. We have spent a lot of time working with the graphics capabilities of DirectX. We also covered how the DirectX API allows us to control input devices. Now we are going to look at another facet of DirectX, the ability to control sound devices. This capability is found in the DirectSound and AudioVideoPlayback namespaces.

Sound in Games

Sound creates an ambiance in a game that provides for a more immersive game experience. Imagine how dull a game would be without sound effects; nothing would indicate when you fire your cannon or an explosion occurs. Sounds also can be used to increase the drama of a scene by increasing the tempo as the action increases.

Sound effects also provide the same audible cues we expect in real life, such as the direction and speed of a person approaching us based on the volume, direction, and frequency of the footsteps. These sound effects add realism to the game just like proper physical behavior of objects do (something I will cover in an upcoming article about physics). Games also provide background music to make playing the game more fun. In newer games, artists who have their music included in a sound track for a popular game see an upswing of sales — it is not unusual for well-known artists to provide music for a game soundtrack. In effect, games have reached the same level as movies with the regards to the importance of soundtracks.

In BattleTank2005 I want to integrate sound in the following way. First, I want standard sound effects for shooting, explosions, and engine noise, and I want that sound to be directionally accurate. What I mean is that when I am getting shot at by an enemy to my left, I want the sound to come from the left and the volume to be an indicator of the proximity of the unit.

Secondly, I want to be able to play background music during game play and I want to control what music plays when in the game. This means I want to have one song play during the splash screen and game setup, another while playing the game, and yet another during the HiScore capturing (we are going to add these screens and states in a later article).

I am going to cover the first requirement in this article, and then cover sound effects and playing MP3 and WMA files with the AudioVideo namespace in the next article. Before we add these features, let's review the capabilities of DirectSound.

DirectSound

The DirectSound namespace only supports playing 2 channel waveform audio data at fixed sampling rates (PCM). While I have no idea what that really means, it is safe to state that you should use DirectSound to play short WAV files and the AudioVideoPlayback namespace for longer MP3 or WMA files. I am not going to cover how to use the sound capturing/recording capabilities of DirectSound namespace — but remember that they exist so you know where to look if your game requires recording sounds as well as playing them.

The DirectSound namespace provides the ability to play and capture sound with three-dimensional positioning effects. DirectSound also provides the ability to add sound effects to the audio played or recorded. Just like in the DirectX3D and the DirectInput namespaces, the actual hardware device used is abstracted into a device class. Just like the device classes in those two namespaces, the DirectSound device uses buffers, has a cooperative level, and has device capabilities. I am not going to cover the sound effects in this article, but they are not forgotten; they will be covered in detail in the next article.

Device

A device is the interface to the audio hardware on the computer. You can either create a Device class using a default GUID (DSoundHelper.DefaultPlaybackDevice) or enumerate all the devices on a system. Like the other device classes, each enumerated device has a list of capabilities stored in a Caps structure in the Caps property for the device. Once you have chosen your device, you instantiate the device class using a specific GUID.

Audio devices also have a cooperative level like the input devices did. The three possible values are: Normal, Priority, and Write Primary. These values are set via the CooperativeLevel enumeration.

Buffers

All the sounds in DirectX are controlled via buffers. These buffers can exist in the memory of the computer or on the sound card itself. The two buffers used in DirectSound are called the primary buffer and secondary buffer.

The primary buffer contains the actual audio data that is sent to the device and is automatically created and managed by the DirectX API. The API mixes the sound in the primary buffer with any secondary buffers. If you need to interact directly with the primary buffer, make sure to change the Cooperative level of the device to Write Primary.

Secondary buffers hold a single audio stream and must be explicitly created by the application. Each application must create at least one secondary buffer to store and play sounds. Each secondary buffer also has a specific waveform format (described in the WaveFormat structure), and only sound data that matches that format can be loaded into that secondary buffer. An application can play sounds of differing formats by creating a separate secondary buffer for each format and letting the API mix them into a common format in the primary buffer. To mix sounds in two different secondary buffers, simply play them at the same time and let the API mix them in the primary buffer. The only limitation to the number of different secondary buffers that can be mixed is the processing power of the system, but remember that any additional processing required will also slow down your game. We have not added any AI or physics computations, but we should be careful with the available processing power.

Any secondary buffer can be used for the life of the application, or it can be created and destroyed as needed. A single secondary buffer can contain the same data throughout the entire game or it can be loaded with different sounds (as long as they match the format). The sound in the secondary buffer can be played once or set up to loop. If the sound to be played is short, it can be loaded into the buffer in its entirety (called a static buffer), but longer sounds must be streamed. It is the responsibility of the application to manage the streaming of the sound to the buffer.

When a buffer is created you have to specify the control options for that buffer using the BufferDescription class. If you use a property of the buffer without first setting it in the control properties, an exception is thrown. The control options can be combined by either setting each property to true or combined in the Flag property.

 1: BufferDescription bufferDescription = new BufferDescription ( );

 2: // Use the seperate properties

 3: bufferDescription.ControlVolume = true;

 4: bufferDescription.ControlPan = true;

 5: // or combine them in the Flags property

 6: bufferDescription.Flags = BufferDescriptionFlags.ControlVolume | BufferDescriptionFlags.ControlPan;

Controlling Volume, Pan, and Frequency

To control these settings of the buffer you must first set the ControlPan, ControlVolume, and ControlFrequency properties of the buffer to true. You can then set the pan, volume, and frequency values using the buffer's Pan, Volume, and Frequency properties.

Volume is expressed in hundredths of a decibel and ranges from 0 (full volume) to -10,000 (completely silent). The decibel scale is not linear, so you may reach effective silence well before the volume setting reaches true silence at -10,000. There is also no way to increase the volume of the sound above the volume it was recorded at, so you have to make sure to record the sound with a high enough volume to at least match the desired maximum volume in the game.

Pan is expressed as an integer and ranges from -10,000 (full left) to +10,000 (full right), with 0 being center.

The frequency value is expressed in samples per seconds and represents the playback speed of the buffer. A larger number plays the sound faster and raises the pitch while a smaller number slows the speed down and lowers the pitch. To reset the sound to its original frequency, simply set the frequency value to 0. The minimum value for frequency is 100 and the maximum value is 200,000.

At this point you may think that we could use the volume, pan, and frequency settings to manipulate the sound and make it reflect the direction and distance of its origin. This was, after all, one of our original requirements. But instead of us performing the calculations to determine the relative locations and distances of each object, DirectX provides an API to do just that for us.

3D Sound

The 3D features of DirectX allow us to locate sounds in space and apply Doppler shift to moving sounds.

Note   Check out this excellent explanation of the Doppler effect at Wikipedia, or use this applet to help yourself to visualize what it is.

Before describing how DirectX handles sound in three dimensions, it is probably useful to talk about how we perceive sound. DirectX uses these same principles to make the sound appear as realistic as possible.

1. The volume of a sound decreases at a fixed rate as the distance to the listener increases. This effect is called Rolloff. The relationship between the volume of a sound and its distance from the listener is inverse-proportional, meaning that if the distance is halved the volume doubles. (See: http://en.wikipedia.org/wiki/Inverse_square_law)
   
   
2. The listener perceives sounds coming from the left as louder in the left ear than the in right ear (interaural intensity difference) and also hears sounds coming from the left sooner in the left ear than the right ear (interaural time difference). (See: http://en.wikipedia.org/wiki/Interaural_Intensity_Difference)
   
   
3. The shape of the ear produces an effect called "muffling": sounds coming from the front are perceived as louder than those coming from the back. This is, of course, because the human ear is directed towards the front of the head.
   
   
4. The ridges of the earlobe slightly alter the sound arriving from different directions. This provides cues to the brain about the location of the sound source. This effect can be modeled mathematically and is called the Head Related Transfer Function (HRTF). (See: http://en.wikipedia.org/wiki/Head_Related_Transfer_Function)

We already know that DirectX uses the left-handed Cartesian coordinates system and Vectors to express position and directional information. This same system is also used by DirectSound in its computations. One important piece of information when dealing with 3D sound is that the default unit of measurement for distance is the meter and the default measurement for velocity is meters per second. You need to make sure to use a common system of measurement in the game. You can change this by setting the DistanceFactor property of the Listener3D object to a value that represents the meters per application-specified distance unit. If you have been using feet in all your calculations up to this point, simply set this value to 0.3048 (there are 0.3048 meters in a foot).

Also, since we are leaving the manipulation of the sound to DirectX (as opposed to us changing the volume, pan, and frequency), we must ensure that the sound source we are using is a mono and not stereo source. Finally, make sure to set the Control3D property of the buffer to true to enable 3D sounds.

DirectSound uses two objects to manage 3D sounds in the application: Buffer3D and Listener3D.

3D Buffers

Unlike the SecondaryBuffer, a Buffer3D object does not inherit from the Buffer class. Instead you create a 3D Buffer object by passing it a SecondaryBuffer in the constructor. The 3D Buffer exposes a number of properties that determine how the sound is processed.

The MinDistance property determines at which distance the sound volume is no longer increased. You can also use this setting to make certain sounds appear louder even if they were recorded at the same volume (see the DirectX documentation for a detailed explanation of this). The default value for this property is 1 meter, meaning that the sound is at full volume when the distance between the listener and the sound source equals 1 meter.

The MaxDistance property is the opposite and determines the distance after which the sound no longer decreases in volume. The default value for this property is 1 billion meters, which is well beyond hearing range anyway. To avoid unnecessary processing, you should set this value to a reasonable value and set the Mute3DAtMaximumDistance property of the BufferDescription to true.

Finally, we can also specify values for the sound cone if the sound is directional. A sound cone is almost identical to the cone produced by a spotlight (see article 6). It consists of a set of angles, one for the inside and one for the outside cone, and orientation, and an outside volume property. Check out the DirectX documentation for more detail on sound cones.

3D Listeners

While the 3D Buffer describes the source of a sound, the 3D Listener describes the, well, listener. Just as the position, orientation, and velocity of the buffer affects the sound, so does the position, orientation, and velocity of the listener. The default listener in DirectX is located at the origin pointing toward the positive z-axis, and the top of the head is along the positive y-axis. Each application can only have one Listener3D object.

To change the way the player hears the sound in your game, you manipulate the position, orientation, and velocity of the Listener. You can also control global settings of the acoustic environment like the Doppler shift or Rolloff factor.

Note   The DopplerFactor and RolloffFactor properties are a number between 0 and 10. Zero means that the value is turned off. One represents the real world values of these acoustic effects. All other values are multiples, so that a 2 means doubling the real world effect, 3 means tripling it, and so on.

In BattleTank2005 we are going to add three new classes; a SoundDevice class to represent the actual audio device, a SoundListner class to encapsulate the Listener3D object, and a SoundEffects class to represent each separate sound effect. Each tank in BattleTank2005 can have multiple sounds associated with it, such as engine noise and the noise made when firing. To integrate sound we are going to update the Tank class to play these sounds at the appropriate time and with the appropriate position information. I did not add this functionality to the UnitBase class because the stationary objects (the obstacles) will not have any sounds associated with them.

Before we start adding these classes we need add a reference to the Microsoft.DirectX.DirectSound.DLL assembly. Make sure to choose the 1.0 and not the 2.0 version. BattleTank2005 has not yet been updated to use the beta versions of the 2.0 DirectX API. Add a new class called SoundDevice and add the using statement for Microsoft.DirectX.DirectSound. All three of the classes will implement the IDisposable interface and use the same Dispose pattern that we used in the Keyboard and Mouse classes. (I omitted that portion from the code samples below to keep them more compact and easy to understand).

Following the now familiar patterns we add a private variable called _device to the SoundDevice class and instantiate it in the constructor. We also need to set the CooperativeLevel before we can use the device. As discussed earlier, we will use CooperativeLevel.Priority setting. We also pass a reference of the game form to this method so that the device can receive Windows messages. Finally, we surround the device creation code with a Try/Catch, since things can go wrong whenever we work with devices.

 1: using System;

 2: using Microsoft.DirectX.DirectSound;

 3:  

 4: namespace BattleTank2005

 5: { 

 6: class SoundDevice : IDisposable 

 7: { 

 8: public SoundDevice( System.Windows.Forms.Form parentForm ) 

 9: { 

 10: try

 11: {

 12: _device = new Microsoft.DirectX.DirectSound.Device(); _device.SetCooperativeLevel(parentForm, CooperativeLevel.Priority); } catch

 13: {

 14: // Can not use sounds

 15: }

 16: }

 17: 

 18: public Microsoft.DirectX.DirectSound.Device AudioDevice 

 19: { 

 20: get { return _device; } 

 21: } 

 22: 

 23: private Microsoft.DirectX.DirectSound.Device _device; 

 24: }

 25: }

The next class we need is the SoundListener class. After adding the using statements for DirectSound and DirectX, we construct the class by passing a reference to the SoundDevice class created earlier. The Listener needs to be associated with the Primary Buffer of the audio card so it can "hear" the final mixed sounds. Even so, the SoundListener class is largely passive, so we do need to update its position, velocity, and orientation to enable 3D sounds on the buffer. Once the buffer is created we pass it to the constructor of the Listener3D class to create the Listener. The final step is to store the Listener3DSettings of the listener in a local variable so we can access them in the Update method.

The Update method provides the way in which we pass the position information to the Listener object.

The last step is to apply the updated values to the Listener. We do this by calling the CommitDeferredSettings method of the Listener3D class after updating the Listener3DSettings values. This method simply commits all changes made to the Listener3DSettings since the last time the method was called. When all is done, the SoundListener class is positioned at the correct location in the game.

 1: using System;

 2: using Microsoft.DirectX;

 3: using Microsoft.DirectX.DirectSound;

 4:  

 5: namespace BattleTank2005

 6: { 

 7: class SoundListener : IDisposable 

 8: { 

 9: public SoundListener(SoundDevice soundDevice) 

 10: { 

 11: BufferDescription bufferDescription = new BufferDescription(); 

 12: bufferDescription.PrimaryBuffer = true; 

 13: bufferDescription.Control3D = true; 

 14: 

 15: // Get the primary buffer

 16: Microsoft.DirectX.DirectSound.Buffer buffer = new Microsoft.DirectX.DirectSound.Buffer(bufferDescription, soundDevice.AudioDevice); 

 17:  

 18: // Attach the listener to the primary buffer

 19: _listener3d = new Listener3D(buffer); 

 20: 

 21: // Store the initial parameters

 22: _listenerSettings = new Listener3DSettings(); 

 23: _listenerSettings = _listener3d.AllParameters; 

 24: } 

 25:  

 26: public void Update(Vector3 position ) 

 27: { 

 28: _listener3d.Position = position; 

 29: _listener3d.CommitDeferredSettings(); 

 30: } 

 31: 

 32: private Microsoft.DirectX.DirectSound.Listener3D _listener3d; 

 33: private Listener3DSettings _listenerSettings; 

 34: }

 35: }

Now that we have classes representing the audio device and a class to "listen" to the sounds, we need to actually create the sounds. For this we add the SoundEffect class. Once again we need to add the using statement for the DirectSound namespace. We also need to add a using statement for the DirectX namespace because we are going to use the Vector3 class.

A SoundEffect is created by passing a reference to the SoundDevice and a path to a WAV file containing a sound. In the constructor, we create a BufferDescription object that will "turn on" all of the capabilities we want. For right now we want the ability to control sounds in 3D, adjust the volume, and change the frequency. Next we create a secondary buffer passing in the path to the sound file and the BufferDescription we just created. To create the Buffer3D that we need to play 3D sounds, we pass the SecondaryBuffer to the Buffer3D class on instantiation, and voila! we have a 3DBuffer.

Once the Buffer3D class is set up we can access the properties and change the settings. We set the MaxDistance to a more manageable number. This setting combined with the Mute3DAtMaximumDistance setting on the SecondaryBuffer ensures that sounds too distant to hear are not played at all and don't consume any processing cycles.

To actually use the SoundEffect in the game we provide three public methods: one to play the sound one to stop the Sound (if it is looping) and one to update the class. The Play method either plays the sound once or loops the sound depending on the setting of the _isLooping variable. If the sound is looping, we need to be able to stop it, and that is what the Stop method does. The Update method is the way in which we pass the updated position of the tank the sound is associated with to the sound buffer so it can be accurately calculated.

 1: using System;

 2: using Microsoft.DirectX.DirectSound;

 3: using Microsoft.DirectX;

 4:  

 5: namespace BattleTank2005

 6: { 

 7: public class SoundEffects : IDisposable 

 8: { 

 9: public SoundEffects( SoundDevice soundDevice, string soundFile) 

 10: { 

 11: BufferDescription bufferDescription = new BufferDescription(); 

 12: bufferDescription.Control3D = true; 

 13: bufferDescription.ControlVolume = true; 

 14: bufferDescription.ControlFrequency = true; 

 15: bufferDescription.Mute3DAtMaximumDistance = true; 

 16: 

 17: try

 18: {

 19: _secondaryBuffer = new SecondaryBuffer(soundFile, bufferDescription, soundDevice.AudioDevice); 

 20: _3dBuffer = new Buffer3D(_secondaryBuffer); 

 21: _3dBuffer.MaxDistance = 10000; 

 22: }

 23: catch

 24: {

 25: // Can not use sounds

 26: }

 27: }

 28: 

 29: public void Update(Vector3 position){ 

 30: _3dBuffer.Position = position; 

 31: } 

 32: 

 33: public void Play() 

 34: { 

 35: if (_isLooping == true) 

 36: _secondaryBuffer.Play(0, BufferPlayFlags.Looping); 

 37: else

 38: _secondaryBuffer.Play(0, BufferPlayFlags.Default);

 39: }

 40:  

 41: public void Stop() 

 42: { 

 43: _secondaryBuffer.Stop(); 

 44: _secondaryBuffer.SetCurrentPosition(0); 

 45: } 

 46: 

 47: public bool IsLooping 

 48: { 

 49: set { _isLooping = value; } 

 50: } 

 51:  

 52: public int Volume 

 53: { 

 54: set { _secondaryBuffer.Volume = value; } 

 55: } 

 56:  

 57: public int Frequency 

 58: { 

 59: set { _secondaryBuffer.Frequency = value; } 

 60: } 

 61:  

 62: private SecondaryBuffer _secondaryBuffer; 

 63: private Buffer3D _3dBuffer; 

 64: private bool _isLooping; 

 65: }

 66: }

Now we need to integrate these new classes into the overall game. The first step is to add a private variable to the GameEngine class to hold a reference to the SoundDevice and SoundListener classes because we can only have one of each of these classes. At the bottom of the GameEngine class, add the following code:

private SoundDevice _soundDevice;

  
private SoundListener _soundListener;

Next, we need to instantiate each class. The Initialize class of the GameEngine is the perfect spot for this, but to keep sound-related items together we will create a method called ConfigureSounds. In the GameEngine class add the following method:

private void ConfigureSounds()

  
{

  
_soundDevice = new SoundDevice(this);

  
_soundListener = new SoundListener(_soundDevice);

  
}

Now add a call to the ConfigureSounds method to the Initialize method of the GameEngine right after the call to the ConfigureDevice method.

ConfigureDevice();
    
ConfigureSounds()

With regard to the SoundDevice class, this is all we have to do. After creation all we need this class for is its reference to the Device object. The SoundListener class, however, needs to be updated with the correct position information in each frame. The Render method of the GameEngine class is the perfect place for this. We simply pass in the position of the camera class since it represents our location in the game. In the Render method of the GameEngine class, add the following code immediately after the call to the Update method of the camera.

Each tank gets a unique instance of the SoundEffect class for each sound it can make. First we need to add some private variables to hold the two sound effects we want the tank to make. At the bottom of the Tank class add the following code:

private SoundEffects _engineSound;

  
private SoundEffects _fireSound;

To make sure each tank has the necessary sound we will pass them in the constructor. Update the constructor of the Tank class to look as follows (the new code is in bold):

 1: public Tank(Device device, string meshFile, Vector3 position, float scale, 

 2: float speed, SoundEffects fireSound, SoundEffects engineSound)

 3: : base(device, meshFile, position, scale)

 4: { 

 5: _speed = speed; 

 6: _engineSound = engineSound; 

 7: _engineSound.IsLooping = true; 

 8: _engineSound.Play(); 

 9: _fireSound = fireSound; 

 10: }

Once the sound effects are associated with the tank instance we start the engine sound after setting it to looping.

The next step is to change the Update method of the Tank class to add updating the 3D buffer with the position of the tank. Add the following code to the end of the Update method:

if (_engineSound != null)

  
{

  
_engineSound.Update(base.Position);

  
}

The shooting sound of the tank is not continuous, and whether or not the tank shoots will be determined by the AI we are going to add later on. For now, all we are going to do is create the necessary framework to play the shooting sound. Add the following method to the Tank class:

public void Shoot()

  
{

  
if (_fireSound != null)

  
{

  
_fireSound.Update(base.Position);

  
_fireSound.Play();

  
}

  
}

The final step for updating the tank class to be sound ready is to update the CreateTanks method of the GameEngine. We need to create the SoundEffect for the engine noise and the firing noise, and pass them to the tank class on creation. Change the CreateTanks method to look as follows:

private void CreateTanks()

  
{

  
_tanks = new List<UnitBase>();

  
SoundEffects engineSound1 = new SoundEffects(_soundDevice, @"EngineSound1.wav");

  
engineSound1.Volume = -1000;

  
engineSound1.Frequency = 100000; // Set to a value between 100 - 200000 SoundEffects engineSound2 = new SoundEffects(_soundDevice, @"EngineSound2.wav");

  
engineSound2.Volume = -1000;

  
engineSound2.Frequency = 10000; // Set to a value between 100 - 200000 SoundEffects fireSound = new SoundEffects(_soundDevice, @"Fire.wav");

  
Tank newTank1 = new Tank(_device, @"bigship1.x", new Vector3(0.0f, 20.0f, 100.0f), 

  
 1f, 10.0f, fireSound, engineSound1);

  
Tank newTank2 = new Tank(_device, @"bigship1.x", new Vector3(100.0f, 20.0f, 100.0f), 

  
 1f, 10.0f, fireSound, engineSound2);

  
_tanks.Add(newTank1);

  
_tanks.Add(newTank2);

  
}

This is where you can experiment with changing the volume or frequency of the sound effect. Fly around and get closer to each spaceship, and the sound will vary in direction and volume according to your position. Change the frequency, and the pitch will change, and you can guess what the volume setting does.

Summary

When you play BattleTank2005 now, you should hear the engine noises of the various enemy tanks properly adjusted for their spatial relationship to the listener (you). At this point, we have integrated the first set of the audio features we want to add to BattleTank2005. You should definitely experiment with the various settings to hear their effect. I have left several optional settings commented in the code so you can easily change them. In the next article we are going to cover how to use the built-in sound effect manipulation of DirectSound to change the sounds, and how to play a regular MP3 file for the soundtrack using the AudioVideoPlayback namespace.

Until then: Happy coding!

1. Beginning Game Development Part 1 - Introduction
2. Beginning Game Development Part II - Introduction to DirectX
3. Beginning Game Development: Part III - DirectX II
4. Beginning Game Development: Part IV - DirectInput
5. Beginning Game Development: Part V - Adding Units
6. Beginning Game Development: Part VI - Lights, Materials and Terrain
7. Beginning Game Development: Part VII –Terrain and Collision Detection
8. Beginning Game Development: Part VIII - DirectSound
9. Beginning Game Development: Part VIII - DirectSound II
10. Beginning Game Development: Part VIII - DirectSound III

Welcome to the fifth article on beginning game development. At this point we have a working 3D environment and can manipulate the camera direction and location using the keyboard and mouse. In this article we are going to add 3D objects to the game using predefined mesh files and implement some simple culling.

Code cleanup

The cleanup in this article consists mainly of fixing the navigation keys and removing some items we no longer need. The following changes have already been integrated into the code for this article:

• Replaced the radian/degree conversion methods in the Camera class with the utility classes in the Geometry class.
• Fixed the key assignments in the CheckForInput method in the GameEngine class so that:
  • W and S adjust the Z-axis. W is forward (positive) and S backward (negative)
  • A and D adjust the X-axis. A is left (negative) and D is right (positive).
  • Q and Z adjust the Y-axis. Q is up (positive) and Z is down (negative). Movement along the Y-axis is going to be removed later on, since our tank can not fly.
• Adjusted the initial position of the camera to be above the surface level by setting the _z variable in the Camera class to 10. This represents our vantage point in the tank, which should be higher than zero.
• Removed the Joystick class.
• Updated to the August SDK.
• Changed the GetElapsedTime method in the HiResTimer class to return a float and changed _deltaTime in GameEngine to a float.
• Removed HiResTimer.Reset from the GameEngine Render method, moved HiResTimer.Start into the constructor of the GameEngine class.

IDispose

You may have noticed that some of the classes, such as the Keyboard and Mouse classes, implement the IDisposable interface. This is an implementation of the Dispose pattern in .NET as explained in the .NET Framework Reference topic Implementing Finalize and Dispose to Clean Up Unmanaged Resources.

The Dispose pattern in .NET is intended to be used when a program makes use of resources that are not managed by the .NET runtime. These "unmanaged" resources need to be cleaned up in a special way to ensure that they are released in a deterministic manner. Since the .NET garbage collection is non-deterministic, we need to use a particular set of steps to ensure this cleanup is done correctly. These steps are defined in the Dispose pattern.

We use a lot of unmanaged resources in game development, so it is best to implement the Dispose pattern in every class that interacts with DirectX or file resources (almost all of our classes). This will protect us against memory leaks and increase the performance of the game.

You can read the topic mentioned above to get more background information on this pattern and garbage collection for .NET. I have added the Dispose pattern in all of the classes for this article, and will do so going forward.

What we need in BattleTank 2005 now are units. If you go back to the screenshot of the original game shown in the first article, you see that we need to add shapes and opposing tanks. The shapes are obstacles for you or the enemy tanks to use as cover. The enemy tanks are what we are going to eventually shoot at. These objects also aid us in navigation in the otherwise bare landscape. You may remember that we had to write out the camera location to the console to see that we were moving because there were no reference points in the scene. In the next article we will complete the scene by adding some terrain.

Units

For BattleTank 2005 we are going to have two types of 3D objects: Obstacles and Tanks. The main difference between them is that tanks can move and obstacles can not. Since we are going to have lots of obstacles and tanks, we are going to organize them so that they can be manipulated in bulk. We do this by adding them to a collection.

We could add both types of objects to a single collection, but it makes sense to separate each type into its own collection. Separating the objects in this manner allows us to concentrate on a particular group without incurring the overhead of testing each unit for its type, which improves performance. We can then update the position of the mobile units while skipping the stationary units.

Generics

In previous versions of .NET, creating a collection class to hold the units and ensuring that it was type-safe was pretty involved. Each collection in .NET 1.0 and 1.1 was a collection of objects. This meant that it accepted any value or reference type, making it very flexible. But this also meant that we had to cast the object to its proper type whenever we retrieved an object from the collection. This meant we ran the danger of the object cast failing. Accounting for the possible exception and testing each object before the cast incurred more overhead.

With .NET 2.0 we can use Generics to create type-safe collections for us with minimum effort. These collection classes are safer and perform better than regular collection. This is only one of the possible uses of generics, but probably the most common.

To learn more about generics check out these articles at MSDN:

• An Introduction to C# Generics
• MSDN Magazine: Introducing Generics in the CLR

All units, regardless of their purpose, have a number of things in common. To make the application easier to maintain, we are going to factor all of the common characteristics of the unit into a single base class. All units will derive from the common base class and be extended with custom properties and methods.

Creating a base class and derived classes creates an object hierarchy that then allows us to treat all units polymorphically, which is a very powerful concept in object oriented programming. Check out these Visual Studio .NET topics on polymorphism at MSDN:

• Visual Basic Reference: Polymorphism
• Visual Basic and Visual C# Concepts: Polymorphism in Components

The resulting base class looks like this.

Visual C#

public abstract class UnitBase : IDisposable
{
    public UnitBase (Device device, string meshFile,
        Vector3 position, float scale )
    public void Render ( Camera camera )

    public bool IsCulled
    public Vector3 Position
    public float Radius
    private void LoadMesh ( )
    private void ComputeRadius ( )

    private Vector3 _position;
    private float _radius;
    private bool _isCulled;
    private Device _device;
    private string _meshFile;
    private float _scale;
    private Mesh _mesh = null;
    private Material[] _meshMaterials;
    private Texture[] _meshTextures;
}

Visual Basic

Public MustInherit Class UnitBase
    Implements IDisposable
    Public Sub New(ByVal device As Device, _
        ByVal meshFile As String, ByVal position As Vector3, _
        ByVal scale As Single)

    Public Sub Render(ByVal camera As Camera)

    Public Property IsCulled() As Boolean
    Public Property Position() As Vector3
    Public Property X() As Single
    Public Property Y() As Single
    Public Property Z() As Single
    Public ReadOnly Property Radius() As Single
    Public Sub Dispose() Implements IDisposable.Dispose
    Protected Overridable Sub Dispose(ByVal disposing As Boolean)
    Protected Overrides Sub Finalize()
    Private _disposed As Boolean
    Private Sub LoadMesh()
    Private Sub ComputeRadius()
    Private m_position As Vector3
    Private m_radius As Single
    Private m_isCulled As Boolean
    Private m_device As Device
    Private m_meshFile As String
    Private m_scale As Single
    Private m_mesh As Mesh = Nothing
    Private m_meshMaterials As Material()
    Private m_meshTextures As Texture()
End Class

While most of this should make sense, you may be wondering what a mesh file is and why we are loading it.

3D Modeling

At some point you realize that creating complex 3D objects in code line by line is pretty silly. The simple cube we created for the skybox alone was almost 200 lines of code. There has to be a better way to create 3D objects.

Most 3D models are created by artists using dedicated modeling programs such as Maya or 3ds Max. These programs store the information about their models in proprietary file formats (iff for Maya and 3ds for 3DS Max). DirectX can not directly read these file formats, but it can read a format called the X file.

X Files

DirectX defines a file format called the X file format. It contains the definition for a 3D model. We can use these files to dramatically reduce the amount of code we need to write when loading 3D models into our game by loading them from the X file. In DirectX lingo, the X files are mesh files.

Mesh

If you remember from our previous article, a mesh is data that describes a 3D shape. Mesh data includes a list of vertices that comprise the shape, information on how the vertices are connected to each other, and texture information for all vertices.

There are also conversion programs available that convert 3D objects files from other formats into the X file format. The DirectX SDK actually ships with plug-ins for Maya and 3ds Max that allow you to convert files created with these programs into the X file format.

So where can you get some X files to start working with? The DirectX SDK includes a folder called Media under the Samples folder which contains a number of X files that you can use. The DirectX SDK also includes a number of utilities that allow you to work with the X files such as the DirectX viewer and MeshViewer. All of the utilities are located in the Utilities folder. Check out these and the other utilities that come with the SDK, as they can save you time and effort.

Free 3D models: Unless you are very graphically talented it is probably best for an artist to create the models for your game. There are a large number of free 3D models available on the internet created by artists to show of their skills. Generally they don't mind if you use their work for you own gratification, but if you use it in a commercial game, that's a whole other issue. Make sure to read and understand the usage rules for each model before using it. A good site for free models is: http://www.3dcafe.com/.

Using X files with predefined models opens up an entirely new world of integrating 3D objects into our game. No longer do we need to worry abut the low-level details of each object, we can simply load a previously created mesh file.

Updating the Skybox

The first place we are going to use this newfound knowledge is to clean up the skybox code. The SDK includes a file called lobby_skybox.x in the Samples\Media\Lobby folder that describes a cube like the one we are currently using for our sky box. I copied this file to the Resources folder as skybox.x and updated the texture files to match the names of our texture files.

Changing textures: Most X files can be opened in a simple text editor. You can search the file for the references to the texture files (look for TextureFilename) and replace them with your own, or you can substitute your own texture files during the mesh loading phase by passing the texture file name to the TextureLoader.FromFile method. If you want to see something cool, copy the lobby_skybox.x files and all of the JPG files from the SDK media folder to the resource folder, then change the name of the X file in the skybox LoadMesh method to this X file. The resulting skybox is the lobby of the building where all the game developers work at Microsoft.

In the Skybox class remove the SetupCubeFaces method, the six methods starting with Copy (CopyLeftFaceVertexBuffer, CopyFrontFaceVertexBuffer, etc.) and the RenderFace method. You can also remove all of the private variables declared at the bottom of the class except for the Device variable. In the Render method, remove the lines of code that check the Pitch and Heading of the camera. Finally, replace the call to SetupCubeFaces in the constructor with a call to LoadMesh.

Now add the following three variable declarations at the bottom of the class.

Visual C#

private Mesh _mesh = null;
private Material[] _meshMaterials;
private Texture[] _meshTextures;

Visual Basic

Private m_mesh As Mesh = Nothing
Private m_meshMaterials As Material()
Private m_meshTextures As Texture()

We already know what a mesh and a texture is, but what is the material?

Material

Materials describe how polygons reflect ambient and diffuse light, as well as information about specular highlights and if the polygons appear to emit light. The main thing to remember is that while textures define how polygons look, materials define how they reflect light.

Loading a Mesh

Loading the mesh from a file is very simple. All you have to do is to call the FromFile method of the Mesh class. (You should spend some time to familiarize yourself with the Mesh class and its methods, since it is one of the core classes you will use.)

In the Skybox class add the following code.

Visual C#

private void LoadMesh ( )
{
    ExtendedMaterial[] materials = null;
    Directory.SetCurrentDirectory ( 
        Application.StartupPath + @"\..\..\..\Resources\" );
    _mesh = Mesh.FromFile (@"skybox.x",
        MeshFlags.SystemMemory, _device, out materials);
    if ( ( materials != null ) && ( materials.Length > 0 ) )
    {
        _meshTextures = new Texture[materials.Length];
        _meshMaterials = new Material[materials.Length];
        for ( int i = 0 ; i < materials.Length ; i++ )
        {
            _meshMaterials[i] = materials[i].Material3D;
            _meshMaterials[i].Ambient = _meshMaterials[i].Diffuse;
            if (materials[i].TextureFilename != null && 
                    (materials[i].TextureFilename != string.Empty))
                _meshTextures[i] = TextureLoader.FromFile ( _device, 
                    materials[i].TextureFilename );
        }
    }
}

Visual Basic

Private Sub LoadMesh()
    Dim materials As ExtendedMaterial() = Nothing
    Directory.SetCurrentDirectory(Application.StartupPath _ 
        & "\..\..\..\Resources\")
    m_mesh = Mesh.FromFile("skybox.x", MeshFlags.SystemMemory, _
        m_device, materials)

    If (Not (materials Is Nothing)) AndAlso _
        (materials.Length > 0) Then
        m_meshTextures = New Texture(materials.Length) {}
        m_meshMaterials = New Material(materials.Length) {}
        Dim i As Integer = 0
        While i < materials.Length
            m_meshMaterials(i) = materials(i).Material3D
            m_meshMaterials(i).Ambient = m_meshMaterials(i).Diffuse
            If Not (materials(i).TextureFilename Is Nothing) AndAlso _
                    (Not (materials(i).TextureFilename = String.Empty)) Then
                m_meshTextures(i) = TextureLoader.FromFile( _
                    m_device, materials(i).TextureFilename)
            End If
            System.Math.Min(System.Threading.Interlocked.Increment(i), i - 1)
        End While
    End If
End Sub

While DirectX handles most of the work of reading the X file and converting it into an object for us (i.e. the creation of the vertex and index buffers etc.) we have to manually manage loading the materials and textures for the mesh.

The last step to integrate the X file and textures into the Skybox is to modify the Render method of the Skybox class. Immediately after the _device.RenderState.CullMode = Microsoft.DirectX.Direct3D.Cull.None; line add the following code.

Visual C#

for ( int i = 0 ; i < _meshMaterials.Length ; i++ )
{
    _device.Material = _meshMaterials[i];
    _device.SetTexture ( 0, _meshTextures[i] );
    _mesh.DrawSubset ( i );
}

Visual Basic

While i < m_meshMaterials.Length
    m_device.Material = m_meshMaterials(i)
    m_device.SetTexture(0, m_meshTextures(i))
    m_mesh.DrawSubset(i)
    System.Math.Min(System.Threading.Interlocked.Increment(i), i - 1)
End While

Once again we iterate over the meshMaterials and then call the DrawSubset method of the Mesh to draw each subset in turn. That's it; the entire Skybox class is now only about 80 lines long and much easier to read.

Returning to the UnitBase class, the next item we need to look at is the IsCulled flag.

Culling

We briefly covered culling in the third article. Culling is simply the removal of entire objects from the scene so they will not be rendered. The logic to determine what objects should be removed can range from the very simple to the very complex. In BattleTank 2005 we are going to cull all of the objects that do not fall into the view frustum of the scene.

To determine if the unit is in the view frustum, we enhance the Camera class to provide us the info about the current view frustum so that we can check each object and see if it falls inside or outside of the frustum. To perform this check, we use the Radius property of the UnitBase class which is computed in the ComputeRadius method.

The BoundingSphere method of the Geometry class (the same one we use now for converting radians to degrees and vice versa) computes a sphere that completely contains all the points in the mesh using a vertex data of the mesh. The mesh contains this information in the vertex buffer. To access this buffer, it is best to lock it before access and unlock it when done. You should also make sure to dispose the vertex buffer when you are done. The safest way to do this is to leverage the using statement that will ensure that Dispose is called regardless of what happens.

Visual C#

private void ComputeRadius ( )
{
    using ( VertexBuffer vertexBuffer = _mesh.VertexBuffer )
    {
        GraphicsStream gStream = vertexBuffer.Lock ( 0, 0,
            LockFlags.None );
        Vector3 tempCenter;

        _radius = Geometry.ComputeBoundingSphere (gStream,
            _mesh.NumberVertices, _mesh.VertexFormat, 
            out tempCenter ) * _scale;

        vertexBuffer.Unlock ( );
    }
}

Visual Basic

Private Sub ComputeRadius()
    Dim vertexBuffer As VertexBuffer = Nothing
    Try
        vertexBuffer = m_mesh.VertexBuffer
        Dim gStream As GraphicsStream = _
            vertexBuffer.Lock(0, 0, LockFlags.None)
        Dim tempCenter As Vector3
        m_radius = Geometry.ComputeBoundingSphere(gStream, _
            m_mesh.NumberVertices, m_mesh.VertexFormat, tempCenter) * _
            m_scale
    Finally
        vertexBuffer.Unlock()
        vertexBuffer.Dispose()
    End Try
End Sub

You can probably understand why using the radius of the object is a very rough way of culling objects. It works fine and is fairly accurate if the objects are simple shapes, but for more complex shapes the bounding sphere becomes much larger than the basic object itself.

In a commercial game a lot of effort is invested in creating a culling routine that eliminates the most objects it can. We could also get fancy here and identify objects that are only partially in the frustum, but without the corresponding ability to render only a portion of the unit, we are just wasting our time. Instead we will treat any unit that has even a single point in the view frustum as being completely in the frustum.

So now that we have the radius of the unit, we need to know what the frustum is so we can check the radius against it.

View Frustum

Adding the frustum info to the camera is easy. First we add some data structures to hold the information about the view frustum. If you recall from the previous article, a frustum resembles a pyramid with the top cut off. This means that we need to store the corners of the top and bottom square and the plane for each side. For the corners we use an array of the familiar Vector3 structure. For the planes DirectX provides a convenient Plane structure.

Visual C#

private Vector3[] _frustumCorners;
private Plane[] _frustumPlanes;

Visual Basic

private Vector3[] _frustumCorners;
private Plane[] _frustumPlanes;

We then initialize the arrays in the constructor (two squares with four corners equals 8 points, and the four sides of the polygon plus the top and bottom make six planes).

Visual C#

_frustumCorners = new Vector3[8];
_frustumPlanes = new Plane[6];

Visual Basic

m_frustumCorners = New Vector3(8) {}
m_frustumPlanes = New Plane(6) {}

The next step is to compute the frustum using the current view and projection matrices.

Visual C#

private void ComputeViewFrustum ( )
{
    Matrix matrix = _viewMatrix * _perspectiveMatrix;
    matrix.Invert ( );

    _frustumCorners[0] = new Vector3 ( -1.0f, -1.0f, 0.0f ); // xyz
    _frustumCorners[1] = new Vector3 ( 1.0f, -1.0f, 0.0f ); // Xyz
    _frustumCorners[2] = new Vector3 ( -1.0f, 1.0f, 0.0f ); // xYz
    _frustumCorners[3] = new Vector3 ( 1.0f, 1.0f, 0.0f ); // XYz
    _frustumCorners[4] = new Vector3 ( -1.0f, -1.0f, 1.0f ); // xyZ
    _frustumCorners[5] = new Vector3 ( 1.0f, -1.0f, 1.0f ); // XyZ
    _frustumCorners[6] = new Vector3 ( -1.0f, 1.0f, 1.0f ); // xYZ
    _frustumCorners[7] = new Vector3 ( 1.0f, 1.0f, 1.0f ); // XYZ
    for ( int i = 0 ; i < _frustumCorners.Length ; i++ )
        _frustumCorners[i] = Vector3.TransformCoordinate (
            _frustumCorners[i], matrix );

    // Now calculate the planes
    _frustumPlanes[0] = Plane.FromPoints (
        _frustumCorners[0], 
        _frustumCorners[1], 
        _frustumCorners[2] ); // Near
    _frustumPlanes[1] = Plane.FromPoints ( 
        _frustumCorners[6], 
        _frustumCorners[7], 
        _frustumCorners[5] ); // Far
    _frustumPlanes[2] = Plane.FromPoints ( 
        _frustumCorners[2], 
        _frustumCorners[6], 
        _frustumCorners[4] ); // Left
    _frustumPlanes[3] = Plane.FromPoints ( 
        _frustumCorners[7], 
        _frustumCorners[3], 
        _frustumCorners[5] ); // Right
    _frustumPlanes[4] = Plane.FromPoints ( 
        _frustumCorners[2], 
        _frustumCorners[3], 
        _frustumCorners[6] ); // Top
    _frustumPlanes[5] = Plane.FromPoints ( 
        _frustumCorners[1], 
        _frustumCorners[0], 
        _frustumCorners[4] ); // Bottom
}

Visual Basic

Private Sub ComputeViewFrustum()
    Dim matrix As Matrix = m_viewMatrix * m_perspectiveMatrix
    matrix.Invert()
    m_frustumCorners(0) = New Vector3(-1.0F, -1.0F, 0.0F)
    m_frustumCorners(1) = New Vector3(1.0F, -1.0F, 0.0F)
    m_frustumCorners(2) = New Vector3(-1.0F, 1.0F, 0.0F)
    m_frustumCorners(3) = New Vector3(1.0F, 1.0F, 0.0F)
    m_frustumCorners(4) = New Vector3(-1.0F, -1.0F, 1.0F)
    m_frustumCorners(5) = New Vector3(1.0F, -1.0F, 1.0F)
    m_frustumCorners(6) = New Vector3(-1.0F, 1.0F, 1.0F)
    m_frustumCorners(7) = New Vector3(1.0F, 1.0F, 1.0F)
    Dim i As Integer = 0
    While i < m_frustumCorners.Length
        m_frustumCorners(i) = _
            Vector3.TransformCoordinate(m_frustumCorners(i), matrix)
        System.Math.Min( _
            System.Threading.Interlocked.Increment(i), i - 1)
    End While
    m_frustumPlanes(0) = Plane.FromPoints(m_frustumCorners(0), 
        m_frustumCorners(1), m_frustumCorners(2))
    m_frustumPlanes(1) = Plane.FromPoints( _
        m_frustumCorners(6), _
        m_frustumCorners(7), _
        m_frustumCorners(5))
    m_frustumPlanes(2) = Plane.FromPoints( _
        m_frustumCorners(2), _
        m_frustumCorners(6), _
        m_frustumCorners(4))
    m_frustumPlanes(3) = Plane.FromPoints( _
        m_frustumCorners(7), _
        m_frustumCorners(3), _
        m_frustumCorners(5))
    m_frustumPlanes(4) = Plane.FromPoints( _
        m_frustumCorners(2), _
        m_frustumCorners(3), _
        m_frustumCorners(6))
    m_frustumPlanes(5) = Plane.FromPoints( _
        m_frustumCorners(1), _
        m_frustumCorners(0), _
        m_frustumCorners(4))
End Sub

First we combine the view and projection matrices by multiplying them. Next we initialize the eight corners of the frustum as a cube immediately in front of the camera. These corners are then transformed and used to create the 6 planes using the FromPoints method of the plane.

The frustum is computed upon initialization of the class and on each render loop. Add a call to ComputeViewFrustum( ) to the bottom of the constructor of the Camera class and at the end of the Render method of the Camera class. (It needs to be at the end so it can use the newly computed view and projection matrices.) Now we can use the computed frustum and the radius for each unit to determine whether any part of the unit is in the frustum and should be rendered. The IsInViewFrustum method returns true if the unit is inside the frustum and false otherwise.

Visual C#

public bool IsInViewFrustum ( UnitBase unitToCheck )
{
    foreach ( Plane plane in _frustumPlanes )
    {
        if ( plane.A * unitToCheck.Position.X + plane.B *
             unitToCheck.Position.Y + plane.C * unitToCheck.Position.Z + 
             plane.D <= ( -unitToCheck.Radius ) )
        return false;
    }
    return true;
}

Visual Basic

Public Function IsInViewFrustum(ByVal unitToCheck As UnitBase) As Boolean
    For Each plane As Plane In m_frustumPlanes
        If plane.A * unitToCheck.Position.X + plane.B * _
            unitToCheck.Position.Y + plane.C * unitToCheck.Position.Z + _
            plane.D <= (-unitToCheck.Radius) Then
            Return False
        End If
    Next
    Return True
End Function

The process of culling should take place before the unit is rendered. We accomplish this in the Render method of the BaseUnit class by checking the frustum of the camera before actually rendering the mesh. By placing it into the actual Render method, we avoid having to check the cull state elsewhere in the code.

Visual C#

if (camera.IsInViewFrustum ( this ) == false )
    return;

Visual Basic

If camera.IsInViewFrustum(Me) = False Then
    Return
End If

Now that we have the basic infrastructure in place, it's time to start adding units. But the UnitBase class is abstract, so it can not be instantiated. The entire purpose of the base class was to keep common unit properties and functionality together. Now it's time to create some classes that represent the objects we are going to use in BattleTank 2005, namely obstacles and tanks.

Visual C#

public class Obstacle : UnitBase
{
    public Obstacle ( Device device, string meshFile, 
        Vector3 position, float scale )
         : base ( device, meshFile, position, scale )
    {
    }
}

Visual Basic

Public Class Obstacle
    Inherits UnitBase

    Public Sub New(ByVal device As Device, ByVal meshFile As String, _
    ByVal position As Vector3, ByVal scale As Single)
        MyBase.New(device, meshFile, position, scale)
    End Sub
End Class

The Obstacle class currently does nothing more than call its base class, but we are going add to this class later on.

Visual C#

public class Tank : UnitBase
{
    public Tank ( Device device, string meshFile, 
        Vector3 position, float scale ) 
        : base ( device, meshFile, position, scale )
    public void Update ( float deltaTime )
    private float _speed = 10.0f;
}

Visual Basic

Public Class Tank
    Inherits UnitBase

    Public Sub New(ByVal device As Device, ByVal meshFile As String, _
        ByVal position As Vector3, ByVal scale As Single)
        MyBase.New(device, meshFile, position, scale)
    End Sub
    Public Sub Update(ByVal deltaTime As Single)
        MyBase.Z -= (m_speed * deltaTime)
    End Sub
    Private m_speed As Single = 10.0F
End Class

The Tank class adds a _speed property we need to describe and an Update method.

Using time to simulate movement

The Update method takes in a float that describes the amount of time in seconds that has passed since the last render loop. In the second article we added a variable called deltaTime which we used to compute the frame rate. This value is the value we want to use from now on to compute the position of moving objects. We use the principle of time to ensure a similar experience on each computer regardless of the speed of the computer and make the movement appear fluid. For example, if we updated the position of a moving object by 1 in each pass through the render loop, the object would move fast on faster computers since they are able to complete a render loop faster. You may have seen this behavior when experimenting with the rotating cube. Another problem is that each pass through the render loop is not performed at the same speed, depending on the other operations the CPU is performing, so that the movement may appear choppy. (Again, the easiest way to understand this is to experiment. Change the increment of the Z axis by one instead of the speed * time formula and see what happens.)

Notice that we only need to update the tanks since the obstacles do not move.

Visual C#

foreach ( Tank tank in _tanks )
{
    tank.Update ( _deltaTime );
}

Visual Basic

For Each tank As Tank In m_tanks
    tank.Update(m_deltaTime)
Next

The actual Update method in the tank simply moves the tank towards the origin for now, using a predefined speed.

Visual C#

public void Update ( float deltaTime )
{
    base.Z -= ( _speed * deltaTime );
}

Visual Basic

Public Sub Update(ByVal deltaTime As Single)
    MyBase.Z -= (m_speed * deltaTime)
End Sub

Next we create two generic collections in the GameEngine class to hold the mobile and stationery units.

Visual C#

private List<UnitBase> _obstacles;
private List<UnitBase> _tanks;

Visual Basic

private List<UnitBase> _obstacles;
private List<UnitBase> _tanks;

The actual units are added to the collection in the CreateObstacles and CreateTanks methods.

Visual C#

private void CreateObstacles ( )
{
    _obstacles = new List<UnitBase> ( );
    _obstacles.Add ( new Obstacle ( _device, @"car.x", 
        new Vector3 ( 0, 0, 200 ), 1f ) );
    _obstacles.Add ( new Obstacle ( _device, @"car.x", 
        new Vector3 ( 60, 0, 100 ), 1f ) );
    _obstacles.Add ( new Obstacle ( _device, @"car.x", 
        new Vector3 ( -60, 0, 150 ), 1f ) );
    _obstacles.Add ( new Obstacle ( _device, @"car.x", 
        new Vector3 ( 60, 0, -100 ), 1f ) );
    _obstacles.Add ( new Obstacle ( _device, @"car.x", 
        new Vector3 ( -60, 0, -150 ), 1f ) );
}

private void CreateTanks ( )
{
    _tanks = new List<UnitBase> ( );
    _tanks.Add ( new Tank (_device, @"bigship1.x", 
        new Vector3 ( 0, 0, 200 ), 1f ) );
    _tanks.Add ( new Tank (_device, @"bigship1.x", 
        new Vector3 ( 100, 0, 300 ), 1f ) );
    _tanks.Add ( new Tank (_device, @"bigship1.x", 
        new Vector3 ( -100, 0, 500 ), 1f ) );
    _tanks.Add ( new Tank (_device, @"bigship1.x", 
        new Vector3 ( 100, 0, -200 ), 1f ) );
    _tanks.Add ( new Tank (_device, @"bigship1.x", 
        new Vector3 ( -100, 0, -400 ), 1f ) );
}

Visual Basic

Private Sub CreateObstacles()
    m_obstacles = New List(Of UnitBase)()
    m_obstacles.Add(New Obstacle(m_device, "car.x", _
        New Vector3(0, 0, 200), 1.0F))
    m_obstacles.Add(New Obstacle(m_device, "car.x", _
        New Vector3(60, 0, 100), 1.0F))
    m_obstacles.Add(New Obstacle(m_device, "car.x", _
        New Vector3(-60, 0, 150), 1.0F))
    m_obstacles.Add(New Obstacle(m_device, "car.x", _
        New Vector3(60, 0, -100), 1.0F))
    m_obstacles.Add(New Obstacle(m_device, "car.x", _
        New Vector3(-60, 0, -150), 1.0F))
End Sub
Private Sub CreateTanks()
    m_tanks = New List(Of UnitBase)
    m_tanks.Add(New Tank(m_device, "bigship1.x", _
        New Vector3(0, 0, 200),1.0F))
    m_tanks.Add(New Tank(m_device, "bigship1.x", _
        New Vector3(100, 0, 300), 1.0F))
    m_tanks.Add(New Tank(m_device, "bigship1.x", _
        New Vector3(-100, 0, 500), 1.0F))
    m_tanks.Add(New Tank(m_device, "bigship1.x", _
        New Vector3(100, 0, -200), 1.0F))
    m_tanks.Add(New Tank(m_device, "bigship1.x", _
        New Vector3(-100, 0, -400), 1.0F))
End Sub

If you look at the coordinates for the obstacles and tanks, you will see that I placed them along similar axes to help me orient myself. You could also modify these methods to create a random number of obstacles and tanks placed at random coordinates. Just make sure to add logic to avoid objects overlapping each other or being too close to the origin and obscuring the camera.

Levels

A more flexible and extensible solution is to read the number, type and location of obstacles and tanks from a file. This file could also contain other play-specific settings and be loaded automatically based on some internal logic. The most common use of this scenario is for predefined levels. A player would have the ability to advance to more difficult levels after meeting some completion criteria. This allows you to easily create an ever-changing play experience and fine-tune the playability of each level, something you can't do with random placement. Setting the game up that way also allows players to customize the game for themselves. You would normally provide a level editor when following this route.

The final step is to call these methods. The best place is the constructor of the GameEngine class right after the Camera class is created.

Visual C#

public GameEngine ()
{
    InitializeComponent ( );
    this.SetStyle (ControlStyles.AllPaintingInWmPaint | 
                    ControlStyles.Opaque, true );
    ConfigureInputDevices ( );
    ConfigureDevice ( );
    _skyBox = new SkyBox ( this._device );
    _camera = new Camera ( );
    CreateObstacles ( );
    CreateTanks ( );
    this.Size = new Size ( 800, 600 );
    HiResTimer.Start ( );
}

Visual Basic

Public Sub New()
    InitializeComponent()
    Me.SetStyle(ControlStyles.AllPaintingInWmPaint Or _
        ControlStyles.Opaque, True)
    ConfigureInputDevices()
    ConfigureDevice()
    m_skyBox = New SkyBox(Me.m_device)
    m_camera = New Camera
    CreateObstacles()
    CreateTanks()
    Me.Size = New Size(800, 600)
    HiResTimer.Start()
End Sub

On each render loop all we have to do is to iterate over the appropriate collection and render those that are in the frustum. We call the RenderUnits method in the Render method of the GameEngine class immediately after rendering the skybox.

Visual C#

private void RenderUnits ( )
{
    foreach ( UnitBase ub in _obstacles )
    {
        ub.Render ( _camera );
    }

    foreach ( UnitBase ub in _tanks )
   {
        ub.Render ( _camera );
    }
}

Visual Basic

Private Sub RenderUnits()
    For Each ub As UnitBase In m_obstacles
        ub.Render(m_camera)
    Next
    For Each ub As UnitBase In m_tanks
        ub.Render(m_camera)
    Next
End Sub

That's all. Now we have units.

Conclusion

If you run the game now you will notice three things.

• The units seem to float in mid-space.
• The units are all white.
• You can drive right through each unit.

The first problem can be solved by adding a terrain to the game to show a solid surface along the Y axis. The second problem can be solved by adding lights to the scene. The final issue will be solved once we add collision detection to the game. Other then these items, the game is getting more playable by the day. In the next article we are going to add the missing terrain using a heightmap, add lights so we can see the colors of the units, and add some collision detection.

As you may have noticed, I have changed (and will continue to do so) the various graphics in the game from article to article. This is intended to encourage you to implement your own graphics to change the underlying game into something completely different. You could easily change this game to be set in space, or turn it into a powerboat racing game by just changing the graphics. Give it a try.

As usual, I ran out of time. In the last article I had promised to add the HUD back, but I ran out of space. I will try to accomplish this in the coming articles. I also wanted to discuss Action mapping to enhance the way we are tracking the keyboard and mouse inputs, but this subject will have to be covered in a later article. In addition, I am planning to add a simple debugging console to the game.

Along with these features, the next articles are going to discuss adding Artificial Intelligence to the opposing tanks, making our game conform to realistic physical forces, and some cool sounds to make playing the game more fun. So stay tuned.

Until then: Happy coding.

1. Beginning Game Development Part 1 - Introduction
2. Beginning Game Development Part II - Introduction to DirectX
3. Beginning Game Development: Part III - DirectX II
4. Beginning Game Development: Part IV - DirectInput
5. Beginning Game Development: Part V - Adding Units
6. Beginning Game Development: Part VI - Lights, Materials and Terrain
7. Beginning Game Development: Part VII –Terrain and Collision Detection
8. Beginning Game Development: Part VIII - DirectSound
9. Beginning Game Development: Part VIII - DirectSound II
10. Beginning Game Development: Part VIII - DirectSound III

Welcome to the fourth article on beginning game development. In this article we are going to cover the input device portion of DirectX, called DirectInput. Using DirectInput you can control joysticks, a mouse or the keyboard.

Before we start I need to cover a couple of items that were brought to my attention via feedback from the readers (thank you everyone for taking the time to do this) and changes not directly related to the items covered in this article.

Code Cleanup

To make adding the code for this section easier and to make the code more reusable I have moved some of the code from the GameEngine class into separate classes such as Camera. Encapsulating the camera functionality in a separate object makes the code easer to change and to read. The following changes have already been integrated into the code for this article.

1. I moved the FrameworkTimer class out of the DirectX support code into a class called HiResTimer and removed the using statements for Microsoft.Samples.DirectX.UtilityToolkit. For the VB version I converted the FrameworkTimer class into VB and removed the reference to the DirectX Sample Framework library.
2. I refactored the device creation code in the constructor of the GameEngine class into the ConfigureDevice method.
3. I refactored all code that deals with the device in the OnPaint method of the GameEngine class into the Render method.
4. I refactored the code that sets up the camera in the OnPaint method of the GameEngine class into the Camera class.
5. I removed the CreateCrossHairVertexArrayTop, CreateCrossHairVertexArrayBottom, CreateTestTriangle, and CreateTestCube methods from the GameEngine Class.
6. Removed the System.Collections.Generic, System.ComponentModel, System.Data and System.Text using statements from the GameEngine class.
7. I removed all of the code used for experimenting with the camera settings.

In addition to these general housekeeping changes I added some code that I needed to make the DirectInput portion more interesting.

Skybox

The infinite 3D space we have created has one problem: it's infinite. We have no distinguishing terrain features to orient us and, as such, have no idea in which direction we are facing. We could create a number of complex 3D objects to draw a realistic terrain, but this is very slow and we really do not need 'real' terrain, but only to create the look of real terrain. To create this illusion of seeing a horizon and terrain in the distance, we make use of a technique called the skybox. A skybox creates the effect you get when placing your head into a cardboard box, the inside of which is painted with a landscape: Regardless where you are and where you look you see the inside of the box and nothing else.

In our game we create a cube and display textures (or pictures for us that prefer to use more normal definitions) on the inside walls of the cube. The top would be textured like the sky, the bottom like the ground and the remaining four sides have a texture applied to them that shows a horizon and terrain. The pictures for the four sides are designed in such a manner that they match perfectly at the edges and produce a seamless landscape. These four sides could then represent cardinal directions such as east, west, north and south (if your game is set on Earth).

To achieve the correct effect, we need to ensure that all objects are drawn on top of the skybox. This is done by disabling Z-buffering before drawing the skybox and enabling it after we are done.

Visual C#

_device.RenderState.ZBufferWriteEnable = false; 
// draw the skybox here 
_device.RenderState.ZBufferWriteEnable = true;

Visual Basic

_device.RenderState.ZBufferWriteEnable = False
'draw the skybox here
_device.RenderState.ZBufferWriteEnable = True

The next thing we need to ensure is that the player can never actually get close to or beyond the skybox (otherwise they would notice the illusion). We accomplish this by ensuring that the viewpoint is always in the center of the skybox.

First we assign an Identity matrix to the world matrix. Since the vertices of the skybox are in model space (offset around zero), this ensures that they are not translated into world space. Then we set the use the View matrix of the camera to set the View matrix of the skybox.

Visual C#

Matrix worldMatrix = Matrix.Identity;
Matrix viewMatrix = cam.View;

viewMatrix.M41 = 0.0f;
viewMatrix.M42 = 0.0f;
viewMatrix.M43 = 0.0f;

_device.Transform.View = viewMatrix;
_device.Transform.World = worldMatrix;

Visual Basic

Dim worldMatrix As Matrix = Matrix.Identity
Dim viewMatrix As Matrix = cam.View
viewMatrix.M41 = 0.0F
viewMatrix.M42 = 0.0F
viewMatrix.M43 = 0.0F
_device.Transform.View = viewMatrix
_device.Transform.World = worldMatrix

Drawing the actual skybox uses the techniques we have discussed in the previous articles and I am not going to cover them in detail. The basic steps are as follows.

1. Define a PositionNormalTextured vertex array to hold the data for the four corners of each cube face and texture information.
2. Load the texture for each cube face from a file.
3. Setup the Vertex buffer for each face.
4. On each Render loop readjust the skybox.
5. On each Render loop disable Z-buffering.
6. On each Render loop use the Camera object passed in to determine the direction the camera is facing and draw the appropriate face.
7. On each Render loop turn Z-buffering back on.

If you look at the RenderFace method of the SkyBox class, you will notice that it is identical to the code we used to draw the triangle and cube in the last article.

Visual C#

_device.SetStreamSource ( 0, faceVertexBuffer, 0 );
_device.VertexFormat = CustomVertex.PositionNormalTextured.Format;
_device.SetTexture ( 0, faceTexture );
_device.DrawPrimitives ( PrimitiveType.TriangleStrip, 0, 2 );

Visual Basic

_device.SetStreamSource(0, faceVertexBuffer, 0)
_device.VertexFormat = CustomVertex.PositionNormalTextured.Format
_device.SetTexture(0, faceTexture)
_device.DrawPrimitives(PrimitiveType.TriangleStrip, 0, 2)

Camera Class

The other major refactoring I did for this article is to move all the camera-related code into the Camera class. The fixed values such as FoV and aspect ratio used in the Perspective matrix are set as internal properties with the appropriate default values. I have also added methods that allow the camera to be moved left or right and up or down, and a method that moves the position of the camera. Why I added these methods will become clear once we integrate user input later in the article.

Now that all of the graphics for the game except the enemy units are done, let's get the tank moving so we can explore our new world.

Controlling Input

Controlling input devices is not nearly as cool as graphics manipulation or artificial intelligence, but without it you couldn't have a game. Reacting to user input allows the user to move around in and manipulate the 3D world we have created.

The DirectInput API allows you to control the mouse, keyboard, joystick, game-pad, or force feedback device. Some games also provide the ability for voice input to control the game, but that is beyond the scope of our game.

Adding DirectInput

The first step when adding input support to an application is to reference the Microsoft.DirectX.DirectInput.dll assembly. The next step is to add the using statement to each class in which you plan to use the DirectInput classes (unless you really like typing).

Detecting Devices

A good API provides a common way to access similar devices. This is true in DirectX where physical devices such as video cards, sound cards, and input devices are abstracted into the Device class. This class shields us as developers from knowing any of the hardware-specific details. In the DirectInput namespace a Device represents any of the potential input devices.

Another familiar construct is the Manager class. We used the Manager class from the Direct3D namespace to get information about the adapters and to retrieve device capabilities for each adapter. In DirectInput the process is very similar.

To get a list of specific devices such as all keyboards connected to the computer, you use the GetDevices method of the Manager class and pass in the DeviceClass or DeviceType and one of the EnumDevicesFlags enumeration values to filter the list further. A computer can have many input devices but as a minimum it should have a keyboard and mouse.

Note: Most of the time you are going to use EnumDevicesFlags.AttachedOnly to get only the attached devices of a particular type.

To make things a little more obscure, a mouse is considered a Pointer type in the DeviceClass enumeration. You can use any combination of to retrieve a custom list of input devices.

Each call to GetDevices returns a DeviceList class. This DeviceList in turn contains a DeviceInstance structure for each device. The DeviceInstance structure contains the information about each device, the most important of which is the InstanceGuid. This is a unique identifier for each device on our system that we need to know so we can communicate with that device.

Note: Just because a device is in the DeviceList does not mean that it is actually attached. You can use the InstanceGuid and the GetDeviceAttached method to determine if the device is attached.

The Manager class exposes a Devices property that contains a DeviceList.

Note that the DeviceInstance structure is not actually a device; there is nothing we can do with it in terms of connecting to it. The only use it has is to provide a GUID which we can then use to actually connect to or acquire that device.

Connecting to a Keyboard

The first device we are going to connect to is the keyboard. This is probably the most common device used to interact with games. Most modern games enable the user to control the game using the keyboard and the mouse, as there are too many actions to perform to use just one of these devices. Depending on your audience, you need to choose the primary input device and decide whether to offer configurable choices for secondary devices. You also need to remember that some computers, such as slate-mode Tablet PCs, have no keyboard, so offering alternate input means broadens your potential audience.

Regardless of what input options you offer, the steps to set up any input device are the same.

1. Instantiate a Device class passing the type of device.
2. Set the cooperation level of the device.
3. Set the format of the data returned for the device.
4. Acquire the device.
5. Poll the device.
6. Read the state data to determine what actions the user did.

Using good OO practices, we first create a keyboard class that will encapsulate all keyboard-specific functionality and provide a single access point for the rest of the game to any keyboard functionality.

The first step is to create a Device object for the keyboard. We do this using the Keyboard value of the SystemGuid enumeration. This lets us connect to the default keyboard. Using the default keyboard is safer than enumerating the devices and picking a specific one, because you don't know beforehand what devices all your users might have.

Visual C#

_device = new Device ( SystemGuid.Keyboard );

Visual Basic

_device = New Device(SystemGuid.Keyboard)

The next step is to set the Cooperative level of the device. The values of the CooperativeLevelFlags enumeration determine how much control we chose to take over the device and how much control we leave to other applications.

The CooperativeLevelFlags enumeration contains five values.

• Exclusive
• NonExclusive
• Foreground
• Background
• NoWindowsKey

The Background and Foreground values are mutually exclusive, as are the Exclusive and NonExclusive values. The Foreground option states that we only want data from the device if the window we passed into the SetCooperativeLevel method has the focus. The Background option simply means that we always want data from the device. Exclusive means that we want priority for control of the device while NonExclusive means we don't. Even when using the Exclusive option it is still possible to lose the device, which is why we add the reacquire logic to the Poll method to ensure we can get the device back when we want to read its state. The NoWindowsKey option can be combined with any of the other settings and specifies that we want to ignore the Windows logo key on the keyboard. This setting is important when running in full screen mode, because the Windows key causes the application to loose focus.

For BattleTank 2005 we combine the Background and NonExclusive values to allow other applications maximum control over this device.

We also need to pass in a reference to the window we are using so DirectX knows which window's input we are interested in.

Visual C#

_device.SetCooperativeLevel ( form, CooperativeLevelFlags.Background | 
    CooperativeLevelFlags.NonExclusive ); 

Visual Basic

_device.SetCooperativeLevel(form, CooperativeLevelFlags.Background Or _ 
    CooperativeLevelFlags.NonExclusive)

The next step is to determine the data format we expect this device to return. We cover the contents of this data structure a little later in the article.

Visual C#

_device.SetDataFormat ( DeviceDataFormat.Keyboard ); 

Visual Basic

_device.SetDataFormat(DeviceDataFormat.Keyboard)

The last step is to actually acquire the device. You can think of this like opening a communications channel to the device. Since there are lots of things that could go wrong at this point, it is best to wrap the Acquire call into a try/catch block.

Visual C#

try
{
    _device.Acquire ( );
}
catch ( DirectXException ex )
{
    Console.WriteLine ( ex.Message );
}

Visual Basic

Try
    _device.Acquire()
Catch ex As DirectXException
    Console.WriteLine(ex.Message)
End Try

After acquiring the device we can read its state, which is a byte array. The first 256 values of this array hold the state of the keyboard; the next 8, the state of the mouse; and the last 32, the state of the joystick. Setting the device data format simply restricts the returned array to the set of values for the specified device. The KeyboardState structure, for example, only contains the first 256 bytes of the raw state.

Visual C#

private KeyboardState _state; 

Visual Basic

Private _state As KeyboardState

To get this state from the device we first call the Poll method. This method communicates with the actual hardware. Then we copy the state into a local data structure (the _state variable).

Since we are going to do this on every frame, I placed this particular sequence of calls into their own public method called Poll. In the game loop we then call _keyboard.Poll() and use the state data structure to see what keys were pressed. This is where we deal with a device which may have been acquired by another application by attempting to reacquire it.

Visual C#

try
{
    _device.Poll ( );
    _state = _device.GetCurrentKeyboardState ( );
}
catch ( NotAcquiredException )
{
    // try to reqcquire the device
    try
    {
        _device.Acquire ( );
    }
    catch ( InputException iex )
    {
        Console.WriteLine ( iex.Message );
        // could not get the device
    }
}
catch ( InputException ex2 )
{
    Console.WriteLine ( ex2.Message );
}

Visual Basic

Try
    _device.Poll()
    _state = _device.GetCurrentKeyboardState
Catch generatedExceptionVariable0 As NotAcquiredException
    Try
        _device.Acquire()
    Catch iex As InputException
        Console.WriteLine(iex.Message)
    End Try
Catch ex2 As InputException
    Console.WriteLine(ex2.Message)
End Try

The only step remaining is to examine the state data returned to see what actions the user performed.

In addition to managing the device state each time we poll the device, we want to make sure to release it when we are finished using it. We accomplish this by calling the Unacquire method of the device in the Dispose method.

Visual C#

if ( _device != null )
    _device.Unacquire ( );

Visual Basic

If Not (_device Is Nothing) Then
    _device.Unacquire()
End If

Connecting to a Mouse

Connecting to a mouse is almost identical to connecting to a keyboard. The differences are the SystemGuid passed to the Device constructor, the DeviceDataFormat, the data structure used to store the state information, and the method call used to retrieve the device state.

Visual C#

_device = new Device ( SystemGuid.Mouse );
_device.SetDataFormat ( DeviceDataFormat.Mouse );
private MouseState _state;
public void Poll ( )
{
    _device.Poll ( );
    _state = _device.CurrentMouseState;
}

Visual Basic

_device = New Device(SystemGuid.Mouse)
_device.SetDataFormat(DeviceDataFormat.Mouse)
Private _state As MouseState
Public Sub Poll()
        _device.Poll()
        _state = _device.CurrentMouseState
End Sub

Using the mouse also provides the ability to define how the X, Y and Z (No, don't pick up your mouse, the Z value is the value for the mouse scroll wheel on certain mice) values are reported on each poll. Setting the AxisModeAbsolute value to true returns the coordinates in screen coordinates, while setting this value to false returns the change in pixels from the previous poll. We set this value as soon as we have acquired the device.

Visual C#

_device.Acquire ( );
_device.Properties.AxisModeAbsolute = false;

Visual Basic

_device.Acquire()
_device.Properties.AxisModeAbsolute = False

Using the false option is valuable if you want to determine the speed in which the user moved the mouse using the time elapsed between polls and the distance traveled in that time frame while the first option is more valuable if the user is selecting something from the screen.

Connecting to a Joystick

Connecting to a joystick follows the same general steps as for the keyboard and mouse, but, since there is no such thing as a default joystick, no corresponding SystemGuid value exists. Instead, we need to use the GetDevices method of the Manager class, passing in GameControl type for the DeviceClass and AttachedOnly for the EnumDevicesFlags to enumerate any attached joysticks. You would probably want to present some type of UI to the user to let them choose from a list of devices found or you could just use the first device as the code snippet does.

Visual C#

DeviceList gameControllerList = 
    Manager.GetDevices(
        DeviceClass.GameControl, 
        EnumDevicesFlags.AttachedOnly);

if (gameControllerList.Count > 0)
{
    foreach (DeviceInstance deviceInstance in gameControllerList)
    {
        _device = new Device(deviceInstance.InstanceGuid);
        _device.SetCooperativeLevel(form,
            CooperativeLevelFlags.Background | 
            CooperativeLevelFlags.NonExclusive);
        break;
    }
}

Visual Basic

Dim gameControllerList As DeviceList
gameControllerList = Manager.GetDevices(DeviceClass.GameControl, _
    EnumDevicesFlags.AttachedOnly)
If (gameControllerList.Count > 0) Then
    Dim deviceInstance As DeviceInstance
    For Each deviceInstance In gameControllerList
        _device = New Device(deviceInstance.InstanceGuid)
        _device.SetCooperativeLevel(Form, CooperativeLevelFlags.Background 
        Or CooperativeLevelFlags.NonExclusive)
        Break()
    Next
End If

The next step is to specify a new DeviceDataFormat and new type for the _state data structure. Finally you need to retrieve the joystick state from the device inside the Poll method.

Visual C#

_device.SetDataFormat ( DeviceDataFormat.Joystick );
private JoystickState _state;
public void Poll ( )
{
    _device.Poll ( );
    _state = _device.CurrentJoystickState;
}

Visual Basic

_device.SetDataFormat(DeviceDataFormat. Joystick)
Private _state As JoystickState
Public Sub Poll()
        _device.Poll()
        _state = _device.CurrentJoystickState
End Sub

In BattleTank 2005 we are not going to use a joystick, but feel free to add this capability on your own if you have a joystick. If you own a force-feedback device you might also want to experiment with using it in the game.

Now that we have access to the various forms of input devices, and know how to retrieve their state we need to know how to read the various state data structures to determine user actions.

Determining User Actions

Each of the data structures for the state are byte arrays. The KeyboardState is a byte array 256 bytes long. Each byte represents the state of a key on the keyboard and the position in the array matches the value of the Key enumeration. The indexer for the KeyboardState returns a Boolean value for each index checked. For example, to see if the user pressed the Escape key you simply test that the most significant bit is set at that index location (position 1 for Escape) in the array. If this expression returns true then the user pressed the Escape key, otherwise it returns false.

Each poll method may return values for multiple keys such as when the user pressed certain key combinations (Ctrl+Alt+Delete is a common one for me when I program). DirectInput supports a maximum of five key values, but you should be nice to your users and stick to single key actions if possible.

Visual C#

_state[Key.Escape] 

Visual Basic

_keyboard.State(Key.Escape)

The MouseState is a structure that provides three public properties for the X, Y and Z values, as well an eight byte long array for the state of the mouse buttons that is retrieved by calling the GetMouseButtons method.

Checking for the button information is the same for the mouse buttons as it was for the keyboard keys. You simply check the most significant bit at each position to determine if the corresponding button was pressed.

Visual C#

if ( 0 != mouseButtons[0])
    Console.WriteLine ( "Primary Button pressed" );

Visual Basic

If Not (0 = _mouse.MouseButtons(0)) Then
    Console.WriteLine("Fire!")
End If

The 0 position represents the primary button which could be the left or right mouse button depending on how the user configured the mouse.

Depending on the AxisModeAbsolute setting, the X, Y and Z values return the absolute or relative position of the mouse. Regardless of this setting the values for the X axis are always positive to the right and negative to the left, positive forward and negative backward for the Y value, and positive when spinning the scroll wheel forward and negative backward for the Z value.

Reacting to User Action

Now that we can detect what the user is doing, it is time to take that input and use it to manipulate our world. First we create a method called CheckForInput that will contain all of the input-related code. (In a later article I will show you why this is not the best way of tracking and reacting to user input and how a system called Action Mapping can be used to reduce the amount of code and avoid code duplication.) For right now we are going to set up BattleTank 2005 to use the cursor keys to change the heading and pitch of the camera (move it up/down and left/right). Note that this does not change the location of the camera. The first step is to poll the devices to retrieve the latest state information.

Visual C#

_keyboard.Poll ( );
_mouse.Poll ( );

Visual Basic

_keyboard.Poll()
_mouse.Poll()

Then we test the state for the keys we are interested in and react accordingly.

Visual C#

if ( _keyboard.State[Key.LeftArrow] )
    _camera.MoveCameraLeftRight ( -0.5f );

if ( _keyboard.State[Key.RightArrow] )
    _camera.MoveCameraLeftRight ( 0.5f );

if ( _keyboard.State[Key.UpArrow] )
    _camera.MoveCameraUpDown ( -0.5f );

if ( _keyboard.State[Key.DownArrow] )
    _camera.MoveCameraUpDown ( 0.5f );

Visual Basic

If _keyboard.State(Key.LeftArrow) Then
    _camera.MoveCameraLeftRight(-0.5F)
End If
If _keyboard.State(Key.RightArrow) Then
    _camera.MoveCameraLeftRight(0.5F)
End If
If _keyboard.State(Key.UpArrow) Then
    _camera.MoveCameraUpDown(-0.5F)
End If
If _keyboard.State(Key.DownArrow) Then
    _camera.MoveCameraUpDown(0.5F)
End If

We also want to use the mouse to move the camera, so we add another set of checks for the mouse input.

Visual C#

if ( 0 != ( _mouse.State.X | _mouse.State.Y ) )
{
    _camera.MoveCameraLeftRight ( _mouse.State.X / 10 );
    _camera.MoveCameraUpDown ( _mouse.State.Y / 10 );
}

Visual Basic

If Not (0 = (_mouse.State.X Or _mouse.State.Y)) Then
    _camera.MoveCameraLeftRight(_mouse.State.X / 10)
    _camera.MoveCameraUpDown(_mouse.State.Y / 10)
End If

You can adjust the increments used in the MoveCameraLeftRight and MoveCameraUpDown methods to make the movement slower or faster.

The final step is to add a key that enables us to exit the application. The Escape key is the natural choice:

Visual C#

if ( _keyboard.State[Key.Escape] )
{
    Application.Exit ( );
}

Visual Basic

If _keyboard.State(Key.Escape) Then
    Application.Exit()
End If

In addition to moving the camera around, we also want to move the location of the camera since that is how we are going to simulate driving around in our tank. The only problem is that, with no fixed items in the world, we can't really tell when we have moved, since the only reference point is the skybox, which never changes position. To overcome this limitation until we add units in the next article, I am simply writing out the new camera location to the Console whenever it changes.

Visual C#

if ( _keyboard.State[Key.W] )
    _camera.MoveCameraPosition ( 10, 0, 0 );

if ( _keyboard.State[Key.S] )
    _camera.MoveCameraPosition ( -10, 0, 0 );

if ( _keyboard.State[Key.A] )
    _camera.MoveCameraPosition ( 0, 10, 0 );

if ( _keyboard.State[Key.D] )
    _camera.MoveCameraPosition ( 0, -10, 0 );

if ( oldX != _camera.X )
{
    Console.WriteLine ( _camera.X + ", " + _camera.Y );
    oldX = _camera.X;
}

Visual Basic

If _keyboard.State(Key.W) Then
    _camera.MoveCameraPosition(10, 0, 0)
End If
If _keyboard.State(Key.S) Then
    _camera.MoveCameraPosition(-10, 0, 0)
End If
If _keyboard.State(Key.A) Then
    _camera.MoveCameraPosition(0, 10, 0)
End If
If _keyboard.State(Key.D) Then
    _camera.MoveCameraPosition(0, -10, 0)
End If
If Not (oldX = _camera.X) Then
    Console.WriteLine(_camera.X & ", " & _camera.Y)
    oldX = _camera.X
End If

The last piece of input-checking we need to add is checking the mouse buttons. For right now, let's assume that the default button on the mouse causes the tank to fire. We are going to add more exciting action later on, but all we can do now is to write "Fire!" to the Console.

Visual C#

if ( 0 != _mouse.MouseButtons[0] )
    Console.WriteLine ( "Fire!" );

Visual Basic

If Not (0 = _mouse.MouseButtons(0)) Then
    Console.WriteLine("Fire!")
End If

That's it for input. As I mentioned before, there are better ways of relating keyboard and mouse keys and movement to actions in the game. You may also notice that when moving the camera, sometimes a single button click causes two movements. This is due to the fact that the game loop is faster than we are and the key is pressed long enough to be picked up in two game loops. We are also going to fix that in the next article.

Summary

Once again I find myself running out of space before being able to cover all of the items I wanted, but I hope there is enough stuff here to let you experiment on your own. We are going to continuously refine the game in each iteration rather than trying to get it perfect the first time; that is the sprit of Agile development. The important things to remember are how to use the Device class to acquire and then poll an input device, and how to determine the input from the State objects.

Even though we are now able to maneuver through the 3D world, it is not very exciting, since other than the skybox there are no other items in our world. In the next article we are going to fix that by adding units, both stationary and mobile, and work on collision detection. We are also going to refine the camera to help us in reducing the number of items we need to render by tacking the frustum. Oh—yes, I do know that the targeting crosshairs are gone; they will be back in the next article in the form of a real Heads-Up-Display (HUD) class.

Until then: Happy coding.

Introduction

Welcome to the third article on beginning game development. In this article we are going to cover some of the more advanced DirectX principles such as transforms, matrices, culling and clipping.

Before we start, I need to cover a couple of items that were brought to my attention via feedback from the readers (thank you everyone for taking the time to do this) and changes not directly related to the items covered in this article.

Code Cleanup

These changes have already been integrated into the code for this article.

1. I updated to the June 2005 version DirectX SDK. I did have an issue with the DirectX assemblies being added to the Global Assembly Cache (GAC), so if you have any build errors, update the references to: C:\Program Files\Microsoft DirectX 9.0 SDK (June 2005)\Developer Runtime\x86\DirectX for Managed Code.
2. In the last article you surrounded the IsWindowed setting for the PresentParameters with a #if DEBUG statement. To enable this option you must go to the Project settings and enable it:
   • Right-click the BattleTank2005 project and select Properties.
   • Select the Build tab.
   • In the general section, check the Define DEBUG constant option.
3. Change the color in the device.Clear method call from DarkBlue to Black.
4. Add the following code at the very end of the GameEngine constructor to make the form a more standard size.

Visual C#

// force the window to a standard size
// the provides the correct aspect ratio of 1.33
this.Size = new Size ( 800, 600 );

Visual Basic

'force the window to a standard size
' the provides the correct aspect ratio of 1.33
Me.Size = New Size(800, 600)

5. Change the Startup position of the form to CenterScreen.
   • Right-click the GameEngine form and select View Designer.
   • In Properties, change the StartPosition property to CenterScreen

Now we can actually draw something on the screen and start creating the game.

Drawing the targeting crosshairs.

In BattleTank 2005 we are sitting inside of a tank and looking through the targeting scope at the world around us. We use the targeting crosshairs to make it easier to hit and destroy the enemy. In real life the crosshairs are fixed in the optics of the cannon, so they are always visible and located in the same spot when looking through the targeting scope as a Heads-up Display (HUD).

In our game we have two choices when drawing the crosshairs.

1. Draw them directly onto the center of the screen using screen coordinates.
2. Draw them using world coordinates and ensure that the view point is located such that they are visible and centered on the screen.

The tradeoff here is between speed and extensibility. If we choose the first option we do not have to transform the coordinates, since they are already in screen coordinates, which is faster. In effect, we are removing the targeting crosshairs from the model space we are creating. The downside is that if we chose to change the game later on and allow the player to leave the tank, the crosshairs would also be visible when they walk around. The second option requires the coordinates to be adjusted and transformed, but provides us with the ultimate flexibility to change the game later on.

I am going to use option 2 because it is the most flexible and I am not going to waste time trying to optimize the game for speed before knowing that it is slow. When you write a game you will be faced with design choices like this and you have to understand the tradeoffs you are making.

Before we move on, let's define a model that will make it easier to describe and (we hope) understand the terms we are going to cover in this article.

A Model

Imagine an empty room. I determine where in the room the X, Y, Z origin is located. In this example let's say that the front left corner of the room is the origin in this world. This room becomes my World Space. (A real world space is infinite, but for now we can make do with the finite space of the room.)

World Space: An infinite three-dimensional Cartesian space. You place your objects anywhere you want in this world to create the environment you want.

Now I place a chair in the room at a predefined location. Each point on the chair can be accurately described using a set of Cartesian coordinates (X, Y, Z) and optional information about each point such as color (Color) and texture (Tu, Tv). If you think back to the last article you will notice that this makes each point a vertex. Since we have lots of separate vertices, we store all of them in a vertex array. When this array is loaded into memory it becomes a vertex buffer.

Vertex buffer

Vertex buffers are ideally suited for the complex transformations that DirectX needs to perform. DirectX provides a number of predefined vertex types representing the most common vertex formats. These types are defined as structures in the CustomVertex class.

We are going to use the PositionColored vertex for the targeting crosshairs. This vertex provides X, Y, Z properties and a Color property, which is exactly what we need. This vertex also defines the coordinates' world space rather than screen space, which is what we decided to do.

Add the following methods to the GameEngine class after the OnPaint method.

Visual C#

private CustomVertex.PositionColored[] CreateCrossHairVertexArrayTop ( )
{ 
    CustomVertex.PositionColored[] crossHairs = 
        new CustomVertex.PositionColored[7];
    float zval = 0f;
    
    // top of targeting crosshairs
    crossHairs[0].Position = new Vector3 ( -1f, 1f, zval );
    crossHairs[1].Position = new Vector3 ( -1f, 2f, zval );
    crossHairs[2].Position = new Vector3 ( 0f, 2f, zval );
    crossHairs[3].Position = new Vector3 ( 0f, 3f, zval );
    crossHairs[4].Position = new Vector3 ( 0f, 2f, zval );
    crossHairs[5].Position = new Vector3 ( 1f, 2f, zval );
    crossHairs[6].Position = new Vector3 ( 1f, 1f, zval );
    
    crossHairs[0].Color = Color.Green.ToArgb ( );
    crossHairs[1].Color = Color.Green.ToArgb ( );
    crossHairs[2].Color = Color.Green.ToArgb ( );
    crossHairs[3].Color = Color.Green.ToArgb ( );
    crossHairs[4].Color = Color.Green.ToArgb ( );
    crossHairs[5].Color = Color.Green.ToArgb ( );
    crossHairs[6].Color = Color.Green.ToArgb ( );
        
    return crossHairs;
}
    
private CustomVertex.PositionColored[] CreateCrossHairVertexArrayBottom ()
{
    CustomVertex.PositionColored[] crossHairs = 
        new CustomVertex.PositionColored[7];
    
    // bottom of targeting crosshairs
    float zval = 0f;
    
    // bottom of targeting crosshairs
    crossHairs[0].Position = new Vector3 ( 1f, -1f, zval );
    crossHairs[1].Position = new Vector3 ( 1f, -2f, zval );
    crossHairs[2].Position = new Vector3 ( 0f, -2f, zval );
    crossHairs[3].Position = new Vector3 ( 0f, -3f, zval );
    crossHairs[4].Position = new Vector3 ( 0f, -2f, zval );
    crossHairs[5].Position = new Vector3 ( -1f, -2f, zval );
    crossHairs[6].Position = new Vector3 ( -1f, -1f, zval );
    
    crossHairs[0].Color = Color.Green.ToArgb ( );
    crossHairs[1].Color = Color.Green.ToArgb ( );
    crossHairs[2].Color = Color.Green.ToArgb ( );
    crossHairs[3].Color = Color.Green.ToArgb ( );
    crossHairs[4].Color = Color.Green.ToArgb ( );
    crossHairs[5].Color = Color.Green.ToArgb ( );
    crossHairs[6].Color = Color.Green.ToArgb ( );
    
    return crossHairs;
}

Visual Basic

Private Function CreateCrossHairVertexArrayTop() As _
        CustomVertex.PositionColored()
    Dim crossHairs(7) As CustomVertex.PositionColored
    Dim zval As Single = 0.0F
    ' top of targeting crosshairs
    crossHairs(0).Position = New Vector3(-1.0F, 1.0F, zval)
    crossHairs(1).Position = New Vector3(-1.0F, 2.0F, zval)
    crossHairs(2).Position = New Vector3(0.0F, 2.0F, zval)
    crossHairs(3).Position = New Vector3(0.0F, 3.0F, zval)
    crossHairs(4).Position = New Vector3(0.0F, 2.0F, zval)
    crossHairs(5).Position = New Vector3(1.0F, 2.0F, zval)
    crossHairs(6).Position = New Vector3(1.0F, 1.0F, zval)

    crossHairs(0).Color = Color.Green.ToArgb()
    crossHairs(1).Color = Color.Green.ToArgb()
    crossHairs(2).Color = Color.Green.ToArgb()
    crossHairs(3).Color = Color.Green.ToArgb()
    crossHairs(4).Color = Color.Green.ToArgb()
    crossHairs(5).Color = Color.Green.ToArgb()
    crossHairs(6).Color = Color.Green.ToArgb()

    Return crossHairs
End Function
Private Function CreateCrossHairVertexArrayBottom() As _
        CustomVertex.PositionColored()
    Dim crossHairs(7) As CustomVertex.PositionColored

    ' bottom of targeting crosshairs
    Dim zval As Single = 0.0F

    ' bottom of targeting crosshairs
    crossHairs(0).Position = New Vector3(1.0F, -1.0F, zval)
    crossHairs(1).Position = New Vector3(1.0F, -2.0F, zval)
    crossHairs(2).Position = New Vector3(0.0F, -2.0F, zval)
    crossHairs(3).Position = New Vector3(0.0F, -3.0F, zval)
    crossHairs(4).Position = New Vector3(0.0F, -2.0F, zval)
    crossHairs(5).Position = New Vector3(-1.0F, -2.0F, zval)
    crossHairs(6).Position = New Vector3(-1.0F, -1.0F, zval)

    crossHairs(0).Color = Color.Green.ToArgb()
    crossHairs(1).Color = Color.Green.ToArgb()
    crossHairs(2).Color = Color.Green.ToArgb()
    crossHairs(3).Color = Color.Green.ToArgb()
    crossHairs(4).Color = Color.Green.ToArgb()
    crossHairs(5).Color = Color.Green.ToArgb()
    crossHairs(6).Color = Color.Green.ToArgb()

    Return crossHairs
End Function

Remember that the coordinates for the Position property of each vertex are defined in world space coordinates. We will transform them to screen coordinates in a while. Also note that you must call the ToArgb method to convert Color to the 32-bit integer format required by DirectX.

Before we continue we need to let the device know which type of vertex we chose. We accomplish this by setting the VertexFormat property of the Device class to the Format property of the vertex we used. This property determines the fixed function pipeline the device will use. Don't worry what exactly that is for right now; you just need to know that we are using the position and colored pipeline.

In the OnPaint method, immediately following the device.Clear method add the following code.

Visual C#

device.VertexFormat = CustomVertex.PositionColored.Format;

Visual Basic

device.VertexFormat = CustomVertex.PositionColored.Format

With the crosshairs defined, we must now tell the device to actually render the object described in the vertex buffer to the screen. This is accomplished using the DrawUserPrimitives method of the device class. So what are Primitives?

Drawing Primitives

Drawing Primitives are collections of vertices that define a single three-dimensional object. There are six primitives in DirectX listed in the PrimitiveType enumeration.

1. Line List: Mainly used for adding Heads-up Display (HUD) information to a screen. The primitive count is equal to the number of points divided by two. The number of points must be even for this type to work.
2. Line Strip: This has the same uses as the Line List but renders a single continuous line. The primitive count is equal the number of vertices minus 1.
3. Point List: Mainly used for rendering individual points in particle images such as explosions or stars in the night sky. The primitive count is equal to the number of points in the vertex buffer.
4. Triangle Fan: This is most useful when drawing an oval object.
5. Triangle List: This is the most commonly used primitive. The primitive count is the number of vertices divided by three,
6. Triangle Strip: These are most useful when rendering rectangular objects.

In our case we choose the LineStrip type to draw the crosshairs to the screen since it is an HUD. In the OnPaint method, immediately following the device.Clear method add the following code.

Visual C#

device.DrawUserPrimitives ( PrimitiveType.LineStrip, 6, 
    CreateCrossHairVertexArrayTop ( ) );
device.DrawUserPrimitives ( PrimitiveType.LineStrip, 6, 
    CreateCrossHairVertexArrayBottom ( ) );

Visual Basic

device.DrawUserPrimitives(PrimitiveType.LineStrip, 6, _
    CreateCrossHairVertexArrayTop())
device.DrawUserPrimitives(PrimitiveType.LineStrip, 6, _
    CreateCrossHairVertexArrayBottom())

The DrawUserPrimitives method requires us to pass in the PrimitiveType, the count of primitives to render, and the source of the vertex data for the object. Since we are using the LineStrip primitive, the seven points in each vertex buffer create six lines.

Up to this point we have not actually drawn anything to the screen, just cleared the device; so we need to tell the device that we are planning to do so. This is accomplished with the BeginScene method of the device class.

Begin Scene/End Scene

As I mentioned in the first article, there are a lot of correlations between movies and a DirectX game. The first we encountered was frame. Now we are going to add Scenes and little later a camera.

We use the BeginScene and EndScene methods of the device to define the starting and ending points of a scene. The BeginScene method prepares the device for the actions that follow by locking the back buffer. The EndScene method tells the device that we are finished drawing and unlocks the back buffer. You must always call EndScene after calling BeginScene otherwise the back buffer will remain locked. The BeginScene and EndScene methods work closely together with the Present method to mange the back buffer; if one of these method calls fails the others will fail also.

In the OnPaint method of the GameEngine class, add calls to BeginScene and EndScene. The call to BeginScene needs to occur immediately after the Clear method call.

Visual C#

device.Clear ( ClearFlags.Target, Color.Black, 1.0f, 0 );
// Tell DirectX we are about to draw something
device.BeginScene ( );

Visual Basic

device.Clear(ClearFlags.Target, Color.Black, 1.0F, 0)
' Tell DirectX we are about to draw something
device.BeginScene()

And the EndScene method needs to be called immediately before the Present method call.

Visual C#

// Tell DirectX that we are done drawing
device.EndScene ( );
// Flip the back buffer to the front
device.Present ( );

Visual Basic

' Tell DirectX that we are done drawing
device.EndScene()
' Flip the back buffer to the front
device.Present()

Now we are almost done. The last step remaining is to convert the world coordinates of each three-dimensional object into screen coordinates.

In the last article we covered a lot of the DirectX terminology you need to understand. We are almost done with new terms, but before we can successfully render a 3-D world to the screen we need to cover one last set of definitions.

Lights, Camera, Action

In our model we have described each point on the chair using Cartesian coordinates and a color value and stored these points in a vertex buffer. But DirectX still can't render the chair for me. Why? The missing pieces of information are our location in the room and the direction we are looking. We also need to determine how to handle the projection. Only with this information can the 3-D world be converted into the 2-D picture displayed on the screen.

In DirectX our (the viewer's) location is called the camera location and it is defined by the View Matrix. From now on consider the terms view and camera to be synonymous. The projection is the way distance is applied to the objects and can be compared to the lens setting of the camera.

Cameras are very powerful tools in creating cool 3-D games. You can attach the camera to a moving object to get the feeling of actually being inside, or offset it slightly to the rear to get a chase view. You can also set up multiple static cameras in your world and view the action by switching from camera to camera.

All of the computations involved in converting the world coordinates to screen coordinates are performed used a Matrix. These computations are called Transforms. Almost all of the heavy lifting performed in DirectX is the transformation of coordinates using Matrices.

Transforms (http://en.wikipedia.org/wiki/Transformation_%28mathematics%29): Transformations change the coordinates of three-dimensional objects based on the view, projection type and world transform specified. These transformations are accomplished via a set of 4x4 matrices.

Matrix (http://en.wikipedia.org/wiki/Matrix_%28mathematics%29): A rectangular table of numbers that is very efficient in transformations.

You could spend a lot of time understanding the exact details of transformations with matrices. Understanding how they work is important, but you will not have to perform any manual calculations on your own, so we can skip the details for now. The Matrix class contains a number of the most common methods for manipulating matrices.

The first step is placing and orienting the camera in our three-dimensional world.

View Transform

The view matrix defines the location of the camera and the orientation of the camera (by specifying a target). The view matrix also includes a value to determine which direction is considered to be up in our world. This is almost always the Y axis. You can either define your own matrix or use the built-in Matrix.LookAtLH and Matrix.LookAtRH methods. Since we are using the left handed coordinate system we naturally use the LookAtLH method (LH stands for Left Handed). Even if you do not explicitly define a view, then DirectX uses a default view.

In the OnPaint method of the GameEngine class, add the following code immediately after the device.Clear method call.

Visual C#

device.Transform.View = Matrix.LookAtLH(new Vector3 (0, 0, 5f), 
    new Vector3(0, 0, 0), new Vector3(0, 1, 0));

Visual Basic

device.Transform.View = Matrix.LookAtLH(New Vector3(0, 0, 5.0F), _
    New Vector3(0, 0, 0), New Vector3(0, 1, 0))

In Battle Tank 2005 we are placing the camera at the origin (0,0) and slightly forward on the Z axis. We then point the camera at the origin, and identify the Y axis as up by providing a value for Y.

After placing and orienting the camera we need to define the projection we are going to use.

Projection Transform

In DirectX there are two types of projections to choose from:

• Perspective (http://en.wikipedia.org/wiki/Perspective)
• Orthogonal (http://en.wikipedia.org/wiki/Orthogonal_projection)

The Perspective projection is the most commonly used projection and is how humans see the world. In this projection objects appear smaller the further away from us they are and become deformed at some distance (like a road appears to converge toward the horizon).

Orthogonal projection, on the other hand, ignores distance (the Z value) so items retain their size regardless of their distance from the camera.

We are going to use the Perspective Projection in BattleTank 2005. The projection determines how the vertices of the objects in the viewing frustum (http://en.wikipedia.org/wiki/Viewing_frustum) are transformed. The viewing frustum defines the three-dimensional space in which objects are visible to the camera. You can visualize this as a pyramid with the top cut off. The base of the pyramid is the far plane, the top the near plane, and the field of view is the angle at the apex. To perform this transformation we need to know four pieces of information.

1. Field of View (FoV): This is typically 45 degrees or ¼ of p (Math.PI / 4). Reducing the FoV value is like zooming in on the scene, while a larger FoV value is like zooming out. A value greater then 45 degrees is like looking at the scene through a fisheye lens.
2. Aspect Ratio: This is identical to the aspect ratio of your TV or Monitor and is always calculated as the viewport Width/Height. The viewport is nothing other than the form onto which we are rendering the game. Standard aspect ratios for computer screens are 1.33 (640x480 or 1280x1024).
3. Near Clipping Plane: Objects closer to the camera than this plane are not rendered.
4. Far Clipping Plane: Objects beyond this plane are not rendered.

   Radians (http://en.wikipedia.org/wiki/Radian): In DirectX most angles are expressed as radians rather than degrees. To convert from degrees to radians, simple multiply the degree value by p/180, where n is the measure of the angle in degrees. The DirectXDX library contains helper functions to perform the conversion for you in the Geometry class.

Using these values and some fancy math, DirectX transforms the vertices of each object from world coordinates to screen coordinates. To a certain extent, this transformation is what we do in our heads when we draw a picture of a three-dimensional space. We draw distant objects smaller, even though the actual object has not really changed its size, and we distort objects further away.

In the OnPaint method of the GameEngine class, add the following code immediately after the device.Transform.View method call added in the previous step.

Visual C#

device.Transform.Projection = Matrix.PerspectiveFovLH ( (float)Math.PI / 
    4, this.Width / this.Height, 1.0f, 100.0f);

Visual Basic

device.Transform.Projection = Matrix.PerspectiveFovLH ((single)Math.PI / _
    4, Me.Width / Me.Height, 1.0f, 100.0f)

For BattleTank 2005 we used the traditional setting for the FoV of 45 degrees. Next we set the aspect ratio base and then define the viewing frustum as between 1 and 100 in our world coordinate space. The values for the clipping planes define the size of our visible world and can represent anything we want. One unit equals 10 meters in BattleTank 2005 so we have a 1 kilometer playing field.

At this point you have to use some common sense when defining the viewing frustum. We could easily declare that each unit equals one kilometer, making the viewable area 100 kilometers deep. However, if we make the tanks regular size, you will never be able to see them beyond a couple of kilometers, so why waste resources rendering them to the screen if the player cannot see them?

While the View and Projection Matrices describe the camera and camera lens, the world transformation matrix converts the model space coordinates into world space coordinates. These world space coordinates are then converted to screen coordinates in the View and Projection transforms.

World Transform

The last transform is a world transform. This transforms the object we are rendering from model space into world space.

In a world transform you can move, rotate and scale each object. This transform applies to all objects drawn after setting the transform, until a new transform is specified.

Model Space: We define each object by defining each vertex with respect to the model.

In BattleTank 2005 we are not going to use the World transform at this time, but I have included a transform in the code for this article that uses a test cube for you to experiment with. I suggest you play with changing the values for all three transforms and see how the results look on the screen. That is the easiest way to really understand what the various settings do. See the Experimenting section for details on how to do this.

Lights

Whenever we draw a primitive using world coordinates, DirectX uses lighting to determine the color of each pixel. But since we have not yet defined a light source, we can simply turn the lights off at this time. If we do not turn lighting off, then DirectX assumes no lights are shining on the scene and renders each pixel as black.

In the OnPaint method of the GameEngine class, add the following code immediately after the device.Transform.Projection method call added in the previous step.

Visual C#

// turn off the light source
device.RenderState.Lighting = false;

Visual Basic

' turn off the light source
device.RenderState.Lighting = False

In addition to controlling the lighting, the RenderState also allows us to control the culling behavior.

Culling

Culling is an operation that eliminates entire objects (unlike clipping, which removes only portions) from the scene that fall outside of the viewing frustum to reduce the total set of objects to render. The overall goal is of course speed; by eliminating the non essential objects the scene can be rendered faster.

Clipping: Clipping discards portions of any single object that fall outside of the viewing frustum. Clipping is automatically managed by DirectX and requires no further intervention.

When drawing a three-dimensional object, DirectX does not render the primitives (triangles) that comprise the faces of those objects that do not face the camera. This is called back face culling.

DirectX determines which side of an object is facing the camera by using the order (winding) of the vertices. If you choose either clockwise or counterclockwise, then the vertices that are wound the opposite are on the back of the object and are culled. The default mode is counterclockwise culling, so you need to make sure to define your vertices in a clockwise order.

The culling options are set in the RenderState by assigning one of the Cull enumeration settings to the device.RenderState.CullMode property.

In the OnPaint method of the GameEngine class, add the following code immediately after device.RenderState.Lighting code added in the previous step.

Visual C#

// Turn off backface culling
device.RenderState.CullMode = Cull.None;

Visual Basic

 ' Turn off backface culling
device.RenderState.CullMode = Cull.None

In the code that accompanies this article I have added a couple of extra items to make it easier for you to experiment with the various settings we just covered.

Experimenting

To remove the HUD display, comment out the following lines: 122 and 123 (in VB.NET the lines are 92 and 93).

You can also display a rotating cube by un-commenting lines 98, 101, 120 and commenting line 95 (VB.NET: 68, 71, 87, 90 and 65). You can change any of the values in the models or adjust the View, Projection and World transforms to see the effect of your changes.

Line Numbers: To turn on line numbers, go to Tools | Options | Text Editor | All Languages and check the Line Numbers box in the Display group. If you don't see the full options tree, just check the Show all Settings option in the lower left of the Options dialog.

Summary

In these first three articles we have covered a lot of ground. The steps in the upcoming articles build upon the foundation laid in these first three articles. At this point you should know how to create a device and hook it to a Windows form and create a game loop using the OnPaint and Invalidate methods. You should be able to create and draw your own three-dimensional objects using vertex buffers and the DrawUserPrimitives method, set up a camera, and transform the models into world space.

If something is unclear at this time, you should review the links provided in the articles, the DirectX SDK, or go to one of the resources listed on the web. Once you have fully understood these principles, the rest of the game development process will be much easier.

With this knowledge you are ready to perform all but the most advanced operations in DirectX. The only steps required to add more objects to our world in BattleTank 2005 are to define them in model space, store them in a vertex buffer, and render them to the screen. As you imagine, complex objects consist of thousands of separate vertices, and defining them all in code is almost impossible, very error prone and extremely boring. So in the next article I will cover how to accomplish this task more efficiently. In the next article we are also going to finish of the last graphic pieces and then focus on controlling the tank using the classes in the DirectInput namespace.

Until then: Happy coding!

This is Part 1 of an introductory series on game programming using the Microsoft .NET Framework and managed DirectX 9.0.

WARNING: Managed DirectX is no longer supported.  If you want to do 3D graphics with the .NET Framework, please use XNA (http://creators.xna.com)

1. Beginning Game Development Part 1 - Introduction
2. Beginning Game Development Part II - Introduction to DirectX
3. Beginning Game Development: Part III - DirectX II
4. Beginning Game Development: Part IV - DirectInput
5. Beginning Game Development: Part V - Adding Units
6. Beginning Game Development: Part VI - Lights, Materials and Terrain
7. Beginning Game Development: Part VII –Terrain and Collision Detection
8. Beginning Game Development: Part VIII - DirectSound
9. Beginning Game Development: Part VIII - DirectSound II
10. Beginning Game Development: Part VIII - DirectSound III

Part I – Introduction

Welcome to the first article of an introductory series on game programming using the Microsoft .NET Framework and managed DirectX 9.0.

This series as aimed at beginning programmers who are interested in developing a game for their own use with the .NET Framework and DirectX. The goal of this series is to have fun creating a game and learn game development and DirectX along the way. Game programming and DirectX have their own terms and definitions that can be difficult to understand, but after awhile, you’ll crack the code and be able to explore a new world of possibilities. I will keep things as straightforward as possible and decode terms as they appear. Another part of the learning curve comes from the math you’ll need to deal with DirectX. I am going to point out some resources along the way that will help you brush up on, or learn, the math skills you’ll need to keep going in DirectX.

In this series, we are going to build a simple game to illustrate the various components of a commercial game. We will cover how to create great looking graphics in 3D, how to handle user input, how to add sound to a game, how to create computer opponents using Artificial Intelligence, and how to model real-world physics. In addition we are going to cover how to make your game playable over the network and how to optimize your game for performance. Along the way, I will show you how to apply principles of object-oriented development and, as well, I will share some of my experience in creating well-organized and elegant code.

Tools:

Before we start writing our first game we need to talk about the tools we will use.

The most important tool for any developer is the Integrated Development Environment (IDE). This is where you are going to spend the majority of your time writing and debugging code, so it needs be powerful and fast.

Visual Studio 2005 (also known by the codename “Whidbey") is the third version of the standard Microsoft IDE for .NET Framework-based applications. Visual Studio 2005 introduces a number of Express versions that provide most of the functionality of their more advanced counterparts but are simplified for the novice, hobbyist, and student developer and cost much less (There are express versions available for VB, C#, C++, J# and for Web Developers using ASP.NET). For this series, I am going to use both Visual C# Express and Visual Basic Express. If you have not already done so, download the C# or Visual Basic Visual Studio Express IDE at: http://msdn.microsoft.com/express.

The second important tool we need to create a great looking game is a graphics Application Programming Interface (API). Without such an API it would be extremely difficult to access the graphics capabilities of your PC. The API we are going use is the DirectX API. This API allows us to create powerful multimedia applications on the Windows platform. To work on the game, you will need to download the latest DirectX SDK at: http://www.microsoft.com/windows/directx/default.aspx. Make sure that you download the SDK and not just the runtime. The SDK includes samples and other utilities that are extremely useful when developing using DirectX.

At some point in your game development experience you are going to have to create or modify graphics. Every copy of Microsoft Windows comes with Microsoft Paint, and while it is not the most powerful program, you already own it and it is good enough for most of our needs.

As we dive deeper into DirectX and cover 3D models and sounds, you might find the need to use other programs to manipulate the image or sound files. As we cover these topics I will point you towards free or inexpensive programs and resources on the Web.

Finally, you need to know where to go to get help. One of the best places is  the public newsgroups. Here, you can ask questions and get answers from people with the same interests as you. Microsoft MVPs and employees also monitor these newsgroups and provide help for you along the way. The newsgroups that are going to be of most interest for game programming are:

• Managed DirectX: microsoft.public.win32.programmer.directx.managed
• C#: microsoft.dotnet.languages.csharp
• VB: microsoft.dotnet.languages.vb

Other places to go for inspiration and help for gaming are:

• The ZBuffer: http://www.thezbuffer.com/
• GameDev.net: http://www.gamedev.net/
• flipCode: http://www.flipcode.com/
• Gamasutra: http://www.gamasutra.com/ [Professional audience, but many articles from Game Developer, including tutorials]

 What makes a successful game?

My first experience using a computer was in 1981 on a Sinclair ZX Spectrum. The first 5 years of my computing life were spent on nothing but writing and modifying games for the Sinclair and later the Commodore 64, but, heck, what else are you going to do as a teenager? While much has changed in terms of hardware capabilities and available APIs, the properties of a great game have not.

Games today have become so complex that they require large numbers of developers, graphic artists, testers and managerial overhead to develop. They rival large commercial enterprise application in their complexity and cost many millions of dollars to develop and market. The payback, however, can be enormous and rival Hollywood blockbuster movies in sales – Halo 2 grossed $100M in its first day of availability.  

All successful games have a couple of features in common that made them stand out.

• The main ingredient for a successful game is the game idea. Regardless how cool your graphics are, how good the music is, if the idea is lame no one is going to play the game.
• The second most important feature is the playability of the game. If the game is too hard then players are quickly going to get frustrated and stop playing. Conversely, if the game play is too easy then the player is going to get bored and stop playing. A good game provides multiple levels of difficulty that continuously challenge the player without overwhelming or boring them.
• Together, the game idea and its playability are the “game design” (not to be confused with “level design,” which is the application of the overall game design to specific segments of the game). There are certain game designers who have a golden touch. Shigeru Miyamoto (the creator of Donkey Kong, Zelda, and Mario) and Will Wright (Sim-everything) are two prominent examples. Miyamoto’s keynote address to the 1999 Game Developer’s Conference is available at http://www.gamasutra.com/features/20030502/miyamoto_01.shtml and Wright’s recent discussion of the design philosophy of Spore (http://www.gamespy.com/articles/595/595975p1.html?fromint=1) are good inspirations for designers of all stripes, while the book “Theory of Fun for Game Design” by Raph Koster has gotten excellent reviews in the community.
• The third ingredient to a successful game is the set of graphics. They need to be good enough to compliment the game idea and game play but not so resource intensive or flashy that they distract from it.
• The final ingredient is performance. No one wants to play a slow game. I still remember an adventure game on my Commodore64 that took 10 minutes to render each scene. I still played it, mind you, because the game idea was great and there were no other options around but it was irritating.  Graphics and performance are closely related. The more fancy graphics you add to a game to slower the performance. The next biggest performance issue is the AI. A lot of game development today focuses on how to make things faster and not coming up with new ideas. However, when you’re learning a complex programming technique such as game programming, it’s vitally important not to optimize prematurely. An understanding of the performance pipelines, and the skills to write clean code, profile it, and improve it are much more important than any single optimized function.  

If you apply your design efforts in this order you, too, can create a great game. It may not be a refined first person shooter like Battlefield 1942, but Tetris is arguably one of the most popular games and has neither fancy 3D graphics nor Dolby digital sound. Even today, games like Gish (http://www.chroniclogic.com/index.htm?gish.htm) demonstrate what can come from creative independent developers. If you can write enough of a game to show your game idea, then maybe you can interest the large gaming companies in your game. The Independent Games Festival is the “Sundance” of the game community, runs concurrently with the professional Game Developers Conference and, believe me, is among the most closely-watched events at the show.

Our Game idea: 

Now that you know what features make a great game, the next step is to lay out the game proposal for our game.

Idea: Since coming up with a unique and creative game idea is the core of any game, I am going to cheat and use the game idea from the first 3D game I ever saw: Atari’s Battlezone. (If I had that great idea why would I let of all you know anyway?) Battlezone is a basic first-person shooter game in which you are looking through the viewfinder of a tank into a 3D landscape. The goal is to destroy as many of the opponent’s tanks as possible before getting destroyed yourself. The landscape includes random objects behind which you can hide. The game screen includes a radar to show you the location of your opponents and the current score.

Playability: The original game started out fairly slowly but kept adding more opponent tanks and other random enemies.  The game also increased the speed and intelligence of the opponents. All of this kept the game challenging but playable.

Graphics: The original game used graphics that proved just engaging enough to feel like you were in a 3D world, but because of the hardware available in 1980 (an 8-bit processor running at 1.5 megahertz) it rendered the 3D objects as wire frames. These graphics were advanced when the game first came out, but we are going to improve upon them using the magic of DirectX (and the magic of 25 years of Moore’s Law!).

Screenshot of Atari’s Battlezone game – complete with wire frame mountains, tanks, and even a wire frame moon for added realism!

Performance: This game pushed the limits of the hardware available at the time. This is evident in the use of the wire frame objects. If the game had been written to fill these objects then it would have been unplayable. With today’s advanced hardware we should not have any performance issues other than those introduced by us writing sloppy code.

Now that we have decided on a game, the next step is to write down the goals of your game. This does not need to be anything formal but the simple act of writing things down has the tendency to make ideas clearer. At a minimum you need to determine the object of the game, what the player can and cannot do and how the player interacts with the game. We also should define what the scoring system is going to be like and what are the victory conditions.

For our game these are the simple specification I came up with.

• A 3D first-person shooter game
• The goal is to destroy as many enemies as possible
• The player can move through the landscape on the ground just as a regular tank can. The tank can not fly, nor can it change speed.
• The game play will be controlled through the keyboard for moving and shooting. The mouse will be used to interact with the menus and start/stop the game. We will not support a joystick.
• The player will receive a score that is based on the distance at which the enemy tank was destroyed. The further the tank was, the higher the score. Each round fired reduces the score by a set amount, unless that round hits a target.
• The game will be divided into levels. Each level will have a pre-defined number of enemies. Once all enemies have been eliminated, the player advances to the next level. There is no limit to the levels.

Now we are ready to do some coding. In general, it is best to write down just the overall idea of the application. Spending a lot of effort upfront designing every little detail is just a waste of time. As we add more functionally to the game we will continuously do small design sessions to formulate our ideas. This iterative approach to developing software is the best way to create good software, and is more fun at the same time.

Creating the game Project:

Now we are ready to write some code. The first step is to create a new solution in Visual Studio 2005.

• Select File | New | Project and choose Windows Application from the template list. In the Name field at the bottom of the dialog, replace the default WindowsApplication1 with BattleTank2005 and click OK.

Visual Studio now creates a new solution for us called BattleTank2005 that contains a single project with the same name.

First, we need to rename the class to something more descriptive. Naming is one of the most efficient methods of keeping code well organized and understandable. Always choose names that clearly describe what the item is doing and avoid meaningless names like Class1 and Form1.

• From the Edit menu, select Find and Replace, then select Quick Replace. Set the Find What field to 'Form1', Replace What field to 'GameEngine' and the Look in field to 'Current Project' (see Figure below). Click Replace All to make this change (there should be five changes made)
• Next right-click Form1 in the Solution Explorer and select Rename. Change Form1.cs to GameEngine.cs.

Replacing Form1 text with GameEngine. You'll thank yourself later.

Another trick to keeping things organized is to ensure that the files in the Solution Explorer are named exactly the same as the classes they contain and to always create a separate file for each distinct element such as each class or enumeration.

Now we have a Windows application that we can run, but it doesn’t do anything. The form has no other controls on it such as buttons you can click or textboxes to display any information. In a regular Windows Forms application we would now add such controls to the forms to create our final application, but for our game we are going draw everything using the DirectX API rather than the Windows Forms API.

We really only need the Form for its Windows Handle, which is basically its unique name among all the other windows on the screen. We will use this handle to set up our DirectX drawing surface. The other use of the Form is that it contains an event that we are going to use to create our render loop.

Adding the Render loop

A game is much different from a regular application, such as Microsoft Word. Word presents a screen to the user that mimics a page in a typewriter and then waits for the user to do something. This something could be pressing the keys on the keyboard or selecting a menu item from the menu with the mouse. While waiting for the user to interact with the application Word does nothing. (Actually I lie: it does do things like run spell checking and auto save in the background but nothing you as the user can see). Generally, programs written using the Windows Forms library generally have the same behavior – they don’t consume CPU time unless the user is doing something (of course, it’s possible to use the Timer control or the capabilities of the System.Threading namespace to do things independent of the user).

Games are different. As you know, smooth movement in games requires the screen to be updated many times per second. The “flicker fusion threshold” at which static images begin to fuse is generally taken to be 1/16 of a second, although it actually varies depending on illumination (brighter lights like computer monitors require higher frame rates) and where on the retina the image falls (peripheral vision requires higher rates than foveal vision). Although movies are shown at 24 frames per second (FPS), 30 FPS is often considered the lowest-acceptable rate for video games, and most actiongame players tune their graphics for no less than 60 FPS.

Because the render loop is called dozens of times per second and runs nonstop, game programming almost always uses the render loop as the “stopwatch” of the game, calculating everything inside the loop, not just graphics, but physics, AI, checking for user input, and scores. (Again, you could use the Timer class or threads to write a multithreaded game, but doing so would introduce significant complexity without any clear benefits and although multithreading in the .NET Framework’s Common Language Runtime  is quite efficient, the slight overhead could knock a couple frames per second off your game.)

So how do we get the computer to run this loop? The form we added earlier has an event called the Paint event. The Paint event for a Windows Form object is called whenever the form is redrawn. This normally occurs only when you maximize a form or when a form is covered by another form that is moved.

As all Windows Forms programming, even game programming, is event-based, understanding the principles of events and event handlers is critical. Although the event is triggered automatically, we need to create a special method called an event handler to be able to intercept the event and do something in response to it..

• In the GameEngine class add the following code after the constructor.

Visual C#

protected override void OnPaint(PaintEventArgs e)
{
          
}

Visual Basic

Protected Overrides Sub OnPaint(ByVal e As PaintEventArgs)
          
End Sub

This is our event handler. When is it called? “OnPaint” – when the Paint event occurs. One thing is still missing. Even though Windows and the Windows Forms library automatically raise the event, some actions that we might expect to trigger the Paint event don’t. Minimizing a window, for example, does not trigger the Paint event, since Windows does not see the need to repaint the entire form (Windows is just being efficient since we are actually displaying less when we are shrinking the form). So we cannot rely on these automatically-created events to manage the loop we need for our game.