Input module

Module for reading input and working with player bindings.

Scripts ask about roles, not physical keys. A role is a game action such as jumping, drawing a weapon, or opening a menu. The key or button that triggers it depends on the player's device and layout.

Use \{input ...} in text to draw the binding for a role.

Properties

  • trx.input.backend (trx.input.Backend). The current input source. (read-only)
  • trx.input.layout (trx.input.Layout). The current layout for the current input source. (read-only)
  • trx.input.is_listening (boolean). Whether script input capture is on. (read-only)

Enums

  • trx.input.Role - 77 names

    A game action the player can bind to a key or button. In text, \{input ...} draws its current binding.

    Click here to see a list of all symbols.

    ACTION, BACK, CAMERA_BACK, CAMERA_DOWN, CAMERA_FORWARD, CAMERA_LEFT, CAMERA_RESET, CAMERA_RIGHT, CAMERA_UP, CHANGE_OUTFIT, CHANGE_TARGET, CROUCH, CYCLE_LIGHTING_MODEL, DRAW, ENTER_CONSOLE, EQUIP_AUTOS, EQUIP_DESERT_EAGLE, EQUIP_GRENADE_LAUNCHER, EQUIP_HARPOON, EQUIP_M16, EQUIP_MAGNUMS, EQUIP_MP5, EQUIP_PISTOLS, EQUIP_ROCKET_LAUNCHER, EQUIP_SHOTGUN, EQUIP_UZIS, FAST_FORWARD_CHEAT, FLY_CHEAT, FORWARD, ITEM_CHEAT, JUMP, LEFT, LEVEL_SKIP_CHEAT, LOAD, LOOK, MENU_BACK, MENU_COARSE_ADJUST, MENU_CONFIRM, MENU_DOWN, MENU_FINE_ADJUST, MENU_LEFT, MENU_RIGHT, MENU_SHOW_INFO, MENU_SKIP, MENU_TAB_LEFT, MENU_TAB_RIGHT, MENU_UP, OPTION, PAUSE, QUICK_LOAD, QUICK_SAVE, RESET_BINDINGS, RIGHT, ROLL, SAVE, SCREENSHOT, SLOW, SLOW_MOTION_CHEAT, SPRINT, STEP_LEFT, STEP_RIGHT, SWITCH_BORDERS, SWITCH_UPSCALING, TOGGLE_BILINEAR_FILTER, TOGGLE_FPS_COUNTER, TOGGLE_FULLSCREEN, TOGGLE_PHOTO_MODE, TOGGLE_TEXTURES, TOGGLE_TRAPEZOID_FILTER, TOGGLE_UI, TOGGLE_WIREFRAME, TURBO_CHEAT, UNBIND_KEY, USE_BIG_MEDI, USE_BINOCULARS, USE_FLARE, USE_SMALL_MEDI

  • trx.input.Backend

    An input source, such as keyboard, controller, or touch.

    • trx.input.Backend.KEYBOARD = 0
      The keyboard, with the mouse.
    • trx.input.Backend.CONTROLLER = 1
      A game controller.
    • trx.input.Backend.TOUCH = 2
      The on-screen controls.

  • trx.input.Layout

    A saved set of bindings for one input source. The default layout is read-only; the custom layouts belong to the player.

    • trx.input.Layout.DEFAULT = 0
      The bindings the game ships with.
    • trx.input.Layout.CUSTOM_1 = 1
      The player's first layout.
    • trx.input.Layout.CUSTOM_2 = 2
      The player's second layout.
    • trx.input.Layout.CUSTOM_3 = 3
      The player's third layout.

Structures

  • trx.input.Slot

    Which of the two bindings a role can use. Counted from 1.

  • trx.input.Binding

    The slot, input source, and layout of a role binding.

    Properties:

    • backend: trx.input.Backend, optional. Input source. Defaults to the current one.
    • layout: trx.input.Layout, optional. Layout. Defaults to the current one.
    • slot: trx.input.Slot, optional, default 1. Binding slot. Defaults to the first.

  • trx.input.Capture

    A binding capture waiting for the player to press something.

    Methods:

    • capture:cancel()
      Stops the capture and leaves the binding as it was.

      Turning capture off is part of this, so a script that gives up does not have to do it itself.

      Returns: boolean. Whether the capture was still running.

Functions

  • trx.input.signals
    Input roles as signals.

    Each role has one shared signal, so several consumers of the same role use one read per tick.

  • trx.input.is_held(role)
    Whether a role is active right now.

    This stays true while the player holds the bound key or button. Use it for actions that continue while held.

    Parameters:

    Returns: boolean. Whether the role is active.

  • trx.input.is_pressed(role)
    Whether a role became active this frame.

    This is true for one frame only. Use it for actions that happen once per press.

    Parameters:

    Returns: boolean. Whether the role was pressed.

  • trx.input.is_anything_held()
    Whether any role is active right now.

    Use this to wait for the player to let go before reading input for something else, such as a rebind.

    Returns: boolean. Whether anything is held.

  • trx.input.hold_off(role)
    Keeps a handled role inactive until the player releases it.

    Use this after a script handles a press, so the same press does not reach other input code or fire again while held.

    Parameters:

  • trx.input.is_backend_enabled(backend)
    Whether an input source is enabled.

    Disabled sources are not read or shown in the controls dialog.

    Parameters:

    Returns: boolean. Whether the input source is enabled.

  • trx.input.role_name(role)
    The name the game shows for a role, in the player's language.

    Parameters:

    Returns: string. The name of the role.

  • trx.input.layout_name([layout])
    The name the game shows for a layout, in the player's language.

    Parameters:

    • layout (trx.input.Layout, optional). The layout to name. Defaults to the current one.

    Returns: string. The name of the layout.

  • trx.input.key_name(role, [opts], [backend], [layout])
    Text for the key or button bound to a role.

    This is the text drawn by \{input ...}: a glyph when one exists, otherwise a key name. Empty bindings return nil.

    Use trx.input.Binding to choose a slot, input source, or layout without placeholder nils. Positional arguments still work.

    Parameters:

    Returns: string or nil. The key text, or nil if the binding is empty.

  • trx.input.has_glyph(role, [opts], [backend], [layout])
    Whether trx.input.key_name has text to draw for a role binding.

    Use this to hide prompts for unbound roles.

    Use trx.input.Binding to choose a slot, input source, or layout without placeholder nils. Positional arguments still work.

    Parameters:

    Returns: boolean. Whether the binding has text to draw.

  • trx.input.is_rebindable(role)
    Whether the player can change a role's binding.

    Roles reserved by the game cannot be rebound and do not count as conflicts.

    Parameters:

    Returns: boolean. Whether it can be bound.

  • trx.input.is_unbindable(role)
    Whether the player can leave a role without a binding.

    Parameters:

    Returns: boolean. Whether it can be left unbound.

  • trx.input.is_conflicted(role, [opts], [layout])
    Whether another role uses the same binding in the same layout.

    Use trx.input.Binding to choose an input source or layout without placeholder nils. Positional arguments still work.

    Parameters:

    Returns: boolean. Whether the binding is used twice.

  • trx.input.listen(enabled)
    Turns script input capture on or off.

    While capture is on, scripts can read or bind input without the game acting on the same input. Turn capture off as soon as the input is handled.

    Parameters:

    • enabled (boolean). Whether script input capture is enabled.

  • trx.input.with_listen(fn)
    Runs a function with script input capture on.

    Restores the previous capture state after the function returns or raises an error. Returns the function's results.

    Parameters:

    • fn (function). Function to run while input is captured.

    Returns: any. What the function returned.

  • trx.input.bind_pressed(role, [opts], [backend], [layout])
    Binds a role to the key or button the player is holding.

    Returns false if no input is held. Call it each frame while waiting for input, with trx.input.listen on or from inside trx.input.with_listen. The default layout is read-only.

    Use trx.input.Binding to choose a slot, input source, or layout without placeholder nils. Positional arguments still work.

    Parameters:

    Returns: boolean. Whether a key was taken.

  • trx.input.capture(role, [opts], [done])
    Binds a role to the next key or button the player presses.

    The capture spans frames: it waits for the player to let go of what is already down, turns capture on, and takes the first press after that. The previous capture state is restored when it lands or when the capture is cancelled.

    Use this instead of trx.input.listen and trx.input.bind_pressed, which only answer for the frame they run on. The default layout is read-only.

    Use trx.input.Binding to choose a slot, input source, or layout without placeholder nils.

    Parameters:

    • role (trx.input.Role). The role to bind.
    • opts (trx.input.Slot or trx.input.Binding, optional). Binding to write. Defaults to the first slot on the current source and layout.
    • done (function, optional). Called when the capture ends. Called with:
      • bound (boolean). Whether a key was taken.

    Returns: trx.input.Capture. The running capture.

  • trx.input.unbind(role, [opts], [backend], [layout])
    Clears one role binding.

    The default layout is read-only, and roles reserved by the game cannot be left unbound.

    Use trx.input.Binding to choose a slot, input source, or layout without placeholder nils. Positional arguments still work.

    Parameters:

  • trx.input.reset_layout([opts], [layout])
    Restores a custom layout to the default bindings.

    Use trx.input.Binding to choose an input source or layout without placeholder nils. Positional arguments still work.

    Parameters:

  • trx.input.signals.held(role)
    A signal for whether a role is active.

    It is true while the player holds the bound key or button. It changes when the role becomes active and when it stops.

    Parameters:

    Returns: trx.signal.Signal. The role's signal.

  • trx.input.signals.pressed(role)
    A signal for when a role becomes active.

    It is true for one tick only, so listeners run once per press.

    Parameters:

    Returns: trx.signal.Signal. The role's signal.