Upgrade Guide: XNA Game Studio Express to XNA Game Studio 2.0
XNA Game Studio 2.0 introduces many new features to developers previously working with creating games in XNA Game Studio Express or XNA Game Studio Express 1.0 Refresh. This guide explains the process for making the transition to XNA Game Studio 2.0, and explains common scenarios you may encounter.
For a quick understanding of the new features introduced in XNA Game Studio 2.0, see What's New in This Release.
The upgrade process for an XNA Game Studio Express game consists of two main parts:
- You must first upgrade your game project. This upgrade is necessary in every case, regardless of the complexity or simplicity of the project.
- You may need to modify your game code to work with changes in the XNA Framework.
Changes to deploying and playing your games on Xbox 360 using XNA Game Studio Connect may also affect your experience.
Upgrading Your Project
Projects that were created in XNA Game Studio Express or XNA Game Studio Express 1.0 Refresh must be upgraded to work with XNA Game Studio 2.0. You have a choice in how you want to upgrade your project:
- You may use the Project Upgrade Wizard for XNA Game Studio 2.0, available on the XNA Creators Club Online Web site, to upgrade your project to the new XNA Game Studio 2.0 format.
- You may manually upgrade your project by creating a new project in XNA Game Studio 2.0. This is more time-consuming, especially for larger projects.
Option 1: Upgrade with Project Upgrade Wizard for XNA Game Studio 2.0
The Project Upgrade Wizard for XNA Game Studio 2.0 is available for download on the XNA Creators Club Online Web site. Instructions are included that will take you through the upgrade process.
Option 2: Manual Upgrade
Use the following procedure to upgrade your project without using the Project Upgrade Wizard.
- Create a new game project.
- Add all code files and other source files that are not built as content to the new project.
- Add all files that are built as content to the nested content project associated with the new project.
- Update the properties on the new project itself so that they match your original project—for example, Name, Description, and any special build or debug configurations.
- Update the properties on the files within the project so that they match those in your original project. Updating the properties is especially important for content files.
- If your game includes multiple game projects or game-library projects, repeat the preceding steps for each project to add them to the Visual Studio 2005 Solution for the game.
If your game uses a Content Pipeline extension, you can add that project directly to the Solution.
- Update the project for the Content Pipeline extension so it references the XNA Framework 2.0 assemblies.
- Use the References node in the nested content project to reference the Content Pipeline extension.
- Set any necessary references between the projects within the solution.
After Upgrading Your Project
Build the solution to test for any errors due to changes in the XNA Framework 2.0 assemblies or project configuration issues.
- Note that your content now builds to a subdirectory that is called Content by default; you can change this name by setting the Content Root Directory property on the content project node.
|If you have both Windows and Xbox 360 versions of your game, you should upgrade one version of the game using the preceding steps, then use the Cross-Platform Game Project Converter.|
Modifying Your Code
Once your have built your upgraded project, you may encounter build errors due to changes in the XNA Framework.
If you have errors, see XNA Framework Changes in XNA Game Studio 2.0 for information on how to modify your code appropriately. The following section lists some of the common XNA Framework scenarios you may encounter after upgrading your project.
Common Code Modification Scenarios
The following sections contain a variety of scenarios you may encounter when reviewing your code after a project upgrade.
Application Model Changes
XNA Game Studio 2.0 introduces changes into the Application Model that affect the Game class. These changes are visible in the template code inserted into the Game1.cs file when a new project is created in XNA Game Studio 2.0.
Most notably, LoadGraphicsContent and UnloadGraphicsContent have been deprecated, and are replaced by LoadContent and UnloadContent. The deprecated functions are still called in XNA Game Studio 2.0 and therefore will not keep your game from loading content, but these calls may be removed in a later version of XNA Game Studio, so it is recommended that you change your method signatures for LoadGraphicsContent and UnloadGraphicsContent to LoadContent and UnloadContent.
Next, the Game class now provides the Content property, which returns a ContentManager that can be used to load content into the game. This means you no longer need to instantiate your own ContentManager as you did in XNA Game Studio Express, though it will still work.
Finally, the Game class now provides the GraphicsDevice property, which allows you to access the GraphicsDevice associated with the Game object. This, like the previous change, is merely for ease of use and does not require that you change your code.
The largest impact to the XNA Framework will be felt in the Microsoft.Xna.Framework.Graphics namespace. Three particular scenarios exist where you may need to change your code: use of the ResourceUsage enumeration, use of render targets, and use of dynamic vertex and index buffers.
If you are using classes that held a ResourceUsage value, you will encounter build breaks. See XNA Framework Changes in XNA Game Studio 2.0, Graphics namespace, for information on which new value type you should use for each class.
Several changes have been made to the effect and render target functionality in XNA Game Studio 2.0. You will see first that references to ResourceManagementMode in the RenderTarget class no longer resolve, and the Effect.Lost and Effect.Reset events are no longer available. Resource management of effects and render targets is now resolved automatically by the XNA Framework. Remove any event handlers that hook Effect.Lost and Effect.Reset, and remove references to ResourceManagementMode.
Next, render targets had differing persistence behavior between Windows and Xbox 360 in XNA Game Studio Express. Windows would persist data in a render target frame-to-frame (unless multisampling was enabled), but Xbox 360 would discard it. You can now unify the behavior between platforms by setting the RenderTarget.RenderTargetUsage property. The property is set to PreserveContents by default.
Last, render targets now use a ResolveTexture2D class to hold their texture data. It behaves much like a standard Texture2D object but is optimized for holding resolved render target data. You must now instantiate this class for use with the GraphicsDevice.ResolveBackBuffer method if you wish to resolve the contents of the back buffer
See Render Targets for more information.
Dynamic Vertex and Index Buffers
If your XNA Game Studio Express game used vertex and index buffers dynamically—that is, if you were writing to VertexBuffer and IndexBuffer objects continuously such as in the case of dynamic terrain generation or particle systems, you are familiar with the VertexBuffer.SetData method. Calls to this method will cause an error when built. This is due to the signature of the method being changed to no longer take a SetDataOptions parameter.
Previously, SetDataOptions was used to prepare a vertex or index buffer to be used dynamically. In XNA Game Studio 2.0, dynamic vertex and index buffers have their own classes: DynamicVertexBuffer and DynamicIndexBuffer. To use dynamic vertex and index buffers, instantiate these classes rather than using the standard VertexBuffer and IndexBuffer classes. Much of the intialization and settings work necessary to set up a dynamic buffer is handled automatically with this new class.
Since the buffers are dynamic, the XNA Framework cannot handle automatically reloading content in the case of a device reset. When you create DynamicVertexBuffer and DynamicIndexBuffer objects, you must hook the DynamicVertexBuffer.ContentLost and the DynamicIndexBuffer.ContentLost events, and respond to them by reloading content into the buffers yourself.
XNA Game Studio 2.0 introduced changes into the Microsoft.Xna.Framework.Storage namespace. First, if you were writing data to the title location for your game, you will have to change to write to user storage. To do this, see the Storage Overview topic, and How To: Get a StorageDevice Asynchronously.
When you write to user storage, you will need to use the Guide features to allow the user to select where they would like to store their data. Previously, it was possible to synchronously call up the Guide - this would halt your game until the Guide was available. This is no longer allowed in XNA Game Studio 2.0.
You must now call up the Guide asynchronously, thus allowing your game loop to continue to run. This does not mean you cannot pause your game during time in the Guide, but you can no longer call synchronously and lock the game entirely. To learn how to call up the storage selector asynchronously, see How To: Get a StorageDevice Asynchronously.
Finally, if you already were using the Guide asynchronously, you will find that this functionality has moved out of the Storage namespace, and into Guide.BeginShowStorageDeviceSelector and Guide.EndShowStorageDeviceSelector in the GamerServices namespace.
There are many other changes, including additions to audio and input, as well as the addition of the new Net and GamerServices namespaces to enable multiplayer support over System Link and LIVE. To learn more about these new features, including sample code and tutorials about integrating them into your game, see What's New in This Release.
XNA Game Studio Connect
To deploy and play XNA Game Studio 2.0 games on Xbox 360, you must download XNA Game Studio Connect from Xbox LIVE Marketplace. See Connecting to Your Xbox 360 Console with XNA Game Studio 2.0 for information on downloading XNA Game Studio Connect.
Downloading XNA Game Studio Connect does not overwrite the XNA Game Launcher, which is used to deploy games made in XNA Game Studio Express. Both applications work together on your Xbox 360 console. When browsing your deployed games using XNA Game Studio Connect, you will see any XNA Game Studio Express games you deployed using the XNA Game Launcher. You can play these XNA Game Studio Express games from XNA Game Studio Connect. However, the XNA Game Launcher cannot play XNA Game Studio 2.0 games.
If you play an XNA Game Studio Express game from XNA Game Studio Connect, you will be returned to the XNA Game Launcher, not XNA Game Studio Connect, upon exiting the game. If you wish to then deploy or play an XNA Game Studio 2.0 game, you must exit the XNA Game Launcher and start XNA Game Studio Connect.