Pointer

Pointer is not creatable, there's only one instance of it. It can only be accessed through its globally exposed variable.

Pointer is a shortcut to Client.Pointer.

Pointer allows to catch user pointer events. (mouse events or touch events depending on the device)

It's a useful abstraction allowing inputs to work on any platform. (PC, mobile, web, etc.)

⚠️ Even if there's no such thing as a visual pointer on a touch screen, we do consider 2 modes: pointer shown and pointer hidden.

Pointer Shown

Switching to that mode when calling Pointer:Show().

When the pointer is "shown":

Pointer.Click, Pointer.Down and Pointer.Up functions are called on left clicks or one finger touches (when the action is not caught by a button or some other LocalEvent listener first).

Pointer.Drag is called when moving the mouse or finger between down and up events.

Pointer.Drag2 is called when moving the mouse while pressing right click, or moving on a touch screen with 2 fingers down.

Pointer.Zoom is called scrolling with the mouse wheel or pinching in/out with 2 fingers.

These actions are disabled: Client.AnalogPad, Client.Action2, Client.Action2Release, Client.Action3, Client.Action3Release

(Client.DirectionalPad, Client.Action1 & Client.Action1Release remain available)

Pointer hidden

Switching to that mode when calling Pointer:Hide().

When the pointer is "hidden":

Client.DirectionalPad is called when activating directional keys (WASD keys on a QWERTY keyboard by default) or the directional pad on touch screens (available in both modes).

Client.AnalogPad is called when moving the mouse or moving on a touch screen with one finger down. It's often used to control the camera.

All 3 action buttons are available: Client.Action1, Client.Action1Release, Client.Action2, Client.Action2Release, Client.Action3, Client.Action3Release

Functions

nil Hide ( )

Virtual game pads appear on touch screens.

Direction keys and gamepad start triggering Client.DirectionDidChange

The pointer is hidden by default.

Pointer:Hide()
nil Show ( )

Pointer callbacks start being triggered on mouse and touch events.

User interface elements such as Buttons become active.

Pointer:Show()

Properties

function Cancel

Triggered after a down event, if the pointer action is interrupted by another event (releasing outside the app, phone call, etc).

Pointer.Cancel = function()
    -- cleanup some variables
end
function Click

Triggered when pressing and releasing pointer at same position (left mouse button click or one touch finger down and up).
The callback parameter is a PointerEvent.

Pointer.Click = function(pointerEvent)
    print(pointerEvent.X, pointerEvent.Y)
end
function Down

Triggered when pressing the pointer (left mouse button or one touch finger down).
The callback parameter is a PointerEvent.

Pointer.Down = function(pointerEvent)
    print(pointerEvent.X, pointerEvent.Y)
end
function Drag

Triggered every frame the pointer is moved after a drag motion started.
The callback parameter is a PointerEvent with non-zero DX and DY values.

Pointer.Drag = function(pointerEvent)
    print(pointerEvent.DX, pointerEvent.DY)
end
function Drag2

Triggered every frame the pointer is moved after a drag2 motion started (right mouse button or 2 touch fingers).
The callback parameter is a PointerEvent with non-zero DX and DY values.

Pointer.Drag2 = function(pointerEvent)
    print(pointerEvent.DX, pointerEvent.DY)
end
function Drag2Begin

Triggered when the pointer is moved with right mouse button or 2 touch fingers down, starting a drag2 motion.

Pointer.Drag2Begin = function()
    -- initialize some variables
end
function Drag2End

Triggered when the pointer is released during a drag2 motion, ending it.

Pointer.Drag2End = function()
    -- cleanup some variables
end
function DragBegin

Triggered when the pointer is moved while down, starting a drag motion.

Pointer.DragBegin = function()
    -- initialize some variables
end
function DragEnd

Triggered when the pointer is released during a drag motion, ending it.

Pointer.DragEnd = function()
    -- cleanup some variables
end
boolean IsHidden read-only

True if the Pointer is hidden, false otherwise.

Pointer:Show()
print(Pointer.IsHidden) -- false
Pointer:Hide()
print(Pointer.IsHidden) -- true
function LongPress

Triggered when pressing for a long time without moving.
The callback parameter is a PointerEvent.

Pointer.LongPress = function(pointerEvent)
    local impact = pointerEvent:CastRay()
    if impact.Block ~= nil then
        impact.Block:Remove()
    end
end
function Up

Triggered when the pointer is released.
The callback parameter is a PointerEvent.

Pointer.Up = function(pointerEvent)
    print(pointerEvent.X, pointerEvent.Y)
end
function Zoom

Triggered when scrolling with mouse wheel or pinching in/out with 2 fingers.

Pointer.Zoom = function(zoomValue)
    -- example: move the camera forward/backward based on the zoom value
    Camera.Position = Camera.Position + Camera.Forward * zoomSpeed * zoomValue
end