Functions and Instance Variables

Need (library reference):

• Random function - this will be covered later in this module.

References:

• Pre-requisite: it is assumed that you have read through the prior tutorials, and are familiar with the concepts covered in those tutorials.

Goals:

• In this tutorial, we will:
  • Examine a naming convention for variables that will help make it clear which variables are local variables, and which are instance variables.
  • Examine how one can freely access an instance variable from within a method.

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.

When the game starts, you'll see a screen that looks similar to this:

As you can see, there is a single soccer ball on the screen.  Using the right thumbstick, you can move the soccer ball around (if you want, you can even move it off the screen).  The program prints out a simple, purely textual message at the top of the screen, and the current location of the soccer ball at the bottom of the screen.  You may also notice that the size of the ball is continuously, randomly changing.

2. Variable Naming Convention

Since the source code to this program is nearly identical to the program uses in the previous tutorial, we will only examine the code that's new, or different. 

Let's start by examining the naming convention for our variables.

• In order to make it clear that a particular variable is an instance variable, we will prefix the name of the variable with "m_".  "m_" is short for 'member variable', meaning instance variable. Examples:
  • m_aBall
    This is aBall, and an instance variable for the Game1 object
  • m_NumMisses
    This is an instance variable, that probably stores the number of misses for something.
• Local variables will be given a normal variable name, without any extra decoration.  Examples:
  • aBall
    This is aBall, and because there's no "m_" at the front, it must be a local variable.
  • thumbLeft
    Another local variable.  Probably used to hold a copy of the input from the left thumbstick
• Named constants will be given a normal variable name, except that the name will be in ALL CAPS, and words will be separated using the underscore character.  Examples:
  • BALL_INIT_X
  • BALL_INIT_RADIUS

Having settled upon this naming scheme, we will use it for this tutorial, and in future tutorials.

• Renaming the instance variables

  We need to declare our instance variables before we can use them. 

  public class Game1 : XNACS1Base {      private XNACS1Circle m_TheSoccer; // a soccer ball     // Constants for circle/ball definition     private const float BALL_INIT_X = 50.0f;     private const float BALL_INIT_Y = 35.0f;     private const float BALL_INIT_RADIUS = 3.0f;

  • The named constants already adhere to the above naming convention, so we don't need to do anything about them.
  • Since the XNACS1Circle is an instance variable, we will put the "m_" at the front of the name.  While we're at it, we will change the name from aBall, to TheSoccer, since it's the only soccer ball on the screen.

    Throughout the rest of the program, we also need to change aBall to m_TheSoccer.  While this needs to be done everywhere, this tutorial won't examine any changes that consist solely of changing the variable's name.

    •  It may be useful to examine Visual Studio's 'Edit' menu, particularly the 'Find And Replace' submenu. "Quick Replace" may be useful for ensuring that you've changed everything that needs to be changed, consistently.

3. Accessing Instance Variables From Other Methods.

As has been mentioned previously, instance variables' lifespans starts when the Game1 object is created (which is when the game starts), and lasts until the Game1 object is destroyed (which happens just before the program exits).  This means that we can, for example, move code from the InitializeWorld method into a new method, and still be able to access the same instance variables from that new method, like so:

• InitializeWorld():

  protected override void InitializeWorld() {     World.SetWorldCoordinate(new Vector2(0,0), 100.0f);     // initialize the soccer ball     InitializeSoccer(); }

  • Since the code for InitializeWorld in the previous tutorial only initialized the soccer ball, we can move all that code into a new function, and have it do the same thing.
  • Generally, it's good to make sure that each function/method has only a single, well-defined purpose.  For example, InitializeSoccer only initializes the soccer ball.  If we want to do something else in the InitializeWorld method, such as create some rectangles, then we should create another, new method to handle creating the rectangles.  We should NOT add the rectangle-related code to the InitializeSoccer method, since the task of creating rectangles is unrelated to the task of creating and initializing the soccer ball.
• InitializeSoccer():
  

  /// <summary> /// This function initializes the soccer ball, /// location, dimension, and texture. /// /// Notice, this function is "inside" the Game1 class and /// have access to _all_ "instance variables" of this class. /// To avoid confusion of "types" of variables, from now on /// all "instance variables" will begin with "m_". /// </summary> private void InitializeSoccer() {     // initialize the soccer ball     m_TheSoccer = new XNACS1Circle();     m_TheSoccer.Center = new Vector2(BALL_INIT_X, BALL_INIT_Y);     m_TheSoccer.Radius = BALL_INIT_RADIUS + RandomFloat();     m_TheSoccer.Texture = "SoccerBall"; }

  • All of this code should be familiar, since it is identical to the initialization code that was inside the InitializeWorld method.
  • You'll notice that m_TheSoccer is an instance variable, we can access it here just as easily as we can access it in the InitializeWorld method, the UpdateWorld method, or any other method.

FURTHER EXERCISES:: 

1. Start from a blank starter project (1000.201, if you need it), and re-do the code from memory as much as possible.  On your first try, do what you can, and keep the above code open so that when you get stuck, you can quickly look up what you forgot (and that after you finish a line, so that you can compare your line to the 'correct' line).  On the next try, do the same thing, but try to use the finished code less.  Repeat this until you can type everything, without refering the tutorial's code.
   • Repeat this exercise daily for several days, so that you really get the hang of this.  As you go on, periodically review this by re-doing this exercise.
2. Setting The Soccer Ball's Radius Using A Separate Function
   For this exercise, you should use the same project that was explained in the above tutorial.
   You'll notice that the code that is used to set the soccer ball's radius in the InitializeSoccer() function is the exact same line that we use to change the soccer ball's radius in the UpdateWorld method.  Create a new method, named something like SetRandomRadius(), which sets the soccer ball's radius in the above manner (i.e., the ball's radius will be set to a value as low as 3.0f, or as high as (but not including) 4.0f).  Then, call that function from both UpdateWorld, and InitializeSoccer.

	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