What is it ?
XGameInput is a GameComponent for the XNA framework that provides the programmer
with
a single point of access to user control input via a XBox 360 gamepad, keyboard
or mouse.
How does it work ?
The component is partially based on the Beta 1 gamepad helper files provided by
Microsoft
as
part of the SpaceWars starter kit but with the addition of mouse and keyboard support.
The component allows the user to create named control inputs and assign these named
inputs to a control source.
How do I use it ?
The source code is provided as a Zip file which contains the complete Visual
Studio
Express project including the component and a small test program that demonstrates
its
use.
Extract the Zip file to a directory of your choosing then open the XGameInput
solution into VSE. You should see two projects, one is the component, the other
the
test harness. Select Build Solution (F6) from the Build menu to build the component
and test harness. If the build is successful, the component should exist as XGameInput.dll
in the Release directory of the component project.
First you need to add a reference to the component DLL in your game project. To
do this,
right click References in the Solution Explorer for your game.
Choose Add Reference...
then select the Browse tab. Browse to the XGameInput.DLL file in the /Release directory
of the component and select it. You can now use the component in your game using
the
instructions below.
Initialisation
At the top of the main game source file add :
In your variables section add :
|
|
private XGameInput m_input = null; |
In the Initialize method in your game you need to create an instance
of XGameLineInput, configure
it then add it to the component list.
Creating Control Inputs
To use the component, you assign named controls for each of the users you
wish to support in your game. When you assign a control input, you specifiy
whether it is a 'stick' input which has an analogue value such as the gamepad
left and right sticks, or the mouse X and Y coordinates or a 'switch' input
such as the A,B,X and Y buttons on the gamepad, the mouse buttons or a keyboard
key. The two triggers on the XBox 360 controller are slightly different in that
they can be assigned a 'stick' type and will return an anaogue value proportional
to the amount of movement of the trigger or a 'switch' type which will return 0
if the trigger is not pressed or 1 if pressed.
You assign a named control using the AddPlayerControl
method.
The code below shows an example of assigning control inputs for a single player
game. This code can be placed in the game initialize method or in another suitable
initialisation routine of your choice.
|
|
protected override void Initialize()
{
m_input = new XGameInput( this );
m_input.AddPlayerControl(PlayerIndex.One,"LeftRight",XGameControlInput.ControlInputType.Stick);
m_input.AddPlayerControl(PlayerIndex.One,"UpDown",XGameControlInput.ControlInputType.Stick);
m_input.AddPlayerControl(PlayerIndex.One,"Fire",XGameControlInput.ControlInputType.Switch);
... |
The above code creates an instance of XGameInput then defines three control inputs,
two being analogue inputs (Stick) and
one being a digital input (Switch).
Attaching Control Inputs
Now the control inputs have been assigned, they need to be attached
to a particular
input source such as a gamepad, keyboard or mouse. To attach an input source you
use the AssignControlInput method as shown
in the example below.
|
|
m_input.AssignControlInput(PlayerIndex.One,"LeftRight",XGameInput.XGameInputPad.ThumbstickRightX);
m_input.AssignControlInput(PlayerIndex.One,"UpDown",XGameInput.XGameInputPad.ThumbstickRightY);
m_input.AssignControlInput(PlayerIndex.One,"Fire",XGameInput.XGameInputPad.LeftTrigger);
|
The above code has assigned the right thumbstick on the gamepad to the "Left/Right"
and "Up/Down"
functions and the left trigger to the "Fire" function.
Reading the Input
At this point, you are now ready to read the control inputs and use them in your
game.
To read the state of the specified inputs, you use the
ControlState method as shown
in the example below. This will typically be done in the Update method.
|
|
float lr,ud,fire;
lr = m_input.ControlState(PlayerIndex.One,"LeftRight");
ud = m_input.ControlState(PlayerIndex.One,"UpDown");
fire = m_input.ControlState(PlayerIndex.One,"Fire"); |
The values returned are :
|
|
- -1.0 to +1.0 for an analogue input (Stick).
- 0.0 or +1.0 for a digital input (Switch).
- 0.0 to +1.0 for a mouse position (Stick).
- 0.0 to +1.0 for an XBox360 controller left or right trigger (Stick).
|
Error Codes
The XGameInput component returns error codes which should be handled
by your code.
AddPlayerControl can return the following
errors :
XGameInputError.None
No errors occurred.
XGameInputError.ControlExists
A control with the specified name has already been defined for the specified
user.
AssignControlInput can return the following
errors :
XGameInputError.None
No errors occurred.
XGameInputError.BadControlSourceType
You are trying to assign a digital input to a control defined as being analogue
(Stick)
or an analogue input to a control defined as a digital input (Switch).
XGameInputError.UndefinedControl
You are trying to assign a input source to a control function that has not been
defined.
ControlState returns a floating point number
based on the control input however,
if an invalid control name is specified then it will return -99.
Finally
The beauty of the XGameInput component is the ability to rapidly
change the input control
type. To change the above example from using the Gamepad to using the mouse simply
requires
the following changes.
|
|
m_input.AssignControlInput(PlayerIndex.One,"LeftRight",XGameInput.XGameInputMouse.MouseX);
m_input.AssignControlInput(PlayerIndex.One,"UpDown",XGameInput.XGameInputMouse.MouseY);
m_input.AssignControlInput(PlayerIndex.One,"Fire",XGameInput.XGameInputMouse.MouseLeftButton); |
To turn the analogue mouse positions into a screen coordinate, multiply
the position returned
by the pixel width and height of your game as shown in the example below.
|
|
float lr,ud,fire;
int x,y;
lr = m_input.ControlState(PlayerIndex.One,"LeftRight");
ud = m_input.ControlState(PlayerIndex.One,"UpDown");
fire = m_input.ControlState(PlayerIndex.One,"Fire");
// For an 800x600 screen
x = (int)(lr * 800);
y = (int)(ud * 600); |
To make use of the keyboard, use the input type Keys as shown in the example below.
|
|
m_input.AssignControlInput(PlayerIndex.One,"Fire",Keys.F1); |
|