# Input & Motion

Touches, gestures, keyboard, mouse and device sensors

[Reference](index.md)

<a id="section-Guides"></a>

## Guides

<a id="Input-in-Codea"></a>

### Input in Codea

Respond to touches and key presses with functions such as `touched(touch)` and `keyPressed(press)`. You can also check what is happening in `draw()`: `key.pressing(key.space)` tells you whether Space is held, and `mouse.x` gives the pointer position.

Touch and keyboard events are delivered before `draw()` runs, so the state you read in `draw()` is up to date for that frame.

## Touches

Define a global `touched(touch)` function to receive touches. It is called each time a touch changes: when a finger goes down, every time it moves, and when it lifts. On a Mac, or an iPad with a mouse or trackpad, a click arrives as a touch of type `touch.pointer`.

```lua
local touches = {}

function touched(touch)
    if touch.ended or touch.cancelled then
        touches[touch.id] = nil
    else
        touches[touch.id] = touch.pos
    end
end

function draw()
    background(40)
    fill(255, 100, 100)
    for id, pos in pairs(touches) do
        ellipse(pos.x, pos.y, 60, 60)
    end
end
```

Each touch provides:

- `touch.id`, a number that stays the same for the life of the touch
- `touch.x`, `touch.y` and `touch.pos`, the current position
- `touch.prevX`, `touch.prevY` and `touch.prevPos`, the position at the previous event
- `touch.deltaX`, `touch.deltaY` and `touch.delta`, the movement since the previous event
- `touch.began`, `touch.changed`, `touch.ended` and `touch.cancelled`, which are true in the matching phase (`touch.moving` is the same as `touch.changed`)
- `touch.state`, the phase as one of `BEGAN`, `CHANGED`, `ENDED` or `CANCELLED` (`MOVING` is the same value as `CHANGED`)
- `touch.tapCount`, the number of quick taps in a row
- `touch.type`, one of `touch.direct`, `touch.indirect`, `touch.pencil` or `touch.pointer`

Positions are in screen coordinates with the origin at the bottom left. Apple Pencil touches also report `force`, `maxForce`, `azimuth`, `altitude`, `precisePos` and `precisePrevPos`.

To poll instead of using the callback, read `touch.current`. It holds the first touch that is down, and keeps its last state after it ends.

```lua
function draw()
    background(40)
    local t = touch.current
    if t.began or t.changed then
        fill(255)
        ellipse(t.x, t.y, 80, 80)
    end
end
```

## Touching Entities

Entities in `scene.main` receive touches through a `touched` method. Return `true` when the touch begins to keep receiving it until it ends. A touch kept by an entity is not passed to the global `touched` function.

```lua
function setup()
    scn = scene()
    scene.main = scn

    local e = scn:entity()
    function e:touched(touch)
        if touch.began then
            print("began", touch.x, touch.y)
        elseif touch.ended then
            print("ended")
        end
        return true
    end
end
```

Without hit testing, every entity with a `touched` method is offered every new touch. Set `entity.hitTest = true` to offer it only touches that land on its 2D or 3D physics body, as seen by the scene’s camera. For a 3D body the method also receives the raycast hit as a second argument.

Inside a callback, `touch:makeExclusive(entity)` gives a touch to that entity alone, and `touch:cancel(scene)` ends it for every entity in the scene that holds it.

## Gestures

Gesture recognizers use the system’s tap, pan, pinch and rotation recognizers and call a function with a [`gesture`](#gesture) when they fire. Keep a reference to each recognizer you create. It stops working once it is garbage collected.

```lua
function setup()
    zoom = 1
    offset = vec2(0, 0)

    pinch = gesture.pinch(function(g)
        zoom = zoom * g.pinchDelta
    end)

    pan = gesture.pan(function(g)
        offset = offset + g.delta
    end, 2, 2)

    doubleTap = gesture.tap(function(g)
        zoom = 1
        offset = vec2(0, 0)
    end, 2)
end

function draw()
    background(40)
    fill(100, 180, 255)
    local size = 120 * zoom
    rect(WIDTH/2 + offset.x - size/2, HEIGHT/2 + offset.y - size/2, size, size)
end
```

A two finger pan moves the square, a pinch scales it, and a double tap resets it. By default a touch is handled by one recognizer at a time. Give recognizers the same non-zero `group` to let them run together, for example `pinch.group = 1` and `pan.group = 1`.

## Keyboard

Hardware keyboards are supported on iPhone, iPad and Mac. The on-screen keyboard is described below.

Read key state from `draw()` with the [`key`](#section-Keyboard) functions. `key.pressing` is true while a key is held. `key.wasPressed` and `key.wasReleased` are true only in the frame where the key went down or came up.

```lua
function setup()
    pos = vec2(WIDTH/2, HEIGHT/2)
end

function draw()
    background(40)
    local speed = 300 * time.delta
    if key.pressing(key.left) then pos.x = pos.x - speed end
    if key.pressing(key.right) then pos.x = pos.x + speed end
    if key.pressing(key.up) then pos.y = pos.y + speed end
    if key.pressing(key.down) then pos.y = pos.y - speed end
    if key.wasPressed(key.space) then print("jump") end

    fill(255)
    ellipse(pos.x, pos.y, 60, 60)
end
```

To react to each key as it happens, define `keyPressed(press)` and `keyReleased(press)`. The [`key.press`](#key.press) passed in holds the `keyCode`, the `modifierFlags` held at the time, and the `characters` the key typed. Use `characters` for shortcuts and individual key actions. For editable text,
use `keyboard.text` as shown below: it handles Unicode, autocorrection, pasting,
and composed characters without slicing UTF-8 strings yourself.

`keyPressed` and `keyReleased` are not called while a user interface text field has focus.

Modifier keys are reported as a bit field. `key.modifiersPressed(key.cmd)` is true while either Command key is held. Combine masks with `|` to require several at once:

```lua
function keyPressed(press)
    if press.keyCode == key.s and key.modifiersPressed(key.cmd | key.shift) then
        print("save as")
    end
end
```

## On-Screen Keyboard

Call `keyboard.show()` to bring up the on-screen keyboard and `keyboard.hide()` to put it away. `keyboard.visible` is true while it is on screen. Touching the screen does not dismiss it.

What the player types collects in `keyboard.text`, including autocorrected and pasted text and the characters of languages such as Korean, which are composed as they are typed. Each insertion also calls `keyPressed`, so code written for a hardware keyboard keeps working.

```lua
function setup()
    keyboard.show()
end

function keyPressed(press)
    if press.keyCode == key.enter then
        print("You typed " .. keyboard.text)
        keyboard.text = ""
    end
end

function draw()
    background(40)
    fill(255)
    text(keyboard.text, WIDTH/2, HEIGHT - 100)
end
```

## Mouse and Trackpad

On a Mac, or an iPad with a mouse or trackpad, the global `mouse` holds the pointer state. `mouse.active` is true while a mouse or trackpad is connected.

```lua
function draw()
    background(40)
    if mouse.left.pressed then
        fill(255, 200, 0)
    else
        fill(255)
    end
    ellipse(mouse.x, mouse.y, 40, 40)
end
```

`mouse.x` and `mouse.y` follow the pointer while it hovers and while a button is held. `mouse.delta` and `mouse.scroll` hold the movement and scrolling since the last frame. Set `mouse.visible = false` to hide the system pointer over the viewer.

Two callbacks report pointer activity. `hover(gesture)` is called as the pointer moves over the viewer with no button held, and `scroll(gesture)` is called for trackpad and scroll wheel scrolling. Both receive a [`gesture`](#gesture) whose `location` is the pointer position. For `scroll`, `gesture.delta` is the scroll movement since the previous call, with positive `y` meaning up.

```lua
local scrollY = 0
local hoverX, hoverY = 0, 0

function scroll(gesture)
    scrollY = scrollY + gesture.delta.y
end

function hover(gesture)
    hoverX, hoverY = gesture.location.x, gesture.location.y
end

function draw()
    background(40)
    fill(255)
    ellipse(hoverX, hoverY + scrollY, 40, 40)
end
```

## Gamepads

Game controllers connected to the device are listed in `gamepad.all`. `gamepad.current` is the controller used most recently, or `nil` if none is connected.

```lua
function setup()
    pos = vec2(WIDTH/2, HEIGHT/2)
    gamepad.connected = function(pad)
        print("connected", pad.vendorName)
    end
end

function draw()
    background(40)
    local pad = gamepad.current
    if pad then
        pos = pos + pad.leftStick.dir * 300 * time.delta
        if pad.a.pressed then print("A") end
    end
    fill(255)
    ellipse(pos.x, pos.y, 60, 60)
end
```

Controllers already connected when the project starts are in `gamepad.all` but do not trigger `gamepad.connected`.

Each button has `pressing`, which is true while it is held, `pressed` and `released`, which are true only in the frame it changed, and an analog `value`. Sticks, the directional pad and the touchpad surface report a `dir` vector along with `x`, `y`, `left`, `right`, `up` and `down`.

`gamepad.virtual` returns an on-screen gamepad with a stick at the bottom left and an `A` button at the bottom right, controlled by touch. While a controller is connected it is hidden and mirrors that controller, so a project can read the same buttons either way:

```lua
function setup()
    pad = gamepad.virtual
    pos = vec2(WIDTH/2, HEIGHT/2)
end

function draw()
    background(40)
    pos = pos + pad.leftStick.dir * 300 * time.delta
    if pad.a.pressed then print("A") end
    fill(255)
    ellipse(pos.x, pos.y, 60, 60)
end
```

## Controlling a scene with parameters

Use **Controls** to rename, move, recolor, or hide the sphere, or make it squash and stretch. Try `1.5 + math.sin(time.elapsed)` in the expression field to make its label move up and down.

The label uses `style.textRenderer(style.atlas)` because its font size is one
world unit and the 3D camera magnifies it. Distance-field glyphs stay sharp as
the label grows on screen. The native renderer rasterizes at the requested font
size, so a one-point native label becomes blurry when enlarged. The camera uses
`camera.depthAndColor` to clear both its color and depth buffers.

#### Controlling a scene with parameters

[Download project](data/downloads/Controlling-a-scene-with-parameters-a0497fd80798.zip) — Open in Codea to run this example.

```lua
-- Use this function to perform your initial setup
function setup()
    print("Hello Parameters!")

    -- Create a simple scene containing a model to play with
    scn = scene.default3d()
    rig = scn.camera:add(camera.rigs.orbit)
    scn.camera:get(camera).clearMode = camera.depthAndColor

    -- Basic entity with a sphere mesh
    ent = scn:entity()
    ent:add(mesh.sphere())

    mat = material.lit()
    mat.color = color.red
    ent.material = mat
    ent.expr = function() return 1.5 end

    -- Draw some text above the entity
    function ent:draw()
        -- Distance-field text stays sharp at this small world-space size.
        style.depth(true).textRenderer(style.atlas).fill(255).fontSize(1)
        shapeMode(CENTER)
        textAlign(CENTER | MIDDLE)
        matrix.translate(0, self.expr(), 0)
        text(self.name)
    end

    -- Auto-update/draw the scene
    scene.main = scn


    parameter.text("Name", ent.name, function(value)
        ent.name = value
    end)

    -- Expression idiom (use multiline as well)
    parameter.text("Expression", "1.5", function(value)
        ent.expr = load("return "..value) or function() return 0 end
    end, true)

    -- Y value for the entity
    parameter.number("Y", 0, 10, 0, function(value)
        ent.y = value
    end)

    -- (De)activate entity
    parameter.boolean("Active", true, function(value)
        print(value and "On" or "Off")
        ent.active = value
    end)

    -- Adjust entity material color
    parameter.color("Color", color.yellow, function(value)
        mat.color = value
    end)

    -- Do a simple tween to squash and stretch
    parameter.action("Action", function()
        scn:tween(ent):punch{sx=2, sy=0.5}:time(1)
    end)

end

```

## Tracking more than one finger

Drag several fingers to move their circles independently. Each position is stored using `touch.id` and removed when the touch ends or is cancelled.

#### Tracking more than one finger

[Download project](data/downloads/Tracking-more-than-one-finger-1f1183bda073.zip) — Open in Codea to run this example.

```lua
-- Track simultaneous fingers by their stable touch IDs.
local fingers = {}
function setup() end
function draw()
    background(30, 35, 45)
    style.fill(255).fontSize(20).textAlign(CENTER | MIDDLE)
    text("Touch and drag to draw circles", WIDTH/2, HEIGHT - 40)
    for id, position in pairs(fingers) do
        style.fill(100, 220, 200).noStroke()
        ellipse(position.x, position.y, 70)
    end
end
function touched(t)
    if t.ended or t.cancelled then
        fingers[t.id] = nil
    else
        fingers[t.id] = vec2(t.x, t.y)
    end
end

```

<a id="section-Touches"></a>

## Touches

<a id="touch"></a>

### touch

```lua
touch
```

Represents a single touch over time. Passed to the global `touched(touch)` function and to entity `touched` methods each time the touch begins, moves or ends

get the unique identifier of this touch

<a id="touch.id"></a>

### touch.id

```lua
touch.id
```

An id that can be used to uniquely identify the touch

get the unique identifier of this touch

<a id="touch.state"></a>

### touch.state

```lua
touch.state
```

The current state of the touch, can be:

- `BEGAN` - the touch began
- `CHANGED` - the touch moved (`MOVING` is the same value)
- `ENDED` - the touch ended
- `CANCELLED` - the touch was cancelled, usually by a gesture recognizer or the system

get the current state of this touch or gesture

<a id="touch.began"></a>

### touch.began

```lua
touch.began
```

`true` if the touch began with this event

check if this touch just began

<a id="touch.changed"></a>

### touch.changed

```lua
touch.changed
```

`true` if the touch moved with this event

check if this touch moved

<a id="touch.moving"></a>

### touch.moving

```lua
touch.moving
```

The same as `changed`

check if this touch moved

<a id="touch.ended"></a>

### touch.ended

```lua
touch.ended
```

`true` if the touch ended with this event

check if this touch ended

<a id="touch.cancelled"></a>

### touch.cancelled

```lua
touch.cancelled
```

`true` if the touch was cancelled

check if this touch was cancelled

<a id="touch.tapCount"></a>

### touch.tapCount

```lua
touch.tapCount
```

The number of quick taps in a row at this location, starting at 1

get the tap count of this touch

<a id="touch.type"></a>

### touch.type

```lua
touch.type
```

The type of touch, can be:

- `touch.direct` - a touch resulting from direct contact with the screen
- `touch.indirect` - a touch that does not result from direct contact with the screen
- `touch.pencil` - a touch from Apple Pencil
- `touch.pointer` - a click from a mouse or trackpad

get the type of this touch

<a id="touch.x"></a>

### touch.x

```lua
touch.x
```

The x position of the touch (in screen coordinates)

get the x position of this touch

<a id="touch.y"></a>

### touch.y

```lua
touch.y
```

The y position of the touch (in screen coordinates)

get the y position of this touch

<a id="touch.prevX"></a>

### touch.prevX

```lua
touch.prevX
```

The previous x position of the touch (in screen coordinates)

get the previous x position

<a id="touch.prevY"></a>

### touch.prevY

```lua
touch.prevY
```

The previous y position of the touch (in screen coordinates)

get the previous y position

<a id="touch.deltaX"></a>

### touch.deltaX

```lua
touch.deltaX
```

The change in x position since the previous event for this touch (in screen coordinates)

get the delta x movement

<a id="touch.deltaY"></a>

### touch.deltaY

```lua
touch.deltaY
```

The change in y position since the previous event for this touch (in screen coordinates)

get the delta y movement

<a id="touch.pos"></a>

### touch.pos

```lua
touch.pos
```

The position of the touch (in screen coordinates) as a vector

get the position as a vec2

<a id="touch.prevPos"></a>

### touch.prevPos

```lua
touch.prevPos
```

The previous position of the touch (in screen coordinates) as a vector

get the previous position as a vec2

<a id="touch.delta"></a>

### touch.delta

```lua
touch.delta
```

The change in position since the previous event for this touch (in screen coordinates) as a vector

get the delta movement

<a id="touch.force"></a>

### touch.force

```lua
touch.force
```

The amount of force being applied, where `1` is an average touch. Reported for Apple Pencil and on devices with 3D Touch, otherwise `0`

get the force of this touch

<a id="touch.maxForce"></a>

### touch.maxForce

```lua
touch.maxForce
```

The maximum possible value of `force`

get the maximum force of this touch

<a id="touch.timestamp"></a>

### touch.timestamp

```lua
touch.timestamp
```

The time when this touch event occurred, in seconds since the device started

get the timestamp of this touch

<a id="touch.azimuth"></a>

### touch.azimuth

```lua
touch.azimuth
```

The direction the pencil points across the screen, in radians (only applies to pencil type touches)

get the azimuth angle of the stylus

<a id="touch.altitude"></a>

### touch.altitude

```lua
touch.altitude
```

The angle of the pencil above the screen, in radians. `0` is flat against the screen and `math.pi / 2` is perpendicular to it (only applies to pencil type touches)

get the altitude angle of the stylus

<a id="touch.radiusTolerance"></a>

### touch.radiusTolerance

```lua
touch.radiusTolerance
```

The amount the estimated radius can vary due to hardware tolerances

get the radius tolerance of this touch

<a id="touch.radius"></a>

### touch.radius

```lua
touch.radius
```

The estimated radius of the touch

get the radius of this touch

<a id="touch.precisePos"></a>

### touch.precisePos

```lua
touch.precisePos
```

The precise location of the touch (if available)

get the precise position of this touch

<a id="touch.precisePrevPos"></a>

### touch.precisePrevPos

```lua
touch.precisePrevPos
```

The previous precise location of the touch (if available)

get the precise previous position of this touch

<a id="touch.current"></a>

### touch.current

```lua
touch.current
```

The first touch that is currently down. It keeps its last state after the touch ends, until a new touch begins. Read it as `touch.current`

get the current primary touch

<a id="touch:cancel"></a>

### touch:cancel(scene)

```lua
touch:cancel(scene)
```

Cancels this touch for every entity in `scene` that holds it. Each of those entities receives the touch once more with the `CANCELLED` state

cancel this touch for a scene

#### Parameters

- **scene** (scene): The scene whose entities hold the touch

<a id="touch:makeExclusive"></a>

### touch:makeExclusive(entity)

```lua
touch:makeExclusive(entity)
```

Gives this touch to `entity` alone. Other entities that hold the touch receive it with the `CANCELLED` state. Does nothing if another entity already holds it exclusively

give this touch to one entity only

#### Parameters

- **entity** (entity): The entity that keeps the touch

<a id="touch.direct"></a>

### touch.direct

```lua
touch.direct
```

direct touch type constant

<a id="touch.indirect"></a>

### touch.indirect

```lua
touch.indirect
```

indirect touch type constant

<a id="touch.pencil"></a>

### touch.pencil

```lua
touch.pencil
```

pencil touch type constant

<a id="touch.pointer"></a>

### touch.pointer

```lua
touch.pointer
```

pointer touch type constant

<a id="section-Constants-Touch-State"></a>

## Constants - Touch State

<a id="entry.BEGAN"></a>

### BEGAN

```lua
BEGAN
```

touch began state constant

<a id="entry.CHANGED"></a>

### CHANGED

```lua
CHANGED
```

touch moved state constant

<a id="entry.MOVING"></a>

### MOVING

```lua
MOVING
```

The same value as `CHANGED`

touch moved state constant

<a id="entry.ENDED"></a>

### ENDED

```lua
ENDED
```

touch ended state constant

<a id="entry.CANCELLED"></a>

### CANCELLED

```lua
CANCELLED
```

touch cancelled state constant

<a id="section-Gestures"></a>

## Gestures

<a id="gesture"></a>

### gesture

```lua
gesture
```

Represents a single gesture event. Passed to gesture recognizer callbacks and to the global `hover(gesture)` and `scroll(gesture)` functions. Each kind of gesture fills in only the fields that apply to it:

- tap - `location`
- pan and scroll - `location`, `translation`, `delta` and `touchCount`
- pinch - `location`, `pinchScale`, `pinchDelta` and `pinchVelocity`
- rotation - `location`, `rotationAngle` and `rotationVelocity`
- hover - `location`

get the current state of this touch or gesture

<a id="gesture.state"></a>

### gesture.state

```lua
gesture.state
```

The current state of the gesture, using the same constants as touches:

- `BEGAN` - the gesture was recognized
- `CHANGED` - the gesture moved or changed
- `ENDED` - the gesture finished or was cancelled

A tap reports `ENDED` once it is recognized.

get the current state of this touch or gesture

<a id="gesture.location"></a>

### gesture.location

```lua
gesture.location
```

The location of the gesture event on the screen

get the location of this gesture

<a id="gesture.translation"></a>

### gesture.translation

```lua
gesture.translation
```

The translation of the gesture event relative to its starting location, with positive `y` pointing up

get the translation of this gesture or joint

<a id="gesture.delta"></a>

### gesture.delta

```lua
gesture.delta
```

The delta of the gesture event since last update

get the delta movement

<a id="gesture.pinchScale"></a>

### gesture.pinchScale

```lua
gesture.pinchScale
```

The scale of a pinch gesture relative to its starting distance

get the pinch scale of this gesture

<a id="gesture.pinchDelta"></a>

### gesture.pinchDelta

```lua
gesture.pinchDelta
```

The ratio of the pinch scale to its value at the last update. Multiply a size by it to follow the pinch

get the pinch delta of this gesture

<a id="gesture.pinchVelocity"></a>

### gesture.pinchVelocity

```lua
gesture.pinchVelocity
```

The rate of change of the pinch scale, in scale factor per second

get the pinch velocity of this gesture

<a id="gesture.rotationAngle"></a>

### gesture.rotationAngle

```lua
gesture.rotationAngle
```

The change in angle of a rotation gesture since the last update, in degrees. Positive values are counter-clockwise, the same direction as `rotate()`.

get the rotation angle of this gesture

<a id="gesture.rotationVelocity"></a>

### gesture.rotationVelocity

```lua
gesture.rotationVelocity
```

The rate of change of the rotation angle, in degrees per second

get the rotation velocity of this gesture

<a id="gesture.touchCount"></a>

### gesture.touchCount

```lua
gesture.touchCount
```

The current number of touches associated with this gesture

get the touch count for this gesture

<a id="gesture.tap"></a>

### gesture.tap

```lua
gesture.tap
```

Tap gesture recognizer (using system gesture recognizer for implementation). The recognizer is removed when it is garbage collected, so keep a reference to it

create a tap gesture recognizer

<a id="gesture.tap-2"></a>

### gesture.tap(callback, tapCount, touchCount)

```lua
gesture.tap(callback, tapCount, touchCount)
```

Creates and registers a new tap gesture recognizer that will call `callback(gesture)` when recognized

create a tap gesture recognizer

#### Parameters

- **callback** (function): The function to call with the gesture
- **tapCount** (integer, optional, default: 1): The number of taps required, such as 2 for a double tap
- **touchCount** (integer, optional, default: 1): The number of fingers required

#### Returns

- **gesture.tap**: 

<a id="gesture.tap.enabled"></a>

### gesture.tap.enabled

```lua
gesture.tap.enabled
```

Enables/disables this gesture recognizer

whether the gesture recognizer is enabled

<a id="gesture.tap.group"></a>

### gesture.tap.group

```lua
gesture.tap.group
```

Recognizers that share the same non-zero group can recognize at the same time. A recognizer in group `0` does not run alongside others

set the group for simultaneous recognition

<a id="gesture.pan"></a>

### gesture.pan

```lua
gesture.pan
```

Pan gesture recognizer (using system gesture recognizer for implementation). The recognizer is removed when it is garbage collected, so keep a reference to it

create a pan gesture recognizer

<a id="gesture.pan-2"></a>

### gesture.pan(callback, minTouches, maxTouches, trackpad)

```lua
gesture.pan(callback, minTouches, maxTouches, trackpad)
```

Creates and registers a new pan gesture recognizer that will call `callback(gesture)` as the pan begins, moves and ends

create a pan gesture recognizer

#### Parameters

- **callback** (function): The function to call with the gesture
- **minTouches** (integer, optional, default: 1): The fewest fingers that can perform the pan
- **maxTouches** (integer, optional, default: 1): The most fingers that can perform the pan
- **trackpad** (boolean, optional, default: false): Also recognize two finger trackpad scrolling as a pan

#### Returns

- **gesture.pan**: 

<a id="gesture.pan.enabled"></a>

### gesture.pan.enabled

```lua
gesture.pan.enabled
```

Enables/disables this gesture recognizer

whether the gesture recognizer is enabled

<a id="gesture.pan.group"></a>

### gesture.pan.group

```lua
gesture.pan.group
```

Recognizers that share the same non-zero group can recognize at the same time. A recognizer in group `0` does not run alongside others

set the group for simultaneous recognition

<a id="gesture.pinch"></a>

### gesture.pinch

```lua
gesture.pinch
```

Pinch gesture recognizer (using system gesture recognizer for implementation). The recognizer is removed when it is garbage collected, so keep a reference to it

create a pinch gesture recognizer

<a id="gesture.pinch-2"></a>

### gesture.pinch(callback)

```lua
gesture.pinch(callback)
```

Creates and registers a new pinch gesture recognizer that will call `callback(gesture)` when recognized

create a pinch gesture recognizer

#### Parameters

- **callback** (function): Function called with the gesture object when its state changes.

#### Returns

- **gesture.pinch**: 

<a id="gesture.pinch.enabled"></a>

### gesture.pinch.enabled

```lua
gesture.pinch.enabled
```

Enables/disables this gesture recognizer

whether the gesture recognizer is enabled

<a id="gesture.pinch.group"></a>

### gesture.pinch.group

```lua
gesture.pinch.group
```

Recognizers that share the same non-zero group can recognize at the same time. A recognizer in group `0` does not run alongside others

set the group for simultaneous recognition

<a id="gesture.rotation"></a>

### gesture.rotation

```lua
gesture.rotation
```

Rotation gesture recognizer (using system gesture recognizer for implementation). The recognizer is removed when it is garbage collected, so keep a reference to it

create a rotation gesture recognizer

<a id="gesture.rotation-2"></a>

### gesture.rotation(callback)

```lua
gesture.rotation(callback)
```

Creates and registers a new rotation gesture recognizer that will call `callback(gesture)` when recognized

create a rotation gesture recognizer

#### Parameters

- **callback** (function): Function called with the gesture object when its state changes.

#### Returns

- **gesture.rotation**: 

<a id="gesture.rotation.enabled"></a>

### gesture.rotation.enabled

```lua
gesture.rotation.enabled
```

Enables/disables this gesture recognizer

whether the gesture recognizer is enabled

<a id="gesture.rotation.group"></a>

### gesture.rotation.group

```lua
gesture.rotation.group
```

Recognizers that share the same non-zero group can recognize at the same time. A recognizer in group `0` does not run alongside others

set the group for simultaneous recognition

<a id="section-Input"></a>

## Input

<a id="Keyboard"></a>

### Keyboard

Functions and constants for reading a hardware keyboard. Key events also call the global `keyPressed(press)` and `keyReleased(press)` functions, except while a user interface text field has focus

Use `key.pressing` for continuous movement and `key.wasPressed` for a
one-off action. Multiply movement speed by `time.delta` so it does not depend
on the frame rate. Modifier masks such as `key.cmd` and `key.shift` can be
combined with `|`. For entered text, use `keyboard.text` so composition,
autocorrection, and Unicode editing are handled by the system.

```lua
function setup()
    x = WIDTH / 2
end

function draw()
    background(30)
    if key.pressing(key.left) then x = x - 200 * time.delta end
    if key.pressing(key.right) then x = x + 200 * time.delta end
    if key.wasPressed(key.space) then x = WIDTH / 2 end
    fill(255)
    ellipse(x, HEIGHT / 2, 40)
end
```

See [Input](#Input-in-Codea) for key callbacks and shortcut examples.

<a id="On-Screen-Keyboard"></a>

### On-Screen Keyboard

The on-screen keyboard. While it is shown, typing sets `keyboard.text` and also calls the global `keyPressed(press)` and `keyReleased(press)` functions, one after the other, for each insertion. `press.characters` holds the inserted text and `press.keyCode` is set for letters, digits, space, return and backspace. A hardware keyboard types into the same text while the on-screen keyboard is shown.

Use the buffer as the source of truth for text entry; do not append
`press.characters` to it yourself, which would duplicate insertions. Clear
or prefill the buffer before showing the keyboard. With a hardware keyboard
attached, text entry can work even when `keyboard.visible` is false.

```lua
function setup()
    keyboard.text = ""
    keyboard.show()
end

function keyPressed(press)
    if press.keyCode == key.enter then
        print("Entered:", keyboard.text)
        keyboard.hide()
    end
end

function draw()
    background(30)
    fill(255)
    shapeMode(CENTER)
    text(keyboard.text, WIDTH / 2, HEIGHT / 2)
end
```

<a id="Mouse"></a>

### Mouse

The pointer state on a Mac, or an iPad with a mouse or trackpad. The global `hover(gesture)` and `scroll(gesture)` functions are also called for pointer movement and scrolling

Positions use drawing coordinates: the origin is at the lower-left of the
viewer. `mouse.delta` and `mouse.scroll` are changes for the current frame,
not accumulated positions. `mouse.left.pressed` stays true while dragging;
compare it with its previous value to detect a new click. Check `mouse.active` before
showing pointer-only UI, and keep a touch alternative for devices without a mouse.

```lua
function setup()
    position = vec2(WIDTH / 2, HEIGHT / 2)
end

function draw()
    background(30)
    if mouse.active and mouse.left.pressed then
        position = mouse.pos
    end
    fill(255, 190, 70)
    ellipse(position.x, position.y, 60)
end
```

See [Input](#Input-in-Codea) for hover and scroll callbacks and pointer locking.

<a id="section-Keyboard"></a>

## Keyboard

<a id="key.pressing"></a>

### key.pressing(keyCode)

```lua
key.pressing(keyCode)
```

Queries whether the key is currently held down

check if a key is currently pressed

#### Parameters

- **keyCode** (constant): The keyCode to query

#### Returns

- **boolean**: Is the key held down

<a id="key.wasPressed"></a>

### key.wasPressed(keyCode)

```lua
key.wasPressed(keyCode)
```

Queries whether the key went down since the previous frame

check if a key was pressed this frame

#### Parameters

- **keyCode** (constant): The keyCode to query

#### Returns

- **boolean**: Was the key pressed down this frame

<a id="key.wasReleased"></a>

### key.wasReleased(keyCode)

```lua
key.wasReleased(keyCode)
```

Queries whether the key came up since the previous frame

check if a key was released this frame

#### Parameters

- **keyCode** (constant): The keyCode to query

#### Returns

- **boolean**: Was the key released this frame

<a id="key.modifiers"></a>

### key.modifiers()

```lua
key.modifiers()
```

Queries the current key modifiers as a bit field, which is composed of the following bit mask constants:

- `key.alt`
- `key.ctrl`
- `key.cmd`
- `key.shift`

Use `key.pressing(keyCode)` to query individual keys such as `key.leftAlt`.

get the current keyboard modifiers

#### Returns

- **integer**: The modifiers currently held

<a id="key.modifiersPressed"></a>

### key.modifiersPressed(modifiers)

```lua
key.modifiersPressed(modifiers)
```

Queries whether all of the supplied key modifiers are currently held. Combine masks with `|`, as in `key.modifiersPressed(key.cmd | key.shift)`

check if keyboard modifiers are pressed

#### Parameters

- **modifiers** (constant): The key modifiers to query as a bit field

#### Returns

- **boolean**: Are the key modifiers currently pressed

<a id="key.press"></a>

### press

```lua
press
```

A single key event, passed to the global `keyPressed(press)` and `keyReleased(press)` functions

get the key code of this key press

<a id="press.keyCode"></a>

### press.keyCode

```lua
press.keyCode
```

The key, as one of the `key` key code constants such as `key.a` or `key.space`

get the key code of this key press

<a id="press.modifierFlags"></a>

### press.modifierFlags

```lua
press.modifierFlags
```

The modifiers held during this key event, as a bit field of `key.alt`, `key.ctrl`, `key.cmd` and `key.shift`

get the modifiers held for this key press

<a id="press.characters"></a>

### press.characters

```lua
press.characters
```

The text produced by the key, taking modifiers such as shift into account

get the text typed by this key press

<a id="Keyboard-Modifier-Masks"></a>

### Keyboard Modifier Masks

These are bit masks for `key.modifiers()`, `key.modifiersPressed()` and `press.modifierFlags`. Each one covers both the left and right key. They are not key codes, so use `key.leftAlt` and similar with `key.pressing()`

<a id="section-Keyboard-Modifier-Masks"></a>

## Keyboard Modifier Masks

<a id="key.alt"></a>

### key.alt

```lua
key.alt
```

alt modifier mask

<a id="key.ctrl"></a>

### key.ctrl

```lua
key.ctrl
```

ctrl modifier mask

<a id="key.cmd"></a>

### key.cmd

```lua
key.cmd
```

command modifier mask

<a id="key.shift"></a>

### key.shift

```lua
key.shift
```

shift modifier mask

<a id="section-Constants-Key-Codes"></a>

## Constants - Key Codes

<a id="key.leftAlt"></a>

### key.leftAlt

```lua
key.leftAlt
```

left alt key constant

<a id="key.rightAlt"></a>

### key.rightAlt

```lua
key.rightAlt
```

right alt key constant

<a id="key.leftCtrl"></a>

### key.leftCtrl

```lua
key.leftCtrl
```

left ctrl key constant

<a id="key.rightCtrl"></a>

### key.rightCtrl

```lua
key.rightCtrl
```

right ctrl key constant

<a id="key.leftCmd"></a>

### key.leftCmd

```lua
key.leftCmd
```

left command key constant

<a id="key.rightCmd"></a>

### key.rightCmd

```lua
key.rightCmd
```

right command key constant

<a id="key.leftShift"></a>

### key.leftShift

```lua
key.leftShift
```

left shift key constant

<a id="key.rightShift"></a>

### key.rightShift

```lua
key.rightShift
```

right shift key constant

<a id="key.esc"></a>

### key.esc

```lua
key.esc
```

escape key constant

<a id="key.enter"></a>

### key.enter

```lua
key.enter
```

The return key

enter key constant

<a id="key.tab"></a>

### key.tab

```lua
key.tab
```

tab key constant

<a id="key.space"></a>

### key.space

```lua
key.space
```

space key constant

<a id="key.backspace"></a>

### key.backspace

```lua
key.backspace
```

backspace key constant

<a id="key.up"></a>

### key.up

```lua
key.up
```

up arrow key constant

<a id="key.down"></a>

### key.down

```lua
key.down
```

down arrow key constant

<a id="key.left"></a>

### key.left

```lua
key.left
```

left arrow key constant

<a id="key.right"></a>

### key.right

```lua
key.right
```

right arrow key constant

<a id="key.insert"></a>

### key.insert

```lua
key.insert
```

insert key constant

<a id="key.delete"></a>

### key.delete

```lua
key.delete
```

delete key constant

<a id="key.home"></a>

### key.home

```lua
key.home
```

home key constant

<a id="key.end"></a>

### key.end

```lua
key.end
```

end key constant

<a id="key.pageup"></a>

### key.pageup

```lua
key.pageup
```

page up key constant

<a id="key.pagedown"></a>

### key.pagedown

```lua
key.pagedown
```

page down key constant

<a id="key.print"></a>

### key.print

```lua
key.print
```

print key constant

<a id="key.plus"></a>

### key.plus

```lua
key.plus
```

plus key constant

<a id="key.minus"></a>

### key.minus

```lua
key.minus
```

minus key constant

<a id="key.leftbracket"></a>

### key.leftbracket

```lua
key.leftbracket
```

left bracket key constant

<a id="key.rightbracket"></a>

### key.rightbracket

```lua
key.rightbracket
```

right bracket key constant

<a id="key.semicolon"></a>

### key.semicolon

```lua
key.semicolon
```

semicolon key constant

<a id="key.quote"></a>

### key.quote

```lua
key.quote
```

quote key constant

<a id="key.comma"></a>

### key.comma

```lua
key.comma
```

comma key constant

<a id="key.period"></a>

### key.period

```lua
key.period
```

period key constant

<a id="key.slash"></a>

### key.slash

```lua
key.slash
```

forward slash key constant

<a id="key.backslash"></a>

### key.backslash

```lua
key.backslash
```

backslash key constant

<a id="key.nonUSBackslash"></a>

### key.nonUSBackslash

```lua
key.nonUSBackslash
```

non-US backslash key constant

<a id="key.tilde"></a>

### key.tilde

```lua
key.tilde
```

tilde key constant

<a id="key.f1"></a>

### key.f1

```lua
key.f1
```

F1 key constant

<a id="key.f2"></a>

### key.f2

```lua
key.f2
```

F2 key constant

<a id="key.f3"></a>

### key.f3

```lua
key.f3
```

F3 key constant

<a id="key.f4"></a>

### key.f4

```lua
key.f4
```

F4 key constant

<a id="key.f5"></a>

### key.f5

```lua
key.f5
```

F5 key constant

<a id="key.f6"></a>

### key.f6

```lua
key.f6
```

F6 key constant

<a id="key.f7"></a>

### key.f7

```lua
key.f7
```

F7 key constant

<a id="key.f8"></a>

### key.f8

```lua
key.f8
```

F8 key constant

<a id="key.f9"></a>

### key.f9

```lua
key.f9
```

F9 key constant

<a id="key.f10"></a>

### key.f10

```lua
key.f10
```

F10 key constant

<a id="key.f11"></a>

### key.f11

```lua
key.f11
```

F11 key constant

<a id="key.f12"></a>

### key.f12

```lua
key.f12
```

F12 key constant

<a id="key.numpad0"></a>

### key.numpad0

```lua
key.numpad0
```

numpad 0 key constant

<a id="key.numpad1"></a>

### key.numpad1

```lua
key.numpad1
```

numpad 1 key constant

<a id="key.numpad2"></a>

### key.numpad2

```lua
key.numpad2
```

numpad 2 key constant

<a id="key.numpad3"></a>

### key.numpad3

```lua
key.numpad3
```

numpad 3 key constant

<a id="key.numpad4"></a>

### key.numpad4

```lua
key.numpad4
```

numpad 4 key constant

<a id="key.numpad5"></a>

### key.numpad5

```lua
key.numpad5
```

numpad 5 key constant

<a id="key.numpad6"></a>

### key.numpad6

```lua
key.numpad6
```

numpad 6 key constant

<a id="key.numpad7"></a>

### key.numpad7

```lua
key.numpad7
```

numpad 7 key constant

<a id="key.numpad8"></a>

### key.numpad8

```lua
key.numpad8
```

numpad 8 key constant

<a id="key.numpad9"></a>

### key.numpad9

```lua
key.numpad9
```

numpad 9 key constant

<a id="key.num0"></a>

### key.num0

```lua
key.num0
```

0 number key constant

<a id="key.num1"></a>

### key.num1

```lua
key.num1
```

1 number key constant

<a id="key.num2"></a>

### key.num2

```lua
key.num2
```

2 number key constant

<a id="key.num3"></a>

### key.num3

```lua
key.num3
```

3 number key constant

<a id="key.num4"></a>

### key.num4

```lua
key.num4
```

4 number key constant

<a id="key.num5"></a>

### key.num5

```lua
key.num5
```

5 number key constant

<a id="key.num6"></a>

### key.num6

```lua
key.num6
```

6 number key constant

<a id="key.num7"></a>

### key.num7

```lua
key.num7
```

7 number key constant

<a id="key.num8"></a>

### key.num8

```lua
key.num8
```

8 number key constant

<a id="key.num9"></a>

### key.num9

```lua
key.num9
```

9 number key constant

<a id="key.a"></a>

### key.a

```lua
key.a
```

A key constant

<a id="key.b"></a>

### key.b

```lua
key.b
```

B key constant

<a id="key.c"></a>

### key.c

```lua
key.c
```

C key constant

<a id="key.d"></a>

### key.d

```lua
key.d
```

D key constant

<a id="key.e"></a>

### key.e

```lua
key.e
```

E key constant

<a id="key.f"></a>

### key.f

```lua
key.f
```

F key constant

<a id="key.g"></a>

### key.g

```lua
key.g
```

G key constant

<a id="key.h"></a>

### key.h

```lua
key.h
```

H key constant

<a id="key.i"></a>

### key.i

```lua
key.i
```

I key constant

<a id="key.j"></a>

### key.j

```lua
key.j
```

J key constant

<a id="key.k"></a>

### key.k

```lua
key.k
```

K key constant

<a id="key.l"></a>

### key.l

```lua
key.l
```

L key constant

<a id="key.m"></a>

### key.m

```lua
key.m
```

M key constant

<a id="key.n"></a>

### key.n

```lua
key.n
```

N key constant

<a id="key.o"></a>

### key.o

```lua
key.o
```

O key constant

<a id="key.p"></a>

### key.p

```lua
key.p
```

P key constant

<a id="key.q"></a>

### key.q

```lua
key.q
```

Q key constant

<a id="key.r"></a>

### key.r

```lua
key.r
```

R key constant

<a id="key.s"></a>

### key.s

```lua
key.s
```

S key constant

<a id="key.t"></a>

### key.t

```lua
key.t
```

T key constant

<a id="key.u"></a>

### key.u

```lua
key.u
```

U key constant

<a id="key.v"></a>

### key.v

```lua
key.v
```

V key constant

<a id="key.w"></a>

### key.w

```lua
key.w
```

W key constant

<a id="key.x"></a>

### key.x

```lua
key.x
```

X key constant

<a id="key.y"></a>

### key.y

```lua
key.y
```

Y key constant

<a id="key.z"></a>

### key.z

```lua
key.z
```

Z key constant

<a id="section-Gamepad"></a>

## Gamepad

<a id="gamepad"></a>

### gamepad

```lua
gamepad
```

A game controller. Read `gamepad.all`, `gamepad.current` and `gamepad.virtual` to get one

get all connected gamepads

<a id="gamepad.all"></a>

### gamepad.all

```lua
gamepad.all
```

A list of all currently connected gamepads

get all connected gamepads

<a id="gamepad.current"></a>

### gamepad.current

```lua
gamepad.current
```

The most recently used gamepad, or `nil` if none is connected

get the current active gamepad

<a id="gamepad.virtual"></a>

### gamepad.virtual

```lua
gamepad.virtual
```

Gets the on-screen gamepad, creating it on first use. It shows a stick at the bottom left and an `A` button at the bottom right, controlled by touch. While a controller is connected it is hidden and mirrors `gamepad.current`

get the virtual gamepad

<a id="gamepad.connected"></a>

### gamepad.connected

```lua
gamepad.connected
```

Callback for when a gamepad is connected. Gamepads that are already connected when the project starts are listed in `gamepad.all` and do not trigger it

callback invoked when a gamepad connects

<a id="gamepad.disconnected"></a>

### gamepad.disconnected

```lua
gamepad.disconnected
```

Callback for when a gamepad is disconnected

callback invoked when a gamepad disconnects

<a id="gamepad.leftShoulder"></a>

### gamepad.leftShoulder

```lua
gamepad.leftShoulder
```

The left shoulder button

get the left shoulder button

<a id="gamepad.rightShoulder"></a>

### gamepad.rightShoulder

```lua
gamepad.rightShoulder
```

The right shoulder button

get the right shoulder button

<a id="gamepad.leftTrigger"></a>

### gamepad.leftTrigger

```lua
gamepad.leftTrigger
```

The left trigger

get the left trigger button

<a id="gamepad.rightTrigger"></a>

### gamepad.rightTrigger

```lua
gamepad.rightTrigger
```

The right trigger

get the right trigger button

<a id="gamepad.dpad"></a>

### gamepad.dpad

```lua
gamepad.dpad
```

The directional pad

get the directional pad

<a id="gamepad.leftStick"></a>

### gamepad.leftStick

```lua
gamepad.leftStick
```

get the left analog stick

<a id="gamepad.rightStick"></a>

### gamepad.rightStick

```lua
gamepad.rightStick
```

get the right analog stick

<a id="gamepad.leftStickButton"></a>

### gamepad.leftStickButton

```lua
gamepad.leftStickButton
```

get the left stick click button

<a id="gamepad.rightStickButton"></a>

### gamepad.rightStickButton

```lua
gamepad.rightStickButton
```

get the right stick click button

<a id="gamepad.a"></a>

### gamepad.a

```lua
gamepad.a
```

get the a button

<a id="gamepad.b"></a>

### gamepad.b

```lua
gamepad.b
```

get the b button

<a id="gamepad.x"></a>

### gamepad.x

```lua
gamepad.x
```

get the x button

<a id="gamepad.y"></a>

### gamepad.y

```lua
gamepad.y
```

get the y button

<a id="gamepad.home"></a>

### gamepad.home

```lua
gamepad.home
```

get the home button

<a id="gamepad.menu"></a>

### gamepad.menu

```lua
gamepad.menu
```

get the menu button

<a id="gamepad.options"></a>

### gamepad.options

```lua
gamepad.options
```

get the options button

<a id="gamepad.touchpadButton"></a>

### gamepad.touchpadButton

```lua
gamepad.touchpadButton
```

get the touchpad button

<a id="gamepad.touchpadSurface"></a>

### gamepad.touchpadSurface

```lua
gamepad.touchpadSurface
```

get the touchpad surface

<a id="gamepad.batteryLevel"></a>

### gamepad.batteryLevel

```lua
gamepad.batteryLevel
```

The battery charge, from `0` to `1`

get the battery level of the gamepad

<a id="gamepad.batteryState"></a>

### gamepad.batteryState

```lua
gamepad.batteryState
```

The battery state, one of `gamepad.charging`, `gamepad.discharging`, `gamepad.full` or `gamepad.unknown`

get the battery state of the gamepad

<a id="gamepad.light"></a>

### gamepad.light

```lua
gamepad.light
```

The color of the controller’s light, on controllers that have one

get or set the gamepad light color

<a id="gamepad.playerIndex"></a>

### gamepad.playerIndex

```lua
gamepad.playerIndex
```

The player number shown on the controller, one of `gamepad.unset`, `gamepad.player1`, `gamepad.player2`, `gamepad.player3` or `gamepad.player4`

get or set the player index of the gamepad

<a id="gamepad.vendorName"></a>

### gamepad.vendorName

```lua
gamepad.vendorName
```

The name of the controller as reported by its maker

get the vendor name of the gamepad

<a id="gamepad.unset"></a>

### gamepad.unset

```lua
gamepad.unset
```

no player index constant

<a id="gamepad.player1"></a>

### gamepad.player1

```lua
gamepad.player1
```

player 1 index constant

<a id="gamepad.player2"></a>

### gamepad.player2

```lua
gamepad.player2
```

player 2 index constant

<a id="gamepad.player3"></a>

### gamepad.player3

```lua
gamepad.player3
```

player 3 index constant

<a id="gamepad.player4"></a>

### gamepad.player4

```lua
gamepad.player4
```

player 4 index constant

<a id="gamepad.charging"></a>

### gamepad.charging

```lua
gamepad.charging
```

battery charging state constant

<a id="gamepad.discharging"></a>

### gamepad.discharging

```lua
gamepad.discharging
```

battery discharging state constant

<a id="gamepad.full"></a>

### gamepad.full

```lua
gamepad.full
```

battery full state constant

<a id="gamepad.unknown"></a>

### gamepad.unknown

```lua
gamepad.unknown
```

battery unknown state constant

<a id="gamepad.button"></a>

### gamepad.button

```lua
gamepad.button
```

A button or trigger on a gamepad

get whether this button is being pressed

<a id="gamepad.button.pressing"></a>

### gamepad.button.pressing

```lua
gamepad.button.pressing
```

`true` while the button is held down

get whether this button is being pressed

<a id="gamepad.button.pressed"></a>

### gamepad.button.pressed

```lua
gamepad.button.pressed
```

`true` only in the frame the button went down

get whether this button was just pressed

<a id="gamepad.button.released"></a>

### gamepad.button.released

```lua
gamepad.button.released
```

`true` only in the frame the button came up

get whether this button was just released

<a id="gamepad.button.value"></a>

### gamepad.button.value

```lua
gamepad.button.value
```

How far the button is pressed, from `0` to `1`. Triggers report values in between

get the analog value of this button

<a id="gamepad.button.touching"></a>

### gamepad.button.touching

```lua
gamepad.button.touching
```

`true` while a finger rests on the button, on controllers that can sense it

get whether the touchpad is being touched

<a id="gamepad.directionalPad"></a>

### gamepad.directionalPad

```lua
gamepad.directionalPad
```

A stick, directional pad or touchpad surface on a gamepad

get the direction as a vec2

<a id="gamepad.directionalPad.dir"></a>

### gamepad.directionalPad.dir

```lua
gamepad.directionalPad.dir
```

The direction, with each axis from `-1` to `1`

get the direction as a vec2

<a id="gamepad.directionalPad.x"></a>

### gamepad.directionalPad.x

```lua
gamepad.directionalPad.x
```

get the x value of the directional pad

<a id="gamepad.directionalPad.y"></a>

### gamepad.directionalPad.y

```lua
gamepad.directionalPad.y
```

get the y value of the directional pad

<a id="gamepad.directionalPad.left"></a>

### gamepad.directionalPad.left

```lua
gamepad.directionalPad.left
```

get if the directional pad is moved left

<a id="gamepad.directionalPad.right"></a>

### gamepad.directionalPad.right

```lua
gamepad.directionalPad.right
```

get if the directional pad is moved right

<a id="gamepad.directionalPad.up"></a>

### gamepad.directionalPad.up

```lua
gamepad.directionalPad.up
```

get if the directional pad is moved up

<a id="gamepad.directionalPad.down"></a>

### gamepad.directionalPad.down

```lua
gamepad.directionalPad.down
```

get if the directional pad is moved down

<a id="section-On-Screen-Keyboard"></a>

## On-Screen Keyboard

<a id="keyboard.show"></a>

### keyboard.show()

```lua
keyboard.show()
```

Shows the on-screen keyboard. It stays up when the screen is touched, until `keyboard.hide()` is called

show the on-screen keyboard

<a id="keyboard.hide"></a>

### keyboard.hide()

```lua
keyboard.hide()
```

Hides the on-screen keyboard

hide the on-screen keyboard

<a id="keyboard.visible"></a>

### keyboard.visible

```lua
keyboard.visible
```

`true` while the on-screen keyboard is on screen. With a hardware keyboard attached, the system may not show it after `keyboard.show()`

check if the on-screen keyboard is showing

<a id="keyboard.text"></a>

### keyboard.text

```lua
keyboard.text
```

The text typed so far, including text from autocorrection, pasting, and characters still being composed in languages such as Korean or Japanese. Set it to replace the text, for example `keyboard.text = ""` to clear it

get or set the text typed on the on-screen keyboard

<a id="section-Mouse"></a>

## Mouse

<a id="mouse"></a>

### mouse

<a id="mouse.x"></a>

### mouse.x

```lua
mouse.x
```

The current horizontal position of the pointer in screen coordinates. Updated while the pointer hovers over the viewer and while a button is held

x position of the mouse

<a id="mouse.y"></a>

### mouse.y

```lua
mouse.y
```

The current vertical position of the pointer in screen coordinates. Updated while the pointer hovers over the viewer and while a button is held

y position of the mouse

<a id="mouse.pos"></a>

### mouse.pos

```lua
mouse.pos
```

The current position of the pointer as a `vec2`

position of the mouse

<a id="mouse.dx"></a>

### mouse.dx

```lua
mouse.dx
```

The horizontal movement of the pointer since the last frame

change in x since the last frame

<a id="mouse.dy"></a>

### mouse.dy

```lua
mouse.dy
```

The vertical movement of the pointer since the last frame

change in y since the last frame

<a id="mouse.delta"></a>

### mouse.delta

```lua
mouse.delta
```

The movement of the pointer since the last frame as a `vec2`

change in position since the last frame

<a id="mouse.scroll"></a>

### mouse.scroll

```lua
mouse.scroll
```

The scroll wheel or trackpad scroll amount this frame

scroll amount this frame

<a id="mouse.left"></a>

### mouse.left

```lua
mouse.left
```

The left mouse button. Trackpad clicks also count as the left button

left mouse button

<a id="mouse.middle"></a>

### mouse.middle

```lua
mouse.middle
```

The middle mouse button

middle mouse button

<a id="mouse.right"></a>

### mouse.right

```lua
mouse.right
```

The right mouse button

right mouse button

<a id="mouse.active"></a>

### mouse.active

```lua
mouse.active
```

Whether a mouse or trackpad is currently connected

whether a mouse is connected

<a id="mouse.visible"></a>

### mouse.visible

```lua
mouse.visible
```

Gets or sets the visibility of the system pointer cursor

show or hide the mouse cursor

<a id="section-Motion"></a>

## Motion

<a id="motion"></a>

### motion

Read the device’s acceleration, rotation, and orientation to respond to tilts and movement. Motion tracking uses battery power; call `motion.stop()` when you no longer need it.

<a id="motion.autoStart"></a>

### motion.autoStart

```lua
motion.autoStart
```

If set, motion tracking will start automatically as soon as any attribute is read. Default is `true`.

Set to false if you want to control when motion is tracked manually using the `start` and `stop` functions.

start motion tracking automatically on first access

<a id="motion.start"></a>

### motion.start(referenceFrame)

```lua
motion.start(referenceFrame)
```

Start tracking motion metrics.

- `motion.referenceFrame.XArbitraryZVertical` (default): The X-axis is arbitrary and the Z-axis is vertical.
- `motion.referenceFrame.XArbitraryCorrectedZVertical`: The X-axis is arbitrary and the Z-axis is vertical. If available, the magnetometer will be used to correct for accumulated yaw errors.
- `motion.referenceFrame.XMagneticNorthZVertical`: The X-axis points toward the magnetic north and the Z-axis is vertical.
- `motion.referenceFrame.XTrueNorthZVertical`: The X-axis points toward the true north and the Z-axis is vertical.

start motion tracking

#### Parameters

- **referenceFrame** (number): The reference frame in which to track motion metrics. Can be one of the following values:

<a id="motion.referenceFrame"></a>

### motion.referenceFrame

```lua
motion.referenceFrame
```

Reference frame constants for motion tracking.

motion reference frame constants

<a id="motion.stop"></a>

### motion.stop()

```lua
motion.stop()
```

Stop tracking motion metrics and set autoStart to false.

stop motion tracking

<a id="motion.updateInterval"></a>

### motion.updateInterval

```lua
motion.updateInterval
```

The interval, in seconds, at which motion data is updated. This value can be set to control the frequency of motion updates. A lower value means more frequent updates, which can provide smoother motion tracking but may consume more power. The default value is 1/30 second.

Note that the interval is clamped between limits defined by the system.

interval between motion updates

<a id="motion.gravity"></a>

### motion.gravity

```lua
motion.gravity
```

The gravity vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

current gravity vector

<a id="motion.acceleration"></a>

### motion.acceleration

```lua
motion.acceleration
```

The acceleration vector in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

current acceleration vector

<a id="motion.rotationRate"></a>

### motion.rotationRate

```lua
motion.rotationRate
```

The rotation rate in the device’s reference frame. This vector is automatically rotated to follow device orientation changes.

current rotation rate

<a id="motion.sensorLocation"></a>

### motion.sensorLocation

```lua
motion.sensorLocation
```

Sensor location constants.

motion sensor location constants

<a id="motion.heading"></a>

### motion.heading

```lua
motion.heading
```

The heading in degrees relative to the current reference frame.

current device heading

<a id="section-Device-Orientation"></a>

## Device Orientation

<a id="motion.attitude"></a>

### motion.attitude

```lua
motion.attitude
```

Represents a measurement of your device attitude. This orientation of a body relative to a given frame of reference.

You can set `motion.attitude.referenceFrame` to specify the frame of reference in which the attitude is expressed.

The value can be one of the following `motion.referenceFrame.XArbitraryZVertical`, `motion.referenceFrame.XArbitraryCorrectedZVertical`, `motion.referenceFrame.XMagneticNorthZVertical`, `motion.referenceFrame.XTrueNorthZVertical`.

<a id="section-Magnetic-Field-Data"></a>

## Magnetic Field Data

<a id="motion.magnetic"></a>

### motion.magnetic

```lua
motion.magnetic
```

Magnetic field data.

current magnetic field data

<a id="motion.magneticAccuracy"></a>

### motion.magneticAccuracy

```lua
motion.magneticAccuracy
```

Magnetic field accuracy constants.

magnetic field accuracy constants