XNA for Silverlight developers: Part 1 - Fundamentals

This article is Part 1 of the series “XNA for Silverlight developers”.

This article is compatible with Windows Phone "Mango". 
Latest update: Aug 1, 2011.

For Silverlight developers who want to delve into XNA, the hard part is not learning the new set of classes in the library, but the fundamental difference in programming style for some parts of XNA compared to Silverlight. Especially when you have no experience in game programming, you might find some things confusing or even illogical. In the first part of this article, I want to give an overview and explanation of the biggest differences. You will run across all these topics again in the following articles in more detail.

Later on, we finally start with some actual code and analyze the structure of an XNA project. We will learn about the concept of content and how to add it to your project. By the end of the article, we will have built a very simple "Hallo World" game that renders some moving content onto the screen. The source code for the sample project can be found at the end of the article.

Some Theory

Event-driven vs. Polling

In Silverlight, when you are interested in any kind of data or information, the common way to get it is to subscribe to some sort of event (I also count callbacks and similar constructs to that). No matter if it is user actions you want to be notified about, the arrival of data from a returning asynchronous operation, or other situations that require transportation of information: the runtime, third party components, or even objects you have written yourself send you a notification whenever the data you have asked for is available. That also works the other way round. If you want to notify someone else that something interesting has happened, for example signal to a UI component that your data has changed, you raise events. We've all gotten used to interfaces like INotifyPropertyChanged, do we?

This picture is quite different in XNA. A lot of work there is done using polling. For example, instead of being notified by an event that the user has touched the screen, you actively keep asking the screen if something interesting happened since your last call. Like on that long trip in the car, when your kids in the back seat keep asking "are we there yet"; with XNA, you are the kids, and you ask 30 times a second.

You may ask yourself why one would voluntarily use polling when there's so much comfort in using events. The answer is simple: to have full control about the processing of that information and data. One drawback of the event-driven model is that events may happen any time. This is a problem in Silverlight applications too, but we have learned to live with it and work around it. For example, let's say you have a button that kicks off a long-running operation. Nobody stops the user from hitting that button twice or three times in a row. If you want to prevent multiple operations from being started, then what you do is ignore subsequent events, or disable the involved UI elements so they do not generate those events anymore. With a polling based model, you simply wouldn't ask anymore. Also, more reasons for and benefits of that approach will become apparent once you learn more details about XNA. Especially user actions could corrupt your data if they happened e.g. between update and drawing operations.

I don't say XNA doesn't have events, and I also don't say XNA doesn't use events. When you create an empty project and inspect the involved classes, as we will in just a few minutes, you'll realize that events are in fact used, for example to cope with system notifications (e.g. when the user has hit a hardware button and your game is suspended or similar things). In a lot of situations, you might want to use events in your own programming logic and game structure too, simply because the alternative often means to clutter your code with loads of flags and statements that check those flags (think complexity of a state machine). I'll try to point out those situations as we go.

Drawing Content (aka "The Groundhog Day Effect")

When you want to make something visible on the screen in Silverlight, you simply add it to the visual tree in a "fire and forget" manner. That means that once added, the runtime will take care of it and draw it for you whenever it is necessary. You don't have to do anything for that, and the element stays visible until you remove it or a parent element from the visual tree (or explicitly set its visibility so it is not drawn, of course).

With XNA, this is very different. A good way is to imagine it as a flip-book. You can draw something nice on the current frame, but as soon as you turn the page to the next frame, you have to start all over again, with a blank piece of paper. In XNA, there is no automatism that tracks and re-draws objects on the screen for you. In every single render frame you have to draw the whole content that should be visible on the screen from scratch, you always start with that "blank piece of paper". In Silverlight there is also a lot of optimization going on to determine which parts of the screen actually need to be re-drawn. You can easily use the EnableRedrawRegions property to turn on a visual demonstration of that concept. In XNA, there's nothing like that. You simply draw the whole screen all the time, 30 times a second (30 is the default target frames per second setting on the Windows Phone platform).

The Game Loop

The central part of each game, the heartbeat if you will, is the game loop. To many modern programmers who have spent a lot of time to adopt the principles of object-oriented programming, having an uber-loop that drives the whole application from a central place seems like an awkward idea. Of course those of you with deeper knowledge or a background of Windows programming know the truth, which manifests itself in what is known as the message pump; but this is way beyond the scope of this article. Let's just agree on the fact that as a Silverlight developer, you won't see anything comparable to the game loop of XNA in your applications, ever. The simplest form of a game loop in pseudo code looks like this:

 while (IsRunning)

 {

   Update();

   Draw();

 }

In fact, this is what actually happens. XNA only adds more functionality to that to make the whole concept more robust (like accommodate for timing and/or performance problems) and to provide the developer with additional information and data. We'll take a closer look at it shortly.

Having such a game loop often requires a different style of thinking in your programming, which is a problem for a lot of developers who start with game programming. As an application developer, you are used to write methods that complete a task by sequentially performing all the required steps. For example, when you want to copy some files, you would create a method that iterates over all the provided file names and call File.Copy() on each one of them. If you follow good practices and want to avoid that these operations freeze your UI, you move them to a background thread, but your code still would execute all the steps sequentially. In XNA, a lot of operations are not performed like that. In each iteration of the game loop, you only perform a tiny step that works towards the final result and then you stop until the next update. In the mentioned sample, that would mean that you would only copy a small part of one file, and then stop and return control to the runtime. In the next iteration, you'd resume your operation, copy another small part, and stop again etc.

Of course you won't find yourself copying a lot of files in XNA. A better example for this approach are animations, something we'll closely look at in a later part of the series. I've often seen that beginners create a "loop within the loop" and try to perform the logic of the whole animation within a single frame – which of course results in no visual effect at all. Instead, you need to learn these "baby steps" that require only tiny progress updates for the current frame, but sum up to the overall result you want to achieve in the long run. An interesting detail is that Silverlight's built-in animation system has to do exactly the same behind the scenes. Of course those details are hidden from the developer and the runtime does all that logic in this case; you only control those animations by simply setting some properties.

Your First XNA Project

After all this theoretical introduction you're probably eager to start with some code, so we'll finally dive into the real stuff now. After you've downloaded and installed the required tools for developing games for Windows Phone 7 (you can find them as web installer here) you can create your first game project in Visual Studio/Game Studio:

As you can see there are only two templates for Windows Phone, one for a game, and a second one for a class library. For now, select the game template, enter a name and hit the OK button. The following screenshot shows the structure of your solution after Visual Studio has prepared everything:

The first thing to note is that actually two projects have been created. The game itself is the first one in solution explorer, but below that there's a second entry for the content project. As you can see the game project references the content project using a "Content Reference". Visual Studio has also added some default references to common assemblies, like parts of the XNA library used for rendering and input in the game project, and various importers in the content project.

The Content Project

A full discussion of the XNA content pipeline is far beyond the scope of this article; however, you need to understand some of the basics and reasons how and why content in XNA games is separated from the actual game. "Content" is everything in your game project that is not executable code. Among game developers, the more common term for this kind of content probably is "assets". Your game assets include all graphics and related things (like textures, but also effects, 3D models and even fonts), audio (music, sound effects) and also other accompanying content, for example level data files or similar.

So instead of adding these assets to your game project, you add them to the content project. Let's just do that and add an existing image. Right-click the content project and select "Add/Existing item...". Browse to some image file on your hard disk and import it. You can also safe the following image file to your hard disk and use it, or download the source code at the end of the article:

For a better understanding of what happens with this imported image, select it and take a look at the properties window of Visual Studio:

Your assets are handled in a two-stage process. First they are read by an importer that knows how to treat that particular input format and transform it into a unified intermediate format. That means that no matter if e.g. your input image is a JPG or PNG, after the import process it will be available in the content pipeline as the same representation for further processing. The second step is a content processor that transforms the imported asset into the final, compiled format that is later used in the game. This separation adds a lot of flexibility to the overall process. For example, a sound file can be both processed into a sound effect as well as a song (we'll learn the difference between those two in a later part). Importing the file always is the same and can be done by the same importer in both cases. However, the final transformation requires two different processors.

For most file types, the required helpers for the content processing are detected automatically, but you can always override these. Of course you can also extend the content pipeline with your own importers and processors, to add the ability to use non-standard formats, or to create custom formats which you can use directly in your game later. We will briefly see how that works in a later part.

Reasons for the Content Pipeline

Why do we have this separation in place for XNA games, when we simply could add the images as resources or content to the game project itself? In fact, even a newly created game project (see above) already has some images added to it for the background and the game thumbnail! The main reason the assets are processed separately is (as often) improved performance. An important detail of the content pipeline is that the assets are imported and transformed at compile time. This means that when you build your solution, all your assets are processed and transformed into managed objects. Loading and handling of these objects at runtime then can be performed very fast, as they will always have the same format. Imagine the game needed to load different image formats at runtime. Not only may importing some formats (that use a more sophisticated compression, for example) be much slower than others, there might also be several sub-formats or encoding differences that add more complexity to the process even when you apparently use the same format for all resources.

Of course another reason is that you have more flexibility what programs you can use to generate your assets. The content pipeline supports the most common formats out of the box; for example, it doesn't matter if your images are BMPs, JPGs, PNGs, TGAs or in DDS format. All of those can be imported, which spares you the manual conversion or looking for suitable exporters for your graphics software. Some of these formats could not be used in the game project natively. The content pipeline also allows to perform additional steps automatically during the import, like creating multiple versions of a texture of different sizes ("mipmaps"), which otherwise you'd also have to do manually in an extra tool.

There have also been discussions about drawbacks of the content pipeline though. For example, by default XNA uses an uncompressed format for textures, which increases the size of your images significantly when the source files actually are compressed images like JPGs or PNG.s In turn, loading times may actually suffer. The texture content processor has the ability to compress images using the DXT format which can be activated in the properties window of an image. But then again this requires that your texture size is a power of two, which might not be the case and can result in additional (manual) work you need to perform to prepare your images, which kind of contradicts the idea of a smooth and comfortable import process.

The Game Project

After you've created the solution, the game project is already fully functional. You can simply hit F5 and it will start running and show an empty screen in cornflower blue. To this end Visual Studio uses the emulator that ships with the developer tools for Windows Phone:

This means the template already initializes everything in a way that there's already some visual experience, and theoretically you could start adding your own content and game logic right away. However, the initialization is not really complete. For example, when you take a closer look at the emulator you will realize that the game (which really only is a blue rectangle at the moment) doesn't occupy the whole screen; there's a black border around it. That is why we should take a look at some of the initialization options before we actually start adding our logic.

An important note on the emulator: The emulator for Windows Phone 7 is great. It's not perfect, has its flaws, is missing some possibilities, and you might see some stuttering with games and similar glitches, but compared to previous emulators for Windows CE/Mobile my experience is that it's much better and faster in most areas, especially at startup and deployment of your projects. And it allows you to test your games easily without access to an actual device. However, please never publish a game to the market place without testing it on a real device first! The emulator actually is faster than real devices, and there are even some special cases with really huge differences. Some of these things will be emulated more accurately in the first major update of the platform ("Mango") and the corresponding development tools, for example the time it takes to check for trial mode. But there will still be huge differences regarding rendering performance even in this updated version, so please take this advice seriously. And of course it's always a good idea to use a real device to make sure your concepts (like input and the intended way of controlling your game) really work and feel right on actual hardware.

The Basic Setup

Take a look at the source code of the Game1.cs file. Each XNA game derives from a built-in Game class that provides much of the required basic logic. One can say that with XNA, Microsoft has managed to neatly hide most of the difficult details required to set up a DirectX based game. When you're using DirectX in C++, or even in former attempts to bring DirectX to the managed world (Managed DirectX), you had and have to care about pesky details like acquiring and resetting lost devices and surfaces and other things, all of which is now handled for you behind the scenes. It really never has been easier to create games using this technology.

When you take a look at the constructor of the class, you see some of the initialization code:

 public Game1()

 {

     graphics = new GraphicsDeviceManager(this);

     Content.RootDirectory = "Content";

     // Frame rate is 30 fps by default for Windows Phone.

     TargetElapsedTime = TimeSpan.FromTicks(333333);            

 }

The graphics device manager does exactly what its name says, it manages the graphics device for you, and allows to manipulate various properties of that device through simple property values and methods. Three things you most likely want to configure here are full-screen mode, the supported screen orientation(s) and resolution.

To support full-screen mode, you only need to set the corresponding property accordingly. The same is true for the supported screen orientations. This is a bit flag enum, which means you can combine multiple values to indicate that your game supports multiple screen orientations. In most cases though, implementing support for different orientations is complex, and sometimes doesn't even work without changing game mechanics, so it's totally valid to only support one orientation.

You should also set the back buffer dimensions, depending on the screen orientation. Think of the back buffer as the canvas you are drawing on; it is a direct representation of the screen, so usually its dimensions will be those of the device screen's native resolution (480x800 in portrait mode, or 800x480 in landscape mode). You can also render your game at smaller resolutions and make use of the built-in hardware scaler to zoom it to full screen size (it does that automatically). This will improve performance dramatically (at the cost of reduced visual quality), but it's usually not necessary, especially for simple games. Note the naming of these properties ("Preferred...") which indicates that your settings will automatically be discarded when you set it to non-supported values (e.g. values larger than what is supported by the device).

 public Game1()

 {

     graphics = new GraphicsDeviceManager(this);

     graphics.IsFullScreen = true;

     graphics.SupportedOrientations = DisplayOrientation.Portrait;

     graphics.PreferredBackBufferWidth = 480;

     graphics.PreferredBackBufferHeight = 800;

     Content.RootDirectory = "Content";

     // Frame rate is 30 fps by default for Windows Phone.

     TargetElapsedTime = TimeSpan.FromTicks(333333);            

 }

The Content property of the game class is a content manager instance that allows you to access the assets you have added in your content project. It's set up for you automatically (you can also use multiple instances of content managers, but in the beginning this will not be necessary), all you have to do is set the RootDirectory property value. You can structure your assets in the content project by creating folders (for example for the different asset types, or to group assets by level or similar). All content however is located below a (virtual) root directory. The name of that root directory is something that you can change in the properties of the content project. By default it is set to "Content" both in the content project and here in the constructor of the game class, so if you just leave it at that it will work without any additional changes.

The last line of code in the constructor indirectly sets the desired frame rate you want to achieve by setting the target elapsed time. This is part of the sophistication I have talked about before, which is added to the game loop by XNA. What you basically say is that your game logic should be updated 30 times a second. XNA will try to adhere to this settings as good as possible. If your game is not very demanding (as in finishing an iteration of the game loop is faster than the target time), it will idle and wait for the next update to be triggered. On the other hand, if your game is complex or poorly optimized, the game loop may fall behind and not be able to provide 30 frames per second. In that case, the game will try to keep up by skipping drawing calls, and let your game logic update multiple times in succession (as drawing is way less important than updating your logic, which may break things if it doesn't happen as expected).

When your update and draw methods are called, XNA will provide you with some values, like the elapsed time since the last call. These values also include a property you can monitor to determine whether the game loop takes too long and XNA needs to skip frames to keep up (GameTime.IsRunningSlowly). You can fine-tune all these settings, but you should just keep them at default values for now.

The Game Methods

The rest of your game class contains the main methods you need to create a full game. The comments that have been added by the project template actually are pretty comprehensive and should give you an idea of the particular details.

• Initialize: Here you can add any initialization logic required by your game which is not related to graphics or your content.
• LoadContent/UnloadContent: The LoadContent method is called whenever it is necessary to load your game assets. In these methods you make use of the content manager provided by your game to load textures, sounds and other required assets which you have added to your content project before. In the UnloadContent counterpart you can do some clean-up if necessary. Please note that the content manager cleans up any content managed through it automatically, so you don't need to take care of that separately.
• Update: This is the place where you update all game logic. For example, it is here where you will take care of user input, performing animations, triggering sounds and handling general things like checking if the player has won or lost the game or updating your AI. By default, this method contains a check for the back button press which per certification requirement needs to exit the game if you're on the main screen.
• Draw: Within this method, you draw all content that should be visible on the screen. This includes not only sprites like the player and enemies, or effects, but also things like background graphics, text, menu or message box overlays and similar things.

Hallo World!

Let's use all we have learned so far to show the single texture we have imported into the content project on the screen. This will conclude our "Hallo World" project.

Loading Content

First of all, we will use the LoadContent method to actually load the texture. To store it permanently, we'll also add a class field for it:

 Texture2D block;

 ...

 protected override void LoadContent()

 {

     // Create a new SpriteBatch, which can be used to draw textures.

     spriteBatch = new SpriteBatch(GraphicsDevice);

     // TODO: use this.Content to load your game content here

     block = Content.Load<Texture2D>("Block");

 }

Simple, is it? You can use the Load method of a content manager to load assets from your compiled content. Simply pass in the name (including the relative path from the root directory, if you've chosen to put your assets into sub folders) and set the required generic type to the type of asset you want to load. In this case, we need to use Texture2D, as we want to load a normal two-dimensional image.

You can also see that in the LoadContent method, a SpriteBatch object is created, something we haven't talked about so far. The sprite batch is a helper class that is used to draw two-dimensional images and text on the screen. As the name implies it does that in a batch, which improves performance a lot. Will see how it works in a moment.

Updating the Logic

But first let's add some movement logic to our Hallo World game to make it a bit more interesting. For this, we use the Update method of the game class:

 Vector2 position;

 double angle;

 ...

 protected override void Update(GameTime gameTime)

 {

     // Allows the game to exit

     if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)

          this.Exit();

     // TODO: Add your update logic here

     // take the screen width

     var screenWidth = graphics.GraphicsDevice.Viewport.Width;

     // calculate the new rotation agle

     angle -= gameTime.ElapsedGameTime.TotalSeconds;

     // update the x and y coordinates

     position.X = (float)(screenWidth / 2.0 - block.Width / 2.0 + 200 * Math.Cos(angle));

     position.Y = (float)(screenWidth / 2.0 - block.Height / 2.0 + 200 * Math.Sin(angle));

     base.Update(gameTime);

 }

Positions are stored as vectors in XNA, which is why we need to add a class field of type Vector2 (a two-dimensional vector) for the position of the sprite. We also store the current rotation angle. In the Update method, we first fetch the actual screen width from the graphics device (more specifically from its view port). This value is identical to the value we have set as preferred back buffer width in the constructor of the game class.

The following lines update the rotation angle depending on the elapsed game time since the last call of the Update method and then calculate the x and y coordinates for a circular motion. This is the moment to remember the "baby steps" philosophy I have talked about in the beginning of the article. The Update method is called 30 times a second, which means that the gameTime.ElapsedGameTime property will be a very small time span (ideally 33.3 milliseconds). We need to adjust the motion values by similar very small values to create a smooth movement that is not too fast. To this end, we make the calculation dependent on that elapsed time value passed into the Update method. You will always see this approach for calculations, and over time you will become used to it. It's pretty easy to create the desired velocity for a movement with this. For example, let's say you want to move an object by 200 pixels a second, then you simply multiply that reference value (200 pixels/second) by the elapsed seconds since the last update (e.g. 0.033 seconds) and get the number of pixels you need to move the object in the current frame (6.67 pixels). In our example, we increase the angle by the elapsed seconds. Since a full rotation requires 2 * PI ~= 6.3 radians, this is the number of seconds the sprite needs to complete a circle.

Tip: It's a great idea to agree on one unit for all these calculations across your whole application. For example, if you use seconds in one part and milliseconds in other parts, things can easily become confusing when you need to connect both parts at a later point. I prefer to use seconds.

Output to the Screen

On to the Draw method! If you look at the draw method, you can see that it contains a single call to GraphicsDevice.Clear(), which takes a color as argument. That is where the cornflower blue comes from. Of course you can change that to anything you like. In addition, add the following code:

 protected override void Draw(GameTime gameTime)

 {

     GraphicsDevice.Clear(Color.DarkGoldenrod);

     // TODO: Add your drawing code here

     spriteBatch.Begin();

     spriteBatch.Draw(block, position, Color.Red);

     spriteBatch.End();

     base.Draw(gameTime);

 }

That is how you use the sprite batch. You tell it to begin a batch, queue up all drawing operations, and in the end call the End() method to have it process all the operations you have just added. For our simple project, we only have one thing to do: draw the block texture. The Draw method of the sprite batch has several overloads that let you resize or rotate the texture that should be drawn. You can also add a tint, which I did by setting the color argument to red. This is especially handy when you have several similar objects in your game that only are different in their color. You can then use a grey scale version of the texture and add the color here.

If you compile and run the project, you shouldn't receive any errors, and the result looks like this:

There you go, your first XNA project. I strongly encourage you to play with the different features we have learned today. Change the supported orientations, the back buffer resolution, the movement of the sprite, and make use of some of the overloads of the sprite batch draw method.

A word on "Mango"

What this article demonstrates stays valid for the first platform update (code name "Mango") without exceptions, if you are creating an XNA game. However, Mango offers new project types that mix XNA and Silverlight in the same application; this feature changes the basic setup and the way the update and draw logic is executed. If you are interested in these new possibilities and how to use them, please read part 12 of this series to learn more about it.

Summary

In this article we've learned some of the major differences in programming style between XNA and Silverlight. We have seen a few of those differences in the sample project, and finished by creating a small game application that already moves some content around the screen. You should also have developed an understanding for the concept of content and how content management in XNA works. You can download the full source code of the sample project here:

This article was quite lengthy and covered a lot of the details we needed to finally get some tangible results; Hopefully it still was an interesting read for you and has whet some appetite for the things that will follow. Now that we have created a basis we can use to build upon, I will try to keep the next parts shorter so they can be digested a bit easier and make more of a lighter read. Feel free to leave any comments and feedback, and of course also suggestions what can be improved or what you want to see in future episodes.

About the Author

Peter Kuhn aka "Mister Goodcat" has been working in the IT industry for more than ten years. After being a project lead and technical director for several years, developing database and device controlling applications in the field of medical software and bioinformatics as well as for knowledge management solutions, he founded his own business in 2010. Starting in 2001 he jumped onto the .NET wagon very early, and has also used Silverlight for business application development since version 2. Today he uses Silverlight, .NET and ASP.NET as his preferred development platforms and offers training and consulting around these technologies and general software design and development process questions.

He created his first game at the age of 11 on the Commodore 64 of his father and has finished several hobby and also commercial game projects since then. His last commercial project was the development of Painkiller:Resurrection, a game published in late 2009, which he supervised and contributed to as technical director in his free time. You can find his tech blog here: http://www.pitorque.de/MisterGoodcat/