Simple Input and Output (I/O)

• Pre-requisite: it is assumed that you have read through the prior tutorials, and are familiar with basic I/O concepts, and how to echo messages to the top and bottom of the screen in an XNACS1Lib-based game
• It may be useful to refer to refer to the diagram illustrating the Draw-Update loop (which explains that your initialization code will be called once, and then the XNACS1Lib will repeatedly call your Update method (after which it will Draw the screen) ), in order to have a clear picture of how your game executes.

Goals:

• To gain experience writing code that interacts with users via the XNACS1Lib library.
• In this tutorial, we will:
  • Examine the code that produces the messages
  • Examine how comments can be used to leave notes for yourself & other programmers
  • Examine how comments can be used to temporarily remove code from your program without deleting it

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 .

Once we compile and run this project, the program display 'Thumbstick: {X:0 Y:0}" at the top of the screen. 

If you move the left thumbstick towards the right, you'll see the X value change in response. If you move the left thumbstick towards the left, you'll see the X value change to a negative value. Similarly with moving the left thumbstick forwards & backwards (sometimes described as "up and down"), you'll see the Y values change appropriately. 
The default keyboard to controller mapping assigned the J key to mean "push the thumbstick to the left", the K key to mean "push the thumbstick to the right", the I key to mean "push the thumbstick up", and the M key to mean "push the thumbstick to the down".

2. Background :  

I/O in the context of an interactive, graphical application (such as a video game) commonly consists of determining the current status of the various parts of the video game controller.  Is the 'A' button being pushed? Are the thumbsticks being held at an angle?  And if so, how far right/left or forwards/backwards are they being held?.  In this tutorial, we will examine how our code can detect input from the left thumbstick. 

For each of the thumbsticks, our C# code can determine if the thumbstick is being held at an angle, and if so, by how much.  As you will see in the example program, the current state of the thumbstick is expressed in C# as an (X,Y) pair, where the X value is how far left or right the thumbstick is being pushed, and the Y value is how far forwards or backwards it's being held.  If the thumbstick is not being pushed, then both the X and Y values should be 0.  These values can each range from -1 to +1.  Using an actual XBox controller, you'll see that these values are continuous , meaning that the X and Y values can be ANY number between -1 and +1.  If you're using the keyboard, you'll notice that you can only get -.75, 0, or +.75, because keyboard keys can only detect whether a key is being pushed down, not how hard the key is being pushed.

Before we go into the details of how to work with thumbstick input, it's worth taking a moment to consider what sorts of input a video game can and can't easily collected. Basically, anything on an XBox360 controller can be used as input.  There are a number of 'buttons' on the XBox controller - each of the A, B, X and Y buttons, the left and right bumpers, the Start and Back buttons, and the thumbsticks (which can be being pushed down, like a button) are buttons.  All of these buttons are either being pushed, or they're not - in this sense, they are discrete (meaning that have only one of a limited number of values).  As discussed above, the thumbsticks can be pushed forwards, backwards, or side to side, in which case they give continuous input (potentially any number between -1 and +1).  Keep in mind that for a normal video game, the player will NOT have a keyboard connected to their XBox360.  It's actually quick and painless to plug a USB keyboard into your XBox360, but since most people don't play games with such a keyboard already connected, we should avoid depending on the presence of a keyboard.

Finally, a quick note on this tutorial: the goal is to explore the principles of I/O for an interactive, graphical program (like a video-game), and not to examine all possible details of all possible inputs.  So for this tutorial, we will examine how to get input from only the left thumbstick.  We will leave the details of getting input from buttons, the right thumbstick, etc, etc, till later.

3. Examining The Program:

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

• InitializeWorld():
  Since we want the lower-left corner to still be at (0,0), and since we want the width of the window to be 100 units wide, InitializeWorld looks the same as in previous tutorials:

  protected override void   InitializeWorld() {     World.SetWorldCoordinate( new Vector2 (0,0), 100.0f); }

• UpdateWorld():

  We still have the 'exit when the user pushes the Back button' logic here, so that the player can actually quit the game when it's played on an XBox360. This is also where we read the current state of the left thumbstick, and then display a message at the top of the screen telling the user about the thumbstick.

  
  

  There are a number of new things here, for right now, we'll start by looking at the first couple of new lines, and ignore everything else in the method:

  protected override void   UpdateWorld() {    if ( GamePad.ButtonBackClicked())         this .Exit();           // Version #1:     EchoToTopStatus( "ThumbStick: " + GamePad.ThumbSticks.Left); }

• First, let's look at syntax issues (i.e., issues relating to 'what do you type?')
  • The method starts with the line " // Version #1: "
    • This is what is called a comment : it's something that a programmer wrote into the code, that C# will ignore.  This is useful for a couple of reasons, but the most important one is that it allows us to write normal, English notes for ourselves (and our co-workers) in our C# source code, without affecting the execution of our program.
    • There are a couple different ways you can create a comment.  What you see here is a single-line comment : it starts with the two forward-slash characters, right next to each other, with no space in between ( // ).  Staring with these two slashes, the C# compiler ignores anything else, until the line ends. In order to help visually remind you that this is actually a comment, Visual Studio draws the comment in a different color (normally green, as you see above)(you can change the color that Visual Studio uses, if you really want to)
    • You should try moving this comment down to the next line - put it the comment at the very end of the next line, so that the next line reads
      EchoToTopStatus( "ThumbStick: " + GamePad.ThumbSticks.Left); // Version #1:
      Everything should still compile and run just fine.
  • You'll notice that since we want to display a message to the top of the screen, we use the EchoToTopStatus command.  And since part of our message is some text, we will still enclose the text Thumbstick: in double quotes, like so: "ThumbStick: " .

    • Notice that the text "ThumbStick: " contains a blank space, right after the colon character, and before the closing double-quote.

  • In C# (and Java, and many other languages), if we want to join together some text and something else, we can do so using the + symbol. 

    Joining text with other text is called concatenation , so in this case, the + symbol represents the concatenation operator.

    • This symbol is also used to indicate addition, but only when you're using the + in between two numbers. 
    • Since stuff that's surrounded by double-quotes is (by definition) text in C#, C# knows to use the concatenation operator, even through the thumbstick is not text.  What happens is that C# automatically converts the Left thumbstick to being text, and then concatenates the two pieces of text together. 
      • If you're curious about how C# know how to convert a 'Thumbstick' to 'text': It doesn't.  The programmers who created the code that represents the thumbstick also wrote a quick command that will convert the current state of the thumbstick into appropriate text.
  • The next thing, GamePad.ThumbSticks.Left, identifies the part of the XBox360 controller that we want to output. 
    • After you've run the program, try deleting GamePad.ThumbSticks.Left, and then typing it in again, yourself.  You'll notice that Visual Studio will try to offer suggestions, in a drop-down list.  This feature is called IntelliSense, and is incredibly helpful.  At the same time, you don't want to end up in a job interview and find yourself unable to write even basic code on a whiteboard, nor do you want to lose points on a quiz or exam because you're used to Visual Studio being your crutch.  Instead, use IntelliSense to remind yourself of what you need to do only when you get stuck, while you are practicing writing code as much from memory as possible.  Do not rely on IntelliSense to write your code for you!!
• Second, let's look at semantic issues (i.e., issues relating to 'what does this mean?')
  • Since you're going to be seeing several different ways of doing this same thing, you'll notice that the comment serves as a note that this is Version #1. 
  • You should notice that when the concatenation operator asks the thumbstick to convert itself to text, the thumbstick produces the "{X:0 Y:0}" style output that you see on the screen.
    • Remember that on a keyboard the keys are discrete, binary inputs which means that have only 2 values: "pushed", or "not pushed".  In this case, when a key is pushed to go right, C# see the value +0.75 (left is -0.75, up is +0.75, and down is -0.75).  The thumbsticks are continuous, which means that they can take on any value between -1 and +1, depending on how much the thumbstick is being tilted.  Therefore, the exact values you see on your screen will depend on whether you're using a keyboard or controller, and if you're using a controller, how much you're pushing on the controller.
  • A very natural question to ask yourself is: "What if we wanted to produce different-looking output?"  We'll see how to do exactly this, in Version #3 of this tutorial.
    • Keep in mind, as you're learning how to program, that pushing yourself to figure out new things is extremely important.  Especially at this early stage, pushing yourself to figure out new things is almost more important than exactly what it is that you're figuring out.  Get in the habit of figuring how to do more than you're being told about, so that when it comes time for you to write a program for yourself, or your job, or an organization that you're volunteering at, you've already got the hang of figuring out things that you weren't specifically instructed about.

UpdateWorld(), Version #2

• Let's now examine the next couple lines of code in the UpdateWorld method, as we attempt to produce our own, custom format for the message at the top of the screen:

  protected override void  UpdateWorld() {    if (GamePad.ButtonBackClicked())         this .Exit();    // Version #1: Basic input, basic output    EchoToTopStatus( "ThumbStick: " + GamePad.ThumbSticks.Left);    // Version #2:    //EchoToTopStatus("ThumbStick: X is " + GamePad.ThumbSticks.Left.X);

• If you look at the next couple of lines of C# source code, you'll notice that both lines start with //, meaning that both lines are comments.  First first of these lines (" // Version #2: ") actually does contain a comment.  The second line contains actual code, but because the line starts with a comment, that code will NOT be included in the final program.  That line of code has been commented out .  This is a very useful trick to learn, because it allows you to remove a line of code from your program without permanently deleting that code .  This means that if a line of code is giving you trouble, you can temporarily remove it by commenting it out.  Similarly, you put the code back into the program by uncommenting the commented out code.  Right now, you should comment out the first statement, and uncomment the second statement, so that your code looks equivalent like the following (don't do anything about the rest of the method).
  

  protected override void UpdateWorld() {     if (GamePad.ButtonBackClicked())         this .Exit();          // Version #1: Basic input, basic output     // EchoToTopStatus("ThumbStick: " + GamePad.ThumbSticks.Left);     // Version #2:     EchoToTopStatus( "ThumbStick: X is " + GamePad.ThumbSticks.Left.X);

  
  NOTE: that since the " // Version #2: " line is intended to be a comment, we do NOT remove the // from the start of it.

• At this point, everything should compile and run just fine.  Notice the message that you're seeing at the top of the screen.
• Notice that the only thing we've changed about the code is that we've added a .X onto the end, and we modified the message text.  What we're doing here is telling C# that we're not interested in the entire left thumbstick, just the X (horizontal) part. 
• Let's say that we wanted to produce a custom message, but one that displays both the X and Y values of the left thumbstick. One approach would be to display the X on the top of the screen, and Y on the bottom of the screen, but what do we do if we want to output multiple items on the same line?

UpdateWorld(), Version #3

• Comment out Version #2, and uncomment Version #3, and your program should compile and run.  When run, you should see " ThumbStick: X is 0 Thumbstick: Y is 0 " at the top of the screen (until you move the thumbstick, that is :)  ).
  • Notice that this tutorial is NOT showing what the code looks like after commenting out Version #2, and uncommenting Version #3.  This is done purposefully, to help push you to make sure that you're really able to do this on your own, and that you're not just blindly repeating the instructions here without actually thinking about it. This trend will continue as you go through the tutorials, so make sure that you have a solid understanding of everything that's been covered in each tutorial before going on to subsequent tutorials!
• You'll notice that we accomplish the goal of outputting multiple items by repeatedly using the concatenation operator.

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 referring 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. After you work the tutorial's "Version #2" material, try doing the following:
   • Make sure that you can change the message text to something else.  Maybe try setting things up so that the message like I simply cannot believe it, but the current X value of  the thumbstick is 0 are displayed in the top status bar.
   • See if you can get the value of X to show up BEFORE the message text.  So something like 0 is the current value of X would be a good message to print.
   • Can you get the value of X to show up at the top of the screen, and the value of Y at the bottom?  What about showing the X (or Y) value at both the top AND bottom of the screen?
3. If you uncomment Version #2, but you DO NOT COMMENT OUT Version #1, you still get the same message as the one you see when the follow the directions for Version #2.  Why?
   • Hint: Make sure that you can explain what's going on, using the 'sequence' concept from previous exercises

	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