Arrays: Using Arrays (And Loops) To Keep Track of Multiple Objects

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 how to use an array of object references, in order to keep track of a number of on-screen objects

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, this program draws five soccer balls across the screen.  The program also draws a basketball on the screen, and allows you to move the basketball using the right thumbstick.  You may also move the fifth soccer ball using the left thumbstick.  The major change for the player in this game is that pressing the A button both increments the value stored in element #0 in the array, and also adjusts the size of soccerball #0 to reflect that value.  Similarly, the B button controls the second array element and soccer ball, the X button the third, and the Y button the fourth. 

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

  // Notice the way array is declared in C#     private int[] m_MyArray;     // an array of Circles to represent the SoccerBalls     private XNACS1Circle[] m_SoccerBalls;

  • The major change for this tutorial is that we will keep track of all five soccer balls using an array of references to XNACS1Circle objects.
  • In order to do that, we need to declare an instance variable to keep track of the array of XNACS1Circle object references, like so:
    private XNACS1Circle[] m_SoccerBalls;
    • Notice that this follows the same pattern as the array of integers - we declare the array to be private, and we choose the name of the array to be m_SoccerBalls.
    • Since we want an array of references to XNACS1Circle objects, we list the type as being XNACS1Circle, along with the characteristic open and close square brackets ( [] ) that indicate that this is an array of XNACS1Circle objects, instead of being a single object.
• InitializeWorld():

  // initialization for the soccer balls     float xOffset = 0.0f;     // Allocate memory for the soccer ball array     m_SoccerBalls = new XNACS1Circle[ARRAY_SIZE];     // here is the for loop and accessing the array     for (int i = 0; i < ARRAY_SIZE; i++)     {         m_SoccerBalls[i] = CreateABallAt(xOffset + BALL_INIT_X, "SoccerBall");         m_SoccerBalls[i].Label = m_MyArray[i].ToString();         xOffset = xOffset + SPACE_BETWEEN_BALLS;     }

  • The basic approach that we'll use for this InitializeWorld method is to put the left-most soccer ball at (BALL_INIT_X, BALL_Y_POS), then put the next soccer a distance of BALL_INIT_X to the right of the first, the third is moved a further BALL_INIT_X distance to the right, and so on.
  • The new initialization code for this tutorial starts off by declaring a float to keep track of how much horizontal distance there is between the first soccer ball and the current soccer ball that we're about to place on the screen.  Since we start with the first soccer ball, there is no "distance" yet, so we initialize it to zero:
        float xOffset = 0.0f;
  • Next, we allocate space for an array of objects:
        m_SoccerBalls = new XNACS1Circle[ARRAY_SIZE];
    The major difference between this and the integer array is that  m_SoccerBalls is an (instance) variable, which refers to an array of references to objects, while m_MyArray is a variable that refers to an array of integers. 
    • Because of this, m_MyArray[0] can immediately be used to store an integer (since m_MyArray[0] is an integer), but m_SoccerBalls[0] must be initialized with a reference to an object.  
    • C# will automatically initialize each element of an array of references to have the special value null, which indicates that the element does not refer to any object (i.e., it means that the element is not a valid reference to an existing object).  We'll represent null pictorially using a line that doesn't connect to anyting.
    • After this line of code is executed, the initialization step of the for loop is execute, and once that's done, variables xOffset, i,  m_MyArray and m_SoccerBalls will look like the following picture:
      (Note that we've changed the initialization code for m_MyArray so that it puts 5, not 10, into each element)
      
      
  •  During the first iteration through the loop, the following things happen:
    1. The program executes the check:
           i<ARRAY_SIZE
       And finds that i ( with the value 0) is less than ARRAY_SIZE (with the value 5), therefore the check is true, and the body of the loop is executed.
    2. The body of the loop consists of a multiple statements (which is why it MUST include the opening and closing curly braces). The first statement is
               m_SoccerBalls[i] = CreateABallAt(xOffset + BALL_INIT_X, "SoccerBall");

       This creates a new XNACS1Circle object, initializes that object with a starting location, radius, and texture (image), and then returns a reference to that object back to InitializeWorld, which then assigns it to the zeroth element of the array.  Once this line has finished, the variables will look like the picture below (Note that the Label of the new object is not yet set)
       
       

    3. Next, the statement
               m_SoccerBalls[i].Label = m_MyArray[i].ToString();

       is executed.  Since the value of i is currently 0, m_MyArray[i] means the same thing as m_MyArray[0].  Calling the ToString() method on the integer stored in element zero of the m_MyArray array will convert the number which is stored there (which is 5, currently) to a string, which will then be assigned to the 'Label' property of the new object.  Thus, the new object will look like:
       

    4. Next, we will move xOffset over, so that we're ready to create the next circle:
               xOffset = xOffset + SPACE_BETWEEN_BALLS;
       this will increase the value of xOffset by 15.0f.
    5. Since the body of the loop is done, we go back to the increment portion of the for loop, and execute that:
           i++
       This increments i by one, so that after executing the complete first iteration of the loop, we see:

       
       

  •  During the second iteration through the loop, the following things happen:
    1. The program executes the check:
           i<ARRAY_SIZE
       And finds that i ( with the value 1) is less than ARRAY_SIZE (with the value 5), therefore the check is true, and the body of the loop is executed.
    2. The body of the loop consists of a multiple statements (which is why it MUST include the opening and closing curly braces). The first statement is
               m_SoccerBalls[i] = CreateABallAt(xOffset + BALL_INIT_X, "SoccerBall");

       This creates a new XNACS1Circle object, initializes that object with a starting location, radius, and texture (image), and then returns a reference to that object back to InitializeWorld, which then assigns it to the first element of the array. 

    3. Next, the statement
               m_SoccerBalls[i].Label = m_MyArray[i].ToString();

       is executed.  Since the value of i is currently 1, m_MyArray[i] means the same thing as m_MyArray[1].  Calling the ToString() method on the integer stored in element one of the m_MyArray array will convert the number which is stored there (which is 5, currently) to a string, which will then be assigned to the 'Label' property of the new object.

    4. Next, we will move xOffset over, so that we're ready to create the next circle:
               xOffset = xOffset + SPACE_BETWEEN_BALLS;
       this will increase the value of xOffset by 15.0f, to a new total of 30.0f
    5. Since the body of the loop is done, we go back to the increment portion of the for loop, and execute that:
           i++
       This increments i by one, so that after executing the complete first iteration of the loop, the variables now look like:
       
       
  • This pattern continues through the third, fourth, and fifth iterations of the loop, which serves to fully initialize each element of the array to have the value 10.  We say that the loop has traversed the array, because the loop allows us to access each and every element of the array (if we want - we don't have to change the value of all the elements if we don't want to)
• UpdateWorld():

  #region control the soccer balls: 0 to 3 with buttons: A, B, X, Y and 4's location with left thumbstick     String msg = "Clock on buttons to increment array: A-0 B-1 X-2 Y-3!";     EchoToTopStatus(msg);     int nth = -1;     if (GamePad.ButtonAClicked())         nth = 0;     if (GamePad.ButtonBClicked())         nth = 1;     if (GamePad.ButtonXClicked())         nth = 2;     if (GamePad.ButtonYClicked())         nth = 3;     if (nth >= 0)     {         m_MyArray[nth] += 1;         m_SoccerBalls[nth].Radius = m_MyArray[nth];         m_SoccerBalls[nth].Label = m_MyArray[nth].ToString();     }         // control location of soccer-4 with right thumbstick     m_SoccerBalls[4].CenterX += GamePad.ThumbSticks.Right.X;     m_SoccerBalls[4].CenterY += GamePad.ThumbSticks.Right.Y;     #endregion

  • Let's first, quickly examine how the fifth soccer ball is moved around on the screen, before moving on to the more complicated explanation about how the soccer ball sizes are adjusted. This is done using the statements:
        // control location of soccer-4 with right thumbstick

        m_SoccerBalls[4].CenterX += GamePad.ThumbSticks.Right.X;

        m_SoccerBalls[4].CenterY += GamePad.ThumbSticks.Right.Y;
    The only thing that's new about these statements is that instead of using a variable like m_Soccer, we're using  the last element of the array - m_SoccerBalls[4].

  • For changing the size of the soccer balls, the basic strategy that we'll be using to update the soccer balls is this: the variable nth ( as in 1^st, 2^nd, 3^rd, 4^th, 5^th, ... N^th) is given the value -1, which we choose specifically to mean that "None of the buttons are being pushed".  The program will then check if any of the buttons are currently being pushed - if the A button, which controls the left-most soccer ball, is being pushed, then we'll set nth to be 0.  Not only is zero the index of the left-most soccer ball in the m_SoccerBalls array, but it's also the index of the left-most soccer ball's size in the m_MyArray array.  Similarly, pushing the B button nth to be 1, X = 2, and Y = 3.  Once we get through figuring out which (if any) soccer ball should have it's radius incremented, we will increase the radius (but only if a soccer ball was changed).  Let's walk through that in more detail:
  • Firstly, we need to declare and initialize the variable nth:
        int nth = -1;
    • The trick that we're using here, of having -1 mean "not a valid selection" is an extremely common trick, and one that you should strive to become very comfortable with.
  • If the user is pushing the A button, then we want to access element #0 for the the m_MyArray, and m_SoccerBalls arrays.  In that case, we'll set nth to zero:

        if (GamePad.ButtonAClicked())

            nth = 0;

  • Similarly, if the B button is being pressed, then nth should be 1, if the X button is being pressed, then nth should be 2, and if the Y button is being pressed, then nth should be 3:

        if (GamePad.ButtonBClicked())

            nth = 1;

    
    

        if (GamePad.ButtonXClicked())

            nth = 2;

    
    

        if (GamePad.ButtonYClicked())

            nth = 3;

  • We only want to execute the 'change the radius of the soccer ball' logic IF the user is actually pushing a button.  Since we initialized nth to be -1, we know that if none of the buttons are being pushed, and therefore nth must still be zero.  The other option is that the user is pushing a button, in which case nth will have the value 0, or 1, or 2, or 3.  This if statement will only be true if the user has pushed a button:
        if (nth >= 0)
  • If the user has pushed a button, then the following code will be executed:

        {

            m_MyArray[nth] += 1;

            m_SoccerBalls[nth].Radius = m_MyArray[nth];

            m_SoccerBalls[nth].Label = m_MyArray[nth].ToString();

        }

    for the purposes of this tutorial, let's assume that the user has pushed the X button, and that all the variables and objects look like so:
    

    • The statement
              m_MyArray[nth] += 1;

      will use the current value of nth (which is 2), to retrieve the value stored at m_MyArray[2] (which is 5), then add one to that number (which is then 6), then store that number back into m_MyArray[2].

    • The statement
              m_SoccerBalls[nth].Radius = m_MyArray[nth];
      will use the current value of nth (which is 2), to retrieve the value stored at m_MyArray[2] (which is now 6), and assign that to the Radius property of the circle object referred to by slot 2 of the m_SoccerBalls array
    • The statement
              m_SoccerBalls[nth].Label = m_MyArray[nth].ToString();

      will use the current value of nth (which is sitll 2), to retrieve the value stored at m_MyArray[2] (which is now 6), convert that integer to a string, and then assign that to the Label property of the circle object referred to by slot 2 of the m_SoccerBalls array.

  • Once all of that is done, the variables and objects will look like:
    
  • The third, fourth, and fifth iterations of the loop continue this pattern, slowly building up the arrayMsg string, so that the EchoToBottomStatus command can display it at the bottom of the screen.
• The key lesson to learn here is that since we now have an array of references to the soccer balls, our program can now interact with the soccer balls.  Previously, we would have had to create a separate instance variable for each and every one, and then duplicate a large amount of code in order to have our program use 5 separate circles. 

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 Circles
   For this exercise, you should use the same project that was explained in the above tutorial, and modify it so that it does the following:
   1. Have the program put 7 soccer balls on the screen. 
   2. The A button should increase the size of the SECOND soccer ball (from the left), the B button should increase the size of the FOURTH, the X button the FIFTH, and the Y button the SIXTH.
   3. The left thumbstick should move the seventh ball around the screen. 
3. Increasing and Decreasing The Soccer Ball Sizes
   For this exercise, you should use the same project that was explained in the above tutorial, and modify it so that when you push the A button, the radius of all the soccer balls is increased by 1.  When you push the B button, the radius of all the soccer balls should be decreased by 1. 

	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