# tecs.input


## Gameplay input

`tecs.input` folds typed platform events into gameplay input. The application
creates one [`Input`](/modules/input/#tecs.input.Input) as `app.input`; ordinary game
code does not construct or feed it. The module owns replay, layers, edge
detection and fixed-step latching.

### Three input tiers

Live state answers whether a key or button remains held. Frame edges answer
whether it changed this frame. Latched edges answer that question for the next
fixed step. The same `keyPressed`, `mousePressed` and
`Gamepad:buttonPressed` methods select frame or latched edges from the phase.
The engine consumes a latched edge in the first fixed step after it arrived.

### Layer capture

A blocking layer hides every device from lower layers. Calls that omit a layer
read the base layer, so gameplay becomes quiet while a menu owns capture.
Moving capture clears pending edges, text, wheel movement and mouse deltas.

```teal
local pause <const> = app.input:pushLayer("pause")

if app.input:keyPressed("Escape", pause) then
    app.input:popLayer()
end

-- The base layer cannot read while pause owns capture.
if app.input:keyDown("W") then
    movePlayer()
end
```

Pass false to `pushLayer` for an observing overlay. Because capture does not
move, the overlay does not clear edges.

### Focus and text input

Focus loss releases held keys, mouse buttons, gamepad buttons, fingers,
modifiers and pen pressure. The resulting release edges let a game finish the
active action.

Bind text input to the layer that owns the field. Popping the layer stops the
input method and clears composition.

```teal
local field <const> = app.input:pushLayer("playerName")
app.input:startTextInput(
    field,
    {
        area = {
            x = 40, y = 200, width = 320, height = 24, cursor = 80
        },
    }
)
```

Append `input.text` once per frame. Draw `input.composition` until the input
method commits it. Update the text area when the field scrolls or its caret
moves.

### Gamepads and sensors

`Input:gamepads` returns a live connection-order list. Hold a
[`Gamepad`](/modules/input/#tecs.input.Gamepad) object or match its `guid` to follow
hardware because list positions move and instance ids do not survive a
reconnect. Gamepad queries use the same layers and fixed-step tiers as keyboard
and mouse queries.

Standalone sensors do not belong to a gamepad. Enumerate them with
`tecs.input.sensors`, open one by instance id, poll it, and close it explicitly.

## Gamepads

Each [`Gamepad`](/modules/input/#tecs.input.Gamepad) owns one device's identity, event
state, capabilities, and outputs. A retained reference remains safe after
disconnection: queries return neutral values, outputs return false, and
`connected` stays false. A reconnect creates a new object rather than reviving
the old one.

Buttons use positional names. `"south"` names the button nearest the player on
every pad. `label("south")` returns the hardware label, such as `"a"` or
`"cross"`, for a prompt.

```teal
local pad <const> = app.input:gamepad(1)
if pad ~= nil and pad.connected then
    local moveX <const> = pad:axis("leftX")
    if pad:buttonPressed("south") then
        jump()
    end
end
```

Axes use a 0.15 deadzone by default. Output methods return false when the
device disconnects or lacks the requested hardware, so optional rumble and
lights need no capability branch.

Gamepad sensors remain off until `enableSensor` starts their event stream.
Their readings pass through the same layer stack as buttons and replay from
recorded events.

## Standalone sensors

Standalone accelerometers, gyroscopes and platform-specific sensors do not
belong to a gamepad. Enumerate a snapshot, open the selected instance id, poll
it, and close it explicitly.

```teal
for _, device in ipairs(tecs.input.sensors()) do
    local sensor <const>, reason <const> = tecs.input.openSensor(
        device.id
    )
    if sensor ~= nil then
        local values <const>, readError <const> = sensor:read()
        if values ~= nil then
            print(sensor.name, values[1], values[2], values[3])
        else
            print(readError)
        end
        sensor:destroy()
    else
        print(reason)
    end
end
```

`Sensor:read` returns three values by default and accepts one to sixteen for a
platform-specific sensor. Acceleration uses meters per second squared and
rotation uses radians per second.

## Module contents

### Constructors

| Constructor | Description |
| --- | --- |
| [`newInput`](/modules/input/#tecs.input.newInput) | Builds the input state a game reads, with a single base layer. |

### Types

| Type | Kind | Description |
| --- | --- | --- |
| [`Device`](/modules/input/#tecs.input.Device) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes one enumerated sensor before open. |
| [`Gamepad`](/modules/input/#tecs.input.Gamepad) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | A Gamepad owns one attached gamepad and folds its event state. |
| [`Input`](/modules/input/#tecs.input.Input) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | An Input folds platform events once a frame and exposes live state, frame edges and fixed-step latched edges. |
| [`Layer`](/modules/input/#tecs.input.Layer) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Identifies a position from pushLayer. |
| [`Options`](/modules/input/#tecs.input.Options) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes framework construction options for Input. |
| [`Sensor`](/modules/input/#tecs.input.Sensor) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes an opened standalone sensor. |
| [`SensorDevice`](/modules/input/#tecs.input.SensorDevice) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes an enumerated standalone sensor before open. |
| [`TextArea`](/modules/input/#tecs.input.TextArea) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes a caller-writable text rectangle. |
| [`TextOptions`](/modules/input/#tecs.input.TextOptions) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes caller-writable text-input options. |
| [`Touch`](/modules/input/#tecs.input.Touch) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Describes a finger from touches. |
| [`TouchpadFinger`](/modules/input/#tecs.input.TouchpadFinger) | <span class="tealdoc-kind-badge tealdoc-kind-type">type</span> | Describes a gamepad touch. |

### Functions

| Function | Kind | Description |
| --- | --- | --- |
| [`openSensor`](/modules/input/#tecs.input.openSensor) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Opens an attached standalone sensor by instance id. |
| [`sensors`](/modules/input/#tecs.input.sensors) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the standalone sensors attached now in platform order. |

## Constructors

<a id="tecs.input.newInput"></a>
### tecs.input.newInput <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Builds the input state a game reads, with a single base layer.

Holds no devices yet. `refreshDevices` opens the pads already attached,
and everything after that arrives as events.



```teal
function tecs.input.newInput(options: InputOptions): Input
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | [`InputOptions`](/modules/input/#tecs.input.Options) | The engine omits this record for a headless state. Keys and pads still fold while window commands report failure. |

#### Returns

| Type | Description |
| --- | --- |
| [`Input`](/modules/input/#tecs.input.Input) | Returns the state. The application owns one; a test may build another. |

## Types

<a id="tecs.input.Device"></a>
### tecs.input.Device <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes one enumerated sensor before open.


```teal
record tecs.input.Device
    id: number
    name: string
    kind: string
    platformType: integer
end
```

<a id="tecs.input.Device.id"></a>
#### tecs.input.Device.id <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `id` to an instance id that remains valid
while the device stays attached.


```teal
tecs.input.Device.id: number
```

<a id="tecs.input.Device.name"></a>
#### tecs.input.Device.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `name` to the device display name.


```teal
tecs.input.Device.name: string
```

<a id="tecs.input.Device.kind"></a>
#### tecs.input.Device.kind <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `kind` to `"accelerometer"`,
`"gyroscope"`, a left or right variant, or `"unknown"`.


```teal
tecs.input.Device.kind: string
```

<a id="tecs.input.Device.platformType"></a>
#### tecs.input.Device.platformType <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `platformType` to its private type number,
or zero when none exists. Ordinary game code ignores this field.


```teal
tecs.input.Device.platformType: integer
```

<a id="tecs.input.Gamepad"></a>
### tecs.input.Gamepad <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

A `Gamepad` owns one attached gamepad and folds its event state.

Input owns the object. Callers use its methods and treat public fields as
read-only snapshots that change on connection and remap events.
Read-only. `Gamepad` names one attached
device. Ordinary game code gets objects from `Input:gamepads` and does
not replace this module field.


```teal
record tecs.input.Gamepad
    record TouchpadFinger
        touchpad: integer
        finger: integer
        x: number
        y: number
        pressure: number
        down: boolean
    end

    id: number
    connected: boolean
    name: string
    kind: string
    guid: string
    path: string
    playerIndex: integer
    touchpads: integer

    openGamepad: function(
        backend: Backend, gate: Gate, id: number
    ): Gamepad
    axis: function(
        self, axis: string | integer, deadzone: number, layer: Layer
    ): number
    buttonDown: function(
        self, button: string | integer, layer: Layer
    ): boolean
    buttonPressed: function(
        self, button: string | integer, layer: Layer
    ): boolean
    buttonReleased: function(
        self, button: string | integer, layer: Layer
    ): boolean
    enableSensor: function(
        self, sensor: string | integer, enabled: boolean
    ): boolean
    hasAxis: function(self, axis: string | integer): boolean
    hasButton: function(self, button: string | integer): boolean
    hasSensor: function(self, sensor: string | integer): boolean
    label: function(self, button: string | integer): string
    power: function(self): string, integer
    rumble: function(
        self, low: number, high: number, seconds: number
    ): boolean
    rumbleTriggers: function(
        self, left: number, right: number, seconds: number
    ): boolean
    sensor: function(
        self, sensor: string | integer, layer: Layer
    ): number, number, number
    sensorEnabled: function(self, sensor: string | integer): boolean
    setLED: function(
        self, red: number, green: number, blue: number
    ): boolean
    setPlayerIndex: function(self, index: integer): boolean
    touchpadFingers: function(
        self, touchpad: integer, layer: Layer
    ): {TouchpadFinger}
end
```

<a id="tecs.input.Gamepad.TouchpadFinger"></a>
#### tecs.input.Gamepad.TouchpadFinger <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

`TouchpadFinger` reports one finger from the latest touchpad event.

Gamepad owns and reuses the record. Callers treat every field as read-only.
Read-only. Exposes
[`TouchpadFinger`](/modules/input/#tecs.input.TouchpadFinger), whose records
`touchpadFingers` returns. Ordinary game code does not replace this
field.


```teal
record tecs.input.Gamepad.TouchpadFinger
    touchpad: integer
    finger: integer
    x: number
    y: number
    pressure: number
    down: boolean
end
```

<a id="tecs.input.Gamepad.TouchpadFinger.touchpad"></a>
##### tecs.input.Gamepad.TouchpadFinger.touchpad <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad sets `touchpad` to the zero-based touchpad index when
it creates the record.


```teal
tecs.input.Gamepad.TouchpadFinger.touchpad: integer
```

<a id="tecs.input.Gamepad.TouchpadFinger.finger"></a>
##### tecs.input.Gamepad.TouchpadFinger.finger <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad sets `finger` to the zero-based slot on that
touchpad. The value identifies a position, not a persistent finger.


```teal
tecs.input.Gamepad.TouchpadFinger.finger: integer
```

<a id="tecs.input.Gamepad.TouchpadFinger.x"></a>
##### tecs.input.Gamepad.TouchpadFinger.x <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad updates `x` from 0 to 1 across the touchpad.


```teal
tecs.input.Gamepad.TouchpadFinger.x: number
```

<a id="tecs.input.Gamepad.TouchpadFinger.y"></a>
##### tecs.input.Gamepad.TouchpadFinger.y <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad updates `y` from 0 to 1 down the touchpad.


```teal
tecs.input.Gamepad.TouchpadFinger.y: number
```

<a id="tecs.input.Gamepad.TouchpadFinger.pressure"></a>
##### tecs.input.Gamepad.TouchpadFinger.pressure <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad updates `pressure` from 0 to 1 when the device
reports it.


```teal
tecs.input.Gamepad.TouchpadFinger.pressure: number
```

<a id="tecs.input.Gamepad.TouchpadFinger.down"></a>
##### tecs.input.Gamepad.TouchpadFinger.down <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Gamepad updates `down` when the finger enters or leaves the
pad and keeps the record for reuse.


```teal
tecs.input.Gamepad.TouchpadFinger.down: boolean
```

<a id="tecs.input.Gamepad.id"></a>
#### tecs.input.Gamepad.id <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `id` to the platform instance id when it opens the
device and never changes it.


```teal
tecs.input.Gamepad.id: number
```

<a id="tecs.input.Gamepad.connected"></a>
#### tecs.input.Gamepad.connected <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `connected` true at open and false permanently
when the device disconnects.


```teal
tecs.input.Gamepad.connected: boolean
```

<a id="tecs.input.Gamepad.name"></a>
#### tecs.input.Gamepad.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `name` at open and on remap. The platform
chooses it, so saved bindings use `guid` instead.


```teal
tecs.input.Gamepad.name: string
```

<a id="tecs.input.Gamepad.kind"></a>
#### tecs.input.Gamepad.kind <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `kind` at open and on remap. It contains a
platform device family such as `"xboxOne"`, `"ps5"` or `"standard"`.


```teal
tecs.input.Gamepad.kind: string
```

<a id="tecs.input.Gamepad.guid"></a>
#### tecs.input.Gamepad.guid <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `guid` at open and on remap. Game code uses
it to match saved bindings.


```teal
tecs.input.Gamepad.guid: string
```

<a id="tecs.input.Gamepad.path"></a>
#### tecs.input.Gamepad.path <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `path` at open and on remap. It contains an
empty string when the platform declines to report one.


```teal
tecs.input.Gamepad.path: string
```

<a id="tecs.input.Gamepad.playerIndex"></a>
#### tecs.input.Gamepad.playerIndex <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `playerIndex` on open, remap and a successful
`setPlayerIndex`. It contains -1 when the device has no slot.


```teal
tecs.input.Gamepad.playerIndex: integer
```

<a id="tecs.input.Gamepad.touchpads"></a>
#### tecs.input.Gamepad.touchpads <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input refreshes `touchpads` at open and on remap.


```teal
tecs.input.Gamepad.touchpads: integer
```

<a id="tecs.input.Gamepad.openGamepad"></a>
#### tecs.input.Gamepad.openGamepad <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Engine-owned. Opens a device for an Input object.

Ordinary game code gets gamepads from `Input:gamepads` and must not call
this function.



```teal
function tecs.input.Gamepad.openGamepad(
    backend: Backend, gate: Gate, id: number
): Gamepad
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `backend` | `Backend` | Input supplies the platform backend. |
| `gate` | `Gate` | Input supplies its shared layer gate. |
| `id` | `number` | Input supplies the platform instance id. |

##### Returns

| Type | Description |
| --- | --- |
| [`Gamepad`](/modules/input/#tecs.input.Gamepad) | Returns the opened gamepad, or nil when the device disappeared. |

<a id="tecs.input.Gamepad.axis"></a>
#### tecs.input.Gamepad:axis <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns an axis value after applying a deadzone.

Sticks return -1 to 1 and triggers return 0 to 1. Values outside the
deadzone keep their original magnitude.



```teal
function tecs.input.Gamepad.axis(
    self, axis: string | integer, deadzone: number, layer: Layer
): number
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `axis` | <code>string &#124; integer</code> | The caller supplies a name or platform number. An unknown name raises. |
| `deadzone` | `number` | The caller supplies the zero threshold or omits it for the hardware-oriented default of 0.15. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `number` | Returns zero when the layer cannot read or no event has set the axis. |

<a id="tecs.input.Gamepad.buttonDown"></a>
#### tecs.input.Gamepad:buttonDown <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a button is held.



```teal
function tecs.input.Gamepad.buttonDown(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a positional name or platform number. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Gamepad.buttonPressed"></a>
#### tecs.input.Gamepad:buttonPressed <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a button went down in the active tier.



```teal
function tecs.input.Gamepad.buttonPressed(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a positional name or platform number. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Gamepad.buttonReleased"></a>
#### tecs.input.Gamepad:buttonReleased <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a button came up in the active tier.



```teal
function tecs.input.Gamepad.buttonReleased(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a positional name or platform number. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Gamepad.enableSensor"></a>
#### tecs.input.Gamepad:enableSensor <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Enables or disables a gamepad sensor event stream.



```teal
function tecs.input.Gamepad.enableSensor(
    self, sensor: string | integer, enabled: boolean
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `sensor` | <code>string &#124; integer</code> | The caller supplies a sensor name or platform number. |
| `enabled` | `boolean` | The caller passes false to disable the stream; nil and true enable it. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the device accepted the change. |

<a id="tecs.input.Gamepad.hasAxis"></a>
#### tecs.input.Gamepad:hasAxis <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether the device carries an axis.



```teal
function tecs.input.Gamepad.hasAxis(
    self, axis: string | integer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `axis` | <code>string &#124; integer</code> | The caller supplies a name or platform number. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection. |

<a id="tecs.input.Gamepad.hasButton"></a>
#### tecs.input.Gamepad:hasButton <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether the device carries a button.



```teal
function tecs.input.Gamepad.hasButton(
    self, button: string | integer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a name or platform number. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection. |

<a id="tecs.input.Gamepad.hasSensor"></a>
#### tecs.input.Gamepad:hasSensor <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether the device carries a sensor.



```teal
function tecs.input.Gamepad.hasSensor(
    self, sensor: string | integer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `sensor` | <code>string &#124; integer</code> | The caller supplies `"gyro"`, `"accelerometer"` or a platform number. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection. |

<a id="tecs.input.Gamepad.label"></a>
#### tecs.input.Gamepad:label <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the hardware label printed on a button.



```teal
function tecs.input.Gamepad.label(
    self, button: string | integer
): string
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a positional name or platform number. |

##### Returns

| Type | Description |
| --- | --- |
| `string` | Returns a label such as `"a"` or `"cross"`, or `"unknown"` after disconnection. |

<a id="tecs.input.Gamepad.power"></a>
#### tecs.input.Gamepad:power <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the power state and charge.



```teal
function tecs.input.Gamepad.power(self): string, integer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |

##### Returns

| Type | Description |
| --- | --- |
| `string` | Returns `"onBattery"`, `"charging"`, `"charged"`, `"noBattery"`, `"unknown"` or `"error"`. |
| `integer` | Returns the percentage from 0 to 100, or -1 when unavailable. |

<a id="tecs.input.Gamepad.rumble"></a>
#### tecs.input.Gamepad:rumble <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Rumbles the low- and high-frequency motors.

A new call replaces an active effect.



```teal
function tecs.input.Gamepad.rumble(
    self, low: number, high: number, seconds: number
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `low` | `number` | The caller supplies the low-frequency strength from 0 to 1. |
| `high` | `number` | The caller supplies the high-frequency strength from 0 to 1. |
| `seconds` | `number` | The caller supplies the duration in seconds. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection or without rumble hardware. |

<a id="tecs.input.Gamepad.rumbleTriggers"></a>
#### tecs.input.Gamepad:rumbleTriggers <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Rumbles the left and right trigger motors.



```teal
function tecs.input.Gamepad.rumbleTriggers(
    self, left: number, right: number, seconds: number
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `left` | `number` | The caller supplies the left strength from 0 to 1. |
| `right` | `number` | The caller supplies the right strength from 0 to 1. |
| `seconds` | `number` | The caller supplies the duration in seconds. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection or without trigger motors. |

<a id="tecs.input.Gamepad.sensor"></a>
#### tecs.input.Gamepad:sensor <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the latest event reading from a gamepad sensor.



```teal
function tecs.input.Gamepad.sensor(
    self, sensor: string | integer, layer: Layer
): number, number, number
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `sensor` | <code>string &#124; integer</code> | The caller supplies a sensor name or platform number. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `number` | Returns the x component, or zero when unreadable. |
| `number` | Returns the y component, or zero when unreadable. |
| `number` | Returns the z component, or zero when unreadable. |

<a id="tecs.input.Gamepad.sensorEnabled"></a>
#### tecs.input.Gamepad:sensorEnabled <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a gamepad sensor is streaming.



```teal
function tecs.input.Gamepad.sensorEnabled(
    self, sensor: string | integer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `sensor` | <code>string &#124; integer</code> | The caller supplies a sensor name or platform number. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns live device state and false after disconnection. |

<a id="tecs.input.Gamepad.setLED"></a>
#### tecs.input.Gamepad:setLED <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Sets the gamepad light color.



```teal
function tecs.input.Gamepad.setLED(
    self, red: number, green: number, blue: number
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `red` | `number` | The caller supplies the red channel from 0 to 1. |
| `green` | `number` | The caller supplies the green channel from 0 to 1. |
| `blue` | `number` | The caller supplies the blue channel from 0 to 1. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false after disconnection or without a light. |

<a id="tecs.input.Gamepad.setPlayerIndex"></a>
#### tecs.input.Gamepad:setPlayerIndex <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Assigns the platform player slot.

A successful call updates the read-only `playerIndex` field.



```teal
function tecs.input.Gamepad.setPlayerIndex(
    self, index: integer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `index` | `integer` | The caller supplies a zero-based slot or -1 for none. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the device accepted the slot. |

<a id="tecs.input.Gamepad.touchpadFingers"></a>
#### tecs.input.Gamepad:touchpadFingers <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the fingers currently on a gamepad touchpad.



```teal
function tecs.input.Gamepad.touchpadFingers(
    self, touchpad: integer, layer: Layer
): {TouchpadFinger}
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Gamepad` |  |
| `touchpad` | `integer` | The caller supplies a zero-based index or omits it for the first touchpad. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `{`[`TouchpadFinger`](/modules/input/#tecs.input.Gamepad.TouchpadFinger)`}` | Returns a new list of Gamepad-owned records. Callers copy values they need to retain. |

<a id="tecs.input.Input"></a>
### tecs.input.Input <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

An `Input` folds platform events once a frame and exposes live state,
frame edges and fixed-step latched edges.


```teal
record tecs.input.Input
    record Layer
        name: string
        blocking: boolean
        index: integer
    end

    record Touch
        device: string
        finger: string
        x: number
        y: number
        normalX: number
        normalY: number
        pressure: number
    end

    record TextArea
        x: integer
        y: integer
        width: integer
        height: integer
        cursor: integer
    end

    record TextOptions
        area: TextArea
    end

    Options: InputOptions
    mouseX: number
    mouseY: number
    mouseDeltaX: number
    mouseDeltaY: number
    wheelX: number
    wheelY: number
    wheelPreferredX: number
    wheelPreferredY: number
    wheelTicksX: integer
    wheelTicksY: integer
    mouseWhich: number
    mouseSynthetic: boolean
    text: string
    composition: string
    compositionStart: integer
    compositionLength: integer
    penX: number
    penY: number
    penPressure: number
    penTiltX: number
    penTiltY: number
    penRotation: number
    penTouching: boolean
    penEraser: boolean
    penWhich: number

    beginFrame: function(self)
    canRead: function(self, layer: Layer): boolean
    captureMouse: function(self, enabled: boolean): boolean
    cursorVisible: function(self): boolean
    destroy: function(self)
    enterFixedPhase: function(self)
    exitFixedPhase: function(self)
    gamepad: function(self, index: integer): Gamepad
    gamepadById: function(self, id: number): Gamepad
    gamepads: function(self): {Gamepad}
    handleEvent: function(self, event: eventStream.Event)
    keyDown: function(
        self, key: string | integer, layer: Layer
    ): boolean
    keyName: function(self, scancode: integer): string
    keyPressed: function(
        self, key: string | integer, layer: Layer
    ): boolean
    keyReleased: function(
        self, key: string | integer, layer: Layer
    ): boolean
    modifierDown: function(self, name: string, layer: Layer): boolean
    modifiers: function(self): integer
    mouseDown: function(
        self, button: string | integer, layer: Layer
    ): boolean
    mousePressed: function(
        self, button: string | integer, layer: Layer
    ): boolean
    mouseReleased: function(
        self, button: string | integer, layer: Layer
    ): boolean
    popLayer: function(self): Layer
    pushLayer: function(self, name: string, blocking: boolean): Layer
    refreshDevices: function(self)
    relativeMouseMode: function(self): boolean
    scancode: function(self, name: string): integer
    screenKeyboardSupported: function(self): boolean
    setCursor: function(self, name: string): boolean
    setRelativeMouseMode: function(self, enabled: boolean): boolean
    setTextInputArea: function(self, area: TextArea): boolean
    showCursor: function(self, visible: boolean): boolean
    startTextInput: function(
        self, layer: Layer, options: TextOptions
    ): boolean
    stopTextInput: function(self): boolean
    textInputActive: function(self): boolean
    textInputLayer: function(self): Layer
    topLayer: function(self): Layer
    touches: function(self, layer: Layer): {Touch}
    warpMouse: function(self, x: number, y: number)
end
```

<a id="tecs.input.Input.Layer"></a>
#### tecs.input.Input.Layer <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Read-only. [`Layer`](/modules/input/#tecs.input.Layer) names a position
returned by `pushLayer`.


```teal
record tecs.input.Input.Layer
    name: string
    blocking: boolean
    index: integer
end
```

<a id="tecs.input.Input.Layer.name"></a>
##### tecs.input.Input.Layer.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Names what the layer is for in diagnostics. Not an identity:
two layers may share a name, and a query is answered from the object
rather than from what it is called.


```teal
tecs.input.Input.Layer.name: string
```

<a id="tecs.input.Input.Layer.blocking"></a>
##### tecs.input.Input.Layer.blocking <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether this layer hides input from the layers
beneath it.


```teal
tecs.input.Input.Layer.blocking: boolean
```

<a id="tecs.input.Input.Layer.index"></a>
##### tecs.input.Input.Layer.index <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the position in the stack. Input compares it against
the topmost blocking layer to decide whether this layer may read.

Fixed when the layer is pushed. Nothing renumbers, because the base
layer is never removed and only the top one ever is, so an index cannot
go stale while its layer is still on the stack.


```teal
tecs.input.Input.Layer.index: integer
```

<a id="tecs.input.Input.Touch"></a>
#### tecs.input.Input.Touch <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

`Touch` reports one finger from the most recent touch event.

Input owns and reuses every field. Callers treat the record as read-only
and copy values they need to retain.
Read-only. [`Touch`](/modules/input/#tecs.input.Touch) names a finger record
returned by `touches`.


```teal
record tecs.input.Input.Touch
    device: string
    finger: string
    x: number
    y: number
    normalX: number
    normalY: number
    pressure: number
end
```

<a id="tecs.input.Input.Touch.device"></a>
##### tecs.input.Input.Touch.device <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `device` to the touch device's opaque identity
when the finger first appears.


```teal
tecs.input.Input.Touch.device: string
```

<a id="tecs.input.Input.Touch.finger"></a>
##### tecs.input.Input.Touch.finger <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `finger` to the finger's opaque 64-bit identity
when the finger first appears.


```teal
tecs.input.Input.Touch.finger: string
```

<a id="tecs.input.Input.Touch.x"></a>
##### tecs.input.Input.Touch.x <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `x` in window coordinates on every touch event.
It may lag a resize until the application updates the conversion size.


```teal
tecs.input.Input.Touch.x: number
```

<a id="tecs.input.Input.Touch.y"></a>
##### tecs.input.Input.Touch.y <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `y` in window coordinates with `x`.


```teal
tecs.input.Input.Touch.y: number
```

<a id="tecs.input.Input.Touch.normalX"></a>
##### tecs.input.Input.Touch.normalX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `normalX` from the platform's 0 to 1 position
on every touch event.


```teal
tecs.input.Input.Touch.normalX: number
```

<a id="tecs.input.Input.Touch.normalY"></a>
##### tecs.input.Input.Touch.normalY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `normalY` with `normalX`.


```teal
tecs.input.Input.Touch.normalY: number
```

<a id="tecs.input.Input.Touch.pressure"></a>
##### tecs.input.Input.Touch.pressure <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `pressure` from 0 to 1 when the surface reports
pressure.


```teal
tecs.input.Input.Touch.pressure: number
```

<a id="tecs.input.Input.TextArea"></a>
#### tecs.input.Input.TextArea <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Callers write `TextArea` before passing it to a text-input method.

Input reads the record immediately and does not retain it.
Read-only. Exposes [`TextArea`](/modules/input/#tecs.input.TextArea), whose
records callers pass to text-input methods.


```teal
record tecs.input.Input.TextArea
    x: integer
    y: integer
    width: integer
    height: integer
    cursor: integer
end
```

<a id="tecs.input.Input.TextArea.x"></a>
##### tecs.input.Input.TextArea.x <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `x` to the rectangle's left edge in
window coordinates.


```teal
tecs.input.Input.TextArea.x: integer
```

<a id="tecs.input.Input.TextArea.y"></a>
##### tecs.input.Input.TextArea.y <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `y` to the rectangle's top edge.


```teal
tecs.input.Input.TextArea.y: integer
```

<a id="tecs.input.Input.TextArea.width"></a>
##### tecs.input.Input.TextArea.width <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `width` to the text run the platform
should keep clear.


```teal
tecs.input.Input.TextArea.width: integer
```

<a id="tecs.input.Input.TextArea.height"></a>
##### tecs.input.Input.TextArea.height <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `height` with `width`.


```teal
tecs.input.Input.TextArea.height: integer
```

<a id="tecs.input.Input.TextArea.cursor"></a>
##### tecs.input.Input.TextArea.cursor <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `cursor` to the caret offset from the
left edge. It defaults to zero.


```teal
tecs.input.Input.TextArea.cursor: integer
```

<a id="tecs.input.Input.TextOptions"></a>
#### tecs.input.Input.TextOptions <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Read-only. Exposes
[`TextOptions`](/modules/input/#tecs.input.TextOptions), whose records
callers pass to `startTextInput`.


```teal
record tecs.input.Input.TextOptions
    area: TextArea
end
```

<a id="tecs.input.Input.TextOptions.area"></a>
##### tecs.input.Input.TextOptions.area <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `area` so the platform can keep its
candidate window and on-screen keyboard clear of the edited text.


```teal
tecs.input.Input.TextOptions.area: TextArea
```

<a id="tecs.input.Input.Options"></a>
#### tecs.input.Input.Options <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Engine-owned. Exposes the framework construction options. Ordinary
game code uses the Input that the application creates and ignores
this field.


```teal
tecs.input.Input.Options: InputOptions
```

<a id="tecs.input.Input.mouseX"></a>
#### tecs.input.Input.mouseX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `mouseX` from the most recent mouse event
and retains it across frames without motion.


```teal
tecs.input.Input.mouseX: number
```

<a id="tecs.input.Input.mouseY"></a>
#### tecs.input.Input.mouseY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `mouseY` with `mouseX`.


```teal
tecs.input.Input.mouseY: number
```

<a id="tecs.input.Input.mouseDeltaX"></a>
#### tecs.input.Input.mouseDeltaX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates `mouseDeltaX` during a frame and clears
it in `beginFrame`.


```teal
tecs.input.Input.mouseDeltaX: number
```

<a id="tecs.input.Input.mouseDeltaY"></a>
#### tecs.input.Input.mouseDeltaY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates `mouseDeltaY` and clears it with
`mouseDeltaX`.


```teal
tecs.input.Input.mouseDeltaY: number
```

<a id="tecs.input.Input.wheelX"></a>
#### tecs.input.Input.wheelX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates horizontal wheel motion during a frame
and clears it in `beginFrame`. Positive `wheelX` scrolls right.


```teal
tecs.input.Input.wheelX: number
```

<a id="tecs.input.Input.wheelY"></a>
#### tecs.input.Input.wheelY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates vertical wheel motion under the sign
convention above and clears it in `beginFrame`.


```teal
tecs.input.Input.wheelY: number
```

<a id="tecs.input.Input.wheelPreferredX"></a>
#### tecs.input.Input.wheelPreferredX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates horizontal wheel motion after applying
the platform's configured scroll direction. Scrolling interfaces
should use this pair; directional gameplay bindings should use
`wheelX` and `wheelY` for their stable sign convention.


```teal
tecs.input.Input.wheelPreferredX: number
```

<a id="tecs.input.Input.wheelPreferredY"></a>
#### tecs.input.Input.wheelPreferredY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates vertical wheel motion under the user's
configured scroll direction and clears it with `wheelPreferredX`.


```teal
tecs.input.Input.wheelPreferredY: number
```

<a id="tecs.input.Input.wheelTicksX"></a>
#### tecs.input.Input.wheelTicksX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates horizontal whole-notch wheel motion
during a frame and clears it in `beginFrame`.


```teal
tecs.input.Input.wheelTicksX: integer
```

<a id="tecs.input.Input.wheelTicksY"></a>
#### tecs.input.Input.wheelTicksY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input accumulates vertical whole-notch wheel motion and
clears it with `wheelTicksX`.


```teal
tecs.input.Input.wheelTicksY: integer
```

<a id="tecs.input.Input.mouseWhich"></a>
#### tecs.input.Input.mouseWhich <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `mouseWhich` to the device from the most recent
mouse button, motion or wheel event.


```teal
tecs.input.Input.mouseWhich: number
```

<a id="tecs.input.Input.mouseSynthetic"></a>
#### tecs.input.Input.mouseSynthetic <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `mouseSynthetic` when that mouse event came
from the platform's touch or pen translation.


```teal
tecs.input.Input.mouseSynthetic: boolean
```

<a id="tecs.input.Input.text"></a>
#### tecs.input.Input.text <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input appends committed text during a frame and clears it
in `beginFrame`.


```teal
tecs.input.Input.text: string
```

<a id="tecs.input.Input.composition"></a>
#### tecs.input.Input.composition <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input replaces `composition` when the input method edits
uncommitted text and clears it on commit or session stop.


```teal
tecs.input.Input.composition: string
```

<a id="tecs.input.Input.compositionStart"></a>
#### tecs.input.Input.compositionStart <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `compositionStart` to the caret offset within
`composition`.


```teal
tecs.input.Input.compositionStart: integer
```

<a id="tecs.input.Input.compositionLength"></a>
#### tecs.input.Input.compositionLength <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `compositionLength` to the selected length
within `composition`.


```teal
tecs.input.Input.compositionLength: integer
```

<a id="tecs.input.Input.penX"></a>
#### tecs.input.Input.penX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penX` from the most recent pen event.


```teal
tecs.input.Input.penX: number
```

<a id="tecs.input.Input.penY"></a>
#### tecs.input.Input.penY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penY` with `penX`.


```teal
tecs.input.Input.penY: number
```

<a id="tecs.input.Input.penPressure"></a>
#### tecs.input.Input.penPressure <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penPressure` from 0 to 1 and clears it when
the pen leaves proximity.


```teal
tecs.input.Input.penPressure: number
```

<a id="tecs.input.Input.penTiltX"></a>
#### tecs.input.Input.penTiltX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penTiltX` in degrees from upright.


```teal
tecs.input.Input.penTiltX: number
```

<a id="tecs.input.Input.penTiltY"></a>
#### tecs.input.Input.penTiltY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penTiltY` with `penTiltX`.


```teal
tecs.input.Input.penTiltY: number
```

<a id="tecs.input.Input.penRotation"></a>
#### tecs.input.Input.penRotation <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penRotation` in clockwise degrees.


```teal
tecs.input.Input.penRotation: number
```

<a id="tecs.input.Input.penTouching"></a>
#### tecs.input.Input.penTouching <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `penTouching` on contact and clears it when
the pen leaves proximity.


```teal
tecs.input.Input.penTouching: boolean
```

<a id="tecs.input.Input.penEraser"></a>
#### tecs.input.Input.penEraser <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `penEraser` when a stroke begins.


```teal
tecs.input.Input.penEraser: boolean
```

<a id="tecs.input.Input.penWhich"></a>
#### tecs.input.Input.penWhich <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `penWhich` to the most recent pen identity. A
second pen replaces the first pen's state.


```teal
tecs.input.Input.penWhich: number
```

<a id="tecs.input.Input.beginFrame"></a>
#### tecs.input.Input:beginFrame <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Starts a new frame and clears frame-local values.

The application calls this before it folds events. Ordinary game
code must not call it.


```teal
function tecs.input.Input.beginFrame(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

None.

<a id="tecs.input.Input.canRead"></a>
#### tecs.input.Input:canRead <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a layer may read input.



```teal
function tecs.input.Input.canRead(self, layer: Layer): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to test the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when a blocking layer sits above it. |

<a id="tecs.input.Input.captureMouse"></a>
#### tecs.input.Input:captureMouse <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Enables or disables mouse capture outside the window.



```teal
function tecs.input.Input.captureMouse(self, enabled: boolean): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `enabled` | `boolean` | The caller passes false to release capture; nil and true enable it. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform accepted the change. |

<a id="tecs.input.Input.cursorVisible"></a>
#### tecs.input.Input:cursorVisible <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether the platform shows the cursor.



```teal
function tecs.input.Input.cursorVisible(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns live platform state. |

<a id="tecs.input.Input.destroy"></a>
#### tecs.input.Input:destroy <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Closes devices and platform input resources.

The application calls this during shutdown. Ordinary game code must
not call it.


```teal
function tecs.input.Input.destroy(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

None.

<a id="tecs.input.Input.enterFixedPhase"></a>
#### tecs.input.Input:enterFixedPhase <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Selects latched edges for a fixed step.

The fixed-phase bracket calls this method. Ordinary game code must
not call it.


```teal
function tecs.input.Input.enterFixedPhase(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

None.

<a id="tecs.input.Input.exitFixedPhase"></a>
#### tecs.input.Input:exitFixedPhase <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Clears latched edges after a fixed step.

The fixed-phase bracket calls this method. Ordinary game code must
not call it.


```teal
function tecs.input.Input.exitFixedPhase(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

None.

<a id="tecs.input.Input.gamepad"></a>
#### tecs.input.Input:gamepad <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns a connected gamepad by connection order.



```teal
function tecs.input.Input.gamepad(self, index: integer): Gamepad
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `index` | `integer` | The caller supplies a one-based position, or nil for the first gamepad. |

##### Returns

| Type | Description |
| --- | --- |
| [`Gamepad`](/modules/input/#tecs.input.Gamepad) | Returns the gamepad, or nil when the position is empty. |

<a id="tecs.input.Input.gamepadById"></a>
#### tecs.input.Input:gamepadById <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns a connected gamepad by platform instance id.



```teal
function tecs.input.Input.gamepadById(self, id: number): Gamepad
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `id` | `number` | The caller supplies an id from a platform event. |

##### Returns

| Type | Description |
| --- | --- |
| [`Gamepad`](/modules/input/#tecs.input.Gamepad) | Returns the gamepad, or nil after it disconnects. |

<a id="tecs.input.Input.gamepads"></a>
#### tecs.input.Input:gamepads <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the live list of connected gamepads.



```teal
function tecs.input.Input.gamepads(self): {Gamepad}
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `{`[`Gamepad`](/modules/input/#tecs.input.Gamepad)`}` | Returns Input-owned storage. Callers may retain a [`Gamepad`](/modules/input/#tecs.input.Gamepad) from it but must not edit the list. |

<a id="tecs.input.Input.handleEvent"></a>
#### tecs.input.Input:handleEvent <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Folds one typed platform event into input state.

The application passes every event here. Input copies every value
it retains. Ordinary game code must not call this method.



```teal
function tecs.input.Input.handleEvent(self, event: eventStream.Event)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `event` | [`eventStream.Event`](/modules/platform/events/#tecs.platform.events.Event) | The engine supplies a borrowed event record. |

##### Returns

None.

<a id="tecs.input.Input.keyDown"></a>
#### tecs.input.Input:keyDown <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a physical key is held.



```teal
function tecs.input.Input.keyDown(
    self, key: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `key` | <code>string &#124; integer</code> | The caller supplies a key name or scancode. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.keyName"></a>
#### tecs.input.Input:keyName <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the platform name for a physical key.



```teal
function tecs.input.Input.keyName(self, scancode: integer): string
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `scancode` | `integer` | The caller supplies a platform scancode. |

##### Returns

| Type | Description |
| --- | --- |
| `string` | Returns the display name for a binding prompt. |

<a id="tecs.input.Input.keyPressed"></a>
#### tecs.input.Input:keyPressed <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a physical key went down in the active tier.

Fixed phases read latched edges; other phases read frame edges.



```teal
function tecs.input.Input.keyPressed(
    self, key: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `key` | <code>string &#124; integer</code> | The caller supplies a key name or scancode. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.keyReleased"></a>
#### tecs.input.Input:keyReleased <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a physical key came up in the active tier.



```teal
function tecs.input.Input.keyReleased(
    self, key: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `key` | <code>string &#124; integer</code> | The caller supplies a key name or scancode. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.modifierDown"></a>
#### tecs.input.Input:modifierDown <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a named modifier is held.



```teal
function tecs.input.Input.modifierDown(
    self, name: string, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `name` | `string` | The caller supplies `"shift"`, `"ctrl"`, `"alt"`, `"gui"`, `"capsLock"` or a sided variant. An unknown name raises. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.modifiers"></a>
#### tecs.input.Input:modifiers <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the modifier mask from the most recent key event.

The value ignores layers and resets on focus loss.



```teal
function tecs.input.Input.modifiers(self): integer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `integer` | Returns the platform modifier bits. |

<a id="tecs.input.Input.mouseDown"></a>
#### tecs.input.Input:mouseDown <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a mouse button is held.



```teal
function tecs.input.Input.mouseDown(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a platform number or `"left"`, `"middle"`, `"right"`, `"x1"` or `"x2"`. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.mousePressed"></a>
#### tecs.input.Input:mousePressed <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a mouse button went down in the active tier.



```teal
function tecs.input.Input.mousePressed(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a button name or number. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.mouseReleased"></a>
#### tecs.input.Input:mouseReleased <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether a mouse button came up in the active tier.



```teal
function tecs.input.Input.mouseReleased(
    self, button: string | integer, layer: Layer
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `button` | <code>string &#124; integer</code> | The caller supplies a button name or number. |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when the layer cannot read. |

<a id="tecs.input.Input.popLayer"></a>
#### tecs.input.Input:popLayer <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Removes and returns the top layer.

The base layer remains in place. Popping the owner of a text-input
session stops that session.



```teal
function tecs.input.Input.popLayer(self): Layer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| [`Layer`](/modules/input/#tecs.input.Input.Layer) | Returns the removed layer, or nil at the base layer. |

<a id="tecs.input.Input.pushLayer"></a>
#### tecs.input.Input:pushLayer <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Pushes a layer and returns it.

A blocking layer moves capture and clears pending edges. A
nonblocking layer observes input without hiding lower layers.



```teal
function tecs.input.Input.pushLayer(
    self, name: string, blocking: boolean
): Layer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `name` | `string` | The caller supplies a diagnostic layer name. |
| `blocking` | `boolean` | The caller passes false for a nonblocking overlay; nil and true create a blocking layer. |

##### Returns

| Type | Description |
| --- | --- |
| [`Layer`](/modules/input/#tecs.input.Input.Layer) | Returns the new layer, which remains caller-owned until `popLayer` removes it. |

<a id="tecs.input.Input.refreshDevices"></a>
#### tecs.input.Input:refreshDevices <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Engine-owned. Opens gamepads present at startup.

The application calls this once before event intake. Ordinary game
code observes the resulting `gamepads` list.


```teal
function tecs.input.Input.refreshDevices(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

None.

<a id="tecs.input.Input.relativeMouseMode"></a>
#### tecs.input.Input:relativeMouseMode <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether relative mouse mode is active.



```teal
function tecs.input.Input.relativeMouseMode(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns live platform state rather than the last request. |

<a id="tecs.input.Input.scancode"></a>
#### tecs.input.Input:scancode <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Resolves and caches a physical key name.



```teal
function tecs.input.Input.scancode(self, name: string): integer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `name` | `string` | The caller supplies the platform key name without regard to case. An unknown name raises. |

##### Returns

| Type | Description |
| --- | --- |
| `integer` | Returns the platform scancode. |

<a id="tecs.input.Input.screenKeyboardSupported"></a>
#### tecs.input.Input:screenKeyboardSupported <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether the platform supplies an on-screen keyboard.



```teal
function tecs.input.Input.screenKeyboardSupported(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns live platform capability state. |

<a id="tecs.input.Input.setCursor"></a>
#### tecs.input.Input:setCursor <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Selects a standard platform cursor.

Input owns the created cursor and releases it on replacement or
`destroy`.



```teal
function tecs.input.Input.setCursor(self, name: string): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `name` | `string` | The caller omits this value or passes `"default"` to restore the platform cursor. An unknown name raises. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform accepted the cursor. |

<a id="tecs.input.Input.setRelativeMouseMode"></a>
#### tecs.input.Input:setRelativeMouseMode <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Enables or disables relative mouse mode.

Relative mode hides the cursor, freezes its position and reports
movement through the delta fields.



```teal
function tecs.input.Input.setRelativeMouseMode(
    self, enabled: boolean
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `enabled` | `boolean` | The caller passes false to disable the mode; nil and true enable it. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform accepted the change. |

<a id="tecs.input.Input.setTextInputArea"></a>
#### tecs.input.Input:setTextInputArea <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Moves the area a running text session reports after its field scrolls
or its caret moves.



```teal
function tecs.input.Input.setTextInputArea(
    self, area: TextArea
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `area` | [`TextArea`](/modules/input/#tecs.input.Input.TextArea) | Input reads this record immediately and does not retain it. A later edit has no effect until another call. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform accepted the hint. Text input continues when it returns false. |

<a id="tecs.input.Input.showCursor"></a>
#### tecs.input.Input:showCursor <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Shows or hides the application cursor.



```teal
function tecs.input.Input.showCursor(self, visible: boolean): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `visible` | `boolean` | The caller passes false to hide the cursor; nil and true show it. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform accepted the change. |

<a id="tecs.input.Input.startTextInput"></a>
#### tecs.input.Input:startTextInput <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Starts text input and optionally binds it to a layer.

Popping the owner layer stops the session.



```teal
function tecs.input.Input.startTextInput(
    self, layer: Layer, options: TextOptions
): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value for a session it will stop explicitly. |
| `options` | [`TextOptions`](/modules/input/#tecs.input.Input.TextOptions) | The caller may supply the edited text area. Input reads the record immediately and does not retain it. |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns whether the platform started the session. |

<a id="tecs.input.Input.stopTextInput"></a>
#### tecs.input.Input:stopTextInput <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Stops text input and clears the current composition.

The layer stack and shutdown path both call this method, so its
declaration sits beside the rest of the text-input contract.



```teal
function tecs.input.Input.stopTextInput(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false when no session was running. The method still clears composition state, so a teardown may call it unconditionally. |

<a id="tecs.input.Input.textInputActive"></a>
#### tecs.input.Input:textInputActive <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns whether this Input started a text-input session.



```teal
function tecs.input.Input.textInputActive(self): boolean
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| `boolean` | Returns false for sessions started outside this object. |

<a id="tecs.input.Input.textInputLayer"></a>
#### tecs.input.Input:textInputLayer <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the layer that owns the current text-input session.



```teal
function tecs.input.Input.textInputLayer(self): Layer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| [`Layer`](/modules/input/#tecs.input.Input.Layer) | Returns nil when no layer owns the session. |

<a id="tecs.input.Input.topLayer"></a>
#### tecs.input.Input:topLayer <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the layer currently on top.



```teal
function tecs.input.Input.topLayer(self): Layer
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |

##### Returns

| Type | Description |
| --- | --- |
| [`Layer`](/modules/input/#tecs.input.Input.Layer) | Returns the live layer object. Callers treat its fields as read-only. |

<a id="tecs.input.Input.touches"></a>
#### tecs.input.Input:touches <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Returns the fingers currently on the touch surface.



```teal
function tecs.input.Input.touches(self, layer: Layer): {Touch}
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `layer` | [`Layer`](/modules/input/#tecs.input.Input.Layer) | The caller omits this value to read the base layer. |

##### Returns

| Type | Description |
| --- | --- |
| `{`[`Touch`](/modules/input/#tecs.input.Input.Touch)`}` | Returns Input-owned list and records that the next call may reuse. Callers copy values they need to retain. |

<a id="tecs.input.Input.warpMouse"></a>
#### tecs.input.Input:warpMouse <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Moves the cursor within the window.

The platform emits a motion event for the warp.



```teal
function tecs.input.Input.warpMouse(self, x: number, y: number)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Input` |  |
| `x` | `number` | The caller supplies the window-coordinate x position. |
| `y` | `number` | The caller supplies the window-coordinate y position. |

##### Returns

None.

<a id="tecs.input.Layer"></a>
### tecs.input.Layer <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Identifies a position from `pushLayer`.


```teal
record tecs.input.Layer
    name: string
    blocking: boolean
    index: integer
end
```

<a id="tecs.input.Layer.name"></a>
#### tecs.input.Layer.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Names what the layer is for in diagnostics. Not an identity:
two layers may share a name, and a query is answered from the object
rather than from what it is called.


```teal
tecs.input.Layer.name: string
```

<a id="tecs.input.Layer.blocking"></a>
#### tecs.input.Layer.blocking <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports whether this layer hides input from the layers
beneath it.


```teal
tecs.input.Layer.blocking: boolean
```

<a id="tecs.input.Layer.index"></a>
#### tecs.input.Layer.index <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the position in the stack. Input compares it against
the topmost blocking layer to decide whether this layer may read.

Fixed when the layer is pushed. Nothing renumbers, because the base
layer is never removed and only the top one ever is, so an index cannot
go stale while its layer is still on the stack.


```teal
tecs.input.Layer.index: integer
```

<a id="tecs.input.Options"></a>
### tecs.input.Options <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes framework construction options for `Input`.


```teal
record tecs.input.Options
    window: loader.CPtr
    backend: Backend
end
```

<a id="tecs.input.Options.window"></a>
#### tecs.input.Options.window <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Engine-owned. The application supplies `window` for text input and
cursor modes. Ordinary game code ignores this field; omitting it makes
window commands report failure for a headless test.


```teal
tecs.input.Options.window: loader.CPtr
```

<a id="tecs.input.Options.backend"></a>
#### tecs.input.Options.backend <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Engine-owned. The application or a platform test supplies `backend`.
Ordinary game code ignores it. Input uses the installed backend when
the field is nil.


```teal
tecs.input.Options.backend: Backend
```

<a id="tecs.input.Sensor"></a>
### tecs.input.Sensor <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes an opened standalone sensor.


```teal
record tecs.input.Sensor
    id: number
    name: string
    kind: string
    platformType: integer

    destroy: function(self)
    read: function(self, count: integer): {number}, string
end
```

<a id="tecs.input.Sensor.id"></a>
#### tecs.input.Sensor.id <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `id` from the opened device.


```teal
tecs.input.Sensor.id: number
```

<a id="tecs.input.Sensor.name"></a>
#### tecs.input.Sensor.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `name` from the opened device.


```teal
tecs.input.Sensor.name: string
```

<a id="tecs.input.Sensor.kind"></a>
#### tecs.input.Sensor.kind <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `kind` from the same vocabulary as
`Device.kind`.


```teal
tecs.input.Sensor.kind: string
```

<a id="tecs.input.Sensor.platformType"></a>
#### tecs.input.Sensor.platformType <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `platformType` to its private type number,
or zero when none exists. Ordinary game code ignores this field.


```teal
tecs.input.Sensor.platformType: integer
```

<a id="tecs.input.Sensor.destroy"></a>
#### tecs.input.Sensor:destroy <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Closes the sensor. Safe to call more than once.


```teal
function tecs.input.Sensor.destroy(self)
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Sensor` |  |

##### Returns

None.

<a id="tecs.input.Sensor.read"></a>
#### tecs.input.Sensor:read <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Reads the newest values.

Three values is the natural size for accelerometers and gyroscopes. A
platform-specific sensor can request up to sixteen.



```teal
function tecs.input.Sensor.read(
    self, count: integer
): {number}, string
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Sensor` |  |
| `count` | `integer` | The caller requests one to sixteen values or omits the count for three. Invalid counts return an error instead of raising. |

##### Returns

| Type | Description |
| --- | --- |
| `{number}` | Returns a fresh caller-owned list. Acceleration uses meters per second squared and rotation uses radians per second. The method returns nil after failure or destruction. |
| `string` | Returns the reason when the first return is nil. |

<a id="tecs.input.SensorDevice"></a>
### tecs.input.SensorDevice <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes an enumerated standalone sensor before open.


```teal
record tecs.input.SensorDevice
    id: number
    name: string
    kind: string
    platformType: integer
end
```

<a id="tecs.input.SensorDevice.id"></a>
#### tecs.input.SensorDevice.id <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `id` to an instance id that remains valid
while the device stays attached.


```teal
tecs.input.SensorDevice.id: number
```

<a id="tecs.input.SensorDevice.name"></a>
#### tecs.input.SensorDevice.name <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `name` to the device display name.


```teal
tecs.input.SensorDevice.name: string
```

<a id="tecs.input.SensorDevice.kind"></a>
#### tecs.input.SensorDevice.kind <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `kind` to `"accelerometer"`,
`"gyroscope"`, a left or right variant, or `"unknown"`.


```teal
tecs.input.SensorDevice.kind: string
```

<a id="tecs.input.SensorDevice.platformType"></a>
#### tecs.input.SensorDevice.platformType <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. The platform sets `platformType` to its private type number,
or zero when none exists. Ordinary game code ignores this field.


```teal
tecs.input.SensorDevice.platformType: integer
```

<a id="tecs.input.TextArea"></a>
### tecs.input.TextArea <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes a caller-writable text rectangle.


```teal
record tecs.input.TextArea
    x: integer
    y: integer
    width: integer
    height: integer
    cursor: integer
end
```

<a id="tecs.input.TextArea.x"></a>
#### tecs.input.TextArea.x <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `x` to the rectangle's left edge in
window coordinates.


```teal
tecs.input.TextArea.x: integer
```

<a id="tecs.input.TextArea.y"></a>
#### tecs.input.TextArea.y <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `y` to the rectangle's top edge.


```teal
tecs.input.TextArea.y: integer
```

<a id="tecs.input.TextArea.width"></a>
#### tecs.input.TextArea.width <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `width` to the text run the platform
should keep clear.


```teal
tecs.input.TextArea.width: integer
```

<a id="tecs.input.TextArea.height"></a>
#### tecs.input.TextArea.height <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `height` with `width`.


```teal
tecs.input.TextArea.height: integer
```

<a id="tecs.input.TextArea.cursor"></a>
#### tecs.input.TextArea.cursor <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `cursor` to the caret offset from the
left edge. It defaults to zero.


```teal
tecs.input.TextArea.cursor: integer
```

<a id="tecs.input.TextOptions"></a>
### tecs.input.TextOptions <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes caller-writable text-input options.


```teal
record tecs.input.TextOptions
    area: TextArea
end
```

<a id="tecs.input.TextOptions.area"></a>
#### tecs.input.TextOptions.area <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. The caller sets `area` so the platform can keep its
candidate window and on-screen keyboard clear of the edited text.


```teal
tecs.input.TextOptions.area: TextArea
```

<a id="tecs.input.Touch"></a>
### tecs.input.Touch <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Describes a finger from `touches`.


```teal
record tecs.input.Touch
    device: string
    finger: string
    x: number
    y: number
    normalX: number
    normalY: number
    pressure: number
end
```

<a id="tecs.input.Touch.device"></a>
#### tecs.input.Touch.device <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `device` to the touch device's opaque identity
when the finger first appears.


```teal
tecs.input.Touch.device: string
```

<a id="tecs.input.Touch.finger"></a>
#### tecs.input.Touch.finger <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input sets `finger` to the finger's opaque 64-bit identity
when the finger first appears.


```teal
tecs.input.Touch.finger: string
```

<a id="tecs.input.Touch.x"></a>
#### tecs.input.Touch.x <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `x` in window coordinates on every touch event.
It may lag a resize until the application updates the conversion size.


```teal
tecs.input.Touch.x: number
```

<a id="tecs.input.Touch.y"></a>
#### tecs.input.Touch.y <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `y` in window coordinates with `x`.


```teal
tecs.input.Touch.y: number
```

<a id="tecs.input.Touch.normalX"></a>
#### tecs.input.Touch.normalX <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `normalX` from the platform's 0 to 1 position
on every touch event.


```teal
tecs.input.Touch.normalX: number
```

<a id="tecs.input.Touch.normalY"></a>
#### tecs.input.Touch.normalY <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `normalY` with `normalX`.


```teal
tecs.input.Touch.normalY: number
```

<a id="tecs.input.Touch.pressure"></a>
#### tecs.input.Touch.pressure <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Input updates `pressure` from 0 to 1 when the surface reports
pressure.


```teal
tecs.input.Touch.pressure: number
```

<a id="tecs.input.TouchpadFinger"></a>
### tecs.input.TouchpadFinger <span class="tealdoc-kind-badge tealdoc-kind-type">type</span>

Describes a gamepad touch.


```teal
type tecs.input.TouchpadFinger = Gamepad.TouchpadFinger
```

## Functions

<a id="tecs.input.openSensor"></a>
### tecs.input.openSensor <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Opens an attached standalone sensor by instance id.



```teal
function tecs.input.openSensor(id: number): sensors.Sensor, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `id` | `number` | The caller supplies an instance id from `sensors`. It stops naming the device after unplug. |

#### Returns

| Type | Description |
| --- | --- |
| [`sensors.Sensor`](/modules/input/#tecs.input.Sensor) | Returns the open sensor, or nil on failure. The caller closes it with `destroy`. |
| `string` | Returns the reason when the first return is nil. |

<a id="tecs.input.sensors"></a>
### tecs.input.sensors <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the standalone sensors attached now in platform order.

A snapshot rather than a subscription: a sensor unplugged after this
leaves an id `openSensor` refuses. Gamepad sensors are not here, since
their identity and event routing live on the pad.



```teal
function tecs.input.sensors(): {sensors.Device}, string
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `{`[`sensors.Device`](/modules/input/#tecs.input.Device)`}` | Returns a fresh caller-owned list. It returns an empty list when no sensors exist or the subsystem cannot start. |
| `string` | Returns the platform's reason when enumeration fails. |