Input

Inherits: Object

处理输入的单例。

描述

处理输入的单例。这包括按键、鼠标点击和移动、游戏手柄和输入动作。可以在项目 > 项目设置的输入映射选项卡中或使用 InputMap 类设置操作及其事件。

教程

• Inputs tutorial index

• 2D Dodge The Creeps Demo

• 3D Voxel Demo

方法

信号

• joy_connection_changed ( int device, bool connected )

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

枚举

enum MouseMode:

• MOUSE_MODE_VISIBLE = 0 —- 如果鼠标光标处于隐藏状态，则使其可见。

• MOUSE_MODE_HIDDEN = 1 —- 如果鼠标光标是可见的，则使其隐藏。

• MOUSE_MODE_CAPTURED = 2 —- 捕获鼠标。鼠标将被隐藏，其位置被锁定在屏幕的中心。

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

• MOUSE_MODE_CONFINED = 3 —- 使鼠标光标可见，并将其限制在游戏窗口中。

enum CursorShape:

• CURSOR_ARROW = 0 —- 箭头光标。标准，默认指向光标。

• CURSOR_IBEAM = 1 —- I 形光标。通常用于指示点击鼠标后文本光标的位置。

• CURSOR_POINTING_HAND = 2 —- 指向手形光标。通常用在指示链接或其他可交互项上。

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

• CURSOR_WAIT = 4 —- 等待型光标。表示应用程序正忙于执行一项操作。这种光标形状表示应用程序在操作过程中仍然可以使用。

• CURSOR_BUSY = 5 —- 忙碌光标。表示应用程序正忙于执行操作。此光标形状表示应用程序在操作过程中不可用（例如，有东西阻塞了主线程）。

• CURSOR_DRAG = 6 —- 拖动光标。通常在拖动东西时显示。

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

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

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

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

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

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

• CURSOR_MOVE = 13 —- 移动光标。表示那些东西可以移动。

• CURSOR_VSPLIT = 14 —- 垂直拆分鼠标光标。在 Windows 上，它与 CURSOR_VSIZE 相同。

• CURSOR_HSPLIT = 15 —- 水平分割的鼠标光标。在Windows上，它与CURSOR_HSIZE相同。

• CURSOR_HELP = 16 —- 帮助光标。通常是一个问号。

方法说明

• void action_press ( String action, float strength=1.0 )

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

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

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

• void action_release ( String action )

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

• void add_joy_mapping ( String mapping, bool update_existing=false )

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

• void flush_buffered_events ( )

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

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

• Vector3 get_accelerometer ( ) const

如果设备有加速度传感器，则返回设备的加速度。否则，该方法返回Vector3.ZERO。

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

注意： 这个方法只在iOS、Android和UWP上工作。在其他平台上，它总是返回Vector3.ZERO。在Android上，每个轴的测量单位是m/s²，而在iOS和UWP上，它是地球重力加速度的倍数g（~9.81 m/s²）。

• float get_action_raw_strength ( String action, bool exact=false ) const

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

如果exact是false，它将忽略InputEventKey和InputEventMouseButton事件的输入修饰符，以及InputEventJoypadMotion事件的方向。

• float get_action_strength ( String action, bool exact=false ) const

返回介于0和1之间的值，代表给定动作的强度。例如，在一个操纵板上，轴（模拟杆或L2、R2触发器）离死区越远，数值就越接近1。如果动作被映射到一个没有轴作为键盘的控件上，返回的数值将是0或1。

如果exact是false，它将忽略InputEventKey和InputEventMouseButton事件的输入修饰符，以及InputEventJoypadMotion事件的方向。

• float get_axis ( String negative_action, String positive_action ) const

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

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

• Array get_connected_joypads ( )

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

• CursorShape get_current_cursor_shape ( ) const

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

• Vector3 get_gravity ( ) const

如果设备有加速度传感器，则返回设备的重力。否则，该方法返回Vector3.ZERO。

注意： 这个方法只在Android和iOS上工作。在其他平台上，它总是返回Vector3.ZERO。在Android上，每个轴的测量单位是m/s²，而在iOS上，它是地球重力加速度的倍数g（~9.81 m/s²）。

• Vector3 get_gyroscope ( ) const

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

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

• float get_joy_axis ( int device, int axis ) const

返回给定索引的游戏手柄轴的当前值，参阅JoystickList。

• int get_joy_axis_index_from_string ( String axis )

返回提供的轴名称的索引。

• String get_joy_axis_string ( int axis_index )

接收一个 JoystickList 轴，并以字符串形式返回其对应的名称。

• int get_joy_button_index_from_string ( String button )

返回所提供的按钮名称的索引。

• String get_joy_button_string ( int button_index )

从JoystickList中接收游戏手柄按钮，并将其对应的名称作为一个字符串返回。

• String get_joy_guid ( int device ) const

在使用游戏手柄重映射的平台上返回一个SDL2兼容的设备GUID。否则返回"Default Gamepad"默认游戏手柄。

• String get_joy_name ( int device )

返回指定设备索引处的手柄名称。

• float get_joy_vibration_duration ( int device )

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

• Vector2 get_joy_vibration_strength ( int device )

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

• Vector2 get_last_mouse_speed ( ) const

返回光标最后一次被移动时的鼠标速度，并且这个速度保持不变，直到鼠标发生了移动的下一帧。这意味着，即使鼠标没有移动，这个函数仍然会返回最后一次运动的值。

• Vector3 get_magnetometer ( ) const

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

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

• int get_mouse_button_mask ( ) const

将鼠标按键作为一个比特掩码返回。如果多个鼠标按钮同时被按下，这些位会被加在一起。

• MouseMode get_mouse_mode ( ) const

返回鼠标模式。有关更多信息，请参阅常量。

• Vector2 get_vector ( String negative_x, String positive_x, String negative_y, String positive_y, float deadzone=-1.0 ) const

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

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

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

• bool is_action_just_pressed ( String action, bool exact=false ) const

当用户开始按下动作事件时，返回true，也就是说，只有在用户按下按钮的那一帧才是true。

这对那些只需要在动作被按下时运行一次的代码中很有用，而不是在按下时每一帧都要运行。

如果exact是false，它将忽略InputEventKey和InputEventMouseButton事件的输入修饰符，以及InputEventJoypadMotion事件的方向。

• bool is_action_just_released ( String action, bool exact=false ) const

当用户停止按下动作事件时，返回true，也就是说，只有在用户释放按钮的那一帧才是true。

如果exact是false，它将忽略InputEventKey和InputEventMouseButton事件的输入修饰符，以及InputEventJoypadMotion事件的方向。

• bool is_action_pressed ( String action, bool exact=false ) const

如果你正在按下动作事件，返回true。请注意，如果一个动作有多个分配的按钮，并且不止一个被按下，释放一个按钮将释放这个动作，即使其他分配给这个动作的按钮仍然被按下。

如果exact是false，它将忽略InputEventKey和InputEventMouseButton事件的输入修饰符，以及InputEventJoypadMotion事件的方向。

• bool is_joy_button_pressed ( int device, int button ) const

如果你正在按下手柄按钮，则返回true，参阅JoystickList。

• bool is_joy_known ( int device )

如果系统知道指定的设备，则返回true。这意味着它将完全按照JoystickList中的定义设置所有按钮和轴的索引。未知的操纵杆可能不会与这些常数相匹配，但你仍然可以从中检索事件。

• bool is_key_pressed ( int scancode ) const

如果你正在按压该键，则返回 true。你可以传递 KeyList 常量。

• bool is_mouse_button_pressed ( int button ) const

如果你正在按压由 ButtonList 指定的鼠标按键，则返回 true。

• bool is_physical_key_pressed ( int scancode ) const

如果你正在按压该键，则返回true。按键由 101/102 键美式 QWERTY 键盘上该键的物理位置确定。你可以传递 KeyList 常量。

• void joy_connection_changed ( int device, bool connected, String name, String guid )

通知 Input 单例连接已更改，以更新 device 索引的状态。

这是内部使用的，不应从用户脚本中调用。有关内部触发的信号，请参阅 joy_connection_changed。

• void parse_input_event ( InputEvent event )

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

示例：

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

• 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。

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

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

注意：仅支持以无损，有损或未压缩压缩模式导入的图像。Video RAM压缩模式不能用于自定义光标。

• 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上，这个值可立即被硬件传感器的值所覆盖。

• void set_mouse_mode ( MouseMode mode )

设置鼠标模式。有关更多信息，请参阅常量。

• void set_use_accumulated_input ( bool enable )

启用或禁用操作系统发送的类似输入事件的累积。当启用输入累积时，在一帧中产生的所有输入事件将被合并，并在该帧完成渲染时发出。因此，这限制了每秒的输入方法调用次数，使之与渲染FPS相一致。

输入累加在默认情况下是启用的。它可以被禁用，将以增加CPU使用率为代价，获得稍微更精确及更灵敏的输入。在需要自由绘制线条的应用中，一般应用在用户绘制线条时禁用输入累加，以获得紧跟实际输入的结果。

• 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 将尝试无限期地播放振动）。

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

• void stop_joy_vibration ( int device )

停止游戏手柄的振动。

• void vibrate_handheld ( int duration_ms=500 )

振动 Android 和 iOS 设备。

注意：Android 需要导出设置中的 VIBRATE 权限。 iOS 不支持持续时间。

• void warp_mouse_position ( Vector2 to )

将鼠标坐标设置为指定的向量。