BadCorporateLogo: XNA Game Studio

Making a Designer of Your Own - An Imperfect Example

Mon, 06 Oct 2008 01:13:06 GMT

Months ago, I started a little project that was supposed to be a diversion from my day job. My day job is building XNA Game Studio... And my project was an experiment to make programming with XNA Game Studio easier. I admit that I'm not very good at creating diversions for myself.

Anyway, after a couple nights of playing with samples from the XNA Creators Club Online web site, I had integrated the MenuScreen class into Visual Studio's designer framework. The result was being able to double-click a code file in a game project, and have a game menu open up in a document window. I added support for dragging-and-dropping menu items from the Toolbox, and editing properties in the Properties Window. It demonstrated some exciting possibilities, but at that point was only barely functional.

After posting some initial screenshots to my blog, I discovered that, although I'm terrible at distracting myself from work, I am pretty good at finding interesting things to work on. My blog traffic exploded by two orders of magnitude, and I received a number of requests for source code.

I'm pretty certain that my source code isn't self-explanatory. The designer I built is a customization for an existing framework, and the vast majority of the functionality isn't in my source. Anyone who understands enough of the framework to see how my source code works doesn't need the source code in the first place. So instead of answering requests with code, I started to explain the framework I was integrating into.

I'm finally at the point where further explanation will be easier to follow with a working example. For that reason, I've put my prototype project on CodePlex. The project doesn't build a ready-to-use designer. The design-time experience is runnable, but not usable. It's got tons of potential, and I'm going to continue working on it, but at this point, it's far from perfect.

My CodePlex project is called ferpect. If you are interested in building designer support for your own libraries, then I encourage you to take a look at it, and join the discussion if you'd like to request specific features be added for your reference.

Ferpect Game Component Model

I'm really looking forward to continuing my work on this project. Now that the fundamentals are out of the way, I think being able to review changesets and associated check-in comments will cut down on the amount of explanation required for new features and concepts.

That's all for now!

Making a Designer of Your Own - Mixing and Folding

Sun, 28 Sep 2008 09:23:51 GMT

For those of you who are waiting for my next article on creating a designer for XNA Framework game components, here it is! I've been working on creating a CodePlex project for the sample source code, but this turned out to be more work than I first imagined. I took a few shortcuts when I initially created my little designer, and for the code to work on other people's machines, I had to implement a bunch of additional features (no more hard-coded paths or pre-compiled assets!).

Anyway, as I continue to get that all prepared, I was forced to fix a few bugs in my designer serializer. I'd forgotten how some of my own code worked, so it took a bit of debugging before I figured out what was going on and how to fix it. Certainly there will be more bugs, so I decided to write about how serialization works -- both for my own benefit, and for others.

What The Heck is Serialization?

In the managed designer infrastructure, serialization is the process of converting objects into source code, and deserialization is the process of converting source code into objects. In general, serialization is easier than deserialization, but both are quite complicated. Fortunately, the managed designer infrastructure provides an extensible serialization implementation based on CodeDom. The key word there is "extensible," because it means we can rely on the standard behavior most of the time, and then customize things when we need to.

For convenience in the following description, let me introduce the term serialization manager as the part of the designer infrastructure that coordinates serialization and deserialization.

To deserialize an object from source code, the serialization manager invokes a parser to convert the source code from a file into its CodeDom representation. The CodeDom represents a type declaration and its initialization method. The serialization manager reflects on the base type to retrieve its DesignerSerializer attributes, which identify the specific CodeDom serializers to use. Then the serialization manager will instantiate the appropriate serializer and invoke its Deserialize method.

There are two kinds of serializers: TypeCodeDomSerializer and CodeDomSerializer. The first is for serializing/deserializing a type declaration. The second is for serializing/deserializing statements. To deserialize an object from code, you need both kinds of serializers.

This is a good time for an example.

Let's say that I have the following code in a file called MenuScreen1.cs:

   1:  public class MenuScreen1 : MenuScreen

   2:  {

   3:      private ToggleMenuItem toggleMenuItem1;

4:

   5:      public MenuScreen1()

   6:      {

   7:          this.InitializeComponent();

   8:      }

9:

  10:      private void InitializeComponent()

  11:      {

  12:          this.toggleMenuItem1 = new Ferpect.GameState.MenuItems.ToggleMenuItem();

  13:          //

  14:          // toggleMenuItem1

  15:          //

  16:          this.toggleMenuItem1.Label = "Sound";

  17:          this.toggleMenuItem1.ToggleValue = true;

  18:          //

  19:          // MainMenuScreen

  20:          //

  21:          this.MenuItems.Add(this.toggleMenuItem1);

  22:          this.Text = "Options";

  23:      }

  24:  }

When the parser reads this file and converts it to its CodeDom representation, it ignores all properties and methods in the class except the InitializeComponent method. The resulting CodeDom is a CodeTypeDeclaration with fields and one method containing a statement collection.

After parsing, the serialization manager needs to get the serializers for the base type of the class being deserialized. By inspecting the CodeTypeDeclaration, the serialization manager will determine the base class is MenuScreen (as seen on line 1). It then uses ITypeResolutionService to get a Type instance for MenuScreen, and then uses TypeDescriptor to get its DesignerSerializer attributes. If the base type doesn't have any DesignerSerializer attributes, the serialization manager continues searching up its inheritance chain until it finds a base type that identifies a TypeCodeDomSerializer.

After finding the type serializer for MenuScreen, the serialization manager will instantiate the serializer and invoke its Deserialize method, passing it the CodeTypeDeclaration for MenuScreen1. The standard TypeCodeDomSerializer will look at the base type in the CodeTypeDeclaration, MenuScreen, and instantiate it.

This very first object is returned to the serialization manager and placed on the design surface. Since it's the first component on the design surface, it becomes the root component, and its name is the name of the type being deserialized, MenuScreen1. The serialization manager then adds MenuScreen1 to its name table.

At this point, MenuScreen1 is only partly deserialized. After adding the root component to its name table, the serialization manager begins to interpret the code statements in the InitializeComponent method. The InitializeComponent method contains statements that are sorted into groups according to the object reference on the left-hand side.

That is, all the statements referencing "toggleMenuItem1" are grouped together, and so are the statements referencing "MenuScreen1". Each member variable is added to the name table, then for each one, the serialization manager retrieves the CodeDomSerializer for the member variable's type, and uses it to deserialize that member's assignment statements. The last step is to retrieve the CodeDomSerializer for MenuScreen, and use it to deserialize the remaining assignment statements for MenuScreen1.

If there is an assignment statement that references another member variable on the right-hand-side, the serialization manager is used to resolve the name. If the object hasn't been added to the name table yet, then the serialization manager will immediately deserialize the named component's statements so that it can return the instance.

In the example above, toggleMenuItem1 will be deserialized into a ToggleMenuItem instance, and that instance's Label and ToggleValue properties will be initialized to "Sound" and true, respectively.

When MenuScreen1's statements are deserialized, you can see there is a reference to toggleMenuItem1 on line 21. The serializer will resolve this reference by asking the serialization manager for an object with that name. Since toggleMenuItem1 is already deserialized at that point, it is returned, and then can be used to be added to the MenuItems collection.

When the deserialization is complete, the design surface shows a MenuScreen instance that has been initialized exactly like the code in the MenuScreen1.cs file.

Serialization is similar, but works in the opposite direction. The root component is serialized into a type declaration, then each of the other components on the design surface becomes a member variable plus some initialization statements, and finally the root component's initialization statements are generated.

The statements usually are generated into the InitializeComponent method, because that's the only method that will be parsed during deserialization. A designer isn't going to be much use if it can't round-trip from objects to code and back again.

The code file, MenuScreen1.cs may contain other code written by the user. For example, the user may add event handlers. After serializing the design surface to CodeDom, the CodeDom is turned into source code by a code generator. That source code is then strategically inserted into the source file to completely replace existing methods with the same names.

Skillful Substitution Explained

In my last post on designers, I said the following:

Every experienced cook knows how to substitute certain ingredients for others. However, it takes a certain amount of skill and know-how to still end up with a palatable result. (I'm really determined to keep this cooking analogy going...)

The reason I started to write this whole series in the first place was to explain how to re-use the existing Windows Forms designer for XNA Framework game components. The problem with trying to use the Windows Forms designer is that it only works with Windows Forms Control classes, and our XNA Framework game components are not Controls.

As I discussed in previoius posts, it is possible to implement a Windows Forms Control that will create an XNA Framework graphics device and draw an XNA Framework game component. Following my example above, let's imagine that MenuScreen is an XNA Framework game component. To be able to design this component in the Windows Forms designer, I need to deserialize MenuScreen into a Control that can draw a MenuScreen component (let's call that a MenuScreenControl).

I need several things for this. First, I need to put an attribute on MenuScreen to point to a custom type serializer. The type serializer is responsible for deserializing the CodeTypeDeclaration into an object instance. With a very small amount of code, it's possible to create a custom TypeCodeDomSerializer that simply modifies the CodeTypeDeclaration it is given so it looks like MenuScreen1 derives from MenuScreenControl, and then passes it along to the TypeCodeDomSerializer for MenuScreenControl.

The MenuScreenControl instance will use ICustomTypeDescriptor to make it look like a MenuScreen instance when viewed through reflection (design-time reflection is always done with TypeDescriptor). Since serialization uses TypeDescriptor, we don't need to modify the TypeCodeDomSerializer's serialization step -- because the ICustomTypeDescriptor implementation fools the serializer into thinking it's serializing a MenuScreen instance.

The MenuScreenControl implementation is pretty straightforward. It is just a GraphicsDeviceControl with ICustomTypeDescriptor. Since it needs to draw a MenuScreen instance, it makes sense to instantiate one of those and store it in a member variable. Then the ICustomTypeDescriptor implementation just needs to invoke TypeDescriptor on the MenuScreen instance.

Note: There is a bit of futzing required to make the properties work properly in the Properties Window, but I'll explain that another time.

The last thing required is a custom CodeDomSerializer, also identified by an attribute on MenuScreen. This one is required to acquire the CodeDomSerializer of a standard Component, and then just delegate its Serialize method to that instance. The reason for this is because the initialization statements are generated by the CodeDomSerializer, and the standard serializer for a Control will generate additional statements for Control layout that won't compile when applied to a game component.

Wrapping Up the Leftovers

At this point, you're probably thinking, "How many times can this guy write 'serializer' in one post?" I don't blame you. But if you stuck through all this, then you're probably starting to see how extensible the designer framework really is, and how finding the right extensibility points is the key to re-using code and saving yourself a truck load of work.

Debugging Zune Games in XGS 3.0

Thu, 18 Sep 2008 04:38:27 GMT

If you've been using XNA Game Studio to develop games for Zune, you're probably familiar with the following debug output:

The thread 0x1234 has exited with code 0 (0x0).

This message gets spit into the Output Window while debugging, about once per second, if not more. It shows up so frequently, in fact, that it makes it very hard to see any other output at all!

Since it's pretty rare that you're actually interested in these thread exit messages, seeing them can get quite aggravating. That's why I'm posting this to explain how to suppress these messages from the debug output.

While debugging, right-click on the Output Window, and uncheck "Thread Exit Messages". Done! Now you can use the Output Window again!

Making a Designer of Your Own - Soup Stock

Sun, 27 Jul 2008 20:56:37 GMT

In my last couple posts, I've been explaining concepts needed to customize the managed designer infrastructure in Visual Studio. I've been forced to put this project aside for quite a while on account of being too busy with other things... But this weekend I really need to think about something other than work for a while. Despite Shawn thinking I'm nuts for having the same hobby as my work, the important thing for me is that I work on different problems. Thinking about my own programming problems doesn't involve quite the stress as thinking about programming problems for work.

Anyway, I've been using the analogy of learning to cook as the theme of my blog posts. In this post, I'm going to describe a set of base classes that we can re-use for nearly any type of designable component. In cooking terms, it'll be like creating a soup stock. It forms the basis of many dishes, and each one can be uniquely characterized by adding different elements!

The Concept

I want to create a visual designer for an XNA Framework drawable component, so the first thing I need is a way to render it in a Visual Studio editor. When I first thought about this, two things came to mind. First, there is already a designer for Windows Forms Controls. Second, the Creators Club Online web site has a sample showing how to render XNA Framework graphics classes in a Windows Form Control.

At this point, it almost seems like there's nothing left to do! On the other hand, I don't really want a Windows Forms Control in my game because Windows Forms is not supported on either Xbox 360 or Zune. I would prefer to keep the code in my game libraries platform-neutral, so I can use the same components no matter what platform I'm targeting. Hmm...

I really want a designable XNA Framework game component that doesn't derive from Control, but creates a Control in the design surface when opened in design view. Furthermore, I want to edit the component's properties instead of the Control's properties. Sounds difficult -- and it is -- but applying the right ingredients to a powerful stock will result in exactly the secret sauce I'm after.

For now, let's focus on building the right stock. Later, I'll explain the switcheroo.

The Prep

The sample (here) provides source code for GraphicsDeviceControl, a Windows Forms Control that renders XNA Framework content. It's trivial to derive from this existing class and override the Draw method to draw whatever XNA Framework content that I want. That means it's trivial to make a designable Control that uses the XNA Framework to render itself.

To get started, we need to prepare a couple things. First, I'd like a base class for my designable components. The XNA Framework's DrawableGameComponent isn't suitable as a base for my designable components because it requires a Game class instance to be provided to its constructor. At design-time, we're not going to have a Game instance, so we wouldn't be able to instantiate and use it. We also would like the base class to derive from Component so that Visual Studio recognizes it as designable (at some point, we're going to need this, even if I haven't explained how it will work yet).

To start, we need two classes: the first will derive from GraphicsDeviceControl, and the second will be a modified version of DrawableGameComponent.

Class	Description
ViewControl<TComponent>	Derives from GraphicsDeviceControl, the control from the sample I mentioned earlier. It instantiates TComponent, which must implement IComponent, IDrawable, and IGameComponent. This control's Draw method will clear the device and invoke Draw on the TComponent instance. ViewControl<> is intended to provide the design-time view for TComponent, so it will also include logic to draw at a fixed timestep so that it doesn't monopolize the IDE's CPU usage.
ViewComponent	A base implementation of IComponent, IDrawable, and IGameComponent. It is very similar to DrawableGameComponent from the XNA Framework, but differs in that it doesn't depend on a Game class being passed to its constructor.

To create a specific designable component, I'll need to introduce more classes. However, each specific designable component can re-use these same base classes. We'll look at examples another time.

The Code

I put the code files below on my skydrive, with links below.

Some of the code files are copied or derived from samples that were made available under the Microsoft Permissive License (Ms-PL). In accordance with the license, my derivative source can only be made available under the same license. Be sure to read it before looking at any of the code files!

For your convenience, I'll note the source of the original code file and a summary of the changes I've made (at least those I remember).

File	Description
GraphicsDeviceService.cs	Originally from the WinForms sample. There were two Interlocked references in this class that worried me. Use of Interlocked implies it should be thread-safe - ~~but if that's the case, the sample code contains several bugs! I fixed the race conditions in AddRef/Release just in case, but there are more I didn't fix.~~ [Edit: Oops! It turns out there wasn't a race condition there at all! The class is not intended to be thread-safe in general, except for the particular case of handling a finalizer thread, which it was doing correctly.]
GraphicsDeviceControl.cs	Originally from the WinForms sample. Removed the "if (!DesignMode)" condition from OnCreateControl. The whole purpose of this control is to render our graphics at design-time! :-) Switched to using the .NET Framework's ServiceContainer rather than the one defined in the sample (which does the same thing).
ViewComponent.cs	This is the base class I want to use for my designable objects. It derives from Component to tie into the designer infrastructure. It also implements IDrawable, IGameComponent, and IUpdateable. These interfaces are implemented so that the specific components you create from this base class can be plugged into any XNA Framework game in a standard way. There is an obvious problem with IGameComponent in that its Initialize method doesn't take any arguments. It's nearly useless as an interface without providing an IServiceProvider instance, because for every object implementing it, you need to define some custom mechanism outside of the interface to connect the object to its environment. To work around this problem, ViewComponent uses a ContentManager property named Content. This property must be set before Initialize is called so that the object can query its environment through the ContentManager's ServiceProvider property. The rest of the events, properties, and methods are implemented as simply as they can be. Attributes are used to provide standard design-time metadata.
ViewControl.cs	This is the control that will draw our components at design-time. It has to serve about the same purpose as the Game class in a game program, which is to provide a graphics device and other services, and to invoke the XNA Framework interface methods at the appropriate time. My view control is quite simple at the moment (it will evolve in the next post). It uses a Stopwatch instance to invalidate the control every 16 milliseconds (max). The Draw method is then overridden to clear the graphics device and draw the ViewComponent specified as the generic type argument. Although I said that the ViewControl is supposed to replace the Game, you might have noticed that this class doesn't actually invoke Initialize or Update on the ViewComponent. That's partly because the decision to invoke Update will depend on the specific ViewComponent instance, so it should be implemented in the specific class that derives from ViewControl<T>. Another reason is because we haven't looked at how to create a ContentManager that can be used at design-time. Invoking Initialize without a ContentManager will not succeed if the ViewComponent needs to load any content.

Next Steps

We've gathered up the primary ingredients, but it's pretty clear we can't just throw them in a bowl and set the mixer on high. We have a ViewControl class that is supposed to draw the ViewComponent, but we don't have a way to get the user experience we need. What we want is to be able to add types in a project that derive from a specific ViewComponent, and have that show up in the designer when you double-click the file.

So, for example, let's say we have this specific ViewComponent:

public class MenuScreen : ViewComponent
{
}

We want to be able to define new classes in our projects like this:

public class MenuScreen1 : MenuScreen
{
}

...And then have MenuScreen appear in the designer when the code file is opened in design view.

As I described in a previous post, the designer infrastructure will instantiate the base class of the designable component. We already know that MenuScreen is a ViewComponent, so it relies on its host to provide a graphics device and to tell it when to draw.

To be able to draw the MenuScreen, we need another class:

public class MenuScreenControl : ViewControl<MenuScreen>
{
}

We don't want this control to show up anywhere in the project where MenuScreen1 is defined, but we do want it to be instantiated in the designer in place of MenuScreen. The magic trick to this is customizing MenuScreen's designer serializer.

For detailed information on designer serialization, refer to Designer Serialization Overview.

When you try to open a code file in design view, the designer infrastructure looks at the base type of the class to see if it inherits from Component. If it does, it then looks to see if the class has a designer serializer. If the type doesn't specify one, the serializer is inherited from its base class. By default, every designable component will use the Component's designer serializer. The job of the serializer is to instantiate the component from its serialized state (or to deserialize it).

The designer serialization is based on CodeDom, so the serializer is passed a CodeDom definition of the base class from the code file, and is asked to deserialize it. Naturally, the default serializer simply instantiates the type specified in the CodeTypeDeclaration passed to it.

By providing a custom designer serializer, we can customize the deserialization step. You might have already guessed that by doing this, we can instantiate a MenuScreenControl in place of the MenuScreen component specified in the CodeTypeDeclaration!

Skillful Substitution

Every experienced cook knows how to substitute certain ingredients for others. However, it takes a certain amount of skill and know-how to still end up with a palatable result. (I'm really determined to keep this cooking analogy going...)

In our designer, it's not enough to just instantiate a MenuScreenControl in place of a MenuScreen. When looking at the design surface, it'll be exactly what a user might expect, but as soon as the user tries working with it, the illusion will fall apart! The Properties Window is going to reveal that the class is a MenuScreenControl instance, and it won't have the MenuScreen's properties. It's like we're trying to pass off tofurkey for the real thing at Thanksgiving dinner! Nobody who's ever had real turkey before is going to be fooled!

More design-time tricks are needed, and this time, ICustomTypeDescriptor is our secret ingredient. By implementing ICustomTypeDescriptor on our MenuScreenControl, we can make it appear to be an instance of MenuScreen. We can give it the same type name, the same properties, the same attributes. The best part is that if we do it right, we'll even fool the MenuScreenControl's serializer into generating code for a MenuScreen. That means no more serializer customization!

To pull off the ICustomTypeDescriptor implementation, a few helper classes are needed. They aren't very complicated, but it'll be easier to just show them off with a sample.

Next time, I'll provide a working sample and explain how to set it up properly. Proper set up is essential to avoid common pitfalls in designer debugging. After that, I'll start to introduce some neat feature ideas specifically for XNA Framework projects.

Compelling Design-Time Experiences in an XNA Game Studio-Based Designer

Tue, 27 May 2008 08:16:51 GMT

The other week, I started playing around with building a designer for Game State Management. It wasn't long before I had something working -- mainly because I leveraged a lot of existing code in the .NET Framework. The screen shots I showed previously are the result -- a design surface that can interact with the Toolbox and Properties Window. This is sufficient to quickly add menu items, edit their appearance, and even generate event handlers for input events.

I was pretty excited about it and that's why I posted to my blog. Unfortunately, the MenuScreen and MenuEntry classes in the Game State Management sample weren't intended to be designable. They didn't have many interesting properties or events, so the designer could only save you from writing a couple lines of code before you had to drop back to source view and type the rest of your program with a keyboard. Gross! ;-P

Last week, I thought about how I often navigate menu screens in games -- selecting a menu item to activate another menu screen, then canceling back to the previous screen, and so forth. To build a navigation system without writing any code, I needed a way to specify what the next screen from within the designer.

What I came up with was a property of type System.Type, which could only be set to a type that derives from GameScreen (the base class for all screens). I implemented a navigation item that, when selected, would activate a new instance of the specified GameScreen type and begin a transition to it. That was pretty easy, except for the idea of someone trying to edit the System.Type property in the Properties Window.

You can customize the design-time behavior of properties by using a TypeConverter, that you can associate with the property by using a TypeConverterAttribute. My custom TypeConverter class uses ITypeDiscoveryService to enumerate all the available GameScreen types in the project and list them in a combobox for easy selection. This new ability to select a screen type in the designer makes it possible to build fancy menus with pop-ups and structured navigation without writing any code. After that, it was a snap to add another navigation item that could both specify the next screen, as well as a second screen to animate during lengthy, asynchronous content loads.

More recently, I thought about how I'd like to customize the appearance of a menu. I'd like to do things like customize the menu's font, or create background screens by selecting textures. I actually would like to be able to create a whole 2D scene out of sprites on non-menu screens, or to display sprites when menu items are activated... But first things first.

A compelling design-time experience for any of this would require the designer to know about the content built by a project. If the menu had a Font property, you'd want the Properties Window to let you choose from a list of SpriteFont items in your project. Then, for a really good design-time experience, you'd want the designer to actually use that SpriteFont when rendering the design surface.

The way I picture that working would be to have a string property for the Font, which specifies the asset name of the SpriteFont. The TypeConverter for this property would enumerate the SpriteFont items from the project, and then the menu would load the asset by name during initialization.

The hard part, unfortunately, is figuring out what SpriteFonts are available in the project at design time.

Tonight, I believe I've solve this problem.

This figure shows a SpriteFont property added to the MenuScreen which lists available SpriteFonts from the content project at design-time. It doesn't yet use that font for rendering the design surface, but that's the next logical step.

Writing a TypeConverter to be aware of the content items was tricky and required very specific domain knowledge of Visual Studio and the managed designer infrastructure, but didn't take a lot of code. I'm still implementing everything in Visual C# Express 2005, and am able to run it and debug it without installing any packages or add-ins into the IDE. I also do not have the VS SDK installed on my laptop. To be honest, I'm a bit surprised at how much you can do without the VS SDK!

Being able to enumerate content from within the designer opens the door to all kinds of interesting scenarios! I'm looking forward to thinking about it some more! (I'm always looking forward to having free time!) :-)

Game State Management for N00bs Like Me

Wed, 14 May 2008 09:01:53 GMT

Last week, I finished writing a design document that I'd been working on for about a month. The design review meeting seemed to go well -- at least, I think it did. There were a lot of nodding heads around the room as I presented my design, and I like to think they were nodding in approval. The alternative is that they were nodding off to sleep, but I'm going to assume that wasn't it. :-)

Anyway, after so long working on the same thing, I decided to take a look at something new and different this past weekend. I installed XNA Game Studio 2.0 and VC# 2005 Express Edition on my laptop at home and started to poke around at some samples. I downloaded Nazeeh's Game State Management project template -- something that I consider to be a terrific example of what a starter kit should really be -- and created a project from it.

For those of you who are not familiar with this template, I'll briefly describe it. It creates a project for a game that has a couple menu screens, and an animated loading screen to entertain people while larger screens (aka, game levels) load asynchronously in the background. It is a slick starting point for just about any game.

I ran the project and put breakpoints in a few places to see how things were being invoked to get a better understanding of the code. Then I modified a few things and found it was reasonably easy to make changes and customize the screens.

For those of you who don't know me, my background is in tools. I make the programs that make it easier to develop games with the XNA Framework, but I don't work on the XNA Framework libraries, and I hardly know anything about game programming. So when I looked at the sample code and saw how easy it was to customize the game state, the first thing I thought of was, "That's pretty cool -- but I can make this easier!"

The funny thing about things being easy is that they are usually easy to automate. Building menus, changing properties, handling input events... Hmm, where have I seen that before?

Instead of playing around with XNA Game Studio to finally learn about game programming, I decided to build a designer for Game State Management! :-)

Tonight, I have a working menu designer. I used the WinFormsGraphicsDevice sample to create a design surface that actually draws the menu screen as menu items are added to it, and updates in real-time as properties are edited. To design a menu, I just need to declare a class that derives from my MenuScreen type, then double-click on the code file, and up pops the designer!

I only have two types of menu items to play with at the moment -- a counter and a toggle. There is a lot of work to do before it would be suitable for general use, but I'm excited about the possibilities. The samples provided a big head-start!

Here's a series of screen shots to show you what I'm talking about.

Figure 1 - Shows the code required to get started (an obvious template candidate). The context menu provides a "View Designer" command to open the designer. Double-clicking the code file in Solution Explorer works just as well.

Figure 2 - The initial design view. This is an XNA GraphicsDevice cleared to CornflowerBlue and rendering a menu with no items.

Figure 3 - Shows the menu after editing the Title property, then adding a ToggleMenuItem and editing its label and name.

Figure 4 - Back to code view to see what the designer generated.

It might not look like much today, but it kept me busy for the past four evenings and was kind of fun! My goal really is to make it easier to get going right away. When I've worked through all the kinks enough to share the designer, I'll blog about how the designer works.

Now it's time for bed!

Game Studio and Visual Studio 2008

Fri, 09 May 2008 07:11:26 GMT

Last December, we released XNA Game Studio 2.0 with support for Visual Studio 2005. This was a big step up from having Visual C# Express support only -- but since it was hot on the heels of the Visual Studio 2008 release, some people were still disappointed. People were excited to get VS 2008, and they were excited to get XGS 2.0 -- but they wouldn't work together!

In and around Microsoft, we have a pretty big community of XGS enthusiasts. Some of them have backgrounds in tools development, including Visual Studio extensibility. Those people knew that the extensibility model for VS 2008 was completely backwards-compatible with VS 2005 (or at least it is advertised to be). So why couldn't XGS 2.0 install into VS 2008?

There were inevitable questions about whether XGS 2.0 could be made to work in VS 2008. Not the naive questions about whether you could compile code against the XNA Framework -- but whether you could get the project system to install into it, use the Content Pipeline, and debug Xbox 360 games. In January, we gave it a shot and it didn't work. It turned out there was a backwards-compatibility bug in VS 2008 that prevented content projects from loading into the IDE. It was a tiny bug with a trivial fix, but one that had to be made by in Visual Studio itself.

As a result of finding this bug, word got out that XGS 2.0 didn't support VS 2008 because it was blocked by a compatibility issue that will be fixed in VS 2008 SP1. When we released our CTP this week, someone asked me how we did it -- because weren't we blocked by the same bug that blocked XGS 2.0?

I'd like to set the record straight on that, because we were never blocked by a compatibility issue.

The incompatibility makes for a convenient excuse, but it’s not the reason we didn’t support VS 2008 in XGS 2.0. Our test team was overburdened even as it was for the XGS 2.0 release. There was absolutely no way we could have delivered support for two versions of VS, even if we’d wanted to. We knew that from the beginning, and originally JoeN and I pushed to make the one version be VS 2008. In the end, our leadership vetoed our proposal and chose VS 2005. That decision was made around April -- eight months before the release of XGS 2.0!

We put our heads down and committed to the task at hand -- shipping on VS 2005.

It wasn't until after VS 2008 had shipped and after XGS 2.0 had shipped that we finally looked at VS 2008. We found and identified the compatibility bug within an hour of getting the XGS 2.0 bits installed into VS 2008. So to be completely honest, if we’d had any intention of supporting VS 2008, we would have easily caught this bug before the Orcas release. Its impact on our projects was obvious, and the fix is trivial. If we’d even bothered to try our stuff in VS 2008 before it shipped, that bug would no longer exist.

Letting people believe that a bug is the reason we don't support VS 2008 is like saying, “Hey, it wasn't not our fault – blame the VS team!” But in fact it is entirely our own responsibility. Whether everyone understands it or not, we decided not to support VS 2008.

I feel pretty strongly now that we made the right choice -- even though I was opposed to it at the time of the decision. If you don't agree, I happen to have good news for you... We're supporting VS 2008 in XGS 3.0!

The XGS 3.0 CTP was released this week to preview our addition of support for Zune, and the CTP targets VS 2008! With this release, you can develop games for Zune from either VS 2008 Standard (or higher) or VC# 2008 Express Edition!

Extending VS 2005 to Improve Cross-Platform Development

Sun, 06 Apr 2008 22:51:16 GMT

Last time I wrote, I had an idea to create an add-in to simplify the view of the solution when developing cross-platform games in XNA Game Studio 2.0. I spent an evening messing with automatically creating and hiding solution folders, but quickly came to the conclusion that simplifying the view was going to be harder than I thought. I've put it aside for a while, and started on something else...

I wrote an add-in that detects when you add a new file to a code project, and then adds that same file to its cross-platform counterpart. Likewise, the add-in also handles renaming files. In this post, I'm going to discuss how I did it, and what its limitations are. If you don't care about the details, but you want to try the add-in, you can skip directly to the download after considering the disclaimer at the end of this post (click to see my Add-Ins).

Detecting Cross-Platform Projects

In XGS 2.0, there is an association between projects created from the "Create Copy of Project..." command and the original. Unfortunately, we didn't expose that association to the automation model, so you can't detect it in macros or add-ins. However, project copies share the same source code. For the vast majority of games, that means cross-platform projects have the same GuidAttribute, defined in the shared AssemblyInfo.cs file. The GUID specified in this attribute is accessible to the automation model, and so it's possible to identify project pairs in a macro by enumerating all projects in a solution and looking for any with a matching assembly GUID.

Handling ProjectEvents.ItemAdded

One thing that gave me trouble was adding empty folders to the project. The code I used for files worked well for folders created in the project root directory, but had strange side-effects when new folders are created under existing folders. In the end, I decided to skip empty folders altogether. There doesn't seem to be any real drawback to this, because empty folders aren't really interesting to a project in the first place. If you later add a file to the empty folder, the paired project will get the new file in the right place, including any folders.

I was actually surprised at how well the handler worked! It magically handles multi-file dependent items like UserControls and Components. (Not that you will want to add those to your Xbox 360 projects, but I was still surprised they preserve the dependency!) Likewise, I was pleased to see that including an entire folder with multiple files into a project was handled correctly. Not bad for a couple hours of absent-minded coding while watching TV!

Handling ProjectEvents.ItemRenamed

Handling the item renamed event was a bit trickier than I first imagined. The event handler receives a reference to the item that was renamed, as well as the item's old name. To rename the item in another project, you can use the item reference to get the full path, then use the old name (not a full path) to recreate the item's old full path. Then you can search for the old item in other projects, remove it, and add the new item (re-using the item added event handler).

Unlike the item added event, the item renamed event does not fire for folder items. Instead, you get the event for any file items under that folder. This is a problem, because you can't reconstruct the old path name from the information given to the event handler. In such a case, the new file name and the old file name are the same, and the old path isn't specified.

To handle folder renaming as well as possible, my add-in will add all the files from under the new path to the cross-platform projects. The old items will still be there, but the files they reference no longer exist. When you later try to build the project, those files will be unresolved and will give you errors. To fix this, just delete the items from your project.

Installing the Add-In

You can download and install the add-in from my XNA Game Studio 2.0\Add-Ins folder. For now there is only one add-in there, but I might eventually add more. The one described in this post is called RighteousTool.Xgs.2.0.AddIns.ProjectSync.vsi.

Be advised that Visual C# 2005 Express Edition does not support add-ins or macros. You'll need to have Visual Studio 2005 in order to install it.

Disclaimer

The add-in referenced by this post is provided by the author as-is and without warranty, either express or implied. Downloading, installing, and using the add-in must be done at your own risk.

Dreaming of a Cross-Platform Utopia

Sat, 29 Mar 2008 03:13:05 GMT

My wife has been sick the whole week, and this morning I woke up with watery eyes and clogged sinuses. I went to work anyway, though, because when I close my office door, I can sometimes go a whole day without talking to anybody. So I went to work and started to work on getting the cross-platform project command to show up in the right place for Zune projects. I could feel the pressure building in my head. My ears popped, and I started to feel like I was underwater. This feeling was very distracting, and my mind wandered... It was then I started to think about Solution Folders (yes, even my daydreams are about Visual Studio extensibility)!

Before I describe my daydream, let me enlighten you about Solution Folders and what they mean to cross-platform development in XNA Game Studio...

Solution Folders provide a convenient way to organize a solution with many projects. If you have a game with several library projects, then going cross-platform doesn't add much overhead in the way of files (one extra file per project), but it can sure make a mess of the Solution Explorer! That's where Solution Folders can shine.

Let's say I have a medium-sized project, with separate libraries for physics, animation, and some kind of high-level game engine. Throw in a couple custom processors, and it might look something like this:

If I run the Create Copy of Project for Xbox 360 command on EpiphanyGame, I'll end up with this:

Woah! Ten projects is starting to look complicated! As you can see, all the new projects are named "Xbox 360 Copy of ...". The prefix has caused all the Xbox 360 projects to be sorted together at the bottom, which is somewhat convenient. But if I wanted to rename them (which I normally do), then I'd lose that organization...

Bleah! If I don't keep these projects collapsed, how am I going to find anything?! :-P

One answer is to create some Solution Folders. If I create one for Windows, one for Xbox 360, and one for Content Pipeline, then I can organize my solution thusly...

The solution folders let me organize the projects by platform, and it's easy to collapse them so the projects for the platform I'm not working on don't get in the way. Okay, now back to my clogged-sinus-induced daydream...

I started to wonder what it would be like if these solution folders were created automatically. Maybe the folder for the platform you're not working on could be collapsed automatically, too. I thought that might be neat. Not too elegant, but maybe it would work for some people. I mean, if the cross-platform copies of the projects could automatically stay in sync with the originals, then you would hardly ever need to switch from one to another. Then I wondered if they could be hidden altogether. I found the answer here. That's cool, I thought, I wonder how we could use that...?

At some point, I realized I'd been staring at the same syntax error in the code window for thirty minutes, and I'd written only about four lines of new code all morning. So I went home.

After I got home, I turned on my trusty laptop and spent ten minutes writing a VS macro. The macro looked at the active solution configuration's platform name, and hid any solution folders that didn't match. The first attempt showed a big flaw in that logic, since the default platform name is "Mixed Platforms". I added a special case for that. Then I added another special case to ignore any solution folder that wasn't a valid platform name. For a mere half-hour of VB programming, it worked pretty good.

I searched around to find an event to trigger the macro when the active configuration changed, but I wasn't able to find one. Unfortunately, that means I'll need to write an add-in to make it work. When I feel a bit better, I think I'll do that!

Feature Requests from Cannibals in the Caribbean

Sun, 09 Mar 2008 17:43:46 GMT

I've recently returned from the 3rd Annual Conference for Game Development in Computer Science Education (GDCSE). Oddly enough, I went to this conference primarily for vacation! It sounds a lot less odd when you realize that the conference was held on a cruise ship floating around the Caribbean! I really enjoyed it, even though I wasn't able to use my laptop while snorkeling... ;-)

Although I primarily focused on enjoying the beautiful weather and luxurious surroundings with my wife, I did mingle with the conference attendees during dinner and other social events. I was really surprised at how many conference attendees were already using the XNA Framework and XNA Game Studio in their schools. When I asked for feedback, most people said that our recent announcements for v3.0 addressed their primary asks. In particular, the ability to publish games. They see it as a great way to motivate students to complete course projects!

One evening, I met three guys from Cannibal Game Studios. Their company makes a game engine that they license to schools for educational purposes. They described their primary goal as ease-of-use, to maximize productivity. They said that the XNA Framework and XNA Game Studio was a natural fit (an earlier version of their engine was built on Managed DirectX).

The guys from Cannibal Game Studios took advantage of the opportunity to give me product feedback. There were two main feature requests/criticisms that they made:

Configure a single asset in the Content project to be processed more than once by the Content Pipeline.
Use a single project to handle multiple platforms.

This is really great feedback! Unfortunately, I'm never allowed to promise anything, no matter how much I want to do it. I think they thought I was not really interested. :-(

Well, I actually think the first feature is really compelling! The second, unfortunately, probably isn't going to happen very soon.

Initially, I asked them to elaborate on why they'd want to process an asset more than once. They used COLLADA files as an example. In COLLADA files, there can be several kinds of data, like geometry, animation, and physics. In a lot of games or game engines, it makes sense to store the different kinds of data in different objects. Likewise, when processing the data, it makes sense to process geometry, animation, and physics separately. The XNA Game Studio Content Pipeline makes this hard because, for a single COLLADA file, you have to import everything all at once! You can process the data separately, but before you can do that, you need to aggregate your various data processors by writing a mega-processor that splits up the data and farms out the work to more targeted processors. This is something they feel should be handled by the Content Pipeline. Or, at least it should be way easier. I completely agree! This is definitely going on the long list of features to consider adding in a future version...

The second big thing they wanted is the ability to develop for multiple platforms in a single project. We actually wanted that in XNA Game Studio Express 1.0, and we got as far as implementing it halfway. Then, while planning for version 2.0, we realized that we'd never have enough time to complete it between one version and the next. At least, not without putting a bunch of restrictions on what you can do in an XNA Game project. The problem is that there are things that make sense in a Windows project that don't make sense in an Xbox 360 project. The same goes for Zune projects, for that matter. (Yes, we've had Zune on our minds for quite some time.) When developing for different platforms, the IDE needs to behave differently, and developers may want to work with different kinds of project items. Changing the project system to make all of these features conditional is a great deal of work -- work that we don't need to do if we let each platform have its own project.

That's why we have the multi-project system that I described in several earlier posts. It was a lot easier to develop a system to convert a project from one platform to another. Although this didn't lead to an ideal development experience, it was something we could do in a short amount of time, and it was something we could improve on in subsequent releases.

In the multi-project scenario, I think there are three main difficulties:

Keeping the two projects in synch when adding, renaming, or removing items.
The Solution Explorer makes it look like there are two copies of everything, and it gets hard to manage bigger projects when you see two of everything.
Although I mentioned working with two of everything, we will add Zune support in XGS 3.0, and probably more platforms at some point in the future. The complexity of working with multiple platforms will grow with the number of platforms, forcing you to have three of everything, or four, etc.

To address the first big problem, we're going to look at automatically synchronizing projects that have been created with our cross-platform wizard. I think the default behavior should assume you want the projects as similar as possible, but would give you the option of excluding items from a specific project when it doesn't belong.

To address the second big problem, I've been thinking about customizing the view in the Solution Explorer. When you clone a project, you don't get two copies of everything -- but each file is represented twice in the Solution Explorer. If we were to hide the projects that are inactive, I think the cross-platform development experience would be a lot more like having one project for all platforms. That is, assuming we synchronize them automatically as discussed above.

The third issue is a problem of scalability. It basically means that the first two problems will get worse if we don't address them. However, I think the scalability problem goes away if we can both synchronize the multiple projects automatically, and present a smarter view of the solution.

If you're interested in the XNA Game Studio development experience, send me your feedback. What new feature would you like to see? What are you trying to do that you find difficult? Leave a comment or send me a message. Better yet, file the request on Connect (don't forget to search for an existing request first)!

Keeping Cross-Platform Game Projects Synchronized

Sun, 24 Feb 2008 19:13:15 GMT

In my last post, Introducing Cross-Platform Development with XNA Game Studio 2.0, I showed how a new command in XGS 2.0 will create a copy of your project for Xbox 360 (or Windows, if you start with an Xbox 360 project). I also explained that when you do this, the only new file created is the project file (.csproj), since the files it contains are the same files as the original project (they are shared). The resulting solution has two projects, but on disk there is only one directory and only one copy of each file.

Working with this kind of solution has a few catches. In particular, you have to take care when you manipulate the files that are shared between the projects. That means any time you add, remove, rename, or move files in one project, you'll probably have to do a quick, manual fix-up in the other. The good news is that future versions of XNA Game Studio can make these actions automatic. The bad news is that the current version does not. :-(

Here's a quick-reference chart of file operations to be careful with:

Operation	Problem	Quick Solution
Add new item/folder	File is not added to the other copy of the project.	In Solution Explorer, click and drag the file into the other project.
Remove an item/folder	Item is not removed from the other project. Depending on what you intended, this might be desirable.	If you want to remove it from the other project, just repeat the same command on the other project.
Delete an item/folder	The item will be deleted from disk, even if it is still being used by the other project.	If you don't want to delete the item from both projects, use the Remove command instead.
Rename an item/folder	The other project will be unaware of the rename. When you compile, the old file name will not be found.	Exclude the unresolved item from the other project, then add the renamed item to it.
Move an item/folder	Similar to renaming, the other project will be unaware of the move, and the old item name won't be found.	Exclude the unresolved item from the other project, then add the moved item to it.

Each project maintains a list of its items, both files and folders, in its project file (.csproj). In XGS 2.0, we didn't have enough time to implement automatic support for these scenarios. However, when a project is copied using our wizard, a marker is placed in the project to identify the relationship between the original and its copy. That marker means that a future version of XGS can start handling these things automatically.

Another feature of XNA Game Studio 2.0 is the nested content project. When you create a new game or game library project, it contains a special "Content" folder for your game's digital content. This special folder is not really a folder at all -- it's another project that compiles game assets with the XNA Game Studio Content Pipeline.

When you use the built-in "Create Copy of <Project> for <Other Platform>" command, the new project will contain the very same Content sub-project, much like it contains the very same code files. The cool thing about having both projects share the same Content sub-project is that when you make changes in the Content project, you don't have to synchronize them in the other platform's copy. There isn't another copy of the Content project, so any changes automatically affect both platforms.

The benefit of this behavior becomes more clear as you start to add more and more content to your game. Even medium-sized games can easily grow to have a couple thousand content items, so the less manual synchronization you have to do, the better.

As well, we introduced the ability to configure Processor Parameters on individual content items. For example, there is a parameter to change the scale of your models, and one to set the transparent color of your sprites. Imagine if you had to set these in two places. If you forgot to change it in the second project, then you might end up with strange bugs like a model that is scaled wrong on Xbox 360 but not on Windows. Trying to figure out what went wrong would be a real pain!

One thing you can't do in XGS 2.0 is add a content item to a Content project and have it be platform-specific. Each code project has exactly one nested Content project, and all copies of the same code project share the same Content sub-project. In the future, we want to add the ability to add additional Content sub-projects to a game, and let you decide whether to share them or not (again, like code files). That way, you'd be able to share the majority of your content from Xbox 360 and Windows, but you'd also be able to add an additional, non-shared project to each of the code projects for platform-specific assets. Say, like title screens with different logos, or different input options for console/PC.

For the most part, it's no big deal if you just add everything to both projects, but if you have a lot of content that is platform-specific, then it could be important to you to reduce the overall size of the game.

Making Improvements in XNA Game Studio 3.0

In XGS 3.0, we'll be adding support for Zune. I suspect that means more people will start working cross-platform, and it also means you may start creating three copies of the same project instead of just two. With three copies of each project, manual synchronization will make working cross-platform a lot more tedious.

Right now, the XNA Community Game Platform team is prioritizing features for the XGS 3.0 and planning out who will work on what. If you're interested in doing cross-platform development, and you want us to invest time in making the experience better, please post a comment here, or start a thread in the creators.xna.com forums, or send us feedback to ask us to make cross-platform development easier. The more demand there is, the more likely we are to assign resources to fix the problems.

Be sure to let us know what features you want the most -- which ones do you currently have problems with, and which new features would you like to see added.

Introducing Cross-Platform Development with XNA Game Studio 2.0

Fri, 22 Feb 2008 06:31:17 GMT

XNA Game Studio (XGS) provides development tools for building games with C#, and the XNA Framework provides a platform to run them on. One really cool feature of the XNA Framework is that it is available for both Windows and Xbox 360. Source code written against the XNA Framework is portable, meaning that the same source code can be compiled for either Windows or Xbox 360. Unfortunately, standard C# projects in Visual Studio don't make it easy for one project to target multiple platforms, so XGS 2.0 introduced a couple new features to smooth things over.

This article is an introduction to cross-platform programming in XGS 2.0. In future versions of XGS, we'll be adding support for more platforms (eg, Zune in XGS 3.0!). That will make it even more important to understand cross-platform development.

First off, most of the XNA Framework API is cross-platform (something like 99%). That means you almost don't have to do anything to make your source code portable to either Windows or Xbox 360. Whichever platform you started writing your game for, basically the exact same source code can be used for the other. That's the premise behind the Create Copy of <Project> for <Other Platform> command. This command can be found on the Project menu, and also the project context menu.

I don't like using "create copy of" as the name of a command, so for the rest of this article, I'm going to call it the Clone Project command.

When you start with a Windows game and clone the project for Xbox 360, the command creates a whole new project and adds it to your solution. The figure below illustrates the outcome.

This view of the solution suggests that there are two copies of everything. That isn't really the case. The Solution Explorer provides a hierarchical view of the solution and its projects. While there are two projects shown, and each has an item called Game1.cs, it is actually the same Game1.cs file in both projects. That is, the one file belongs to two projects.

Ultimately, the entire cloned project is really only one file. No matter how many items you have in your game project, cloning the project will always create exactly one new file. Ever.

At this point you might be wondering why you'd want another project if all the source files are the same anyway. Well, the primary reason is that there are more than just files in the project. Each project has a References node (represented by an expandable gray folder-like icon). If you expand the References node, you'll see the list of assembly references used to build the code in the project. The assemblies referenced are different for the different platforms, and that's the primary thing that distinguishes the output of a Windows project from that of an Xbox 360 project.

Another difference is that the Windows game targets the .NET Framework 2.0, while the Xbox 360 game targets a custom version of the .NET Compact Framework (NetCF) 3.5. For the most part, the NetCF Base Class Library (BCL) is a subset of the .NET Framework BCL. That means the types in the NetCF BCL are almost always exactly the same as what's in the .NET Framework BCL, except when they're not there at all.

For that reason, there are features you can use in a Windows project that you can't use in an Xbox 360 project. As an example, you could add a Web Reference from your Windows game to a web service. There is no support for web services on the Xbox 360, in part because the base classes are missing from the NetCF BCL, and in part because Xbox 360 games aren't allowed to connect to non-Xbox LIVE endpoints.

If you try to clone a Windows project with web references, the files will be removed from the Xbox 360 project. This means your new project won't compile initially, but at least the Error List will tell you where you need to fix up your code. Fixing the code usually means conditionally-compiling the parts that are platform-specific. Xbox 360 projects define the preprocessor symbols XBOX and XBOX360 by default for your cross-platform coding convenience.

One thing to note when editing code in a file shared by two projects is that you'll get Intellisense for the project that opened it. That means if you double-click the file under the Windows project to open it, the editor will give you syntax highlighting and statement completion that matches your Windows project settings. To switch the Intellisense to match your Xbox 360 project settings, including syntax highlighting on conditionally-compiled blocks of code, just close the file and reopen it from under the Xbox 360 project.

Tip: Since the classes available for Xbox 360 projects are generally a subset of the ones available for Windows, you're less likely to write non-portable code if you always open the files from the Xbox 360 project.

Another feature that isn't supported in Xbox 360 projects is Windows Forms. The System.Windows.Forms.dll assembly isn't part of the BCL for Xbox 360, so you can't use Forms in your Xbox 360 games. However, there are times when you might want to use Windows Forms in a Windows version of your game. As an example, you might want a custom form to display an error message if someone tries to run your game on a Windows machine without adequate shader support.

For Forms and Controls, you can't just conditionally-compile the entire class because of the code-behind file (a designer-generated file). Windows Forms use partial classes and tool-generated code that you can't edit by hand. So to remove these types from your Xbox 360 game project, you need to Remove the code files from your Xbox 360 project (use the Remove command, not Delete), and then conditionally-compile any code that references the type.

Tip: Deleting files is dangerous! Remember that even if the file belongs to more than one project, there is only one physical file. If you Delete it, it will be unavailable to all projects! By contrast, the Remove command will remove a file from the project without deleting it.

Well, that's enough to get you started. Next time, I'll write about adding new files, renaming files, and working with Content projects.

Cheers!

Shameless Self-Promotion

Wed, 06 Feb 2008 06:07:52 GMT

My coworker, Nazeeh, writes a much slicker blog than I do. He's started a series of interviews with the XNA Community Game Platform team (the team that makes XNA Game Studio and the XNA Framework). It just so happens that I'm on that team, and last week, Nazeeh focused his attention on me! Check it out!

http://www.nazspace.com/wp/2008/02/03/team-interview-stephen-styrchak/

Debugging Custom Content Pipeline Extensions (Part 3)

Fri, 25 Jan 2008 09:57:19 GMT

If you've ever used Debug.Launch() to debug a custom Content Pipeline extension in XNA Game Studio 2.0, this post is for you. If you've ever wanted to just press F5 and be able to debug your content builds, you're in luck! I've finished a project template that allows integrated debugging of the Content Pipeline from Visual Studio or Visual C# Express.

I've uploaded the template to my SkyDrive. Click the download link to get your own copy!

Download debugtemplate.vsi

The file is a Visual Studio Installer (.vsi) file, and it will install the template into your XNA Game Studio 2.0 project template folder as long as you already have XGS 2.0 installed. Please note that I did not sign the file, so you will get a warning when you install it. Install it at your own risk.

Once you create a project from the template, a readme file will open up to explain how to use it. Let me know what you think. If it's useful, maybe it'll get rolled into the next version of XGS.

Debugging Custom Content Pipeline Extensions (Part 2)

Wed, 23 Jan 2008 07:08:38 GMT

In my previous post, I described what happens when you press F5 to debug a game project, and explained why you can't debug your Content Pipeline Extension Library projects that way. However, I also described many ways in which F5 actions can be customized. By tweaking the settings in just the right ways, it turns out that you can debug your Content Pipeline Extension Library projects in the IDE. Here's how you do it...

XNA Game Studio (XGS) 2.0 projects use a nested Content project to build content. If you look at your project directory in Explorer, you'll find a file called content.contentproj. That's the MSBuild project that builds all your content.

If you want to debug custom components that you use to extend the Content Pipeline, it's as easy as debugging msbuild.exe while it builds the content.contentproj project file. In Visual Studio 2005 (VS), you can accomplish this by changing your Startup Project to launch an external program (msbuild.exe) and pass it the path to your content.contentproj file as a command-line argument (this is described in the XGS documentation, near the bottom of this page on How To: Write a Custom Importer and Processor). The problem, however, is that it's still difficult to set up, and the options described aren't available in Visual C# 2005 Express Edition (VCSExpress).

It turns out that although there is no user interface to change the startup program in VCSExpress, the ability to launch and debug another application is still there. If you want to have a C# Startup Project launch msbuild.exe when you start debugging, all you need to do is add the following XML to its .csproj file (after the <Import> element near the bottom is a good spot).

<PropertyGroup>
<StartAction>Program</StartAction>
<StartProgram>$(MSBuildBinPath)\msbuild.exe</StartProgram>
<StartWorkingDirectory>$(ProjectDir)</StartWorkingDirectory>
</PropertyGroup>

If you want to debug your Content Pipeline components, then you need to add another property, StartArguments, to specify the .contentproj to build, the platform to build it for (Xbox 360 or Windows), and the configuration to build (Debug or Release).

It can get a bit long, but to do it right, you need something like this...

<StartArguments>"Content\Content.contentproj" /p:Configuration="$(Configuration)" /p:Platform="$(Platform)" /p:XnaPlatform="$(XnaPlatform)" /p:ParentProjectDir="$(ProjectDir)"</StartArguments>

If you add these properties to your game project (or game library project), it will launch and debug msbuild.exe as it builds the project's content using the Content Pipeline. That will let you hit breakpoints in your Content Pipeline Extension Library project after hitting F5.

The caveat to all this is that it's tedious. It's also a bit dangerous to edit the XML project files directly, because if you don't know exactly what you're doing, you can end up with a project that won't load, and no idea how to fix it!

One way to make this super convenient and risk-free would be to have a project template to create projects already configured to debug the Content Pipeline! Well, stay tuned! That will be my next post...

Debugging Custom Content Pipeline Extensions (Part 1)

Sat, 19 Jan 2008 21:36:27 GMT

The XNA Framework Content Pipeline (Content Pipeline) is a customizable tool included in XNA Game Studio (XGS) for preparing digital content to be used in your games. The XNA Team Blog has an entry here that describes the Content Pipeline, and there are several tutorials and samples on the XNA Creators Club Online web site that explain how to extend the Content Pipeline with your own custom content importers and processors. Although it is easy to add custom extensions, many people find it difficult to debug their custom components as they develop them. In this post, I'm going to explain what makes them so hard to debug, and later I'll provide instructions on how to set up your Visual Studio or Visual C# Express development environment to make debugging them as easy as pressing F5.

Warning: This is not a tutorial.

A number of people have asked me why they can't hit breakpoints or stop on exceptions in their Content Pipeline Extension Library projects when they debug a game project that uses it. To me, this is a bit like asking why a car doesn't fly when you drive it to the airport. It's hard to answer in a way that will lead to understanding, because I don't know why anyone would expect such a thing. Even though your trip involves flying, you don't fly during every part of the trip. Maybe it's best to start at the beginning.

The Start Debugging command does a lot of things. In most cases, developers don't need to know or think about what those things are, because the end result is usually what they want: they get to debug their code. When that doesn't happen, it helps to know what is expected before trying to identify what went wrong.

When you press F5 in Visual Studio (the common shortcut for Start Debugging), the following things happen:

The IDE determines whether any files need to be saved, and takes the appropriate action.
The IDE determines which projects to build, as well as which project configuration to build.
The IDE chooses an order in which to build the projects, based on the project dependencies.
The IDE builds each project selected in step 2, individually for its selected configuration, in the order computed in step 3.
The IDE determines which projects to deploy (this applies to Xbox 360 projects, but not Windows projects).
The IDE deploys all projects that were identified in step 5.
The IDE determines which programs to start.
The IDE launches each program identified in step 7, with the debugger attached.

There are a number of ways this can be customized.

Step 1: The default is to save all files, but you can change the behavior in Tools Options.
Step 2: The default is to build all projects with a project configuration that matches the active solution configuration, but this can be customized in many ways.
- Configuration Manager allows you to edit solution configurations, which are lists of projects and configurations to be built when the solution configuration is active.
- There is also a command that will limit the solution build to only the Startup Project and its dependencies.
- There is an option to prompt to build deployable projects that are out of date, but otherwise not selected to be built.
Step 3: Project dependencies are usually determined by project-to-project references, but you can add additional dependencies using the Project Dependencies dialog box. This information is stored in the solution file.
Step 4: See steps 2 and 3.
Step 5: You can customize which projects to deploy by editing solution configurations in Configuration Manager, and by changing the active solution configuration.
Step 6: See step 5.
Step 7: The default is to have only one startup project for a solution, but there is an option to have multiple startup projects in one solution.
- A startup project can be configured to launch its output EXE, if it is an EXE project.
- A startup project can also be configured to launch another application (option not available in VC# Express).
Step 8: The IDE will start all startup projects and attach the debugger to each one so that you debug them all simultaneously. (Many developers do not realize that you can debug more than one application at once with the same IDE.)

Okay, now that I've given a summary of what F5 does, let's study a particular example to see why breakpoints in a Content Pipeline Extension Library project are never hit.

Let's consider the Custom Model Importer Sample from the Creators Club Online web site.

In this sample solution, there are two projects: one Windows Game (2.0) project, called ObjImporterGameWindows, and one Content Pipeline Extension Library (2.0) project, called ObjImporter.

When I load this sample project and press F5, the following things are going to happen:

No files are dirty, so nothing needs to be saved.
The active solution configuration is "Debug|x86", and that solution configuration says that both ObjImporter and ObjImporterGameWindows should be built using their respective "Debug|x86" project configurations.
ObjImporter is determined to build first, since ObjImporterGameWindows has an indirect dependency on it through its nested Content project.
The projects are built:
1. ObjImporter is built for "Debug|x86", producing ObjImporter.dll.
2. ObjImporterGameWindows is built for "Debug|x86"
  1. Before the code is built, ObjImporterGameWindows forces the Content subproject to build.
  2. When the Content subproject builds, the Content Pipeline loads the ObjImporter.dll from step 4.2.1 and uses it to build the Tank.obj model.
  3. After the Content subproject is finished building, the code in ObjImporterGameWindows is built, producing ObjImporterGameWindows.exe.
No projects are deployable.
Deployment is skipped.
ObjImporterGameWindows is the startup project, so ObjImporterGameWindows.exe is that application to start.
The IDE launches ObjImporterGameWindows.exe under the debugger.

Now that we've covered the whole Start Debugging process in detail, it's a lot easier to answer the original question, "Why don't I hit breakpoints in my Content Pipeline Extension Library project when I press F5?"

Answer: Debugging doesn't start until step 8, but the ObjImporter.dll library is loaded up and executed in step 4.

When you start debugging in the IDE, you aren't going to hit breakpoints just because they are set. You will only hit them if you debug a process that loads the corresponding binary, and the debugger can find symbols (.pdb file) that says a loaded binary came from that source file.

In the case of a Windows game, you don't start debugging until after the game EXE has been built. By that time, the Content Pipeline is already done its work. Since the breakpoints correspond to ObjImporter.dll, you won't ever hit them this way.

If you want to debug the ObjImporter.dll as it runs in the Content Pipeline, you need to debug something other than your game project. In my next post, I'll explain how to set up a solution so that F5 will debug the Content Pipeline instead of your game.