Input Overview

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.

Note

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

Keyboard

> 100

0

No

Yes

Yes

1

Mouse

5

3

No

Yes

No

1

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.

Mouse

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.

Not all mouse devices support all buttons; for example, older mouse devices may not support the MiddleButton, XButton1 and XButton2 properties.

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.

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.