tecs.input#

Gameplay input#

tecs.input folds typed platform events into gameplay input. The application creates one 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.

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.

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 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 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.

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.

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#

Types#

Functions#

Constructors#

tecs.input.newInput Static#

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.

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

Arguments#

Returns#

Types#

tecs.input.Device record#

Describes one enumerated sensor before open.

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

tecs.input.Device.id field#

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

tecs.input.Device.id: number

tecs.input.Device.name field#

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

tecs.input.Device.name: string

tecs.input.Device.kind field#

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

tecs.input.Device.kind: string

tecs.input.Device.platformType field#

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

tecs.input.Device.platformType: integer

tecs.input.Gamepad record#

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.

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

tecs.input.Gamepad.TouchpadFinger record#

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, whose records touchpadFingers returns. Ordinary game code does not replace this field.

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

tecs.input.Gamepad.TouchpadFinger.touchpad field

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

tecs.input.Gamepad.TouchpadFinger.touchpad: integer

tecs.input.Gamepad.TouchpadFinger.finger field

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

tecs.input.Gamepad.TouchpadFinger.finger: integer

tecs.input.Gamepad.TouchpadFinger.x field

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

tecs.input.Gamepad.TouchpadFinger.x: number

tecs.input.Gamepad.TouchpadFinger.y field

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

tecs.input.Gamepad.TouchpadFinger.y: number

tecs.input.Gamepad.TouchpadFinger.pressure field

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

tecs.input.Gamepad.TouchpadFinger.pressure: number

tecs.input.Gamepad.TouchpadFinger.down field

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

tecs.input.Gamepad.TouchpadFinger.down: boolean

tecs.input.Gamepad.id field#

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

tecs.input.Gamepad.id: number

tecs.input.Gamepad.connected field#

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

tecs.input.Gamepad.connected: boolean

tecs.input.Gamepad.name field#

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

tecs.input.Gamepad.name: string

tecs.input.Gamepad.kind field#

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

tecs.input.Gamepad.kind: string

tecs.input.Gamepad.guid field#

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

tecs.input.Gamepad.guid: string

tecs.input.Gamepad.path field#

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

tecs.input.Gamepad.path: string

tecs.input.Gamepad.playerIndex field#

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

tecs.input.Gamepad.playerIndex: integer

tecs.input.Gamepad.touchpads field#

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

tecs.input.Gamepad.touchpads: integer

tecs.input.Gamepad.openGamepad Static#

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

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

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

Arguments

Returns

tecs.input.Gamepad:axis Instance#

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.

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

Arguments

Returns

tecs.input.Gamepad:buttonDown Instance#

Returns whether a button is held.

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

Arguments

Returns

tecs.input.Gamepad:buttonPressed Instance#

Returns whether a button went down in the active tier.

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

Arguments

Returns

tecs.input.Gamepad:buttonReleased Instance#

Returns whether a button came up in the active tier.

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

Arguments

Returns

tecs.input.Gamepad:enableSensor Instance#

Enables or disables a gamepad sensor event stream.

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

Arguments

Returns

tecs.input.Gamepad:hasAxis Instance#

Returns whether the device carries an axis.

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

Arguments

Returns

tecs.input.Gamepad:hasButton Instance#

Returns whether the device carries a button.

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

Arguments

Returns

tecs.input.Gamepad:hasSensor Instance#

Returns whether the device carries a sensor.

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

Arguments

Returns

tecs.input.Gamepad:label Instance#

Returns the hardware label printed on a button.

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

Arguments

Returns

tecs.input.Gamepad:power Instance#

Returns the power state and charge.

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

Arguments

Returns

tecs.input.Gamepad:rumble Instance#

Rumbles the low- and high-frequency motors.

A new call replaces an active effect.

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

Arguments

Returns

tecs.input.Gamepad:rumbleTriggers Instance#

Rumbles the left and right trigger motors.

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

Arguments

Returns

tecs.input.Gamepad:sensor Instance#

Returns the latest event reading from a gamepad sensor.

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

Arguments

Returns

tecs.input.Gamepad:sensorEnabled Instance#

Returns whether a gamepad sensor is streaming.

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

Arguments

Returns

tecs.input.Gamepad:setLED Instance#

Sets the gamepad light color.

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

Arguments

Returns

tecs.input.Gamepad:setPlayerIndex Instance#

Assigns the platform player slot.

A successful call updates the read-only playerIndex field.

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

Arguments

Returns

tecs.input.Gamepad:touchpadFingers Instance#

Returns the fingers currently on a gamepad touchpad.

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

Arguments

Returns

tecs.input.Input record#

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

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

tecs.input.Input.Layer record#

Read-only. Layer names a position returned by pushLayer.

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

tecs.input.Input.Layer.name field

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.

tecs.input.Input.Layer.name: string

tecs.input.Input.Layer.blocking field

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

tecs.input.Input.Layer.blocking: boolean

tecs.input.Input.Layer.index field

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.

tecs.input.Input.Layer.index: integer

tecs.input.Input.Touch record#

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 names a finger record returned by touches.

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

tecs.input.Input.Touch.device field

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

tecs.input.Input.Touch.device: string

tecs.input.Input.Touch.finger field

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

tecs.input.Input.Touch.finger: string

tecs.input.Input.Touch.x field

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

tecs.input.Input.Touch.x: number

tecs.input.Input.Touch.y field

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

tecs.input.Input.Touch.y: number

tecs.input.Input.Touch.normalX field

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

tecs.input.Input.Touch.normalX: number

tecs.input.Input.Touch.normalY field

Read-only. Input updates normalY with normalX.

tecs.input.Input.Touch.normalY: number

tecs.input.Input.Touch.pressure field

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

tecs.input.Input.Touch.pressure: number

tecs.input.Input.TextArea record#

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, whose records callers pass to text-input methods.

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

tecs.input.Input.TextArea.x field

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

tecs.input.Input.TextArea.x: integer

tecs.input.Input.TextArea.y field

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

tecs.input.Input.TextArea.y: integer

tecs.input.Input.TextArea.width field

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

tecs.input.Input.TextArea.width: integer

tecs.input.Input.TextArea.height field

Caller-writable. The caller sets height with width.

tecs.input.Input.TextArea.height: integer

tecs.input.Input.TextArea.cursor field

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

tecs.input.Input.TextArea.cursor: integer

tecs.input.Input.TextOptions record#

Read-only. Exposes TextOptions, whose records callers pass to startTextInput.

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

tecs.input.Input.TextOptions.area field

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

tecs.input.Input.TextOptions.area: TextArea

tecs.input.Input.Options field#

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

tecs.input.Input.Options: InputOptions

tecs.input.Input.mouseX field#

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

tecs.input.Input.mouseX: number

tecs.input.Input.mouseY field#

Read-only. Input updates mouseY with mouseX.

tecs.input.Input.mouseY: number

tecs.input.Input.mouseDeltaX field#

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

tecs.input.Input.mouseDeltaX: number

tecs.input.Input.mouseDeltaY field#

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

tecs.input.Input.mouseDeltaY: number

tecs.input.Input.wheelX field#

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

tecs.input.Input.wheelX: number

tecs.input.Input.wheelY field#

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

tecs.input.Input.wheelY: number

tecs.input.Input.wheelPreferredX field#

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.

tecs.input.Input.wheelPreferredX: number

tecs.input.Input.wheelPreferredY field#

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

tecs.input.Input.wheelPreferredY: number

tecs.input.Input.wheelTicksX field#

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

tecs.input.Input.wheelTicksX: integer

tecs.input.Input.wheelTicksY field#

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

tecs.input.Input.wheelTicksY: integer

tecs.input.Input.mouseWhich field#

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

tecs.input.Input.mouseWhich: number

tecs.input.Input.mouseSynthetic field#

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

tecs.input.Input.mouseSynthetic: boolean

tecs.input.Input.text field#

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

tecs.input.Input.text: string

tecs.input.Input.composition field#

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

tecs.input.Input.composition: string

tecs.input.Input.compositionStart field#

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

tecs.input.Input.compositionStart: integer

tecs.input.Input.compositionLength field#

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

tecs.input.Input.compositionLength: integer

tecs.input.Input.penX field#

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

tecs.input.Input.penX: number

tecs.input.Input.penY field#

Read-only. Input updates penY with penX.

tecs.input.Input.penY: number

tecs.input.Input.penPressure field#

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

tecs.input.Input.penPressure: number

tecs.input.Input.penTiltX field#

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

tecs.input.Input.penTiltX: number

tecs.input.Input.penTiltY field#

Read-only. Input updates penTiltY with penTiltX.

tecs.input.Input.penTiltY: number

tecs.input.Input.penRotation field#

Read-only. Input updates penRotation in clockwise degrees.

tecs.input.Input.penRotation: number

tecs.input.Input.penTouching field#

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

tecs.input.Input.penTouching: boolean

tecs.input.Input.penEraser field#

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

tecs.input.Input.penEraser: boolean

tecs.input.Input.penWhich field#

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

tecs.input.Input.penWhich: number

tecs.input.Input:beginFrame Instance#

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.

function tecs.input.Input.beginFrame(self)

Arguments

Returns

None.

tecs.input.Input:canRead Instance#

Returns whether a layer may read input.

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

Arguments

Returns

tecs.input.Input:captureMouse Instance#

Enables or disables mouse capture outside the window.

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

Arguments

Returns

tecs.input.Input:cursorVisible Instance#

Returns whether the platform shows the cursor.

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

Arguments

Returns

tecs.input.Input:destroy Instance#

Engine-owned. Closes devices and platform input resources.

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

function tecs.input.Input.destroy(self)

Arguments

Returns

None.

tecs.input.Input:enterFixedPhase Instance#

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

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

function tecs.input.Input.enterFixedPhase(self)

Arguments

Returns

None.

tecs.input.Input:exitFixedPhase Instance#

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

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

function tecs.input.Input.exitFixedPhase(self)

Arguments

Returns

None.

tecs.input.Input:gamepad Instance#

Returns a connected gamepad by connection order.

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

Arguments

Returns

tecs.input.Input:gamepadById Instance#

Returns a connected gamepad by platform instance id.

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

Arguments

Returns

tecs.input.Input:gamepads Instance#

Returns the live list of connected gamepads.

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

Arguments

Returns

tecs.input.Input:handleEvent Instance#

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.

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

Arguments

Returns

None.

tecs.input.Input:keyDown Instance#

Returns whether a physical key is held.

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

Arguments

Returns

tecs.input.Input:keyName Instance#

Returns the platform name for a physical key.

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

Arguments

Returns

tecs.input.Input:keyPressed Instance#

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

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

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

Arguments

Returns

tecs.input.Input:keyReleased Instance#

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

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

Arguments

Returns

tecs.input.Input:modifierDown Instance#

Returns whether a named modifier is held.

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

Arguments

Returns

tecs.input.Input:modifiers Instance#

Returns the modifier mask from the most recent key event.

The value ignores layers and resets on focus loss.

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

Arguments

Returns

tecs.input.Input:mouseDown Instance#

Returns whether a mouse button is held.

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

Arguments

Returns

tecs.input.Input:mousePressed Instance#

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

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

Arguments

Returns

tecs.input.Input:mouseReleased Instance#

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

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

Arguments

Returns

tecs.input.Input:popLayer Instance#

Removes and returns the top layer.

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

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

Arguments

Returns

tecs.input.Input:pushLayer Instance#

Pushes a layer and returns it.

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

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

Arguments

Returns

tecs.input.Input:refreshDevices Instance#

Engine-owned. Opens gamepads present at startup.

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

function tecs.input.Input.refreshDevices(self)

Arguments

Returns

None.

tecs.input.Input:relativeMouseMode Instance#

Returns whether relative mouse mode is active.

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

Arguments

Returns

tecs.input.Input:scancode Instance#

Resolves and caches a physical key name.

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

Arguments

Returns

tecs.input.Input:screenKeyboardSupported Instance#

Returns whether the platform supplies an on-screen keyboard.

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

Arguments

Returns

tecs.input.Input:setCursor Instance#

Selects a standard platform cursor.

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

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

Arguments

Returns

tecs.input.Input:setRelativeMouseMode Instance#

Enables or disables relative mouse mode.

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

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

Arguments

Returns

tecs.input.Input:setTextInputArea Instance#

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

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

Arguments

Returns

tecs.input.Input:showCursor Instance#

Shows or hides the application cursor.

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

Arguments

Returns

tecs.input.Input:startTextInput Instance#

Starts text input and optionally binds it to a layer.

Popping the owner layer stops the session.

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

Arguments

Returns

tecs.input.Input:stopTextInput Instance#

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.

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

Arguments

Returns

tecs.input.Input:textInputActive Instance#

Returns whether this Input started a text-input session.

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

Arguments

Returns

tecs.input.Input:textInputLayer Instance#

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

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

Arguments

Returns

tecs.input.Input:topLayer Instance#

Returns the layer currently on top.

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

Arguments

Returns

tecs.input.Input:touches Instance#

Returns the fingers currently on the touch surface.

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

Arguments

Returns

tecs.input.Input:warpMouse Instance#

Moves the cursor within the window.

The platform emits a motion event for the warp.

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

Arguments

Returns

None.

tecs.input.Layer record#

Identifies a position from pushLayer.

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

tecs.input.Layer.name field#

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.

tecs.input.Layer.name: string

tecs.input.Layer.blocking field#

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

tecs.input.Layer.blocking: boolean

tecs.input.Layer.index field#

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.

tecs.input.Layer.index: integer

tecs.input.Options record#

Describes framework construction options for Input.

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

tecs.input.Options.window field#

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.

tecs.input.Options.window: loader.CPtr

tecs.input.Options.backend field#

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.

tecs.input.Options.backend: Backend

tecs.input.Sensor record#

Describes an opened standalone sensor.

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

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

tecs.input.Sensor.id field#

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

tecs.input.Sensor.id: number

tecs.input.Sensor.name field#

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

tecs.input.Sensor.name: string

tecs.input.Sensor.kind field#

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

tecs.input.Sensor.kind: string

tecs.input.Sensor.platformType field#

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

tecs.input.Sensor.platformType: integer

tecs.input.Sensor:destroy Instance#

Closes the sensor. Safe to call more than once.

function tecs.input.Sensor.destroy(self)

Arguments

Returns

None.

tecs.input.Sensor:read Instance#

Reads the newest values.

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

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

Arguments

Returns

tecs.input.SensorDevice record#

Describes an enumerated standalone sensor before open.

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

tecs.input.SensorDevice.id field#

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

tecs.input.SensorDevice.id: number

tecs.input.SensorDevice.name field#

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

tecs.input.SensorDevice.name: string

tecs.input.SensorDevice.kind field#

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

tecs.input.SensorDevice.kind: string

tecs.input.SensorDevice.platformType field#

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

tecs.input.SensorDevice.platformType: integer

tecs.input.TextArea record#

Describes a caller-writable text rectangle.

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

tecs.input.TextArea.x field#

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

tecs.input.TextArea.x: integer

tecs.input.TextArea.y field#

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

tecs.input.TextArea.y: integer

tecs.input.TextArea.width field#

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

tecs.input.TextArea.width: integer

tecs.input.TextArea.height field#

Caller-writable. The caller sets height with width.

tecs.input.TextArea.height: integer

tecs.input.TextArea.cursor field#

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

tecs.input.TextArea.cursor: integer

tecs.input.TextOptions record#

Describes caller-writable text-input options.

record tecs.input.TextOptions
    area: TextArea
end

tecs.input.TextOptions.area field#

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

tecs.input.TextOptions.area: TextArea

tecs.input.Touch record#

Describes a finger from touches.

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

tecs.input.Touch.device field#

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

tecs.input.Touch.device: string

tecs.input.Touch.finger field#

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

tecs.input.Touch.finger: string

tecs.input.Touch.x field#

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

tecs.input.Touch.x: number

tecs.input.Touch.y field#

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

tecs.input.Touch.y: number

tecs.input.Touch.normalX field#

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

tecs.input.Touch.normalX: number

tecs.input.Touch.normalY field#

Read-only. Input updates normalY with normalX.

tecs.input.Touch.normalY: number

tecs.input.Touch.pressure field#

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

tecs.input.Touch.pressure: number

tecs.input.TouchpadFinger type#

Describes a gamepad touch.

type tecs.input.TouchpadFinger = Gamepad.TouchpadFinger

Functions#

tecs.input.openSensor Static#

Opens an attached standalone sensor by instance id.

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

Arguments#

Returns#

tecs.input.sensors Static#

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.

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

Arguments#

None.

Returns#