GFTouchJoystick

API Reference / Standard / 类索引

• 路径：addons/gf/standard/input/touch/gf_touch_joystick.gd
• 模块：Standard
• 继承：Node2D
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

通用触屏虚拟摇杆节点。 可直接发出方向信号，也可选择映射到 Godot InputMap 动作。

成员概览

类型	名称	签名
信号	direction_changed	signal direction_changed(direction: Vector2)
信号	joystick_pressed	signal joystick_pressed
信号	joystick_released	signal joystick_released
枚举	PositionMode	enum PositionMode
属性	radius	var radius: float = 64.0:
属性	knob_radius_ratio	var knob_radius_ratio: float = 3.0:
属性	color	var color: Color = Color(1.0, 1.0, 1.0, 0.35):
属性	draw_interaction_zone	var draw_interaction_zone: bool = false:
属性	deadzone	var deadzone: float = 0.1
属性	position_mode	var position_mode: PositionMode = PositionMode.FIXED:
属性	interaction_radius	var interaction_radius: float = 160.0:
属性	action_left	var action_left: StringName = &""
属性	action_right	var action_right: StringName = &""
属性	action_up	var action_up: StringName = &""
属性	action_down	var action_down: StringName = &""
属性	emit_joypad_motion	var emit_joypad_motion: bool = false
属性	joypad_device_id	var joypad_device_id: int = -2
属性	joy_axis_x	var joy_axis_x: JoyAxis = JOY_AXIS_LEFT_X
属性	joy_axis_y	var joy_axis_y: JoyAxis = JOY_AXIS_LEFT_Y
方法	get_direction	func get_direction() -> Vector2:
方法	release	func release() -> void:

信号

direction_changed

• API：public

signal direction_changed(direction: Vector2)

摇杆方向变化时发出。方向已归一化并应用死区。

参数：

名称	说明
direction	已归一化并应用死区后的摇杆方向。

joystick_pressed

• API：public

signal joystick_pressed

摇杆按下时发出。

joystick_released

• API：public

signal joystick_released

摇杆释放时发出。

枚举

PositionMode

• API：public

enum PositionMode { ## 摇杆中心保持在场景中摆放的位置。 FIXED, ## 初次触摸时摇杆中心移动到触点，释放后回到原位置。 RELATIVE, }

摇杆定位模式。

属性

radius

• API：public

var radius: float = 64.0:

摇杆半径。

knob_radius_ratio

• API：public

var knob_radius_ratio: float = 3.0:

摇杆手柄半径比例。

color

• API：public

var color: Color = Color(1.0, 1.0, 1.0, 0.35):

摇杆颜色。

draw_interaction_zone

• API：public

var draw_interaction_zone: bool = false:

是否绘制相对摇杆交互范围。

deadzone

• API：public

var deadzone: float = 0.1

输入死区，范围 0 到 1。

position_mode

• API：public

var position_mode: PositionMode = PositionMode.FIXED:

摇杆定位模式。

interaction_radius

• API：public

var interaction_radius: float = 160.0:

相对模式下允许开始触控的交互半径。

action_left

• API：public

var action_left: StringName = &""

左方向动作名。为空则不映射。

action_right

• API：public

var action_right: StringName = &""

右方向动作名。为空则不映射。

action_up

• API：public

var action_up: StringName = &""

上方向动作名。为空则不映射。

action_down

• API：public

var action_down: StringName = &""

下方向动作名。为空则不映射。

emit_joypad_motion

• API：public

var emit_joypad_motion: bool = false

是否额外发送虚拟手柄轴事件。

joypad_device_id

• API：public

var joypad_device_id: int = -2

虚拟手柄设备 ID。建议使用负数以避开真实手柄。

joy_axis_x

• API：public

var joy_axis_x: JoyAxis = JOY_AXIS_LEFT_X

X 轴对应的手柄轴。

joy_axis_y

• API：public

var joy_axis_y: JoyAxis = JOY_AXIS_LEFT_Y

Y 轴对应的手柄轴。

方法

get_direction

• API：public

func get_direction() -> Vector2:

获取当前方向。

返回：当前摇杆方向。

release

• API：public

func release() -> void:

手动释放摇杆并清理动作状态。