Mouse inputs

This module introduce the MouseInput component that enables interactions through local events between game objects and the mouse.

Setup

Add a mouse input component on a game object that already has a camera component with gameObject:AddComponent("MouseInput"[, params])or MouseInput.New( gameObject[, params]).
When you are in the scene editor, you can add the MouseInput scripted behavior instead.

Set some tag(s) on the game objects the component works with (which game objects are checked against the position of the mouse cursor), then pass them as argument of the mouseInput:SetTags( { "tags" } ) function. In the scene editor, you can concatenate several tags with a coma in the tags field.

Then setup a "LeftMouse", "RightMouse", "WheelUp" and "WheelDown" button in your game controls (in the Administration > Game Controls tab).
Not setting one of these buttons will throw an harmless error message in the Runtime Report when the game loads. You may setup a button and not bind it to any key to prevent it.

Mouse events

The OnMouseEnter event is fired at a game object when it is hovered by the mouse for the first time (it is hovered this frame, but it wasn't the last frame).

The OnMouseOver event is fired at a game object each frame that the mouse moves or a button is clicked, kept down or released and the mouse hovers it.

The OnMouseExit event is fired at a game object the frame the mouse stops hovering it (it is not hovered this frame but was hovered the last frame).

The isMouveOver property on a game object tells if it is currently hovered by the mouse. The property is true when the game object is hovered, or false (or nil) otherwise.

Note that a game object may be considered hovered by the mouse even if it's not visible from a camera because it is hidden by another game object in front of it.

Click events

The OnClick (for a single left click (the LeftMouse button was pressed)), OnDoubleClick (for a double left click), OnLeftClickReleased (the LeftMouse button was released) and OnRightClick (the RightMouse button was pressed) events are fired at a game object when the click happens while the mouse hovers the game object.

A double click is two left clicks separated by no more than 20 frames (1/3 of a second).
You can update this value at runtime via the MouseInput.Config.doubleClickDelay property (a number of frames) or by setting the MouseInput.UserConfig() function to return a table with doubleClickDelay as key and a number as value.

function MouseInput.UserConfig()
    return {
        doubleClickDelay = 20, -- Maximum number of frames between two clicks of the left mouse button to be considered as a double click
    }
end

Wheel events

If you did setup a "WheelUp" and "WheelDown" button in you game controls, the OnWheelUp and OnWheelDown events will be fired at the hovered game objects whenever the mouse wheel is rolled up or down.
"Wheel up" is rolling the wheel toward you.