Input

继承： Object

用于处理输入的单例。

描述

Input 是处理键盘按键、鼠标按钮及移动、游戏手柄、输入动作等的单例。动作以及对应的事件可以在项目 > 项目设置的输入映射选项卡中设置，也可以使用 InputMap 类设置。

注意：**Input** 的方法反映的是全局输入状态，不受 Control.accept_event 和 Viewport.set_input_as_handled 的影响，因为这两个方法处理的是输入在 SceneTree 中传播的方式。

教程

• 输入文档索引

• 2D Dodge The Creeps 演示

• 3D 体素演示

属性

方法

信号

joy_connection_changed(device: int, connected: bool) 🔗

连接或断开游戏手柄设备时触发。

枚举

enum MouseMode: 🔗

MouseMode MOUSE_MODE_VISIBLE = 0

如果鼠标光标处于隐藏状态，则使其可见。

MouseMode MOUSE_MODE_HIDDEN = 1

如果鼠标光标是可见的，则使其隐藏。

MouseMode MOUSE_MODE_CAPTURED = 2

捕获鼠标。鼠标将被隐藏，其位置被锁定在窗口管理器窗口的中心。

注意：如果你想在这种模式下处理鼠标的移动，则需要使用 InputEventMouseMotion.relative。

MouseMode MOUSE_MODE_CONFINED = 3

将鼠标光标限制在游戏窗口内，并使其可见。

MouseMode MOUSE_MODE_CONFINED_HIDDEN = 4

将鼠标光标限制在游戏窗口内，并使其隐藏。

enum CursorShape: 🔗

CursorShape CURSOR_ARROW = 0

箭头光标。标准，默认指向光标。

CursorShape CURSOR_IBEAM = 1

I 形光标。通常用于指示点击鼠标后文本光标的位置。

CursorShape CURSOR_POINTING_HAND = 2

指向手形光标。通常用在指示链接或其他可交互项上。

CursorShape CURSOR_CROSS = 3

十字光标。通常出现在可以执行绘制操作或进行选择的区域上方。

CursorShape CURSOR_WAIT = 4

等待光标。表示应用程序正忙于执行某项操作，并且它在操作期间无法使用（例如，某些东西正在阻塞其主线程）。

CursorShape CURSOR_BUSY = 5

忙碌光标。表示应用程序正忙于执行某项操作，并且它在操作期间仍然可用。

CursorShape CURSOR_DRAG = 6

拖动光标。通常在拖动某物时显示。

注意：Windows 上没有拖动光标，因此 CURSOR_DRAG 与该平台的 CURSOR_MOVE 相同。

CursorShape CURSOR_CAN_DROP = 7

可以放下的光标。通常在拖动东西时显示，表示可以在当前位置放下。

CursorShape CURSOR_FORBIDDEN = 8

禁止的光标。表示当前操作是被禁止的（例如，拖动东西时）或某个位置的控件被禁用。

CursorShape CURSOR_VSIZE = 9

垂直调整大小的光标。一个双头的垂直箭头。它告诉用户他们可以垂直地调整窗口或面板的大小。

CursorShape CURSOR_HSIZE = 10

水平调整尺寸的光标。一个双头的水平箭头。它告诉用户他们可以水平调整窗口或面板的大小。

CursorShape CURSOR_BDIAGSIZE = 11

窗口调整大小的光标。该光标是一个双头箭头，从左下方到右上方。它告诉用户他们可以在水平和垂直方向上调整窗口或面板的大小。

CursorShape CURSOR_FDIAGSIZE = 12

窗口调整大小的光标。是一个双头的箭头，从左上角到右下角，与 CURSOR_BDIAGSIZE 相反。它告诉用户他们可以在水平和垂直方向上调整窗口或面板的大小。

CursorShape CURSOR_MOVE = 13

移动光标。表示那些东西可以移动。

CursorShape CURSOR_VSPLIT = 14

垂直拆分鼠标光标。在 Windows 上与 CURSOR_VSIZE 相同。

CursorShape CURSOR_HSPLIT = 15

水平分割的鼠标光标。在 Windows 上与 CURSOR_HSIZE 相同。

CursorShape CURSOR_HELP = 16

帮助光标。通常是一个问号。

属性说明

bool emulate_mouse_from_touch 🔗

• void set_emulate_mouse_from_touch(value: bool)

• bool is_emulating_mouse_from_touch()

如果为 true，则在点击或滑动触摸屏时发送鼠标输入事件。另请参阅 ProjectSettings.input_devices/pointing/emulate_mouse_from_touch。

bool emulate_touch_from_mouse 🔗

• void set_emulate_touch_from_mouse(value: bool)

• bool is_emulating_touch_from_mouse()

如果为 true，则在点击或拖动鼠标时发送触摸输入事件。另请参阅 ProjectSettings.input_devices/pointing/emulate_touch_from_mouse。

MouseMode mouse_mode 🔗

• void set_mouse_mode(value: MouseMode)

• MouseMode get_mouse_mode()

控制鼠标模式。详情请参阅 MouseMode。

bool use_accumulated_input 🔗

• void set_use_accumulated_input(value: bool)

• bool is_using_accumulated_input()

如果为 true，则操作系统发送的相似输入事件将被累积。当输入累积被启用时，在帧期间内所有生成的输入事件，将在帧完成渲染时被合并并发出。因此，这会将每秒输入方法被调用的数量限制为渲染 FPS。

输入累积可以被禁用，以增加 CPU 使用率为代价，获得稍微更具精确性/反应性的输入。在需要徒手绘制线条的应用程序中，输入累积通常应在用户绘制线条时被禁用，以获得与实际输入非常接近的结果。

注意：输入累积默认是启用的 。

方法说明

void action_press(action: StringName, strength: float = 1.0) 🔗

这将模拟按下指定的按键动作。

强度可以用于非布尔运算的动作，它的范围在 0 到 1 之间，代表给定动作的力度。

注意：这个方法不会引起任何 Node._input 调用。它旨在与 is_action_pressed 和 is_action_just_pressed 一起使用。如果你想模拟 _input，请使用 parse_input_event 代替。

void action_release(action: StringName) 🔗

如果已按下指定操作，那么将释放它。

void add_joy_mapping(mapping: String, update_existing: bool = false) 🔗

在映射数据库中添加新的映射条目（SDL2 格式）。可选更新已连接的设备。

void flush_buffered_events() 🔗

将当前缓冲区内的所有输入事件发送给游戏循环。这些事件可能是由于累积输入（use_accumulated_input）或敏捷输入刷新（ProjectSettings.input_devices/buffering/agile_event_flushing）而被缓冲的结果。

引擎已经会在关键的执行点执行此操作，至少每帧一次。然而，在你想要精确控制事件处理时间的高级情况下，这可能是有用的。

Vector3 get_accelerometer() const 🔗

如果设备有加速度计传感器，则返回该设备加速度计传感器的加速度，单位为 m/s²。否则，该方法返回 Vector3.ZERO。

请注意，即使你的设备具有一个加速度计，在从编辑器运行时，该方法也会返回一个空的 Vector3。必须将项目导出到一个支持的设备上，才能从加速度计读取值。

注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。

float get_action_raw_strength(action: StringName, exact_match: bool = false) const 🔗

返回一个介于 0 和 1 之间的值，表示给定动作的原始强度，忽略动作的死区。在大多数情况下，应该改用 get_action_strength。

如果 exact_match 为 false，它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。

float get_action_strength(action: StringName, exact_match: bool = false) const 🔗

返回一个介于 0 和 1 之间的值，表示给定动作的强度。例如，在游戏手柄中，轴（模拟摇杆或 L2、R2 触发器）离死区越远，该值将越接近 1。如果动作被映射到一个如键盘一样没有轴的控制器时，返回值将为 0 或 1。

如果 exact_match 为 false，它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。

float get_axis(negative_action: StringName, positive_action: StringName) const 🔗

通过指定两个动作来获取轴的输入，一个是负的，一个是正的。

这是 Input.get_action_strength("positive_action")-Input.get_action_strength("negative_action") 的简写。

Array[int] get_connected_joypads() 🔗

返回一个 Array，包含当前所有连接手柄的设备 ID。

CursorShape get_current_cursor_shape() const 🔗

返回当前指定的光标形状（见 CursorShape）。

Vector3 get_gravity() const 🔗

如果设备有加速度计传感器，则返回该设备有加速度计传感器的重力，单位为 m/s²。否则，该方法返回 Vector3.ZERO。

注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。

Vector3 get_gyroscope() const 🔗

如果设备有陀螺仪传感器，则返回围绕设备 X、Y、Z 轴的旋转速率，单位为 rad/s。否则，该方法返回 Vector3.ZERO。

注意：这个方法只在 Android 和 iOS 上工作。在其他平台上，总是返回 Vector3.ZERO。

float get_joy_axis(device: int, axis: JoyAxis) const 🔗

返回给定索引（参见 JoyAxis）处的游戏手柄轴的当前值。

String get_joy_guid(device: int) const 🔗

如果平台使用游戏手柄重映射，则返回设备的 GUID，与 SDL2 兼容，例如 030000004c050000c405000000010000。否则返回 "Default Gamepad"。Godot 会根据这个 GUI 使用 SDL2 游戏控制器数据库来确定游戏手柄的名称和映射。

Dictionary get_joy_info(device: int) const 🔗

返回关于设备的额外平台相关信息字典，例如操作系统的原始游戏手柄名称，或者 Steam Input 索引。

在 Windows 上，该字典包含如下字段：

xinput_index：控制器在 XInput 系统中的索引。

在 Linux 上：

raw_name：从操作系统获取的控制器名称，未经 Godot 控制器数据库重命名。

vendor_id：设备的 USB 供应商 ID。

product_id：设备的 USB 产品 ID。

steam_input_index：Steam Input 游戏手柄索引，如果该设备不是 Steam Input 设备则该字段不存在。

String get_joy_name(device: int) 🔗

返回位于指定设备索引的游戏手柄名称，例如 PS4 Controller。Godot 使用 SDL2 游戏控制器数据库来确定游戏手柄的名称。

float get_joy_vibration_duration(device: int) 🔗

以秒为单位返回当前振动效果的持续时间。

Vector2 get_joy_vibration_strength(device: int) 🔗

返回手柄振动的强度：x 是弱马达的强度，y 是强马达的强度。

Vector2 get_last_mouse_screen_velocity() 🔗

返回屏幕坐标中上次的鼠标速度。为了提供精确且无抖动的速度，鼠标速度仅每 0.1 秒计算一次。因此，鼠标速度将滞后于鼠标移动。

Vector2 get_last_mouse_velocity() 🔗

返回上次的鼠标速度。为了提供精确且无抖动的速度，鼠标速度仅每 0.1 秒计算一次。因此，鼠标速度将滞后于鼠标移动。

Vector3 get_magnetometer() const 🔗

如果设备有磁力传感器，则返回设备所有轴的磁场强度，单位为微特斯拉。否则，该方法返回 Vector3.ZERO。

注意：该方法仅适用于 Android 和 iOS。在其他平台上，它总是返回 Vector3.ZERO。

BitField[MouseButtonMask] get_mouse_button_mask() const 🔗

将鼠标按键作为一个位掩码返回。如果多个鼠标按钮同时被按下，则这些位将被加在一起。相当于 DisplayServer.mouse_get_button_state。

Vector2 get_vector(negative_x: StringName, positive_x: StringName, negative_y: StringName, positive_y: StringName, deadzone: float = -1.0) const 🔗

通过指定正负 X 和 Y 轴的四个动作来获取输入向量。

这个方法在获取向量输入时很有用，比如从操纵杆、方向盘、箭头或 WASD。向量的长度被限制为 1，并且有一个圆形的死区，这对于使用向量输入进行运动很有用。

默认情况下，死区根据动作死区的平均值自动计算。然而，你可以把死区覆盖为任何你想要的值（在 0 到 1 的范围内）。

bool is_action_just_pressed(action: StringName, exact_match: bool = false) const 🔗

当用户在当前帧或物理周期中开始按下动作事件时返回 true。只在用户按下按钮的那一帧或周期中为 true。

如果代码只需要在动作按下时执行一次，而不是只要处于按下状态就每帧都需要执行，那么这个方法就很有用。

如果 exact_match 为 false，则会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。

注意：返回 true 并不意味着该动作仍然处于按下状态。动作在按下后是可以很快再释放的，为了不丢失输入，这种情况下仍然会返回 true。

注意：由于键盘重影，即便该动作的某个键处于按下状态，is_action_just_pressed 仍可能会返回 false。详情见文档中的《输入示例》。

注意：在输入处理期间（例如 Node._input），请使用 InputEvent.is_action_pressed 来查询当前事件的动作状态。

bool is_action_just_released(action: StringName, exact_match: bool = false) const 🔗

当用户在当前帧或物理周期中停止按下动作事件时返回 true。只在用户松开按钮的那一帧或周期中为 true。

注意：返回 true 并不意味着该动作仍然处于松开状态。动作在松开后是可以很快再按下的，为了不丢失输入，这种情况下仍然会返回 true。

如果 exact_match 为 false，则会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。

注意：在输入处理期间（例如 Node._input），请使用 InputEvent.is_action_released 来查询当前事件的动作状态。

bool is_action_pressed(action: StringName, exact_match: bool = false) const 🔗

如果正在按下操作事件，则返回 true。

如果 exact_match 为 false，则它会忽略 InputEventKey 和 InputEventMouseButton 事件的额外输入修饰键，以及 InputEventJoypadMotion 事件的方向。

注意：由于键盘重影，is_action_pressed 可能会返回 false，即使动作的某个键被按下时也是如此。有关详细信息，请参阅文档中的 《输入示例》。

bool is_anything_pressed() const 🔗

如果任何动作、按键、游戏手柄按钮或鼠标按钮正被按下，则返回 true。如果动作是通过调用 action_press 以通过代码来模拟，该方法也将返回 true。

bool is_joy_button_pressed(device: int, button: JoyButton) const 🔗

如果游戏手柄按钮（参见 JoyButton）正被按下，则返回 true。

bool is_joy_known(device: int) 🔗

如果系统知道指定的设备，则返回 true。这意味着它设置了所有按钮和轴索引。未知的游戏手柄预计不会匹配这些常量，但仍然可以从中检索事件。

bool is_key_label_pressed(keycode: Key) const 🔗

如果正按下印有 keycode 的键，则返回 true。可以传递一个 Key 常量或任何 Unicode 字符代码。

bool is_key_pressed(keycode: Key) const 🔗

如果在当前键盘布局中正在按该拉丁键，则返回 true。可以传递一个 Key 常量。

只有在非游戏应用程序中，才推荐使用 is_key_pressed 而不是 is_physical_key_pressed。这可确保快捷键将根据用户的键盘布局按预期运行，因为在非游戏应用程序中，键盘快捷键通常取决于键盘布局。如有疑问，请使用 is_physical_key_pressed。

注意：由于键盘重影，即使按下动作的某个键，is_key_pressed 也有可能会返回 false。有关详细信息，请参阅文档中的《输入示例》。

bool is_mouse_button_pressed(button: MouseButton) const 🔗

如果正在按下由 MouseButton 指定的鼠标按钮，则返回 true。

bool is_physical_key_pressed(keycode: Key) const 🔗

如果正按下 101/102 键美式 QWERTY 键盘物理位置上的键，则返回 true。可以传递一个 Key 常量。

与 is_key_pressed 相比，is_physical_key_pressed 被推荐用于游戏内的动作，因为无论用户的键盘布局如何，它都会使 W/A/S/D 布局有效。is_physical_key_pressed 还将确保顶行数字键在任何键盘布局上有效。如有疑问，请使用 is_physical_key_pressed。

注意：由于键盘重影，即使按下动作的某个键，is_physical_key_pressed 也有可能会返回 false。有关详细信息，请参阅文档中的《输入示例》。

void parse_input_event(event: InputEvent) 🔗

向游戏提供一个 InputEvent。可用于通过代码人为地触发输入事件。也会产生 Node._input 调用。

示例：

GDScriptC#

var cancel_event = InputEventAction.new()
cancel_event.action = "ui_cancel"
cancel_event.pressed = true
Input.parse_input_event(cancel_event)

var cancelEvent = new InputEventAction();
cancelEvent.Action = "ui_cancel";
cancelEvent.Pressed = true;
Input.ParseInputEvent(cancelEvent);

注意：调用该函数不会影响操作系统。因此，发送 InputEventMouseMotion 事件并不会将操作系统的鼠标光标移动到指定位置（请改用 warp_mouse），发送 Alt/Cmd + Tab 对应的 InputEventKey 也不会触发当前窗口的切换。

void remove_joy_mapping(guid: String) 🔗

从内部数据库中删除与给定 GUID 匹配的所有映射。

void set_accelerometer(value: Vector3) 🔗

设置加速度传感器的加速度值。可以用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。

注意：这个值在 Android 和 iOS 上可立即被硬件传感器的值所覆盖。

void set_custom_mouse_cursor(image: Resource, shape: CursorShape = 0, hotspot: Vector2 = Vector2(0, 0)) 🔗

设置自定义鼠标光标图像，该图像仅在游戏窗口内可见。还可以指定热点。将 null 传递给 image 参数将重置为系统光标。形状列表见 CursorShape。

image 可以是 Texture2D 或 Image，其大小必须小于等于 256×256。为了避免渲染问题，建议使用小于等于 128×128 的大小。

hotspot 必须在 image 的大小范围内。

注意：不支持使用 AnimatedTexture 作为自定义鼠标光标。如果使用 AnimatedTexture，则只会显示第一帧。

注意：推荐使用 Lossless、Lossy 或 Uncompressed 压缩模式。Video RAM 压缩模式也可以，但会使用 CPU 解压，拖慢加载，相对于无损模式也并不节省内存。

注意：在网络平台上，光标图像允许的最大尺寸为 128×128。 出于安全原因，只有当鼠标光标图像完全位于页面内时，大于 32×32 的光标图像才会显示。

void set_default_cursor_shape(shape: CursorShape = 0) 🔗

设置该视口中使用的默认光标形状，而不是 CURSOR_ARROW。

注意：如果要更改 Control 节点的默认光标形状，请改用 Control.mouse_default_cursor_shape。

注意：这个方法会生成一个 InputEventMouseMotion 以立即更新光标。

void set_gravity(value: Vector3) 🔗

设置加速度传感器的重力值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。

注意：这个值在 Android 和 iOS 上可立即被硬件传感器的值覆盖。

void set_gyroscope(value: Vector3) 🔗

设置陀螺仪传感器的旋转速率值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。

注意：在 Android 和 iOS 上，这个值可立即被硬件传感器的值所覆盖。

void set_magnetometer(value: Vector3) 🔗

设置磁力传感器的磁场值。可用于在没有硬件传感器的设备上进行调试，例如在 PC 上的编辑器中。

注意：在 Android 和 iOS 上，这个值可立即被硬件传感器的值所覆盖。

bool should_ignore_device(vendor_id: int, product_id: int) const 🔗

查询输入设备是否应被忽略。可以通过设置环境变量 SDL_GAMECONTROLLER_IGNORE_DEVICES 来忽略设备。请阅读 SDL 文档了解更多信息。

注意：某些第三方工具可以添加忽略设备列表。例如，SteamInput 从物理设备创建虚拟设备以进行重新映射。为了避免两次处理相同的输入设备，原始设备被添加到忽略列表中。

void start_joy_vibration(device: int, weak_magnitude: float, strong_magnitude: float, duration: float = 0) 🔗

开始振动游戏手柄。游戏手柄通常带有两个震动马达，一强一弱。weak_magnitude 是弱马达的强度（介于 0 和 1 之间），strong_magnitude 是强马达的强度（介于 0 和 1 之间）。duration 是效果的持续时间（以秒为单位）（持续时间为 0 将尝试无限期地播放振动）。调用 stop_joy_vibration 可以提前停止震动。

注意：并非所有硬件都兼容长效果持续时间；如果播放的时长必须超过几秒钟，建议重新启动效果。

注意：对于 macOS，仅 macOS 11 及更高版本支持振动。

void stop_joy_vibration(device: int) 🔗

停止使用 start_joy_vibration 启动的游戏手柄的振动。

void vibrate_handheld(duration_ms: int = 500, amplitude: float = -1.0) 🔗

使手持设备振动指定的持续时间，单位为毫秒。

amplitude 是振动的强度，取值范围为 0.0 为 1.0 之间。如果设为 -1.0 则表示该设备的默认振动强度。

注意：该方法在 Android、iOS 和 Web 上实现。在其他平台上无效。

注意：在 Android 平台上，vibrate_handheld 需要在导出预设中启用 VIBRATE 权限。否则 vibrate_handheld 无效。

注意：在 iOS 平台上，仅 iOS 13 及更高版本支持指定持续时间。

注意：在 Web 平台上，振幅无法修改。

注意：部分浏览器不支持 vibrate_handheld，如 Android 版的 Safari、Firefox 等。

void warp_mouse(position: Vector2) 🔗

将鼠标位置设置为指定的向量，单位为像素，并相对于当前聚焦的窗口管理器游戏窗口左上角的原点。

如果 MouseMode 被设置为 MOUSE_MODE_CONFINED 或 MOUSE_MODE_CONFINED_HIDDEN，则鼠标位置会被钳制在屏幕分辨率的限制内，或者钳制在游戏窗口的限制内。

注意：warp_mouse 仅支持 Windows、macOS 和 Linux。它对 Android、iOS 和 Web 没有影响。