One of the new features of XNA 4.0 is the Content Project. Those of us who’ve worked in XNA 3.1 and earlier are familiar with the old Content folder, which was simply a folder inside your game project into which you’d place your raw content and from which your game would load the compiled XNB files. In theory it could be named anything since one of the things you would do in the constructor for your game is specify the name of the Content folder. XNA 4.0 has moved content (i.e. game assets like music, sound effects, sprite images, 3D models, shader effects) into a separate, special type of project called the Content Project.
With the new Content Project as part of a normal XNA Game Solution, its a sure thing that almost every game will be a multi-project solution. First things first, let’s just go over a bit of terminology. If you already know this, great. If not, this might help clear it up. In Visual Studio, there are two container types: solutions and projects. A solution holds one or more projects and can also hold items not specific to any particular project called solution items. I’ve never seen solution items used in XNA projects, (it would require quite a bit of fiddling and futzing without any real benefit from an XNA perspective) so I’d recommend avoiding them when creating XNA games (certainly when starting out). So for our purposes, a solution holds projects. A project holds individual items that make up the components that are put together to make your game. In a basic XNA 4.0 game, you would have two projects: a Content project, and a “Game” project. The Content project, as mentioned above, is where your content goes in order to be processed by the content pipeline and turned into XNB files (efficiently compressed binary files designed to be quickly loaded into their appropriate XNA Framework class by the ContentManager class). The “Game” project is your game itself. It’s where all the magic happens. Of course over time you’ll probably develop one or more “library” projects that contain classes and extension methods you find yourself needed in game after game. You’ll also probably discover that you’re constantly writing the same code and including the same basic assets (e.g. sprite fonts, splash screen) just to get to the “starting point” from which you begin building a unique game. And this is where we get to the purpose of this post.
One of the great features of Visual Studio is the ability to create your own custom templates. This way, if you write a “base” level project that you like, you can turn it into a template and then create new instances of it for as many different projects as you want. Visual Studio includes the ability to export templates automatically (“hooray”), but it can only export a single project or individual items from a project (“boo”). I’m kidding about the “boo” – the ability to take any arbitrary project or even just one or more individual class files (using the “Item Template” option) and just turn it into a template that you can then use again and again is incredible. Besides, if it could export an entire solution as a template, then I wouldn’t be writing this exciting tutorial to tell you how to do it! Yes, that is the goal, and we’re going to do it using the Windows Phone Game State Management sample as a starting point. You will need to agree to the terms of the Microsoft Permissive License, a copy of which can be obtained from the same webpage as the sample, in order to download and use it. It’s up to you whether you agree or not, but if not, then the rest of this will be quite hard to follow along with. I’ll be including some XML in this example. It too is subject to the Microsoft Permissive License and so if you agree to those terms, please continue reading and if not, you should probably stop now.
So first things first, download the sample, unzip it, and load it up in Visual Studio. For reference, this is all done entirely with the free Microsoft Visual Studio 2010 Express for Windows Phone (which I’ll be calling “Visual Studio” for short from here on out) which comes with the free XNA Game Studio 4.0 Beta, also called the Windows Phone Developer Tools Beta (but it’s the full XNA for all platforms, don’t worry!). It is all also possible in Visual Studio 2010 Pro, Premium, Ultimate, etc., of course (using the same steps). But I’ve made sure to do it with the free tools so that anyone at all can make use of it. As a tip, once you’ve downloaded the zip file, but before you’ve extracted it, go to the folder where you downloaded it to, right click on it, select “Properties”, and then in the “General” tab press the “Unblock” button if you see it (see the picture to the left) and then press Ok. In Windows 7 (and I believe in Vista, too, though I’m not positive), when you download a file from the internet, the operating system tags it as being something it might want to keep track of, just to make sure it doesn’t do bad things to the computer. If you just unzip it, all the files that are unzipped that could potentially be hazardous are also tagged with this special security marker. But if you unblock the zip file first and then unzip it, the special “danger” tag isn’t applied to the unzipped files. This gets rid of that “This project comes from an untrusted source, etc. etc.” message you might come across sometimes when loading samples. So anyway, if you do that and make sure the zip file is unblocked before unzipping it first, you shouldn’t get that message or have any problems. (Always scan all files you download from the internet with a virus scanner that is using the latest definitions. Even from trustworthy sites like the Creators Club. It only takes a couple of seconds and if you make good habits like always virus scanning everything you download part of your routine, you may just save yourself from a catastrophe someday).
Ok. So, file unblocked and unzipped to the location of your choice. Go ahead and open up Visual Studio, and open up the solution using “File”->”Open Project…”. It should load up and be all set. At this point, you could make any changes you wanted to it or compile it first and deploy it just to make sure it works. If you do wish to do that you can, so go ahead and make any changes you want (or don’t as the case may be).
Ok. Let’s proceed. So at this point you’re going to want to go to the “File” menu and choose “Export Template…”.
It may pop up a dialog asking you if you wish to save. If so, just click Yes. You’ll then be presented with a dialog asking you to choose a template type. By default it should have “Project template” selected, which is nice because that’s just what we want. You’ll also see a drop-down box asking you “From which project would you like to create a template?”. Assuming you haven’t changed anything, it should have “GameStateManagementSample (Phone)” selected. We’ll stick with this for now (if you renamed it, go select the game project – we’re doing Content second because… well, ‘cause that’s how we roll.) When you’re ready, click “Next”.
At this point you’ll be presented with the “Select Template Options” section. This part is important! So pay close attention. First, we don’t want to stick with the default really long name. It’s quite long and that length can cause problems. So we’re going to shorten it. In this case, I’ve chosen to shorten it to “PhoneGame”. Nice and short but still reasonably descriptive.
Then we want to write a good “Template description”. Let’s say you become a game-making machine and start cranking out a game a month. Maybe you end up teaming up with a couple of people and together you have several projects going at any one time and have a new game ready every two weeks! The more games you make, the more refined the starting points will get. You might make a platformer and while writing it decide that you’ll want to write a sequel or perhaps a different platformer. So maybe you’ll want to create a platformer starting point. And maybe a puzzle game starting point. And maybe one for XBLIG titles (with all your special saving and loading code built in). So the description can be quite important. Then there’s the Icon Image and Preview Image. These help you identify the project when you’re browsing templates in Visual Studio. You’ll probably want to create a special one at some point (most templates use a .ICO icon file that’s 64x64 pixels, 24bpp, 1-bit alpha, no palette, and not a compressed PNG), but you needn’t worry, you can just use the GameThumbnail.png file that comes with the sample for now if you’d like. Make a note of the Output location. Then make sure that “Automatically import the template into Visual Studio” is NOT checked. We’ll put it into Visual Studio later when we’re ready. So it should look something like the image above when all’s said and done. If you’d like, you can check the “Display an explorer window on the output files folder” checkbox. This will save you a bit of time navigating to it yourself. Then click “Finish”. If you did put that check in, the Explorer window will open and show you your brand new template zip file. It’s nice, but we’re not done yet! Switch back to Visual Studio.
Time to repeat the process. Go to the “File” menu and choose “Export Template…”. Once again it’s a “Project Template” but this time, we must go to the drop-down menu and change the project to “Content”. Click “Next”, and we get to the “Select Template Options” window. This time you probably want to leave the name alone (“Content” is fine). Add a “Template Description” (e.g. “Content Project for PhoneGame”), select an Icon Image and a Preview Image, make sure that “Automatically import the template into Visual Studio” is not checked, and click “Finish”.
At this point, it’s time to leave Visual Studio. If you had it open a folder for you automatically, switch to that folder now. Otherwise, open up Explorer and make your way to the appropriate folder (usually “C:\Users\username\Documents\Visual Studio 2010\My Exported Templates\” where “username” is your user name on your system). Once there, select both the game and the content project templates (if you followed my naming scheme above, they should be “PhoneGame.zip” and “Content.zip”). In another Explorer window create a new directory (the name is not important). You could also use an existing directory, but it should be completely empty – for this reason, it’s better just to make a new directory which you can delete later if you’d like. Switch back to the window with the two zip files. Select them both, then choose “Cut” from the “Edit” menu. Switch back to the window with your empty directory, make sure you are inside the empty directory, and then choose “Edit”->”Paste” to paste the zip files into the empty directory.
And now you’ll want to unzip these. In Windows 7, simply right click on the zip file and choose “Extract All…”. Make sure to extract them into their own directories (i.e. Content.zip should extract into a folder called “Content” and PhoneGame.zip should extract into a folder called “PhoneGame”). Like so:
Now, delete the zip files. Or move them to some other directory. Do something with them such that they are no longer in this directory or any subdirectory of this directory. Done? Good. Now if you look in each of the directories, you should see that they have all of their content from when they were Visual Studio projects plus three additional files:
- “__TemplateIcon.png”, and
The first two might have .ICO extensions if you decided to create “proper” icons for them and if you didn’t set one or either when exporting your templates, then they simply won’t exist, which is no problem.
Now, return back to the directory that has those two directories in it. This is where the “magic” happens. First, we will want an icon for the project. The easiest thing to do is go into one of the subdirectories, copy its “__TemplateIcon.png” file, and paste it here in the base directory. Make a note of the name of the file you choose. I’m going to assume you are using “__TemplateIcon.png”, so replace that with the name of your file if you use something different.
You should now have a directory with two subdirectories, “Content” and “PhoneGame”, and an image file called “__TemplateIcon.png”. Right click in the empty space in this base folder area and choose “New”-> “Text Document”. Name this file whatever you like. I am going to assume that you will have named it “PhoneGame.txt”. Open this file up in your favorite plain text editor (we don’t want any RTF or anything else creeping in – Notepad is suitable). And then paste the following in:
<VSTemplate Version="3.0.0" Type="ProjectGroup" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
<Description>A Windows Phone 7 game template for XNA 4.0</Description>
As you may have noticed, this is a bunch of XML code. If you are interested, you can view the schema here. Things you can change: the “Name” tag’s value can be something other than “PhoneGame”; the “DefaultName” tag’s value can be something other than “MyPhoneGame” (keep it short though – this is what gets used by default when you create a new one of these, e.g. “MyPhoneGame1”, and if it’s too long it will cause problems and you’ll have to come back and shorten it); if you used names other than “PhoneGame” and “Content” you should modify these in the “ProjectTemplateLink” tags as appropriate; if you have a different “Icon” file name, change it to the proper value. Now save this file with an extension of “.vstemplate”. If you used “PhoneGame.txt”, for instance, you will now save it as “PhoneGame.vstemplate”. Then close the file.
If you still have a “PhoneGame.txt” file hanging around, delete it. Your folder contents should now consist of two folders, “Content” and “PhoneGame”, an image file “__TemplateIcon.png”, and the “PhoneGame.vstemplate” file we just created. Select all of these, and add them to a zip file called “PhoneGame.zip”. In Windows 7 (and perhaps Vista too), select all files, right click, and choose “Send to”->”Compressed (zipped) folder”. You should now have a file named “PhoneGame.zip”. Select this file, go to “Edit”->“Copy”. Now go to your “Visual Studio 2010” directory where your projects and other VS2010 files and folders are located. This should be something like “C:\Users\username\Documents\Visual Studio 2010\”. Go to the “Templates” directory in there. Then go to the “ProjectTemplates” subdirectory. You may see various subdirectories in here. Ignore them. Go to “Edit”->”Paste”. You should see “PhoneGame.zip” appear.
Now, go back to Visual Studio. Close the current solution (if you didn’t do so earlier). Then go to “File”->”New Project…”. If you’ve done everything correctly, you should be greeted with this:
Choose a name, press OK, and voila, your very own XNA game template! As a quick final note, there is nothing about this that makes it specific only to XNA games. You can use this for any multi-project solution that you’d like to turn in to a template. And you are not limited to only two projects, either. To add more projects, simply export them, unzip them as you did the others, and then add an additional well-formed “ProjectTemplateLink” tag to the .vstemplate file. Just as I finished writing this, I discovered the How to: Create Multi-Project Templates page on MSDN. Since I’ve already written this out (and taken all these nice screenshots), I figure I will go ahead and post it. But it is a good object lesson in something I’ve learned over time: if you search hard enough, you will find almost everything you could ever imagine explained on MSDN (at least as far as computing and Microsoft products goes :) ). Until next time, good luck!