Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Input

继承: Object

用于处理输入的单例。

描述

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

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

教程

属性

MouseMode

mouse_mode

bool

use_accumulated_input

方法

void

action_press ( StringName action, float strength=1.0 )

void

action_release ( StringName action )

void

add_joy_mapping ( String mapping, bool update_existing=false )

void

flush_buffered_events ( )

Vector3

get_accelerometer ( ) const

float

get_action_raw_strength ( StringName action, bool exact_match=false ) const

float

get_action_strength ( StringName action, bool exact_match=false ) const

float

get_axis ( StringName negative_action, StringName positive_action ) const

int[]

get_connected_joypads ( )

CursorShape

get_current_cursor_shape ( ) const

Vector3

get_gravity ( ) const

Vector3

get_gyroscope ( ) const

float

get_joy_axis ( int device, JoyAxis axis ) const

String

get_joy_guid ( int device ) const

Dictionary

get_joy_info ( int device ) const

String

get_joy_name ( int device )

float

get_joy_vibration_duration ( int device )

Vector2

get_joy_vibration_strength ( int device )

Vector2

get_last_mouse_velocity ( )

Vector3

get_magnetometer ( ) const

BitField<MouseButtonMask>

get_mouse_button_mask ( ) const

Vector2

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

bool

is_action_just_pressed ( StringName action, bool exact_match=false ) const

bool

is_action_just_released ( StringName action, bool exact_match=false ) const

bool

is_action_pressed ( StringName action, bool exact_match=false ) const

bool

is_anything_pressed ( ) const

bool

is_joy_button_pressed ( int device, JoyButton button ) const

bool

is_joy_known ( int device )

bool

is_key_label_pressed ( Key keycode ) const

bool

is_key_pressed ( Key keycode ) const

bool

is_mouse_button_pressed ( MouseButton button ) const

bool

is_physical_key_pressed ( Key keycode ) const

void

parse_input_event ( InputEvent event )

void

remove_joy_mapping ( String guid )

void

set_accelerometer ( Vector3 value )

void

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

void

set_default_cursor_shape ( CursorShape shape=0 )

void

set_gravity ( Vector3 value )

void

set_gyroscope ( Vector3 value )

void

set_magnetometer ( Vector3 value )

bool

should_ignore_device ( int vendor_id, int product_id ) const

void

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

void

stop_joy_vibration ( int device )

void

vibrate_handheld ( int duration_ms=500 )

void

warp_mouse ( Vector2 position )


信号

joy_connection_changed ( int device, bool connected )

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


枚举

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

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


属性说明

MouseMode mouse_mode

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


bool use_accumulated_input

  • void set_use_accumulated_input ( bool value )

  • bool is_using_accumulated_input ( )

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

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

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


方法说明

void action_press ( StringName action, float strength=1.0 )

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

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

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


void action_release ( StringName action )

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


void add_joy_mapping ( String mapping, bool update_existing=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 ( StringName action, bool exact_match=false ) const

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

如果 exact_matchfalse,它会忽略 InputEventKeyInputEventMouseButton 事件的额外输入修饰键,以及 InputEventJoypadMotion 事件的方向。


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

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

如果 exact_matchfalse,它会忽略 InputEventKeyInputEventMouseButton 事件的额外输入修饰键,以及 InputEventJoypadMotion 事件的方向。


float get_axis ( StringName negative_action, StringName positive_action ) const

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

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


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 ( int device, JoyAxis axis ) const

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


String get_joy_guid ( int device ) const

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


Dictionary get_joy_info ( int device ) 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 ( int device )

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


float get_joy_vibration_duration ( int device )

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


Vector2 get_joy_vibration_strength ( int device )

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


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 ( StringName negative_x, StringName positive_x, StringName negative_y, StringName positive_y, float deadzone=-1.0 ) const

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

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

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


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

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

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

如果 exact_matchfalse,则会忽略 InputEventKeyInputEventMouseButton 事件的额外输入修饰键,以及 InputEventJoypadMotion 事件的方向。

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

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

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


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

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

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

如果 exact_matchfalse,则会忽略 InputEventKeyInputEventMouseButton 事件的额外输入修饰键,以及 InputEventJoypadMotion 事件的方向。

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


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

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

如果 exact_matchfalse,则它会忽略 InputEventKeyInputEventMouseButton 事件的额外输入修饰键,以及 InputEventJoypadMotion 事件的方向。

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


bool is_anything_pressed ( ) const

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


bool is_joy_button_pressed ( int device, JoyButton button ) const

如果游戏手柄按钮(参见 JoyButton)正被按下,则返回 true


bool is_joy_known ( int device )

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


bool is_key_label_pressed ( Key keycode ) const

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


bool is_key_pressed ( Key keycode ) const

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

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

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


bool is_mouse_button_pressed ( MouseButton button ) const

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


bool is_physical_key_pressed ( Key keycode ) 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 ( InputEvent event )

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

示例:

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

void remove_joy_mapping ( String guid )

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


void set_accelerometer ( Vector3 value )

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

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


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

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

image 的大小必须小于等于 256×256。为了避免渲染问题,建议使用小于等于 128×128 的大小。

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

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

注意:推荐使用 LosslessLossyUncompressed 压缩模式。Video RAM 压缩模式也可以,但会使用 CPU 解压,拖慢加载,相对于无损模式也并不节省内存。

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


void set_default_cursor_shape ( CursorShape shape=0 )

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

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

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


void set_gravity ( Vector3 value )

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

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


void set_gyroscope ( Vector3 value )

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

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


void set_magnetometer ( Vector3 value )

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

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


bool should_ignore_device ( int vendor_id, int product_id ) const

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

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


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

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

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


void stop_joy_vibration ( int device )

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


void vibrate_handheld ( int duration_ms=500 )

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

注意:该方法在 Android、iOS 和 Web 上实现。它对其他平台没有影响。

注意:对于 Android,vibrate_handheld 需要在导出预设中启用 VIBRATE 权限。否则,vibrate_handheld 将无效。

注意:对于 iOS,仅 iOS 13 及更高版本支持指定持续时间。

注意:某些网络浏览器,如 Safari 和 Android 版的 Firefox 不支持 vibrate_handheld


void warp_mouse ( Vector2 position )

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

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

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