Mouse

BeginnerProgrammer

The mouse is a common input device for desktop games.

There are two ways to handle mouse input in Xenko:

• Query mouse button states.
• For cross-platform games that target mobile devices, you can use PointerEvent lists.For more information, see Pointers.You can access mouse button states and pointer events list from the Input manager.

For more information about these options, see the Input index.

Check mouse availability

Before handling mouse input, use Input.HasMouse to check if a mouse is connected.

Get the mouse position

You can get the mouse position in normalized or absolute coordinates.

Normalized coordinates

MousePosition returns the mouse pointer position in normalized X, Y coordinates instead of actual screen sizes in pixels. This means the pointer position adjusts to any resolution and you don't have to write separate code for different resolutions.

• (0,0): the pointer is in the top-left corner of the screen
• (1,1): the pointer is in the bottom-right corner of the screen

Absolute coordinates

InputManager.AbsoluteMousePosition returns the mouse pointer position in absolute X and Y coordinates (the actual screen size in pixels). For example, if the pointer is in the top-left corner of the screen, the values are (0,0). If the pointer is in the bottom-right corner, the values depends on the screen resolution (eg 1280, 720).

Tip

To get the actual size of the screen, access IPointerDevice.SurfaceSize. For example:

var surfaceSize = Input.Mouse.SurfaceSize;

Query mouse button state changes

You can use the mouse buttons to trigger actions in a project. For example, in first-person shooter games, the left mouse button is commonly used to shoot.

The Input manager has several methods that check mouse button states (Pressed, Down, or Released):

Mouse delta

Use InputManager.MouseDelta to get the change in mouse position in normalized coordinates since the last update. You can use this to analyze mouse movement speed and direction.

Mouse wheel delta

You can use the mouse wheel to trigger actions in a project. For example, in a first-person shooter game, moving the mouse wheel might switch weapons or zoom a camera.

The InputManager.MouseWheelDelta returns a positive value when the user scrolls forwards and a negative value when the user scrolls backwards. A value of 0 indicates no movement.

Lock the mouse position

For some projects, the user needs to move the mouse cursor beyond the borders of the screen. For example, first-person shooter games usually need 360-degree camera rotation. In these cases, you also probably want the mouse cursor to be hidden.

You can lock the mouse position and hide the cursor with the following properties and methods:

Tip

You can get or set mouse visibility with GameWindow.IsMouseVisible.

Example code

public class MouseInputScript : SyncScript
{
    public override void Update()
    {
        //If the left mouse button is pressed in this update, do something.
        if (Input.IsMouseButtonDown(MouseButton.Left))
        {   
        }
        //If the middle mouse button has been pressed since the last update, do something.
        if (Input.IsMouseButtonPressed(MouseButton.Middle))
        {  
        }
        //If the mouse moved more than 0.2 units of the screen size in X direction, do something.
        if (Input.MouseDelta.X > 0.2f)
        {
        }
    }
}

See also

• Pointers
• Virtual buttons
• Keyboard
• Gamepads
• Input overview