Creating Game-Themed Applications from scratch

Goals:

• To add XGA support to a basic XNA project, so that you can create your own games 'from scratch'
  • Note that this will be pretty much a step-by-step guide, without much/any explanation - check the next tutorial for a detailed description of what everything is
  • We'll be using the Microsoft Visual C# 2008 Express Edition, with XNA already installed.  If you're using a different version (such as Visual Studio Professional, 2008 Edition), then some of these steps may be different.

There a number of things that you need to do, and while each one involves several detailed steps, they basically amount to:

• Create a basic XNA project, without any of the custom code
• Download the XNACS1Lib_PC.dll (which contains the needed, custom program/game logic), and tell Visual Studio to use it
• Download a font (Arial.spritefont), and put in your project
• Replace the code for the basic XNA project with code for a basic XNACS1Lib

Notice:  To work with the XNACS1Lib  Library, a bare minimum project must include:

• Supporting Library: XNACS1Lib_PC.dll must be referenced by the project
• Fonts: the Arial.spritefont must be part of the project
• 2 functions:
• InitializeWorld(): allocate memory and initialize instance variables.
• UpdateWorld(): poll user input and update application state.

1. Obtain the example code

• Here is the zip file to the source files and compiled executable of this example.
• Here is the keyboard mapping for the XBOX 360 controller.  
• Here is the main tutorial page for working with XNACS1Lib, and here is the complete documentation of the library: html-page or compiled html help file.

First, you should create a blank XNA project, without any of the extra 'XNACS1Lib' stuff that you'll be using during this term.  You can do that using the File→New Project menu option, as pictured below:

Next, you'll need to fill in the details for your new project. Depending on the version of Visual Studio that you're using, your window may or may not look exactly like what's pictured below, but it should appear to be similar to what is pictured below:

1. In the top-left pane, entitled "Project Types", it may help to select 'XNA Game Studio 2.0', as it will remove options that you don't need from the right-hand pane.
2. In the top-right-hand pane, entitled 'Templates', you should select the 'Windows Game'. 
3. Working our way down, you should pick a 'Name' for your project - it's a good idea to include information about what you're working on in the name.  For example, if this is the first assignment that you're doing in this class, you might name it something like Assign_1. 
4. Next, pick a 'Location' for the project to be stored.  Again, it's a good idea to keep all of your work for this class in one folder, and if there are multiple types of work (for example, put smaller, weekly work underneath one subfolder, and homework projects into a different subfolder)
5. Unless your instructor specifically tells you otherwise, make sure that the 'Create directory for solution' IS checked.  If you create a project with this checked, then the Solution file (the file with the extension .SLN) will go into a new folder, and all the other files will go into a subfolder beneath that new folder.  This will be nice for you because the next time that you sit down to work on your game, you can just double-click on the .SLN file, which will be easy to find, since it's the only file in that new directory you created.
6. Finally, click the 'OK' button to go on.

At this point, you've created a basic, XNA video game.  Since you haven't actually added anything to the game, nothing really happens quite yet.  However, we should be able to see the game compile and run just, without crashing, if we've done everything right.  You can run the program (the video game) a couple of different ways.  Using menu options, you should choose the Debug→Start Debugging option (you can probably get away with using the Debug →Start Without Debugging option for now, but as you do more programming, you'll want to get familiar with the debugger, so get used to using the 'Start Debugging' option).  Another option would be to use the 'F5' keyboard shortcut, which does the same thing.  Here's a picture:

Once you've done that, you should see a blank screen.  Again, the program is doing exactly what you've told it to do: nothing.

At this point, we've created a basic, normal XNA project; let's add in the dynamic link library that contains the custom game logic that we'll use in our games.

• What is a DLL?  (Some Quick Background Information)
  • DLL is actually an acronym, which stands for 'DynamicLink Library', and is intended to contain code that applications can load and use as the programs are running (i.e., the code can be loaded dynamically, as opposed to incorporating the code into the program only at compile time (which is called static linking)).
  • The XNACS1Lib_PC.dll contains code that was written to make XNA easier for you to work with, and is used extensively in these tutorials
  • Since you're creating the new project from scratch, you'll need to download and add the .DLL yourself; 'Starter Projects' already have this DLL added, so you don't have to add this file to a starter project that is given to you.
• First, we'll need a place to put the DLL, so we'll follow these steps to create a folder for the library file:
• Go to the Solution Explorer
  You can activate this by using View → Solution Explorer: . 
  Once it's visible, then you should see it along the right edge of your screen:
  
   
• Navigate to the Assign_1 project (note that if you chose a different name for your game, you will need to find that name, instead)
   
• You can create a new folder by right-clicking on Assign_1, and selecting the Add→New Folder option, as pictured here:
  
  NOTE: you need to right-click on the PROJECT, not the Solution 'Assign_1'!!!
• Pick a name for your new folder - SupportFiles is a good name
  • Creating the new folder will also create a new folder within the file system, as well - so you can use Windows Explorer (or start with My Computer, or My Documents, or however you normally navigate the files on your computer) to locate that folder.
• Download the XNACS1Lib_PC.dll by clicking on this link, and save it into the  SupportFiles folder
• Unfortunately, it appears that Visual Studio won't automatically list the XNACS1Lib_PC.dll in the Visual Studio IDE, despite the fact that the file really is in that directory.  So if you want to see the file in Visual Studio's Solution Explorer, you'll need to right click on the SupportFiles folder, then select the 'Add→Existing Item' menu option, as pictured here:
  
    You'll need to find the XNACS1Lib_PC.dll, and add it in.  You may need to change 'Files of type' to be 'All Files (*.*)', as pictured here:
  
• Having done all that, we have successfully downloaded the DLL, and put it into the SupportFiles folder.  Next, we need to tell Visual Studio that the .DLL contains code that we want to use in our program.
• To include the library file as part of the project:
• Make sure that you have the Solution Explorer open
• Right-click on the project's References folder, and select 'Add Reference', as pictured here:
  
• Click on Browse tab
, and then navigate to and select: SupportFiles/XNACS1Lib_PC.dll, then click the 'OK' button, as pictured here:
• Now we can compile and run the application. Still nothing shows up- this is expected because our application is complete empty.
• If you want to confirm that you've added the DLL (or maybe you're looking at a different project, and you want to see if the DLL has been added in the first place), you can always open up the Solution Explorer, then open up the References (by left-clicking on the little box with the '+' in it that's next to the word References), and see that it's there, like so:
  

4. Including the font file: 

• Create the proper resource folder, in the GSE:
  • Right-Mouse-Button over the Content folder
    • Add → New Folder:  name the new folder: Resources
  • Right-Mouse-Button over the newly created Resources folder
    • Add → New Folder:  name the new folder: Fonts
  • Once you've done these steps, you should see the following:
    
• Include the font file as part of the project:
• Download the Arial.spritefont file, by following this link  Feel free to put this wherever you want. If you put it directly into the Resources\Fonts directory, you'll still need to do the next step.  If you put it anywhere else, Visual Studio will copy the spritefont file into the Resources\Fonts directory when you do the next step.
• Right-Mouse-Button click over the newly created Fonts folder:
  • Add → Existing Item, and navigate to the Arial.spritefont file.  Select it, and click 'OK' to add it
• Once again, we can compile and run the application. Still nothing shows up, but it's still good to do, just to confirm that there are no errors (yet :)  ).

5. Change the source code to build on the custom logic from the library: 

At this point, you should open up the Game1.cs file, using the Solution Explorer, and examine the source code (if you haven't already).  Firstly, you'll notice that the basic XNA source code that worked immediately after creating the project continues to work just fine now.  That's because the custom logic in the XNACS1Lib_PC.dll builds on the excellent XNA framework that Microsoft has created, instead of replacing it.  However, we want to use the XNACS1Lib logic, since it will provide an easier set of functions and objects to use.  In order to do this, we need to do 2 things:

• Make sure to add the 'using XNACS1Lib;' statement at the top of the file, below the other 'using' statements.
• Next, we'll need to remove the existing Game1 class, and replace it with our own.  The easiest way to do that is to fold all the code for Game1 by clicking on the box next to it:
  
• This will cause the entire Game1 class to be displayed as a single line, like so:
  
• Next, select (highlight) that line:
  
• And then press the 'Backspace' key to delete the entire class:
  
• Once you've done that, you can replace it with the new, blank code for the XNACS1Lib.  Thus, your Game1.cs should exactly like the following:

  using System; using System.Collections.Generic; using Microsoft.Xna.Framework; using Microsoft.Xna.Framework.Audio; using Microsoft.Xna.Framework.Content; using Microsoft.Xna.Framework.GamerServices; using Microsoft.Xna.Framework.Graphics; using Microsoft.Xna.Framework.Input; using Microsoft.Xna.Framework.Net; using Microsoft.Xna.Framework.Storage;   using XNACS1Lib;   namespace Assign_1 {      /// <summary>      /// This is the main type for your game      /// </summary>      public class Game1 : XNACS1Base      {                        protected override void InitializeWorld()          {          }            protected override void UpdateWorld()          {          }      } }

• Make sure that your game still compiles & runs.  It should (still) do nothing.
• If you're interested about what the above code is doing, you should continue on to the next exercise, which focuses on exploring a starter project (or in your case, exploring an XNACS1Lib project that you built)

6. Exercises:

1. Remove the .DLL file from the finished program, and try to compile and run the game.  What errors do you get?  Make sure that you carefully inspect these errors, so that if you ever accidentally remove the .DLL (or are given a project without the DLL), you will be able to identify the cause of the error.  You don't need to memorize the exact error message, but you should be able to recognize it.  Once you've done this, add the DLL to the game again.
   • Do the same exercise, but instead remove the .spritefont file.

	This work is supported in part by a grant from Microsoft Research under the Computer Gaming Curriculum in Computer Science RFP, Award Number 15871 and 16531.
2/8/2010