rojo/.cursor/rules/roblox/reference/engine/classes/InputObject.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: InputObject
type: class
memory_category: Instances
summary: |
  An object created when an input begins that describes a particular user input.
description: |
  An `InputObject` represents a single user input, such as mouse movement,
  touches, key presses and more. It is created when an input begins.

  The properties of this object vary according the
  `Class.InputObject.UserInputType|UserInputType`. Each kind of input will
  undergo various changes to its
  `Class.InputObject.UserInputState|UserInputState`. During the lifetime of an
  input, other properties which further describe the input may change, such as
  `Class.InputObject.Position|Position` and `Class.InputObject.Delta|Delta`.
  Keyboard and gamepad button presses will have the
  `Class.InputObject.KeyCode|KeyCode` property set.

  Once created at the beginning of an input, the same object persists and is
  updated until the input ends. As a result, you can track the object's changes
  using the `Class.Object.Changed|Changed` event as the user changes the input
  in question. You can also place these objects into a list of active inputs
  track and interact with the object after it's creation by an event such as
  `Class.UserInputService.InputBegan`. This is mostly useful for touch events,
  as each touch point will have a separate `InputObject`.

  See also `Class.UserInputService` whose events and functions often use
  `InputObject`, and `Class.GuiObject` whose events related to user input use
  `InputObject`.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
deprecation_message: ''
properties:
  - name: InputObject.Delta
    summary: |
      A `Datatype.Vector3` describing the delta between input movements.
    description: |
      A `Datatype.Vector3` describing the delta (change) between input
      movements.

      This is useful when used with the input's
      `Class.InputObject.Position|Position` to track the position and movement
      of the user's input, such as when you're creating custom movement or
      camera scripts. Consider tracking input object changes using the
      `Class.Object.Changed` event or when user input changes via events such as
      `Class.UserInputService.InputChanged` and `Class.GuiObject.InputChanged`.

      Note that an `Class.InputObject` corresponding to
      `Enum.UserInputType.MouseButton1` (left click) and
      `Enum.UserInputType.MouseButton2` (right click) supplied from an
      `Class.UserInputService.InputBegan|InputBegan` callback will not have its
      `Class.InputObject.Delta|Delta` or `Class.InputObject.Position|Position`
      updated once created, except for when the mouse input ends. In order to
      get updated deltas for mouse inputs, you must instead reference an
      `Class.InputObject` from an
      `Class.UserInputService.InputChanged|InputChanged` callback, or call
      `Class.UserInputService:GetMouseDelta()|GetMouseDelta()`. However, any
      `Class.InputObject|InputObjects` corresponding to touch inputs will have
      their delta and position updated every frame throughout their lifetime.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: InputObject.KeyCode
    summary: |
      Contains an Enum that describes the kind of input used.
    description: |
      Contains a `Enum.KeyCode` enum that describes what kind of input was used.
      For types of input like keyboard, this describes what key was pressed. For
      inputs like the mouse, this provides no additional information.
    code_samples: []
    type: KeyCode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: InputObject.Position
    summary: |
      A `Datatype.Vector3` describing the positional value of this input.
    description: |
      A `Datatype.Vector3` describing the positional value of this input.

      For mouse and touch input, this is the screen position of the mouse/touch,
      described in the **X** and **Y** components. The inset applied to GUI
      elements (such as from the top bar) is accounted for in the position. For
      the mouse wheel input, the **Z** component describes whether the wheel was
      moved forward (`1`), backwards (`-1`), or not at all (`0`).

      Note that an `Class.InputObject` corresponding to
      `Enum.UserInputType.MouseButton1` (left click) and
      `Enum.UserInputType.MouseButton2` (right click) supplied from an
      `Class.UserInputService.InputBegan|InputBegan` callback will not have its
      `Class.InputObject.Delta|Delta` or `Class.InputObject.Position|Position`
      updated once created, except for when the mouse input ends. In order to
      get updated positions for mouse inputs, you must instead reference an
      `Class.InputObject` from an
      `Class.UserInputService.InputChanged|InputChanged` callback, or call
      `Class.UserInputService:GetMouseLocation()|GetMouseLocation()`. However,
      any `Class.InputObject|InputObjects` corresponding to touch inputs will
      have their delta and position updated every frame throughout their
      lifetime.
    code_samples: []
    type: Vector3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: InputObject.UserInputState
    summary: |
      Describes the state of an input being performed, following a specific flow
      depending on the `Class.InputObject.UserInputType|UserInputType`.
    description: |
      This property describes the state of an input being performed, following a
      specific flow depending on the
      `Class.InputObject.UserInputType|UserInputType`. It uses the enum of the
      same name, `Enum.UserInputState`.
    code_samples: []
    type: UserInputState
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: State
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
  - name: InputObject.UserInputType
    summary: |
      Describes the kind of input being performed (mouse, keyboard, gamepad,
      touch, etc.).
    description: |
      This property describes the kind of input this `Class.InputObject`
      represents, such as mouse, keyboard, touch, or gamepad input. It uses the
      enum of the same name, `Enum.UserInputType`.
    code_samples: []
    type: UserInputType
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Data
    serialization:
      can_load: false
      can_save: false
    capabilities:
      - Input
methods:
  - name: InputObject:IsModifierKeyDown
    summary: |
      Returns whether the passed in modifier key is down.
    description: |
      Returns `true` if the passed in `modifierKey` such as
      `Enum.ModifierKey|Shift` is being held down.
    code_samples: []
    parameters:
      - name: modifierKey
        type: ModifierKey
        default:
        summary: ''
    returns:
      - type: boolean
        summary: |
          `true` if the passed in `modifierKey` is being held down; `false`
          otherwise.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - Input
events: []
callbacks: []