Using XNA Game Studio 3.0 to Build Cross-Platform Games

It seems like ages since I blogged about cross-platform game programming in XNA Game Studio 2.0. The good news is that the soon-to-be ubiquitous XNA Game Studio 3.0 includes features that make cross-platform programming easier. The bad news is that there are still a couple tricky areas you should know about so you can deal with them appropriately. I'm going to describe the cross-platform features in Game Studio 3.0, and then provide one or two tips to make it easier to work with.

In general, cross-platform programming is an advanced scenario. In Game Studio, we've tried to make it approachable, but to get the most out of your tools, you have to understand how they work so you can configure them to suit your needs. In Visual Studio, there are literally hundreds of configurable options (although not as many in VC# Express). The defaults are set to work with the most common scenarios only.

Some of the defaults don't seem to work well at all with a typical Game Studio cross-platform solution. You might wonder why the default would be selected so poorly, but try to understand that there are millions of Visual Studio users, and only a small percentage of those are Game Studio users. The defaults are set to appeal to *most* people, and sometimes that means they will not appeal to anyone at all within a specific group. On the plus side, you have the option to change these settings.

Incidentally, Sara Ford has a terrific blog about using Visual Studio. If you're a Visual Studio user, I highly recommend you check out her blog. Even if you're already an expert Visual Studio user, you're likely to learn something new from her posts once in a while.

Porting Your Game Project to Another Platform

The XNA Framework is a cross-platform framework. It provides a common API for programming games on Windows, Xbox 360, and Zune. The frameworks aren't exactly the same on each platform, but they are close enough that porting your game from one platform to another often requires only a recompile.

To recompile the source for another platform, you need another project. The reason for this is because the projects need to reference different assemblies for both the XNA Framework and the underlying .NET Framework (Xbox 360 and Zune use the .NET Compact Framework), and C# projects don't provide support for referencing different assemblies for different platforms.

Since you probably want to re-use all the same source code, and you probably don't want to maintain two copies of it, XNA Game Studio has a feature built-in to accomplish this for you. On the Project menu, there is a command named Create Copy of Project for <platform> where <platform> is one of the other supported XNA Framework platforms.

This command does exactly what it says, but less than it implies. It creates a copy of the project file -- the .csproj file -- with a few tweaks to make it work with the new platform. The file is created in the same directory as the original, so instead of copying all the items in the project, they both share the same items. As a result, the new copy of the project adds only one new file to the solution, even though it looks like it copied all the code files as well.

Since both projects contain the same code files, any changes you make to your code files will affect both projects. If you want to write code specific to one platform, you must use preprocessor pragmas to conditionally-compile your code. In some cases, you may want to eliminate the file from one project entirely. To do that, you must right-click on the item, and then select Exclude From Project.

Warning: Be careful not to delete the file if you want to keep it in the other project! There's only one file, so if you delete it, it will be gone from both projects.

In XNA Game Studio 3.0, certain changes to your projects are automatically synchronized across all copies for other platforms. In particular, whenever you add a new item to one project, that item will automatically be added to all copies of that project. If an item is renamed, the rename is reflected in other copies of that project. If an item is deleted, then it is deleted from all copies of the project.

This automatic synchronization should make cross-platform solutions much easier to maintain. If you happen to add an item to one project that you don't want to be shared in the other copies of the project, use the Exclude From Project command in the other projects, as described above.

Something to note when working with multiple copies of your game is that some settings are specific to the project. If you change a Build Action property, for example, then that change will not be reflected automatically in cross-platform copies. Setting project properties are also project-specific, as are adding assembly references.

A special exception applies when working with content items in cross-platform projects. XNA Game projects support a special nested project type, called a content project. In the default projects, this appears as a special folder in the game project named "Content". When you want to build assets using the Content Pipeline, you have to put the items under this folder -- which is really adding them to a special nested project.

When you create a copy of your game project for another platform, the copy shares code files with the original project instead of duplicating them. The same thing applies to the nested content project; the copy ends up nesting the same content project file, without duplicating it.

Because the nested content project file contains all the Content Pipeline settings, including references to importers and processors, and Processor Parameters set for individual assets, the settings always apply to all copies of a game project. That means when you add an item and change its processor parameters, you never need to make the same change in the other copy of your project.

In some cases, you may find that you want to compile some assets for one copy of your game and not the other. For example, if you have a game ported across Windows and Zune, you may want to use higher-resolution sprites in the Windows version of the game than in the Zune version of the game. Since assets in the shared content project are always built for both game projects, you'll always get both high- and low-resolution images in both copies of the game if you put them in the same content project.

A new feature in XNA Game Studio 3.0 allows you to add new content projects to your games. When you do this, the new content project will automatically be added to all copies of your game, just like adding new code files. Similar to code files, however, you can remove content projects from individual game projects with the Remove command.

By using three different content projects, you can build platform-specific content when you need it, and share it when you don't. The key is really to have one content project that is shared, and one in each game project that isn't (by removing it from the other project so it is no longer shared). After setting the Content Root Directory property on the content projects, you can ensure that the assets are built to the same location in either version of the game - meaning your content loading code doesn't need to be platform-specific. For example, you could have a texture named "ControlsLayout" that displays keyboard control layout on Windows, and Gamepad control layout on Xbox 360. The two different textures are in different projects, but they have the same name and each one builds to the same relative output location when the game projects are built (because of the Content Root Directory property). This means the loading code doesn't need to know which texture it's going to get at runtime.

Working With Multi-Platform Solutions

When you work with more than one platform in a single solution, there are a few default settings that often get in the way. I'm going to explain how several options can be customized to streamline your workflow in cross-platform solutions.

F5 and the Startup Project

The Start Debugging command, whose typical shortcut key is F5, is a complex command. By default, it means, "build every project in the active solution configuration, then deploy every project in the active solution configuration that supports deployment, and then run the startup project under the debugger." Start Without Debugging (CTRL-F5) means the same thing, except that it runs the startup project without the debugger.

The part that trips most people up is that changing the startup project doesn't change which projects are built or deployed. So if you are working in a solution with an Xbox 360 game and a Windows copy of that Xbox 360 game, then by default, F5 will continue to build and deploy the Xbox 360 game even if the Windows copy of the game is the startup project. (Same goes for Zune, but it's easier to just talk about one at a time.)

I say default a lot, because I want to impress upon you that you can change it. :-)

There is an option available to only build the startup project and its dependencies when you run. That way, when you change the startup project from the Xbox 360 copy of the game to the Windows copy of the game, you'll stop deploying the Xbox 360 game on F5. The Build Solution command will still all projects in the active configuration, but F5 will skip the ones you don't need.

Another way to avoid deploying projects when you want to work locally is to change the active solution platform in Configuration Manager. By default, the active solution platform in a multi-platform solution is Mixed Platforms. If you open Configuration Manager, you can see that the Mixed Platforms configuration is set to build and deploy all projects (as indicated by the checkboxes). By changing the active platform, you change the set of projects that will be built and/or deployed when you build the solution.

You can quickly change the active platform using the Solution Platform combobox on the standard toolbar.

Warning: The Startup Project is independent of this setting. So if you change the active solution platform, you should also change the Startup Project to correspond to a project for that platform, and vice versa.

Intellisense and This File is Already Open in Another Project

When working with files that are shared across multiple projects, it's important to recognize that the context under which you open a file is relevant. If you don't already know what I'm talking about, that sentence probably didn't make a lot of sense. What I mean is, when you open a file that belongs to a project, the code editor uses settings in that file's project.

Intellisense and statement completion is provided for assemblies referenced by the project, as well as by other code files in the same project. If you have conditionally-compiled blocks of code, syntax highlighting is provided based on preprocessor symbols defined in the active project configuration.

Now, suppose that you have one file that belongs to two projects that reference different assemblies and which define different preprocessor symbols. Then it makes sense for the code editor to provide its functionality based on the project that opened the file. In other words, if you open a shared file under a Windows game project, the code editor will behave differently than if you opened the same shared file under a Zune copy of the Windows game project. If you try to open the file from the Zune project and it was already opened by the Windows project, then an informative dialog will pop up to tell you that the file is already open under another project.

That dialog isn't giving you a warning; it's just telling you that the editor won't give you the context that you might expect. If you double-clicked on the file under the Zune project, you might not expect to see statement completion for types that are not part of the Zune framework's API.

In many cases, it won't make a difference to you, and you can just dismiss the dialog and continue editing. However, if your statement completion or conditional blocks seem to be off, then you might want to close the editor and re-open the file in the context you intended to be working in.

Summary

Cross-platform programming in XNA Game Studio 3.0 is easier than ever. You can port your game to another platform in a single click, and the projects automatically keep themselves in sync when you add, delete, or rename files.

Working with multi-platform solutions, it's important to recognize which projects are going to build and deploy when you press F5. Although not set by default, the "Only build startup projects and dependencies on Run" option is extremely useful. I recommend you set it.

Code editors provide features based on context from the project. Try to open your files from the project corresponding to the platform you're working on, or the editor may not provide the help you want.