Mouse

The Mouse object allows projects to respond to mouse input.

Note on the modern web it is naïve to assume all users have a mouse. Many users now browse the web with touch-screen devices that have no mouse. Therefore if your game uses exclusively mouse or keyboard control, it is impossible to use on touch devices. See the Touch controls tutorial for an alternative control system.

If you only use left clicks, consider instead using the Touch object with Use Mouse Input enabled. This will allow your game to work on touchscreen devices without any further changes.

Mouse conditions

Cursor is over object
True if the mouse cursor is hovering over an object.
Mouse button is down
True if a given mouse button (left, middle or right) is currently being held down.
On any click
Triggered when any mouse button is clicked. Useful for title screens or cutscenes.
On button released
Triggered when a given mouse button is released.
On click
Triggered when a given mouse button is pressed. This can also be used to detect double-clicks.
On mouse wheel
Triggered when the mouse wheel (if any) is scrolled up or down a notch.
On object clicked
Triggered when a given mouse button is pressed while the mouse cursor is over an object. This can also be used to detect double-clicks on objects.
Has pointer lock
True if pointer lock is currently active, i.e. after On pointer locked triggered.
On movement
Triggered every time the mouse moves, or any touch input moves. The MovementX and MovementY expressions provide the amount of movement. This can be used without pointer lock, but mouse movement will still be limited by the boundaries of the window or screen. Since this trigger also works with touch input, it means movement input also works with touch input on mobile devices. Usage with touch input does not require pointer lock, since that only affects the mouse cursor.
On pointer locked
Triggered when the pointer is successfully locked after the Request pointer lock action. The mouse cursor will disappear and only mouse movement values will be available via the On movement trigger.
On pointer unlocked
Triggered when pointer lock is released, restoring the normal mouse cursor behavior. This can happen either by the Release pointer lock action, or at any time if the user manually exits pointer lock, such as by pressing Escape.
On pointer lock error
Triggered if an error occurs attempting to use pointer lock, such as attempting to acquire pointer lock when security restrictions disallow it.

Mouse actions

Set cursor from sprite
Set the cursor image from a Sprite object. This is preferable to setting a sprite to the mouse co-ordinates, because the input lag is significantly lower. Various limitations apply: the sprite image is used as it appears in the image editor, not taking in to account size or rotation in the layout; the image cannot be too large (64x64 is usually the limit); and support varies depending on browser and OS.
Set cursor style
Set the type of mouse cursor showing. The cursor can be hidden completely by choosing None.
Request pointer lock
Request to acquire pointer lock, which hides the mouse cursor and only reports mouse movement values via the On movement trigger and MovementX and MovementY expressions. This allows continuous input without the boundaries of the window or screen stopping movement. This type of input is useful for "mouse look" with the 3D Camera object (see First-person platformer for an example). Normally this can only be used in a user input trigger, such as On click. On pointer locked is triggered if the request is successful, but the request may be denied, for example due to security restrictions, in which case On pointer lock error will trigger. Also note the user can also exit pointer lock at any time, triggering On pointer unlocked.
Release pointer lock
If pointer lock is active, this ends pointer lock and restores the normal mouse cursor behavior.

Mouse expressions

AbsoluteX
AbsoluteY
Return the position of the mouse cursor over the canvas area in the page. This is (0, 0) at the top left of the canvas and goes up to the window size. It is not affected by any scrolling or scaling in the game.
X
Y
Return the position of the mouse cursor in game co-ordinates. This is (0, 0) at the top left of the layout. It changes to reflect scrolling and scaling. However, if an individual layer has been scrolled, scaled or rotated, these expressions do not take that in to account - for that case, use the layer versions below.
X(layer)
Y(layer)
Return the position of the mouse cursor in game co-ordinates, with scrolling, scaling and rotation taken in to account for the given layer. The layer can be identified either by a string of its name or its zero-based index, e.g. Mouse.X("HUD").
MovementX
MovementY
In the trigger On movement, these values provide the amount of horizontal and vertical movement.
Construct 3 Manual 2021-10-19