Input is a general term referring to the process of receiving actions from the user. In XNA Game Studio, the Microsoft.Xna.Framework.Input namespace provides support for all input devices.
|APIs related to input devices physically not available in your game are always available to your code. For example, you can access the Mouse API on Zune, but you cannot retrieve the relevant mouse position. Also, you should not expect an exception or build error when you access APIs related to unavailable input devices.|
Xbox 360 Controller, Mouse, and Keyboard
The Xbox 360 Controller, the keyboard, and the mouse are common input devices. What follows is the differences between these input devices and guidelines for how to use them with your game.
Digital vs. Analog
Input devices have two types of controls: digital and analog. Digital controls report only two possible states—on and off—and are represented by Boolean values. Examples of digital controls are the START button on the Xbox 360 Controller and any button on a keyboard.
Analog controls report a range of values, rather than just off and on. Examples of analog controls are the Xbox 360 Controller stick and the movements of the mouse. Analog values can be represented in a variety of ways. In XNA Game Studio, an analog value on the Xbox 360 Controller is represented as a floating-point value between −1.0 and 1.0 for the sticks, and between 0.0 and 1.0 for the triggers. For the mouse, XNA Game Studio reports mouse cursor values in pixels.
Polling and States
For all input devices in XNA Game Studio, input is received from the user by way of polling: each frame, call a function to receive the current state of an input device, and compare to previous states if necessary. A state is a snapshot of an input device's interactions from the user. At any given moment, a control may have a variety of buttons pressed, analog sticks or triggers held in a direction. The current positions of these buttons and analog controls are reported in a state structure. The following sections describe the methods for retrieving and using state for each input device.
Input Device Types
Each input device has specific advantages and disadvantages. The following table shows a brief comparison of three devices.
|Input Device||Digital Buttons||Analog Controls||Vibration Effects||Supported on Windows||Supported on Xbox 360||Number Allowed on System|
|Xbox 360 Controller||14||4||Yes||Yes||Yes||4|
Xbox 360 Controller
The Xbox 360 Controller provides a good combination of digital buttons and analog sticks, so that many types of games can be played with it.
The controller can be used on either Windows or Xbox 360 systems. Up to four controllers are supported.
How to Use
- Each frame of your game, call the static GetState method from the GamePad class.
- Pass in the index of the player you wish to query. The player associated with a controller is visible on the Ring of Light on the controller.
Query the GamePadState structure you get back to retrieve information on the state of the controller. For more information on retrieving state, including how to determine whether the user has pressed or released a button since the last frame, see How To: Detect Whether a Controller Button Is Pressed.
You may store a previous controller state if you wish to compare states to determine input changes from one frame to the next.
|Controllers may become disconnected during normal gameplay. For information on how to properly detect and handle this situation, see How To: Detect Whether a Controller Is Disconnected.|
The keyboard, with a multitude of digital buttons, is best for complicated simulations with many functions, or when typing text is necessary—but a keyboard has no analog controls for precise movement.
Not all keyboards support the entire range of buttons listed in Keys; for example, older keyboards may not support the VolumeDown, VolumeUp, and VolumeMute members.
If the user's keyboard is connected via USB, it can be used on a Windows system, or on an Xbox 360.
How to Use
- Each frame of your game, call the static GetState method from the Keyboard class.
Query the KeyboardState structure you get back to retrieve information on the state of the keyboard.
You may store a previous keyboard state if you wish to compare states to determine input changes from one frame to the next. See How To: Detect Whether a Key Is Pressed for more information.
The mouse, with its precise analog control, is best for selecting objects, such as in a strategy game, or for moving a viewport, such as in a first-person action game—but a mouse has few digital buttons. Modern mouse devices have three extra buttons in addition to the standard left and right buttons: two digital buttons, usually on the side of the mouse, and a digital button that is activated by clicking down on the scroll wheel. The scroll wheel itself functions as an extra analog control in two directions, but does not provide precise input.
You can set the Game.IsMouseVisible Property to true to make the mouse cursor visible; use the default (false) if you are drawing your own cursor or don't want a cursor.
Mouse devices are used on Windows systems only. They are not supported on Xbox 360.
How to Use
- Each frame of your game, call the static GetState method from the Mouse class.
Query the MouseState structure that is returned to retrieve information on the state of the mouse. Mouse coordinates are relative to the upper-left corner of the game window.
You may store a previous mouse state if you wish to compare states to determine input changes from one frame to the next.
For more information on mouse state, including an example, see How To: Get the Current Mouse Position (Windows).
Input on Zune
Zune devices have two digital buttons, and a ZunePad that is an analog control. The two buttons are the Start and Back buttons. The ZunePad features directional input that is retrieved with the GamePad.GetState method. The Back button maps to GamePadState.Buttons.Back, and the Play/pause button maps to GamePadState.Buttons.B.
For more information, see Zune Programming Considerations.