Index · Object → Node → CanvasItem → Control → VirtualJoystick

VirtualJoystick

A virtual joystick control for touchscreen devices.

Class Description

A customizable on-screen joystick control designed for touchscreen devices. It allows users to provide directional input by dragging a virtual tip within a defined circular area.

This control can simulate directional actions (see action_up, action_down, action_left, and action_right), which are triggered when the joystick is moved in the corresponding directions.

Properties

var action_down: StringName = &"ui_down"

The action to trigger when the joystick is moved down.

var action_left: StringName = &"ui_left"

The action to trigger when the joystick is moved left.

var action_right: StringName = &"ui_right"

The action to trigger when the joystick is moved right.

var action_up: StringName = &"ui_up"

The action to trigger when the joystick is moved up.

var clampzone_ratio: float = 1.0

The multiplier applied to the joystick's radius that defines the clamp zone.

This zone limits how far the joystick tip can move from its center before being clamped.

A value of 1.0 means the tip can move up to the edge of the joystick's visual size.

In JOYSTICK_FOLLOWING mode, this radius also determines how far the finger can move before the joystick base starts following the touch input.

var deadzone_ratio: float = 0.0

The ratio of the joystick size that defines the joystick deadzone. The joystick tip must move beyond this ratio before being considered active.

This deadzone is applied before triggering input actions and affects the joystick's input vector and all related signals.

Note that input actions may also define their own deadzones in the InputMap. If both are set, the joystick deadzone is applied first, followed by the action's deadzone.

By default, this value is 0.0, meaning the joystick does not apply its own deadzone and relies entirely on the InputMap action deadzones.

var initial_offset_ratio: Vector2 = Vector2(0.5, 0.5)

The initial position of the joystick as a ratio of the control's size. (0, 0) is top-left and (1, 1) is bottom-right.

var joystick_mode: VirtualJoystick.JoystickMode = 0

The joystick mode to use.

var joystick_size: float = 100.0

The size of the joystick in pixels.

var tip_size: float = 50.0

The size of the joystick tip in pixels.

var visibility_mode: VirtualJoystick.VisibilityMode = 0

The visibility mode to use.

Inherited from Control (62)
var accessibility_controls_nodes: NodePath[] = []
var accessibility_flow_to_nodes: NodePath[] = []
var accessibility_labeled_by_nodes: NodePath[] = []
var anchor_bottom: float = 0.0
var anchor_left: float = 0.0
var anchor_right: float = 0.0
var anchor_top: float = 0.0
var clip_contents: bool = false
var custom_maximum_size: Vector2 = Vector2(-1, -1)
var custom_minimum_size: Vector2 = Vector2(0, 0)
var focus_neighbor_bottom: NodePath = NodePath("")
var focus_neighbor_left: NodePath = NodePath("")
var focus_neighbor_right: NodePath = NodePath("")
var focus_neighbor_top: NodePath = NodePath("")
var focus_next: NodePath = NodePath("")
var focus_previous: NodePath = NodePath("")
var offset_bottom: float = 0.0
var offset_left: float = 0.0
var offset_right: float = 0.0
var offset_top: float = 0.0
var offset_transform_pivot: Vector2 = Vector2(0, 0)
var offset_transform_pivot_ratio: Vector2 = Vector2(0.5, 0.5)
var offset_transform_position: Vector2 = Vector2(0, 0)
var offset_transform_scale: Vector2 = Vector2(1, 1)
var pivot_offset: Vector2 = Vector2(0, 0)
var pivot_offset_ratio: Vector2 = Vector2(0, 0)
var position: Vector2 = Vector2(0, 0)
var rotation: float = 0.0
var scale: Vector2 = Vector2(1, 1)
var size: Vector2 = Vector2(0, 0)
Inherited from CanvasItem (16)
var light_mask: int = 1
var modulate: Color = Color(1, 1, 1, 1)
var self_modulate: Color = Color(1, 1, 1, 1)
var top_level: bool = false
var visible: bool = true
var y_sort_enabled: bool = false
var z_as_relative: bool = true
var z_index: int = 0
Inherited from Node (14)
var owner: Node

Methods

Inherited from Control (100)
func _can_drop_data(at_position: Vector2, data: Variant) -> bool
func _drop_data(at_position: Vector2, data: Variant) -> void
func _get_cursor_shape(at_position: Vector2) -> int
func _get_drag_data(at_position: Vector2) -> Variant
func _get_tooltip(at_position: Vector2) -> String
func _gui_input(event: InputEvent) -> void
func _has_point(point: Vector2) -> bool
func _structured_text_parser(args: Array, text: String) -> Vector3i[]
func accept_event() -> void
func accessibility_drag() -> void
func accessibility_drop() -> void
func add_theme_color_override(name: StringName, color: Color) -> void
func add_theme_constant_override(name: StringName, constant: int) -> void
func add_theme_font_override(name: StringName, font: Font) -> void
func add_theme_font_size_override(name: StringName, font_size: int) -> void
func add_theme_icon_override(name: StringName, texture: Texture2D) -> void
func add_theme_stylebox_override(name: StringName, stylebox: StyleBox) -> void
func force_drag(data: Variant, preview: Control) -> void
func get_anchor(side: Side) -> float
func get_begin() -> Vector2
func get_cursor_shape(at_position: Vector2 = Vector2(0, 0)) -> Control.CursorShape
func get_end() -> Vector2
func get_focus_neighbor(side: Side) -> NodePath
func get_offset(offset: Side) -> float
func get_rect() -> Rect2
func get_theme_color(name: StringName, theme_type: StringName = &"") -> Color
func get_theme_constant(name: StringName, theme_type: StringName = &"") -> int
func get_theme_font(name: StringName, theme_type: StringName = &"") -> Font
func get_theme_font_size(name: StringName, theme_type: StringName = &"") -> int
func get_theme_icon(name: StringName, theme_type: StringName = &"") -> Texture2D
func get_theme_stylebox(name: StringName, theme_type: StringName = &"") -> StyleBox
func get_tooltip(at_position: Vector2 = Vector2(0, 0)) -> String
func grab_click_focus() -> void
func grab_focus(hide_focus: bool = false) -> void
func has_focus(ignore_hidden_focus: bool = false) -> bool
func has_theme_color(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_constant(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_font(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_font_size(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_icon(name: StringName, theme_type: StringName = &"") -> bool
func has_theme_stylebox(name: StringName, theme_type: StringName = &"") -> bool
func release_focus() -> void
func reset_size() -> void
func set_anchor(side: Side, anchor: float, keep_offset: bool = false, push_opposite_anchor: bool = true) -> void
func set_anchor_and_offset(side: Side, anchor: float, offset: float, push_opposite_anchor: bool = false) -> void
func set_anchors_and_offsets_preset(preset: Control.LayoutPreset, resize_mode: Control.LayoutPresetMode = 0, margin: int = 0) -> void
func set_anchors_preset(preset: Control.LayoutPreset, keep_offsets: bool = false) -> void
func set_begin(position: Vector2) -> void
func set_drag_forwarding(drag_func: Callable, can_drop_func: Callable, drop_func: Callable) -> void
func set_drag_preview(control: Control) -> void
func set_end(position: Vector2) -> void
func set_focus_neighbor(side: Side, neighbor: NodePath) -> void
func set_global_position(position: Vector2, keep_offsets: bool = false) -> void
func set_offset(side: Side, offset: float) -> void
func set_offsets_preset(preset: Control.LayoutPreset, resize_mode: Control.LayoutPresetMode = 0, margin: int = 0) -> void
func set_position(position: Vector2, keep_offsets: bool = false) -> void
func set_size(size: Vector2, keep_offsets: bool = false) -> void
func update_maximum_size() -> void
func update_minimum_size() -> void
func warp_mouse(position: Vector2) -> void
Inherited from CanvasItem (62)
func _draw() -> void
func draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) -> void
func draw_arc(center: Vector2, radius: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false) -> void
func draw_ellipse(position: Vector2, major: float, minor: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_ellipse_arc(center: Vector2, major: float, minor: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_end_animation() -> void
func draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_msdf_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), outline: float = 0.0, pixel_range: float = 4.0, scale: float = 1.0) -> void
func draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multiline_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multimesh(multimesh: MultiMesh, texture: Texture2D) -> void
func draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) -> void
func draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) -> void
func draw_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_style_box(style_box: StyleBox, rect: Rect2) -> void
func draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) -> void
func draw_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) -> void
func force_update_transform() -> void
func get_canvas() -> RID
func hide() -> void
func make_canvas_position_local(viewport_point: Vector2) -> Vector2
func move_to_front() -> void
func queue_redraw() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_visibility_layer_bit(layer: int, enabled: bool) -> void
func show() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal flick_canceled()

Emitted when the tip enters the deadzone after being outside of it.

signal flicked(input_vector: Vector2)

Emitted when the tip moved outside the deadzone and the joystick is released. The input_vector contains the last input direction and strength before release. Its length is between 0.0 and 1.0.

signal pressed()

Emitted when the joystick is pressed.

signal released(input_vector: Vector2)

Emitted when the joystick is released. The input_vector is the final input direction and strength, with a length between 0.0 and 1.0.

signal tapped()

Emitted when the joystick is released without moving the tip.

Inherited from Control (10)
signal focus_entered()
signal focus_exited()
signal gui_input(event: InputEvent)
signal mouse_entered()
signal mouse_exited()
signal resized()
signal theme_changed()
Inherited from CanvasItem (4)
signal draw()
signal hidden()
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

enum JoystickMode
JOYSTICK_FIXED = 0

The joystick doesn't move.

JOYSTICK_DYNAMIC = 1

The joystick is moved to the initial touch position as long as it's within the joystick's bounds. It moves back to its original position when released.

JOYSTICK_FOLLOWING = 2

The joystick is moved to the initial touch position as long as it's within the joystick's bounds. It will follow the touch input if it goes outside the joystick's range. It moves back to its original position when released.

enum VisibilityMode
VISIBILITY_ALWAYS = 0

The joystick is always visible.

VISIBILITY_WHEN_TOUCHED = 1

The joystick is only visible when being touched.