InputObject

Show Deprecated
Not Creatable

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 UserInputType. Each kind of input will undergo various changes to its UserInputState. During the lifetime of an input, other properties which further describe the input may change, such as Position and Delta. Keyboard and gamepad button presses will have the 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 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 UserInputService.InputBegan. This is mostly useful for touch events, as each touch point will have a separate InputObject.

See also:

Code Samples

Handling InputChanged

1-- In order to use the InputChanged event, the UserInputService service must be used
2local UserInputService = game:GetService("UserInputService")
3
4-- Prints the current input position and the change (delta) in position
5local function printMovement(input)
6 print("Position:", input.Position)
7 print("Movement Delta:", input.Delta)
8end
9
10-- A sample function providing multiple usage cases for various types of user input
11local function InputChanged(input, _gameProcessed)
12 if input.UserInputType == Enum.UserInputType.MouseMovement then
13 print("The mouse has been moved!")
14 printMovement(input)
15 elseif input.UserInputType == Enum.UserInputType.MouseWheel then
16 print("The mouse wheel has been scrolled!")
17 print("Wheel Movement:", input.Position.Z)
18 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
19 if input.KeyCode == Enum.KeyCode.Thumbstick1 then
20 print("The left thumbstick has been moved!")
21 printMovement(input)
22 elseif input.KeyCode == Enum.KeyCode.Thumbstick2 then
23 print("The right thumbstick has been moved!")
24 printMovement(input)
25 elseif input.KeyCode == Enum.KeyCode.ButtonL2 then
26 print("The pressure being applied to the left trigger has changed!")
27 print("Pressure:", input.Position.Z)
28 elseif input.KeyCode == Enum.KeyCode.ButtonR2 then
29 print("The pressure being applied to the right trigger has changed!")
30 print("Pressure:", input.Position.Z)
31 end
32 elseif input.UserInputType == Enum.UserInputType.Touch then
33 print("The user's finger is moving on the screen!")
34 printMovement(input)
35 elseif input.UserInputType == Enum.UserInputType.Gyro then
36 local _rotInput, rotCFrame = UserInputService:GetDeviceRotation()
37 local rotX, rotY, rotZ = rotCFrame:toEulerAnglesXYZ()
38 local rot = Vector3.new(math.deg(rotX), math.deg(rotY), math.deg(rotZ))
39 print("The rotation of the user's mobile device has been changed!")
40 print("Position", rotCFrame.p)
41 print("Rotation:", rot)
42 elseif input.UserInputType == Enum.UserInputType.Accelerometer then
43 print("The acceleration of the user's mobile device has been changed!")
44 printMovement(input)
45 end
46end
47
48UserInputService.InputChanged:Connect(InputChanged)
Handling InputEnded

1-- In order to use the InputChanged event, the UserInputService service must be used
2local UserInputService = game:GetService("UserInputService")
3
4-- A sample function providing multiple usage cases for various types of user input
5UserInputService.InputEnded:Connect(function(input, gameProcessed)
6 if input.UserInputType == Enum.UserInputType.Keyboard then
7 print("A key has been released! Key:", input.KeyCode)
8 elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
9 print("The left mouse button has been released at", input.Position)
10 elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
11 print("The right mouse button has been released at", input.Position)
12 elseif input.UserInputType == Enum.UserInputType.Touch then
13 print("A touchscreen input has been released at", input.Position)
14 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
15 print("A button has been released on a gamepad! Button:", input.KeyCode)
16 end
17
18 if gameProcessed then
19 print("The game engine internally observed this input!")
20 else
21 print("The game engine did not internally observe this input!")
22 end
23end)
Handling InputBegan

1-- In order to use the InputBegan event, the UserInputService service must be used
2local UserInputService = game:GetService("UserInputService")
3
4-- A sample function providing multiple usage cases for various types of user input
5UserInputService.InputBegan:Connect(function(input, gameProcessed)
6 if input.UserInputType == Enum.UserInputType.Keyboard then
7 print("A key is being pushed down! Key:", input.KeyCode)
8 elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
9 print("The left mouse button has been pressed down at", input.Position)
10 elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
11 print("The right mouse button has been pressed down at", input.Position)
12 elseif input.UserInputType == Enum.UserInputType.Touch then
13 print("A touchscreen input has started at", input.Position)
14 elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
15 print("A button is being pressed on a gamepad! Button:", input.KeyCode)
16 end
17
18 if gameProcessed then
19 print("The game engine internally observed this input!")
20 else
21 print("The game engine did not internally observe this input!")
22 end
23end)

Summary

Properties

A Vector3 describing the Delta between mouse/joystick movements.

Contains an Enum that describes the kind of input used.

Describes a positional value of this input.

Describes the state of an input being performed, following a specific flow depending on the UserInputType.

Describes the kind of input being performed (mouse, keyboard, gamepad, touch, etc).

Events

Methods

Properties

Delta

A Vector3 describing the Delta (change) between mouse/joystick movements.

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

See also:

KeyCode

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

Enums

NameValueDescription
Unknown0
Backspace8
Tab9
Clear12
Return13
Pause19
Escape27
Space32
QuotedDouble34
Hash35
Dollar36
Percent37
Ampersand38
Quote39
LeftParenthesis40
RightParenthesis41
Asterisk42
Plus43
Comma44
Minus45
Period46
Slash47
Zero48
One49
Two50
Three51
Four52
Five53
Six54
Seven55
Eight56
Nine57
Colon58
Semicolon59
LessThan60
Equals61
GreaterThan62
Question63
At64
LeftBracket91
BackSlash92
RightBracket93
Caret94
Underscore95
Backquote96
A97
B98
C99
D100
E101
F102
G103
H104
I105
J106
K107
L108
M109
N110
O111
P112
Q113
R114
S115
T116
U117
V118
W119
X120
Y121
Z122
LeftCurly123
Pipe124
RightCurly125
Tilde126
Delete127
KeypadZero256
KeypadOne257
KeypadTwo258
KeypadThree259
KeypadFour260
KeypadFive261
KeypadSix262
KeypadSeven263
KeypadEight264
KeypadNine265
KeypadPeriod266
KeypadDivide267
KeypadMultiply268
KeypadMinus269
KeypadPlus270
KeypadEnter271
KeypadEquals272
Up273
Down274
Right275
Left276
Insert277
Home278
End279
PageUp280
PageDown281
LeftShift304
RightShift303
LeftMeta310
RightMeta309
LeftAlt308
RightAlt307
LeftControl306
RightControl305
CapsLock301
NumLock300
ScrollLock302
LeftSuper311
RightSuper312
Mode313
Compose314
Help315
Print316
SysReq317
Break318
Menu319
Power320
Euro321
Undo322
F1282
F2283
F3284
F4285
F5286
F6287
F7288
F8289
F9290
F10291
F11292
F12293
F13294
F14295
F15296
World0160
World1161
World2162
World3163
World4164
World5165
World6166
World7167
World8168
World9169
World10170
World11171
World12172
World13173
World14174
World15175
World16176
World17177
World18178
World19179
World20180
World21181
World22182
World23183
World24184
World25185
World26186
World27187
World28188
World29189
World30190
World31191
World32192
World33193
World34194
World35195
World36196
World37197
World38198
World39199
World40200
World41201
World42202
World43203
World44204
World45205
World46206
World47207
World48208
World49209
World50210
World51211
World52212
World53213
World54214
World55215
World56216
World57217
World58218
World59219
World60220
World61221
World62222
World63223
World64224
World65225
World66226
World67227
World68228
World69229
World70230
World71231
World72232
World73233
World74234
World75235
World76236
World77237
World78238
World79239
World80240
World81241
World82242
World83243
World84244
World85245
World86246
World87247
World88248
World89249
World90250
World91251
World92252
World93253
World94254
World95255
ButtonX1000
ButtonY1001
ButtonA1002
ButtonB1003
ButtonR11004
ButtonL11005
ButtonR21006
ButtonL21007
ButtonR31008
ButtonL31009
ButtonStart1010
ButtonSelect1011
DPadLeft1012
DPadRight1013
DPadUp1014
DPadDown1015
Thumbstick11016
Thumbstick21017

See also:

Position

This property describes a Vector3 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.

For the mouse wheel input, the z component describes whether the wheel was moved forward (1), backwards (-1), or not at all (0).

For KeyCode input, this indicate's the position of the player's Mouse.

See also

UserInputState

UserInputState describes the state of an input being performed, following a specific flow depending on the UserInputType. It uses the enum of the same name, UserInputState. See the enum page for a list of all possible values for this property.

See also:

UserInputType

UserInputType is a property that describes for what kind of input this InputObject represents, such as mouse, keyboard, touch or gamepad input. It uses the enum of the same name, UserInputType. See the enum page for a list of all possible values for this property.

See also:

Events

Methods

IsModifierKeyDown

Parameters

modifierKey: ModifierKey

Returns