Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

VirtualJoystick

继承： Control < CanvasItem < Node < Object

一个用于触摸屏设备的虚拟摇杆控制。

描述

一个为触摸屏设备设计的可自定义屏幕摇杆控制。它允许用户通过在定义好的圆形区域内拖动一个虚拟摇杆头来提供方向输入。

该控件可以模拟方向动作（参见 action_up、action_down、action_left 和 action_right），当摇杆向对应方向移动时触发这些动作。

属性

StringName

action_down

&"ui_down"

StringName

action_left

&"ui_left"

StringName

action_right

&"ui_right"

StringName

action_up

&"ui_up"

float

clampzone_ratio

1.0

float

deadzone_ratio

0.0

Vector2

initial_offset_ratio

Vector2(0.5, 0.5)

JoystickMode

joystick_mode

0

float

joystick_size

100.0

float

tip_size

50.0

VisibilityMode

visibility_mode

0

主题属性

StyleBox

normal_joystick

StyleBox

normal_tip

StyleBox

pressed_joystick

StyleBox

pressed_tip

信号

flick_canceled() 🔗

当摇杆头从死区外移动进入死区内时，触发该信号。

flicked(input_vector: Vector2) 🔗

当摇杆头移出死区后释放摇杆时发出。input_vector 包含释放前的最后输入方向和强度。其长度介于 0.0 和 1.0 之间。

pressed() 🔗

当摇杆被按下时，触发该信号。

released(input_vector: Vector2) 🔗

当摇杆被释放时发出。input_vector 是最终的输入方向和强度，其长度介于 0.0 和 1.0 之间。

tapped() 🔗

当摇杆被松开，且摇杆头没有发生移动时，触发该信号。

枚举

enum JoystickMode: 🔗

JoystickMode JOYSTICK_FIXED = 0

摇杆没有移动。

JoystickMode JOYSTICK_DYNAMIC = 1

只要初始触摸位置在摇杆的边界范围内，摇杆就会移动到该位置。当释放时，它会移回其原始位置。

JoystickMode JOYSTICK_FOLLOWING = 2

只要初始触摸位置在摇杆的边界范围内，摇杆就会移动到该位置。如果触摸点移出了摇杆的作用范围，它会继续跟随触摸输入。当释放时，摇杆会移回其原始位置。

enum VisibilityMode: 🔗

VisibilityMode VISIBILITY_ALWAYS = 0

摇杆始终可见。

VisibilityMode VISIBILITY_WHEN_TOUCHED = 1

仅在触摸时显示摇杆。

属性说明

StringName action_down = &"ui_down" 🔗

当摇杆向下移动时要触发的动作。

StringName action_left = &"ui_left" 🔗

当摇杆向左移动时要触发的动作。

StringName action_right = &"ui_right" 🔗

当摇杆向右移动时要触发的动作。

StringName action_up = &"ui_up" 🔗

当摇杆向上移动时触发的操作。

float clampzone_ratio = 1.0 🔗

  • void set_clampzone_ratio(value: float)

  • float get_clampzone_ratio()

应用于摇杆半径的乘数，用于定义钳制区域。

该区域限制了摇杆头在被钳制前，距离其中心点可以移动的最远距离。

值为 1.0 表示摇杆头可以移动到摇杆视觉尺寸的边缘。

在 JOYSTICK_FOLLOWING 模式下，该半径还决定了手指移动多远后，摇杆底座才开始跟随触摸输入。

float deadzone_ratio = 0.0 🔗

  • void set_deadzone_ratio(value: float)

  • float get_deadzone_ratio()

定义摇杆死区的摇杆尺寸比例。摇杆头必须移动超过这一比例，才会被视为激活。

该死区在触发输入动作之前生效，并会影响摇杆的输入向量（Input Vector）及所有相关信号。

请注意，输入动作（Input Actions）也可能在 InputMap 中定义自己的死区。如果两者都进行了设置，则先应用摇杆的死区，再应用动作的死区。

默认情况下，该值为 0.0，这意味着摇杆不会应用其自身的死区，而是完全依赖 InputMap 动作的死区。

Vector2 initial_offset_ratio = Vector2(0.5, 0.5) 🔗

  • void set_initial_offset_ratio(value: Vector2)

  • Vector2 get_initial_offset_ratio()

摇杆初始位置相对于控件尺寸的比例。 (0, 0) 代表左上角，(1, 1) 代表右下角。

JoystickMode joystick_mode = 0 🔗

要使用的摇杆模式。

float joystick_size = 100.0 🔗

  • void set_joystick_size(value: float)

  • float get_joystick_size()

摇杆的大小（以像素为单位）。

float tip_size = 50.0 🔗

  • void set_tip_size(value: float)

  • float get_tip_size()

摇杆顶部（摇杆头）的大小（以像素为单位）。

VisibilityMode visibility_mode = 0 🔗

要使用的可见性模式。

主题属性说明

StyleBox normal_joystick 🔗

基础摇杆 StyleBox。

StyleBox normal_tip 🔗

摇杆头 StyleBox。

StyleBox pressed_joystick 🔗

基础摇杆按下时的 StyleBox。

StyleBox pressed_tip 🔗

按下时的摇杆头 StyleBox。