Virtual Joystick DX

A fully customizable, modular virtual joystick for touchscreen mobile games. Switch between a smooth 360° analog joystick and an 8-direction D-Pad.

Compatible with Godot 4.3+ — tested on 4.7

Directory & Architectural Structure

The core codebase is fully modularized, separating mathematical computations, custom rendering, region clamping, and hardware detection into independent classes:

addons/virtual_joystick_DX/
├── vjdx_core_script.gd       # Inspector properties, signals, and control state orchestrator.
├── vjdx_renderer.gd          # Stateless class managing custom 2D canvas drawing (_draw).
├── vjdx_region.gd            # Computes viewport boundaries and active region positioning.
├── vjdx_haptics.gd           # Platform-safe haptic feedback wrapper.
├── vjdx_hardware_detector.gd # Gamepad / physical input monitoring for visibility toggle.
├── vjdx_joystick_handler.gd  # Fully owns Joystick movement-mode logic: deadzone math, activation checks (DYNAMIC/FOLLOWING), clampzone release, and reposition-target computation.
├── vjdx_dpad_handler.gd      # 8-direction state machine and custom texture state handling.
├── vjdx_plugin_launcher.gd   # Editor plugin registration script.
└── plugin.cfg                # Plugin configuration file.

Usage

1. Copy addons/virtual_joystick_DX/ into your project's addons/ folder.
2. Project → Project Settings → Plugins → enable Virtual Joystick DX.
3. Add the VirtualJoystickDX node to a CanvasLayer.

Player Script

func _physics_process(_delta: float) -> void:
    var dir := Vector2(
        Input.get_axis("move_left", "move_right"),
        Input.get_axis("move_up",   "move_down")
    )
    velocity = dir * speed
    move_and_slide()

Use get_axis(), not get_vector(). get_vector() applies an internal deadzone that truncates analog values and breaks smooth movement.

Inspector Reference

The Inspector hides parameters that don't apply to the selected style. All hidden values are still saved.

Controller Settings

Controller Style

Deadzone

The maximum allowed deadzone is thumb_radius / joystick_radius. At maximum deadzone, the dead area is exactly as large as the thumb, so the knob resting at center is already at the boundary. The slider max updates in real time when either radius changes.

Haptic Feedback

Press/release vibration is fully independent between Joystick and D-Pad — each style has its own toggle, duration and amplitude. Only the fields matching the current controller_style are shown.

Joystick

D-Pad

Android: requires the Vibrate permission enabled in the export preset (Project → Export → Android → Permissions) — enabling it in Project Settings alone is not enough. Vibration calls are guarded by OS.has_feature("mobile"), so nothing fires on desktop or web.

Joystick Mode

DYNAMIC and FOLLOWING share the same follow mechanic (slide, clamp, auto-release) — they only differ in how the control gets activated. Both return to their origin position on release.

Settings — Input Mapping

Each field is a dropdown showing all built-in and project-defined actions, but also accepts free text — type any action name directly.

Dynamic Visibility (Hardware Detection)

Active Region

In Static / D-Pad mode the control auto-releases if the finger leaves the region during a drag. In Dynamic / Following mode the base clamps to the region boundary instead. Note: the active region only gates activation for STATIC/DYNAMIC — FOLLOWING ignores it for activation and always requires touching the joystick directly.

Colors (Fallback When No Texture Is Set)

Joystick: color_js_base color_js_border color_js_thumb color_js_thumb_active

D-Pad: color_dp_bg color_dp_border color_dp_normal color_dp_active color_dp_arrow

Textures — Joystick (Joystick Only)

Textures — D-Pad (D-Pad Only)

Custom texture slots (visible when dpad_use_textures is ON):

All textures should be dpad_radius × 2 on each axis. Preset SVGs are in addons/virtual_joystick_DX/Dpad textures/preset 1(2)/.

Texture priority: custom slot → preset → code drawing.

Signals

joystick_moved(direction: Vector2)       # every frame while active
joystick_released()                      # on release
hardware_visibility_changed(is_visible: bool)

Dual Joystick Setup

func _ready() -> void:
    var vp := get_viewport().get_visible_rect().size
    $JoyLeft.use_active_region  = true
    $JoyLeft.region_w           = vp.x / 2.0
    $JoyLeft.region_h           = vp.y
    $JoyRight.use_active_region = true
    $JoyRight.region_x          = vp.x / 2.0
    $JoyRight.region_w          = vp.x / 2.0
    $JoyRight.region_h          = vp.y

Troubleshooting