Decision Statements: Chapter Overview

Need (library reference):

• Working with multiple projects inside a single solution
  • Note: "Build" builds everything, may be slow if you're used to single-project solutions
  • Right-click & build to build a single project (useful if other, unrelated projects contain compile errors)
  • To indicate which project to run: Right-click & Set As Startup Object
• Working with random function - covered previously
• Working with Texture files - covered previously
  • We should put in something about copyright
• Working with #regions.  Not tough, but probably good to call out.

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

Goals:

• Throughout this chapter, we will work towards a simple game, with each tutorial adding a little bit more to what we've already done. 
  Since this is the very first tutorial in this chapter, it has two goals:
  1. Examine the final, finished game, so that you know what you're working towards.
  2. Examine this tutorial's project, which doesn't really have any new programming concepts, but instead serves as a starting point that will lead you to the final project.

Before you begin

Let's start by examining the final, finished game that you will create throughout  this chapter. Download and unzip the Example Code, and then open the solution for the 900 tutorials .  In the Solution Explorer, you will see:

• The PongSoccer :   This is NOT the project that we will work with on this tutorial.  Instead, it's the final version of the game that you will make throughout this chapter.  Right click on the project, then select "Set as StartUp Project", then use the Debug →Start Debugging option to run the game.  You should take some time to play the game, and examine what it's doing, but don't worry about any of the code for right now.  A detailed explanation of the game is available in that project's tutorial .  Please read through it, and try out the game, before starting this tutorial.

Once you've done that, you should proceed with this tutorial. 

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:

The rectangle on the far left is a 'paddle'.  You can move it up and down by pushing the left thumbstick up and down.  The rectangle on the far right is also a 'paddle', which you can move up and down by pushing the right thumbstick up and down.  The only other thing on the screen is a picture of a soccer ball.  The soccer ball starts off in (roughly) the center of the screen, moving at a random speed in a random direction.  Even at the end of this tutorial, the soccer ball will not interact with anything - it won't bounce off either paddle, nor the edges of the screen.  Notice that the location of the paddles are displayed at the top of the screen, and the location of the soccer ball is displayed at the bottom.

Notice that since the soccer ball doesn't bounce of anything, it will just keep going.  You can see this by observing that the position of the soccer ball continues to change, even after the soccer ball has left the screen.

Once you've seen what the final, finished game does ( the PongSoccer game ), and what you've seen what this tutorial's game does, you should open up the Game1.cs file for the 010.PaddlesAndBalls project, so that you can examine the source code.  Keep in mind that the goal for this tutorial is to acquaint you with the source that we'll be building on, in future tutorials .  Everything in the file should be familiar, with the possible exceptions of working with images ( aka textures) , creating your own regions , and generating random numbers using XNACS1Lib .

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 { #region Constants for the paddle and ball     // Paddle dimensions (both paddles are the same size)     private const float PADDLE_WIDTH = 1.5f; // width of the paddle     private const float PADDLE_HEIGHT = 10.0f; // Height of the paddle     // paddle initial positions     private const float LEFT_PADDLE_X = 3.0f;     private const float RIGHT_PADDLE_X = 97.0f;     private const float PADDLE_INIT_Y = 20.0f; // both start off at same height     // Ball size, position, and velocity     private const float BALL_INIT_X = 50.0f; // initial ball X and Y positions     private const float BALL_INIT_Y = 25.0f;     private const float BALL_RADIUS = 2.5f; // size of the ball     // We want to specify a minimum and maximum speed for the ball.     // Since we keep track of velocity by keeping track of the separate X and Y speeds,     // we need to define a min & max speed for each of the X and Y directions     private const float BALL_VELOCITY_MIN_X = 0.6f;     private const float BALL_VELOCITY_MAX_X = 1.2f;     private const float BALL_VELOCITY_MIN_Y = BALL_VELOCITY_MIN_X / 3.0f;     private const float BALL_VELOCITY_MAX_Y = BALL_VELOCITY_MAX_X / 3.0f; #endregion     private XNACS1Circle m_TheSoccer; // the soccer ball     // The paddles:     private XNACS1Rectangle m_LeftPaddle;     private XNACS1Rectangle m_RightPaddle;

  • When you first look at the code, the region for " Constants for the paddle and ball " will probably be folded up.  Remember to unfold it, in order to see things as they are above. Once you've unfolded the region, you can see  the #region and #endregion markers.  We've chosen to enclose all the named constant declarations in a region because there's a lot of them, and because it will make the code easier to read if we can (optionally) hide the constants when we want to.
  • If we skip to the instance variables, we see that there's basically just a couple of things that we're keeping track of.  First, let's look at the soccer ball:
        private XNACS1Circle m_TheSoccer; // the soccer ball
    

    The soccer ball is represented using a circle that has a texture (image) put over it, so we declare m_TheSoccer as an XNACS1Circle .  m_TheSoccer will keep track of it's current position and velocity .  Essentially, each time UpdateWorld is called, the ball will be moved by a distance of m_TheSoccer.VelocityX in the horizontal direction, and m_TheSoccer.VelocityY in the vertical direction.  Remember that a positive value for X means that the ball will be moving towards the right, while a negative value means that the ball will move towards the left.  Remember that a positive  value for Y means that the ball will be moving towards the top of the screen, while a negative value means that the ball will move downwards.

  • The paddles are just normal rectangles, and we choose to give them the very clear names of leftPaddle and rightPaddle .  We don't need to track their velocity since they don't have a velocity - they only move when the player uses the thumbsticks.

        // The paddles:

        private XNACS1Rectangle m_LeftPaddle;

        private XNACS1Rectangle m_RightPaddle;

  • Now that you know what data the program will need, we can look at the various constant declarations.  The first three chunks of declarations create named constants that will define what the game looks like when the program starts (i.e., how wide to make the paddle, where to put the paddles, etc). 
        // Paddle dimensions (both paddles are the same size)

        private const float PADDLE_WIDTH = 1.5f; // width of the paddle

        private const float PADDLE_HEIGHT = 10.0f; // Height of the paddle

    
    

        // paddle initial positions

        private const float LEFT_PADDLE_X = 3.0f;

        private const float RIGHT_PADDLE_X = 97.0f;

        private const float PADDLE_INIT_Y = 20.0f; // both start off at same height

    
    

        // Ball size, position, and velocity

        private const float BALL_INIT_X = 50.0f; // initial ball X and Y positions

        private const float BALL_INIT_Y = 25.0f;

        private const float BALL_RADIUS = 2.5f; // size of the ball

    Both paddles will be given a width of PADDLE_WIDTH , and a height of PADDLE_HEIGHT .  By creating (and later, by using) these named constants, we ensure that both paddles will have consistent dimensions. 
    
    Similarly, we position both paddles a distance of PADDLE_INIT_Y from the bottom of the screen, so that they'll both start off at the same height.  However, the left paddle's X value needs to be different from the right paddle's X value, so we define LEFT_PADDLE_X and RIGHT_PADDLE_X .  The left paddle will initially be placed at ( LEFT_PADDLE_X , PADDLE_INIT_Y ), while the right paddle will initially be placed at ( RIGHT_PADDLE_X , PADDLE_INIT_Y ).

    
    Lastly, the ball will initially be placed at ( BALL_INIT_X , BALL_INIT_Y ), and will have a radius of BALL_RADIUS .

  • The last chunk defines the minimum and maximum speed for the soccer ball.  When the program starts, the game will randomly pick a speed (for the X, and the Y, directions) from within the ranges that we define here

        // We want to specify a minimum and maximum speed for the ball.

        // Since we keep track of velocity by keeping track of the separate X and Y speeds,

        // we need to define a min & max speed for each of the X and Y directions

        private const float BALL_VELOCITY_MIN_X = 0.6f;

        private const float BALL_VELOCITY_MAX_X = 1.2f;

        private const float BALL_VELOCITY_MIN_Y = BALL_VELOCITY_MIN_X / 3.0f;

        private const float BALL_VELOCITY_MAX_Y = BALL_VELOCITY_MAX_X / 3.0f;

• InitializeWorld():

  protected override void   InitializeWorld() {     World.SetWorldCoordinate( new Vector2(0,0), 100.0f);     // initialize the left and right paddles     m_LeftPaddle = InitializeRectangle(LEFT_PADDLE_X, PADDLE_INIT_Y, PADDLE_WIDTH, PADDLE_HEIGHT);     m_RightPaddle = InitializeRectangle(RIGHT_PADDLE_X, PADDLE_INIT_Y, PADDLE_WIDTH, PADDLE_HEIGHT);       // initialize the soccer ball     InitializeSoccer(); }

  • The first new thing that we do is to create and initialize the two paddles.  Since the paddles are just rectangles, we can use the InitializeRectangle function that you've seen in previous tutorials.  Similar to other versions of the InitializeRectangle method, we pass in the starting (X,Y) location of the center of each rectangle, along with the width and height.
  • Next, we call the InitializeSoccer function, which will create and initialize the soccer ball.  This includes creating and initializing the circle that will be used to display the picture on-screen, along with the velocity vector:
    

    /// <summary> /// Allocate and initialize the soccer and the velocity for /// the soccer ball /// </summary> private void InitializeSoccer() {     m_TheSoccer = new XNACS1Circle ();     m_TheSoccer.Center = new Vector2 (BALL_INIT_X, BALL_INIT_Y);     m_TheSoccer.Radius = BALL_RADIUS;     m_TheSoccer.Texture = "SoccerBall" ;     // initilize the soccer ball velocity     m_TheSoccer.VelocityX = XNACS1Base .RandomFloat(BALL_VELOCITY_MIN_X, BALL_VELOCITY_MAX_X);     m_TheSoccer.VelocityY = XNACS1Base .RandomFloat(BALL_VELOCITY_MIN_Y, BALL_VELOCITY_MAX_Y);     m_TheSoccer.ShouldTravel = true ;         // notice the soccer ball will travel by itself now (ShouldTravel is true). }

    • You'll notice that InitializeSoccer basically consists of two things: code to initialize the soccer ball, and code to initialize the ball's velocity.  The first three lines in the function should be familiar - create a new XNACS1Circle object, assign it a location of ( BALL_INIT_X , BALL_INIT_Y ), and then assign the circle a radius of BALL_RADIUS .
    • The following is duplicated from 3000.100
      What may be new is the fourth line, m_TheSoccer.Texture = "SoccerBall" ; .  A Texture is (essentially) another word for an image, and "SoccerBall" is the name of an image that has been added to the project's Content/Resource/Textures folder ( without the file extension).  Once you've added the texture file to the project, you can put an image onto the screen by assigning the name of the texture to the object's .Texture property, like we do here.
      • You can add an image by right-clicking on the Textures folder, and selecting Add →Existing Item from the context menu.  Since we've already done that with the SoccerBall.png file, you can use the Solution Explorer to see it:
        
      • XNA doesn�t support all types of images. The following types are supported: .bmp , .dds, .dib, .hdr, .jpg , .pfm, .png , .ppm, and .tga. (From http://msdn2.microsoft.com/en-us/library/bb447762.aspx - look for "Texture - XNA Framework")
    • Next, we initialize the m_Soccer.Velocity vector, and assign to the X & Y parts randomly selected numbers.  This means that the speed the ball is moving in the X direction is randomly picked, and the speed the ball is moving in the Y direction is (separately) randomly picked.
      • Remember that for XNACS1Base .RandomFloat(BALL_VELOCITY_MIN_X, BALL_VELOCITY_MAX_X), RandomFloat will randomly pick a number that may be as low as BALL_VELOCITY_MIN_X (including the value BALL_VELOCITY_MIN_X ),  or may be as high as just slightly below BALL_VELOCITY_MAX_X , but will never be equal to BALL_VELOCITY_MAX_X itself.
  
  

  UpdateWorld():

  protected override void UpdateWorld() {     if (GamePad.ButtonBackClicked())         this .Exit();     // update the left and right paddles with thumbstick     m_LeftPaddle.CenterY = m_LeftPaddle.Center.Y + GamePad.ThumbSticks.Left.Y;     m_RightPaddle.CenterY = m_RightPaddle.Center.Y + GamePad.ThumbSticks.Right.Y;     // the soccer center will be moved by velocity automatically because mTheSoccer.ShouldTravel is true     EchoToTopStatus( "Left Paddle Center=" + m_LeftPaddle.Center + " Right Paddle Center=" + m_RightPaddle.Center);     EchoToBottomStatus( "Soccer Ball position: " + m_TheSoccer.Center); }

  • As per normal, our game will check if the user presses the 'Back' button.  If we're going to exit, there's no sense in doing any work prior to exiting, so we check if we need to exit as the first two lines in the method. 
  • Next, we update the positions of the left and right paddles, based on the left and right thumbstick's Y values:
        // update the left and right paddles with thumbstick

        m_LeftPaddle.CenterY = m_LeftPaddle.Center.Y + GamePad.ThumbSticks.Left.Y;

        m_RightPaddle.CenterY = m_RightPaddle.Center.Y + GamePad.ThumbSticks.Right.Y;

  • Notice, since the m_TheSoccer.ShouldTravel has been initialized to true we do not need update the position of the soccer ball. XNACS1Lib will automatically update the positions all of the objects with ShouldTravel set to true by their corresponding velocity.
    
    

    If the m_TheSoccer.ShouldTravel were false, we could update the center of the soccer ball by:
        // move the soccer center by velocity

        m_TheSoccer.Center = m_TheSoccer.Center + m_BallVelocity;

    Much in the same way that we can assign one Vector2 object directly to another Vector2 object , we can also do addition on entire objects, as well (as we see here).

    • Note that this is a special property of the Vector2 data type - not all objects can be 'added' in this way.  (As a matter of fact, most objects CANNOT be added in this way, which makes the Vector2 somewhat unusual)
    • Let's say that the current position of the ball is (3.14f, 7.2f), and that the velocity of the ball is (0.1f, 0.2f), the following picture illustrates how the new position of the ball is calculated:
      
  • Following that, the center points of both paddles are echoed to the top status bar, and the center point of the soccer ball is echoed to the bottom status bar:
    EchoToTopStatus( "Left Paddle Center=" + m_LeftPaddle.Center + " Right Paddle Center=" + m_RightPaddle.Center);

    EchoToBottomStatus( "Soccer Ball position: " + m_TheSoccer.Center);

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.e.
2. Familiarizing Yourself With The Code: Making Minor Changes
   Using the same project that the above tutorial makes use of, try changing things, in order to make sure that you're familiar with how the code is set up.  Something things to try:
   1. Change the size of the paddles
      Make them wider & taller, or thinner & shorter
   2. Change the starting positions for the paddles.
      Can you have a paddle start off-screen?
   3. Put the soccer ball in a different starting location
   4. Change the size of the soccer ball. 
      If you do this, what happens to the texture?  Is it still the same size, or does it get scaled up (or scaled down) to match the size of the circle?
   5. Try changing the image for the soccer ball
      Find an image and try adding it to the project, and then set the soccer ball (or paddles) to show the image on screen.  You can find images online, or perhaps from a clip-art collection that office productivity applications (like the Microsoft Office Suite) come with. 
      • Note that if you intend to share your game (including posting the game online, or even just sharing it with friends & family), then you need to be aware of copyright issues, and make sure that you're using images that you can legally use.
   6. Change the range of the speed of the soccer ball
      Can you set it up so that (by changing the min & max possible values) that the soccer ball starts off at (essentially) one speed?
      Can you make the ball move more slowly?  More quickly?

	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