(Re-)Implementing A Game Using Functions

References:

• Pre-requisite: it is assumed that you have read through the prior tutorials, and are familiar with the concepts covered in those tutorials.
• For this tutorial, it will be helpful to review the tutorial on translating Math Formulas into C#

Goals:

• In this tutorial, we will:
  • Examine an example of how to create a small game program, using functions.  We will specifically rewrite an earlier tutorial, so that you can compare and contrast the older version of the program that doesn't use functions with this new version that does use functions.

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:

This program is functionally equivalent to 2000.700, so you should read the description for that program before you start in on this tutorial.  You are strongly encouraged to review the material from that tutorial, so that you've comfortable with the concepts used in that tutorial, and the details of the code presented in that tutorial, before attempting to do this tutorial.

2. Examining The Program:

Let's examine the C# source code that produces the behavior we see on-screen

• Declaring the instance variables and named constants

  public class Game1 : XNACS1Base {         private XNACS1Rectangle m_PresentRec;     private XNACS1Rectangle m_FutureRec;     private float m_PresentValue; // present value of the money     private float m_Rate; // interest m_Rate     private float m_Years; // number of years     #region Constants use in the program     // initial values for present, rate and years     private const float INIT_RATE = 0.02f;     private const float INIT_YEARS = 20.0f;     private const float INIT_VALUE = 10.0f;     private const float RATE_SCALE_FACTOR = 0.005f;     private const float INIT_PRESENT_X = 5.0f;     private const float INIT_REC_Y = 5.0f;     private const float REC_WIDTH = 10.0f; // Width of the two rectangles     #endregion

  • We'll need to keep track of each of the rectangles that we see on-screen, so we declare each of them here.  Similarly, we'll need to keep track of the present value of the money, the interest rate, and the number of years that the money will be left in the interest-bearing account.  All of these are (effectively) identical to what was presented in the 2000.700 tutorial.
    • The only change we've made is to make the instance variables adhere to our new naming convention.  As a result, each of the variables now starts with "m_", and the first letter of each word that makes up the name is capitalized
  • We've also gone back, and replaced many of the ' magic numbers ' with named constants, which makes it easier to understand and modify the program.  We've enclosed the constants in a #region , so that you can easily hide the declarations if you want to.
• InitializeWorld():

  protected override void   InitializeWorld() {     World.SetWorldCoordinate( new Vector2(0,0), 100.0f);     m_PresentValue = INIT_VALUE;     m_Years = INIT_YEARS;     m_Rate = INIT_RATE;     // We can comput future value only after we have initialized the above instance variables     float futureValue = ComputeFutureValue();     // initialize the rectangle representing present and future values     m_PresentRec = InitializeRectangle(m_PresentValue, INIT_PRESENT_X);     m_FutureRec = InitializeRectangle(futureValue, m_Years); }

  • The first thing that we do is to initialize the instance variables (the program-wide variables) with some starting values.

        m_PresentValue = INIT_VALUE;

        m_Years = INIT_YEARS;

        m_Rate = INIT_RATE;

  • If you recall, we had previously initialized the local variable with the value future of the money by calculating it right here:
        float futureValue = presentValue * ( float ) Math .Pow((1 + rate), years);

    while this worked fine for that tutorial, we now know how to use functions and this is a perfect opportunity to replace the (rather complicated) formula with a simple call to a function, instead.  Once we've defined our ComputeFutureValue function (which we will examine in detail below), we can instead use the current line of code:
        float futureValue = ComputeFutureValue();

    You'll notice how much more clear this code is - instead of trying to sort through the details of a mathematical-formula-written-in-C#, you can immediately see that we're computing the future value of the money here.

    • You'll notice that the function has no parameters - since the present value of the money, the rate, and the years are all stored in instance variables, we don't need to pass any information to ComputeFutureValue.  ComputeFutureValue can get all the information it needs on it's own.
    • If you're curious about exactly what formula is being used, you'll need to examine the function itself.  An easy way to jump to the code in recent versions of Visual Studio is to right-click on the word " ComputeFutureValue ", then select "Go To Definition".  What's nice is that this will find the definition for you, even if it's in a different file. Another way is to use the 'Find' command (Edit →Find And Replace, then you'll have multiple options), and put in the name of the function that you're looking for.
  • If you recall, we had previously created and initialized both rectangles here, too.  Since most of the work that we were doing to create and initialize the rectangles is identical, we've gone ahead and replaced the two blocks of nearly identical code with two calls to a new function: InitializeRectangle . 
        // initialize the rectangle representing present and future values

        m_PresentRec = InitializeRectangle(m_PresentValue, INIT_PRESENT_X);

        m_FutureRec = InitializeRectangle(futureValue, m_Years);

    • Since the only thing that differentiates the two rectangles are the height, and the X value of the lower-left corner, those are the only parameters that we need to pass to the function.
      
• ComputeFutureValue():

  /// <summary> /// Computes future value based on instance variables: /// m_Year, m_Rate, and m_PresentValue /// Using the standard compound interest formula /// </summary> /// <returns></returns> private float ComputeFutureValue() {     return m_PresentValue * ( float ) Math .Pow((1 + m_Rate), m_Years); }

  • We've defined this function towards the end of the file, in the "Local utility functions" region.
  • You'll notice that this is pretty much identical to the formula that we were using the in previous version of the code:
        presentValue * ( float ) Math .Pow((1 + rate), years);

    All we've done is to update the code so that we're using the new names:
        m_P resentValue * ( float ) Math .Pow((1 + m_R ate), m_Y ears);

  • Once we've calculated the future value of the money, we return that value to the calling function
  • As you have seen, we have replaced the complicated, awkward formula that we had been using in InitializeWorld with a call to this function, thus making the code much more readable.
  • If we wanted to change the formula, we can now do so easily - we can update just this one, single function definition, and know that all the rest of our program (which calls this function) will automatically use our new formula.
    • One specific case of "changing the formula" happens when we discover an error in our formula, and we need to fix the error by changing how we calculate the formula.
• InitializeRectangle():

  /// <summary> /// Allocate and initialize a rectangle for /// representing present and future values /// </summary> /// <param name="height"> initial height of the rectangle </param> /// <param name="xPosition"> inital lower-left x position of the rectangle </param> /// <returns> A properly initialized rectangle </returns> private XNACS1Rectangle InitializeRectangle( float height, float xPosition) {     XNACS1Rectangle rec= new XNACS1Rectangle ();     rec.LowerLeft = new Vector2 (xPosition, INIT_REC_Y);     rec.Height = height;     rec.Width = REC_WIDTH;         return rec; }

  • Since we want to initialize the two rectangles using (nearly) identical steps, we have created  new function to do this work for us.  The function takes two parameters - the height of the rectangle ( height ), and the distance along the X axis from the left edge to the retangle's lower-left corner ( xPosition ).
  • The function then creates a new XNACS1Rectangle object, and stores a reference to that object in the rec local variable
        XNACS1Rectangle rec= new XNACS1Rectangle ();
  • The next step is to set the on-screen location of the rectangle, by assigning the point (xPosition, INIT_REC_Y) to the lower-left corner of the rectangle:
        rec.LowerLeft = new Vector2 (xPosition, INIT_REC_Y);
  • Next, we assign the value stored in the height parameter to the .Height property of the rectangle:
        rec.Height = height;
  • Since all rectangles have the same width, we then assign the standard REC_WIDTH to the .Width property of the rectangle:
        rec.Width = REC_WIDTH;
  • Lastly, we return the reference to our newly created and initialized rectangle back to the calling method.
• UpdateWorld():

  protected override void UpdateWorld() {     if (GamePad.ButtonBackClicked())         this.Exit();     // 1. Update year, rate, and present value based on thumbSticlk     UpdateYearRateValue();     // 2. compute the new futureValue according to the formula     float futureValue = ComputeFutureValue();     // 3. Update the rectangle representing the presentValue     UpdateRectangle(m_PresentRec, m_PresentValue, "present value=" );     // 4. Update the rectangle representing the futureValue     UpdateRectangle(m_FutureRec, futureValue, "future value=" );     // 5. Change futureValue's lower-left corner to show year     m_FutureRec.LowerLeft = new Vector2 (m_Years, 5.0f);     // 6. Last: update the user with what has happened     EchoToTopStatus( "Years=" + m_Years + " m_Rate=" + m_Rate);     EchoToBottomStatus( "LeftThumb-Y adjust Present Value; LeftThumb-X adjust m_Rate; RightThumb-Y adjust Years" ); }

  • We want to rewrite UpdateWorld to use functions for two general reasons:
    1. UpdateWorld now needs to do very similar things, to each of the two different rectangles.  It will minimize our overall work and allow us to change the program more quickly and more reliably if we use functions.
    2. UpdateWorld now does a fair amount of work, and it will help clarify what's going on by taking the various, dense blocks of code and replacing them with clearly named functions.
  • The first step is to collect up any user input, and do an initial processing of that input.  We check if the user wants to exit the program in the standard way, then we read input from the thumbstick, and update the year, rate, and present value instance variables accordingly:
        // 1. Update year, rate, and present value based on thumbSticlk

        UpdateYearRateValue();

  • Once we have all the new numbers, can calculate the future value of the money, using the exact same function as we did when we initialized the game:
        // 2. compute the new futureValue according to the formula

        float futureValue = ComputeFutureValue();

  • Next, we'll update both rectangles.  Note that the first rectangle, that represents the present value of the money, can be completely updated using the UpdateRectangle function:
        // 3. Update the rectangle representing the presentValue

        UpdateRectangle(m_PresentRec, m_PresentValue, "present value=" );

    Whereas the second rectangle, that represents the future value of the money, needs an additional step in order to update it.  Specifically, we'll need to move the second rectangle so that it's distance along the X axis shows how many years the future value is being calculated for:

        // 4. Update the rectangle representing the futureValue

        UpdateRectangle(m_FutureRec, futureValue, "future value=" );

    
    

        // 5. Change futureValue's lower-left corner to show year

        m_FutureRec.LowerLeft = new Vector2 (m_Years, 5.0f);

  • Lastly, we update the messages at the top and bottom of the screen, as appropriate:
        // 6. Last: update the user with what has happened

        EchoToTopStatus( "Years=" + m_Years + " m_Rate=" + m_Rate);

        EchoToBottomStatus( "LeftThumb-Y adjust Present Value; LeftThumb-X adjust m_Rate; RightThumb-Y adjust Years" );

• UpdateYearRateValue():

  /// <summary> /// Updates m_Year, m_Rate, and m_PresentValue based on /// thumbSticks states. /// </summary> private void UpdateYearRateValue() {     float leftThumbY = GamePad.ThumbSticks.Left.Y;     float leftThumbX = GamePad.ThumbSticks.Left.X;     float rightThumbY = GamePad.ThumbSticks.Right.Y;     // Get user's input, accumulate for: m_Years, m_Rate, and m_PresentValue     m_Years = m_Years + rightThumbY;     m_Rate = m_Rate + (RATE_SCALE_FACTOR * leftThumbX);     m_PresentValue = m_PresentValue + leftThumbY; }

  • In this function, we start by making local copies of the user's input, so that subsequent code will be shorter, and easier to read:

        float leftThumbY = GamePad.ThumbSticks.Left.Y;

        float leftThumbX = GamePad.ThumbSticks.Left.X;

        float rightThumbY = GamePad.ThumbSticks.Right.Y;

  • Next, we update the m_Years instance variable based on input from the right thumbstick's Y axis:
        m_Years = m_Years + rightThumbY;
  • Then we update the m_Rate  instance variable based on input from the left thumbstick's X axis, adjusted by a scaling factor (otherwise the user will change the rate too quickly, and the 'future value' rectangle will grow or shrink too rapidly to be used to visualize the information that we're looking at)
        m_Rate = m_Rate + (RATE_SCALE_FACTOR * leftThumbX);
  • Finally, we adjust the present value of the money, by updating the m_PresentValue  instance variable based on input from the left thumbstick's Y axis:
        m_PresentValue = m_PresentValue + leftThumbY;
  • Note that we don't need a return value for the function, because the instance variable that were updated are accessible to all the other functions in the Game1 class
• UpdateRectangle():

  /// <summary> /// change the height and label of "rec" /// </summary> /// <param name="rec"> The rectangle to be changed </param> /// <param name="height"> new height for the rectangle </param> /// <param name="label"> new label for the rectangle </param> private void UpdateRectangle( XNACS1Rectangle rec, float height, String label) {     rec.Height = height;     rec.Label = label + height; }

  • Since we want to initialize the two rectangles using (nearly) identical steps, we have created  a new function to do this work for us.  The function takes three  parameters - the rectangle to update ( rec ), the height of the rectangle ( height ), and the text label to put on the rectangle ( label ).
  • We then assign the new height (stored in the height parameter) into the .Height property of whichever rectangle we're currently updating:
        rec.Height = height;
  • We then create a text label for the rectangle by concatenating the provided label, with the provided height ( label + height ), and then assigning that text to the .Label property of the rectangle:
        rec.Label = label + height;
  • Note that since we're using a parameter ( rec ), when UpdateWorld executes this line:
        UpdateRectangle(m_PresentRec, m_PresentValue, "present value=" );

    rec will refer to the same rectangle that m_PresentRec does, and therefore will update the first rectangle (that displays the present value of the money).  Similarly, when UpdateWorld executes this line:

        UpdateRectangle(m_FutureRec, futureValue, "future value=" );

    rec will refer to the same rectangle that m_FutureRec does, and therefore will update the second rectangle (that displays the future value of the money).

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. Adding Parameters To A Function
   For this exercise, you should use the same project that was explained in the above tutorial.
   Right now, ComputeFutureValue works, and works well.  However, it assumes that we're going to be storing the present value, rate and number of years in instance variables.  Change this function so that it takes (as parameters) the present value, rate and number of years, and then does the same calculation that it's currently doing.  In order to make this work, you'll need to adjust the parts of the program that call this function, too.

3. Adding Parameters To A Function
   For this exercise, you should use the same project that was explained in the above tutorial.
   Add two more rectangles to the program, so that you can show how much money you'll have after m_Year years (this is currently being done, in the above tutorial), then m_Year +10 years, and then m_Year + 20 years, with three separate rectangles

	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