XNA Essentials

Game Programming for Xbox 360, PC + Windows Phone

NAVIGATION - SEARCH

Advanced Debugging Tutorial – Part Two

In the first tutorial we talked about some of the advanced debugging techniques. In this tutorial we will take it a step further and create a debugger visualizer. When we look at data while debugging, sometimes the default representation isn’t quite good enough. For example, the value of a Matrix variable is displayed as simply a string. We could make it into a table structure that actually represents the Matrix. We could also actually display the real color instead of just the color name or RGBA values.

In this tutorial we will be creating a color visualizer. When creating a debugger visualizer there are a few steps that have to take place. We need to do a few more things to get the visualizer be a Windows form that utilizes XNA.

image

Typically one would do the following steps to create a normal visualizer:

  1. Create a class library projects
  2. Add appropriate references (Microsoft.VisualStudio.DebuggerVisualizers; System.Windows.Forms)
  3. Create a class and make the class inherit from the abstract class DialogDebuggerVisualizer
  4. Override the Show method from the abstract class
  5. Add the assembly attribute DebuggerVisualizer setting the appropriate properties
  6. Copying the compiled assembly into one of two folders so Visual Studio can load it and use it

We will be altering the earlier steps a little since we are going to start off with a Creators Club Online Educational Example. We want our windows form to actually utilize XNA and there is no reason to reinvent the wheel. Let’s get started!

Start with the Educational Example: WinForms Series 1: Graphics Device

Extract this to a new folder called XNAVisualizer

Rename the project to XNAVisualizer

Rename the solution file to XNAVisualizer.sln

Open the solution file and rename the project in the Solution Explorer

Rename all of the namespaces to XNAVisualizer.

A shortcut for renaming all of the namespaces is to change one name and then click on the dropdown it makes and select “Rename ‘WinFormsGraphicsDevice’ to ‘XNAVisualizer’

image

Change the project type from Windows Form to Windows Library.

Double click on the Properties node in the Solutions Explorer. Under the Application tab change the Output Type from Windows Application to Class Library

image

While we have the properties window open, we can change the Assembly Name to XNAVisualizer

Delete the SpinningTriangleControl from the project.

Rename SpriteFontControl to ColorControl

We will be adding this control to the form later. This is the control that will display the color being debugged.

Add the following public field to the new ColorControl

public Color BackgroundColor = Color.CornflowerBlue;

Change the contents of the ColorControl’s Draw method to contain:

GraphicsDevice.Clear(BackgroundColor);

spriteBatch.Begin();
spriteBatch.DrawString(font, BackgroundColor.ToString(), new Vector2(10, 10), Color.Black);
spriteBatch.DrawString(font, BackgroundColor.ToString(), new Vector2(11, 11), Color.White);
spriteBatch.End();

In the Initalize method replace the following line:

content = new ContentManager(Services, "Content");

with these three statements:

Assembly visualizerAssembly = Assembly.GetExecutingAssembly();
content = new ContentManager(Services);
content.RootDirectory = visualizerAssembly.Location.Replace(
    visualizerAssembly.ManifestModule.Name, @"Content\"); 

Since this assembly will be running in a special folder we need to explicitly tell it where it can find the Content assets. We are using the Arial font from the original project. We are displaying the Color’s RGBA values using the font. The code is using reflection to get the executing assembly (our visualizer) and then setting the path to the path of the assembly and appends Content\ to the end of it. The Location property contains the full path including the assembly name (XNAVisualizer.dll). The ManifestModule.Name contains the assembly name as well. We are simply removing the assembly name from the path.

Since the code is using reflection we need to add the following using statement to the top of our ColorControl.cs file:

using System.Reflection;

 

Now we can bring our attention to the MainForm.

Remove all controls from the MainForm form

Double click on the MainForm.cs file

Click Ignore Errors and Continue

Remove the combo boxes, the split panel and delete each one. You may have to right click on the form and choose Select ‘spltContainer1’. Once it is selected you can hit the Delete button on the keyboard to remove it.

Make the form itself a lot smaller. For this we are simply wanting to display the color and the RGBA values of the color so it doesn’t need to be too large.

Compile the project and double click on the error to bring us into the MainForm.Designer.cs. Remove the SpinningTriangleControl and vspriteFontControl variables.

Remove the vertexColor_SelectedIndexChanged method from the MainForm class.

Remove the three vertexColors from the MainForm constructor.

Recompile to see 0 errors.

Open the design view of the MainForm again.

Re-add the ColorControl directly to the form by dragging it from the toolbar (under XNAVisualizer Components)

Expand the ColorControl so it fills up the entire form.

Change the form’s FormBorderStyle in the properties panel to FixedToolWindow. This keeps the window from being resized.

Change the Text of the window to “XNA Color Visualizer”

Drag the ColorDialog (from the toolbox under either the All Windows Forms or Dialogs tabs) to the form. This will create colorDialog1.

Double click on the ColorControl to create the _Click event.

Replace the contents of the MainForm class with the following:

public MainForm()
{
    InitializeComponent();
} 

public XnaColor Color
{
    get
    {
        return (colorControl1.BackgroundColor);
    }
    set
    {
        colorControl1.BackgroundColor = value;
        colorControl1.Invalidate();
    }
} 

private void colorControl1_Click(object sender, System.EventArgs e)
{
    if (colorDialog1.ShowDialog(this) == DialogResult.OK)
    {
        Color = new XnaColor(colorDialog1.Color.R, colorDialog1.Color.G, colorDialog1.Color.B, colorDialog1.Color.A);
    }
}

We added a public property Color. The example code declared XnaColor as a type to help distinguish from the XNA Color and the Windows Form Color. We are using the XnaColor type. We simply return the BackgroundColor of our colorControl when Get is called. And for Set we, we set the background color of the control as well as Invalidate our control so it will be redrawn. We could have hooked into the Idle event and called Invalidate continually, but there is no need for this control. The original example does this with the SpinningTriangleControl. Reading the WinFormsGraphicsDevice.htm file would be beneficial to see the pieces of the code we are using but not discussing like GraphicsDeviceControl, GraphicsDeviceService and ServiceContainer.

We populated the colorControl1_Click method by actually displaying the built in Windows Color Dialogbox. If the user clicks OK, we get the selected color from the dialog box and set our color property to the newly selected color. Our color property then sets the BackgroundColor property of the ColorControl. Note: This control does not let us change the Alpha value of the color.

 

The last thing we need to do is actually create our Visualizer code.

Add a new blank code file and name it ColorVisualizer.cs.  Paste the following code:

using System.Diagnostics;

using Microsoft.VisualStudio.DebuggerVisualizers;
using Microsoft.Xna.Framework.Graphics;

[assembly: DebuggerVisualizer(
    typeof(XNAVisualizer.ColorVisualizer),
    Target = typeof(Microsoft.Xna.Framework.Graphics.Color),
    Description = "XNA Color Visualizer")]

namespace XNAVisualizer
{
    public class ColorVisualizer : DialogDebuggerVisualizer
    {
        protected override void Show(IDialogVisualizerService windowService,
                                     IVisualizerObjectProvider objectProvider)
        {
            Color c = (Color)objectProvider.GetObject();

            using (MainForm form = new MainForm())
            {
                form.Color = c;

                windowService.ShowDialog(form);

                if (objectProvider.IsObjectReplaceable)
                {
                    if (form.Color != c)
                    {
                        objectProvider.ReplaceObject(form.Color);
                    }
                }
            }
        }

    }
}

We have to add a reference to the Microsoft.VisualStudio.DebuggerVisualizers assembly by clicking on the References tree node in the Solution Explorer under the XNAVisualizer project. Making sure we are on the .NET tab we scroll down and select the assembly and add it to our references.

The assembly attribute DebuggerVisualizer tells VisualStudio this is the entry point for the visualizer. It tells it what type of data it is visualizing as well as the description.

The visualizer class itself inherits from the DialogDebuggerVisualizer abstract class. We override the Show method to actually display our form with the data being investigated by the debugger. We look at the objectProvider object passed in and cast it to our Color type. We set the Color property on the MainForm to the value we are debugging. We then actually display the MainForm by calling ShowDialog on the windowService object passed in.

If all we wanted to do was display the color we would be done. However, it would be nice to actually change the color on the fly while debugging. This is why we added the Color Dialogbox. We first check to see if the object we are viewing is replaceable. It won’t be replaceable, for example, if we are debugging an enumerated type (i.e. Color.Black). However, if it is a variable holding a value then it will be replaceable and we replace the object by calling ReplaceObject on the objectProvider object passing in our new object (form.Color in this case). There is also a ReplaceData method, but we aren’t discussing that in this tutorial.

After compiling the assembly we need to place it in one of two directories:

\$Documents\Visual Studio 2008\Visualizers

or

\Program Files\Microsoft Visual Studio 9.0\Common7\Packages\Debugger\Visualizers

Since we have Content assets we also want to copy the Content folder and any assets to the Visualizers folder as well. It can be tedious to copy the assemblies and content assets after every compile. We can create a Post Build Event command line to copy it for us. We need to open the properties of the XNAVisualizer project (by double clicking on the Properties node in the Solution Explorer) and go to the Build Events tab. Click on the Edit Post-build button and paste the appropriate variation of the following command and hit OK:

copy "$(TargetPath)" "C:\Users\<User Name>\Documents\Visual Studio 2008\Visualizers"
md "C:\Users\<User Name>\Documents\Visual Studio 2008\Visualizers\Content"
copy "$(TargetDir)\Content\*.*" "C:\Users\<User Name>\Documents\Visual Studio 2008\Visualizers\Content"

(Change the paths as needed)

Now when we run a regular XNA project and we want to debug the color we simply set the breakpoint and when we hover over the color variable we want to debug we click the Magnifying Glass icon which will bring up our newly created form.

Fortunately, the XNA Framework team did a lot of the heavy lifting for us (as usual) in this example by allowing us to utilize XNA in a Windows Form. We simply modified the example to be a Class Library and added the actual Visualizer code.

Debugging the Debugger Visualizer

To debug a debugger visualizer a static test method can be created and then a console app can be created to call the static method. This can be a great way to test the visualizer. Instead of creating a console app with all of the XNA assemblies referenced, I debugged the visualizer by  attaching to another Visual Studio instance.

In the Debugger Visualizer project click on Debug / Attach to Process. A dialog will come up. Select Visual Studio instance you want to debug. This would be your real XNA project that has a XNA Color variable.

image

Now when we set a break point in the main XNA project and hover over a Color variable and hit the magnifying glass it will kick off the Visualizer Debugger and if we had a breakpoint we could step though the code. Pretty cool!

 

A great next step would be to create another visualizer in this project to display Matrices.

For more reading on Visualizers look in the following here.

Download the code from this tutorial here.

Happy Coding!

-Chad

Xbox LIVE Indie Games

It is official! Xbox LIVE Community Games is now Xbox LIVE Indie Games. The name change will be reflected on xbox.com and Xbox LIVE Marketplace later this summer.

The name change isn’t the only thing happening. The prices options for the games are being changed. The days of listing a game for 800 points (about $10 USD) is coming to an end. To me, it was really difficult for a Creator to compete against expansion packs, and XBLA titles anyway. The new price points will be 80, 240 and 400.

On the Creators Club Online site itself there is a new shiny thing called Reputation. The idea is great and hopefully it will inspire Creators to review and test more games. More information about Reputation can be found here.

Upgrades to Xbox LIVE Indie Games will now be automatic! So if you push out an update to your game, the gamer will be asked if they want to download the most updated version of the game. Very cool!

Also, now Creators get a maximum of 50 tokens for their games. This will allow the Creator to give media outlets an easy way to review their game.

New Countries can now submit Indie Games – Germany and Japan. There are also updates for Sweden and Singapore.

For a complete list of the changes see the official story on the XNA Creators Club Website.

There is no time like the present to create your dream game. Get to it!

Happy Coding!

-Chad

XNA Game Studio 3.0 Final is Released

XNA Game Studio 3.0 was released today. All the goodies can be found over at the Creators Club website: http://creators.xna.com/

There is a new starter kit. It is called 'Platformer' and it creates a project for all three platforms (Windows, Xbox 360 and the Zune). It is a great way to dig in and see some of the ways to use one code base to run a game on multiple platforms.

Don't delay, go download your very own copy of XNA Game Studio 3.0 today!

Happy Coding!

-Chad

XNA Game Studio 3.0 Beta

Hello XNA Game Studio 3.0 Beta! I'm excited that this is here.

Right on the heals of the Zune 3.0 software and firmware update today.

XNA GS 3.0 Beta allows us to develop games for our Zunes.  With the CTP that was released in the spring, the Zune device had to reboot anytime a game was closed.  Fortunately, they have made it so closing a game now doesn't require the device to reset itself.  I'm very happy about this, but I really wasn't expecting it.  I am sure it wasn't easy to make sure that no game was hogging up resources after it was closed. UPDATE: I was incorrect in the above praise. It seems the two games that were installed with the Zune 3.0 update (Texas Hold'em and Hexic) do not require a reboot, but normal XNA games do.

You can write code for the Xbox 360, but you can't deploy to it in the beta. We can compile our code for the Xbox 360 and that is helpful, but we can't deploy.

That reminds me ... the Dream Build Play contest is winding up.  Submissions have to be in by September 23rd.  As a reward for just submitting an entry, Microsoft is giving away a 4 month premium creators club membership.  That is $49 value - just for submitting an entry.

Again, to submit a game for DBP it needs to be an Xbox 360 project which means it needs to be compiled with XNA Game Studio 2.0.

So get a game submitted!

Free 1 Year XNA Creators Club Subscription

Well technically it is a Trial subscription, but it allows you to deploy games to your Xbox 360.  This is not a premium subscription, so you won't be able to submit games to the current beta site (for XNA Game Studio 3.0 CTP) or review other's games and you won't be able to download premium content like the Ship starter kit.  But, being able to deploy a game to your Xbox 360 for free is definitely a good thing!

How do you get this free subscription?  Easy - just sign up to be a part of the Dream Build Play competition.  The competition is only for Xbox 360 games (this is why Microsoft is giving away the subscription trials).  The grand prize winner will get $40,000!  That is a nice chunk of change.  The winner may also get to sign a deal with Xbox LIVE Arcade much like some winners from last year's competition.

So don't just stand there ... get the free subscription while it is available and start working on your entry!

Happy Coding!

Chad

Academic Trial Memberships

There was a press release on December 12th that discussed three main topics:

1. XNA Game Studio 2.0 Supports Xbox LIVE.

2. Microsoft will provide a free trial membership in the XNA Creators Club beginning in January, allowing faculty members and students to use XNA Game Studio 2.0 and Xbox 360 for instructional purposes.

3. Another Dream-Build-Play Warm-Up challenge is underway.

 

The piece that is new is number 2 above.  Here is the excerpt from the press release:

Academic Trial Memberships
Since its release last December, XNA Game Studio has been an incredible success, with 750,000 downloads, adoption by more than 300 universities worldwide and at least nine textbooks on the tools in development. In subjects from computer science to fine arts, introductory courses to graduate and research projects—XNA Game Studio is helping faculty members and students explore the boundaries of applied gaming technology in education.

Along with XNA Game Studio 2.0, Microsoft will also provide a free academic trial membership in the XNA Creators Club beginning in January, allowing faculty members and students to use XNA Game Studio 2.0 and Xbox 360 for instructional purposes.

---

There are a couple of universities and community colleges that either have picked up my XNA Unleashed book or are going to this coming semester.  There has been some discussion about providing some extra material to help instructors.  If you are thinking of adopting my book and are interested in any supplemental material, leave a message on the Amazon forum for the book.

Happy Learning!

-Chad