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.

The goal is to create an abstraction for world inputs to work on any platform. A world that's been developped on PC should work great on mobile, and the developer shouldn't have to worry about this.

So 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, users can activate UI buttons.

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 other UI input 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. (we don't support right click up/down events because we can't get the same level of precision on a touch screen)

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

Some actions are disabled when the pointer is shown (like Client.AnalogPad, Client.Action2, Client.Action2Release, Client.Action3, Client.Action3Release)

But Client.DirectionalPad, Client.Action1 & Client.Action1Release remain available.

Pointer hidden

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

When the pointer is hidden, you can't select things in the 3D scene with the mouse cursor or fingers. But you other actions are available:

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 when the system interrupts the app during a pointer motion.

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

Triggered when pressing the pointer (left mouse button or one touch finger down).

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

Triggered every frame the pointer is moved after a drag motion started.

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

Triggered every frame the pointer is moved after a drag2 motion started.

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

Tiggered when pressing for a long time without moving.

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.

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

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

Pointer.Zoom = function(zoomValue)
    -- for example, move the camera back and forth
    Camera.Position = Camera.Position + Camera.Forward * zoomSpeed * zoomValue
    -- we could also play with Camera.FieldOfView for a more convincing zoom effect,
    -- use a velocity-based zoom to have a smooth motion, or any other custom logic
end