godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-09-03 18:14:53 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
godot-docs/classes/class_virtualjoystick.rst
Godot Organization 03bdc7c6bb classref: Sync with current master branch (220b0b2)
2026-03-07 03:52:57 +00:00

472 lines
18 KiB
ReStructuredText
Raw Permalink Blame History

:github_url: hide
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/VirtualJoystick.xml.
.. _class_VirtualJoystick:
VirtualJoystick
===============
**Inherits:** :ref:`Control<class_Control>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
A virtual joystick control for touchscreen devices.
.. rst-class:: classref-introduction-group
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 :ref:`action_up<class_VirtualJoystick_property_action_up>`, :ref:`action_down<class_VirtualJoystick_property_action_down>`, :ref:`action_left<class_VirtualJoystick_property_action_left>`, and :ref:`action_right<class_VirtualJoystick_property_action_right>`), which are triggered when the joystick is moved in the corresponding directions.
.. rst-class:: classref-reftable-group
Properties
----------
.. table::
:widths: auto
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`StringName<class_StringName>` | :ref:`action_down<class_VirtualJoystick_property_action_down>` | ``&"ui_down"`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`StringName<class_StringName>` | :ref:`action_left<class_VirtualJoystick_property_action_left>` | ``&"ui_left"`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`StringName<class_StringName>` | :ref:`action_right<class_VirtualJoystick_property_action_right>` | ``&"ui_right"`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`StringName<class_StringName>` | :ref:`action_up<class_VirtualJoystick_property_action_up>` | ``&"ui_up"`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>` | :ref:`clampzone_ratio<class_VirtualJoystick_property_clampzone_ratio>` | ``1.0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>` | :ref:`deadzone_ratio<class_VirtualJoystick_property_deadzone_ratio>` | ``0.0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`Vector2<class_Vector2>` | :ref:`initial_offset_ratio<class_VirtualJoystick_property_initial_offset_ratio>` | ``Vector2(0.5, 0.5)`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` | :ref:`joystick_mode<class_VirtualJoystick_property_joystick_mode>` | ``0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>` | :ref:`joystick_size<class_VirtualJoystick_property_joystick_size>` | ``100.0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>` | :ref:`tip_size<class_VirtualJoystick_property_tip_size>` | ``50.0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
| :ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>` | :ref:`visibility_mode<class_VirtualJoystick_property_visibility_mode>` | ``0`` |
+------------------------------------------------------------+----------------------------------------------------------------------------------+-----------------------+
.. rst-class:: classref-reftable-group
Theme Properties
----------------
.. table::
:widths: auto
+---------------------------------+-----------------------------------------------------------------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`normal_joystick<class_VirtualJoystick_theme_style_normal_joystick>` |
+---------------------------------+-----------------------------------------------------------------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`normal_tip<class_VirtualJoystick_theme_style_normal_tip>` |
+---------------------------------+-----------------------------------------------------------------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`pressed_joystick<class_VirtualJoystick_theme_style_pressed_joystick>` |
+---------------------------------+-----------------------------------------------------------------------------+
| :ref:`StyleBox<class_StyleBox>` | :ref:`pressed_tip<class_VirtualJoystick_theme_style_pressed_tip>` |
+---------------------------------+-----------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Signals
-------
.. _class_VirtualJoystick_signal_flick_canceled:
.. rst-class:: classref-signal
**flick_canceled**\ (\ ) :ref:`🔗<class_VirtualJoystick_signal_flick_canceled>`
Emitted when the tip enters the deadzone after being outside of it.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_signal_flicked:
.. rst-class:: classref-signal
**flicked**\ (\ input_vector\: :ref:`Vector2<class_Vector2>`\ ) :ref:`🔗<class_VirtualJoystick_signal_flicked>`
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``.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_signal_pressed:
.. rst-class:: classref-signal
**pressed**\ (\ ) :ref:`🔗<class_VirtualJoystick_signal_pressed>`
Emitted when the joystick is pressed.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_signal_released:
.. rst-class:: classref-signal
**released**\ (\ input_vector\: :ref:`Vector2<class_Vector2>`\ ) :ref:`🔗<class_VirtualJoystick_signal_released>`
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``.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_signal_tapped:
.. rst-class:: classref-signal
**tapped**\ (\ ) :ref:`🔗<class_VirtualJoystick_signal_tapped>`
Emitted when the joystick is released without moving the tip.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Enumerations
------------
.. _enum_VirtualJoystick_JoystickMode:
.. rst-class:: classref-enumeration
enum **JoystickMode**: :ref:`🔗<enum_VirtualJoystick_JoystickMode>`
.. _class_VirtualJoystick_constant_JOYSTICK_FIXED:
.. rst-class:: classref-enumeration-constant
:ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` **JOYSTICK_FIXED** = ``0``
The joystick doesn't move.
.. _class_VirtualJoystick_constant_JOYSTICK_DYNAMIC:
.. rst-class:: classref-enumeration-constant
:ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` **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.
.. _class_VirtualJoystick_constant_JOYSTICK_FOLLOWING:
.. rst-class:: classref-enumeration-constant
:ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` **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.
.. rst-class:: classref-item-separator
----
.. _enum_VirtualJoystick_VisibilityMode:
.. rst-class:: classref-enumeration
enum **VisibilityMode**: :ref:`🔗<enum_VirtualJoystick_VisibilityMode>`
.. _class_VirtualJoystick_constant_VISIBILITY_ALWAYS:
.. rst-class:: classref-enumeration-constant
:ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>` **VISIBILITY_ALWAYS** = ``0``
The joystick is always visible.
.. _class_VirtualJoystick_constant_VISIBILITY_WHEN_TOUCHED:
.. rst-class:: classref-enumeration-constant
:ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>` **VISIBILITY_WHEN_TOUCHED** = ``1``
The joystick is only visible when being touched.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Property Descriptions
---------------------
.. _class_VirtualJoystick_property_action_down:
.. rst-class:: classref-property
:ref:`StringName<class_StringName>` **action_down** = ``&"ui_down"`` :ref:`🔗<class_VirtualJoystick_property_action_down>`
.. rst-class:: classref-property-setget
- |void| **set_action_down**\ (\ value\: :ref:`StringName<class_StringName>`\ )
- :ref:`StringName<class_StringName>` **get_action_down**\ (\ )
The action to trigger when the joystick is moved down.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_action_left:
.. rst-class:: classref-property
:ref:`StringName<class_StringName>` **action_left** = ``&"ui_left"`` :ref:`🔗<class_VirtualJoystick_property_action_left>`
.. rst-class:: classref-property-setget
- |void| **set_action_left**\ (\ value\: :ref:`StringName<class_StringName>`\ )
- :ref:`StringName<class_StringName>` **get_action_left**\ (\ )
The action to trigger when the joystick is moved left.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_action_right:
.. rst-class:: classref-property
:ref:`StringName<class_StringName>` **action_right** = ``&"ui_right"`` :ref:`🔗<class_VirtualJoystick_property_action_right>`
.. rst-class:: classref-property-setget
- |void| **set_action_right**\ (\ value\: :ref:`StringName<class_StringName>`\ )
- :ref:`StringName<class_StringName>` **get_action_right**\ (\ )
The action to trigger when the joystick is moved right.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_action_up:
.. rst-class:: classref-property
:ref:`StringName<class_StringName>` **action_up** = ``&"ui_up"`` :ref:`🔗<class_VirtualJoystick_property_action_up>`
.. rst-class:: classref-property-setget
- |void| **set_action_up**\ (\ value\: :ref:`StringName<class_StringName>`\ )
- :ref:`StringName<class_StringName>` **get_action_up**\ (\ )
The action to trigger when the joystick is moved up.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_clampzone_ratio:
.. rst-class:: classref-property
:ref:`float<class_float>` **clampzone_ratio** = ``1.0`` :ref:`🔗<class_VirtualJoystick_property_clampzone_ratio>`
.. rst-class:: classref-property-setget
- |void| **set_clampzone_ratio**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_clampzone_ratio**\ (\ )
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 :ref:`JOYSTICK_FOLLOWING<class_VirtualJoystick_constant_JOYSTICK_FOLLOWING>` mode, this radius also determines how far the finger can move before the joystick base starts following the touch input.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_deadzone_ratio:
.. rst-class:: classref-property
:ref:`float<class_float>` **deadzone_ratio** = ``0.0`` :ref:`🔗<class_VirtualJoystick_property_deadzone_ratio>`
.. rst-class:: classref-property-setget
- |void| **set_deadzone_ratio**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_deadzone_ratio**\ (\ )
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.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_initial_offset_ratio:
.. rst-class:: classref-property
:ref:`Vector2<class_Vector2>` **initial_offset_ratio** = ``Vector2(0.5, 0.5)`` :ref:`🔗<class_VirtualJoystick_property_initial_offset_ratio>`
.. rst-class:: classref-property-setget
- |void| **set_initial_offset_ratio**\ (\ value\: :ref:`Vector2<class_Vector2>`\ )
- :ref:`Vector2<class_Vector2>` **get_initial_offset_ratio**\ (\ )
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.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_joystick_mode:
.. rst-class:: classref-property
:ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` **joystick_mode** = ``0`` :ref:`🔗<class_VirtualJoystick_property_joystick_mode>`
.. rst-class:: classref-property-setget
- |void| **set_joystick_mode**\ (\ value\: :ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>`\ )
- :ref:`JoystickMode<enum_VirtualJoystick_JoystickMode>` **get_joystick_mode**\ (\ )
The joystick mode to use.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_joystick_size:
.. rst-class:: classref-property
:ref:`float<class_float>` **joystick_size** = ``100.0`` :ref:`🔗<class_VirtualJoystick_property_joystick_size>`
.. rst-class:: classref-property-setget
- |void| **set_joystick_size**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_joystick_size**\ (\ )
The size of the joystick in pixels.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_tip_size:
.. rst-class:: classref-property
:ref:`float<class_float>` **tip_size** = ``50.0`` :ref:`🔗<class_VirtualJoystick_property_tip_size>`
.. rst-class:: classref-property-setget
- |void| **set_tip_size**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_tip_size**\ (\ )
The size of the joystick tip in pixels.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_property_visibility_mode:
.. rst-class:: classref-property
:ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>` **visibility_mode** = ``0`` :ref:`🔗<class_VirtualJoystick_property_visibility_mode>`
.. rst-class:: classref-property-setget
- |void| **set_visibility_mode**\ (\ value\: :ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>`\ )
- :ref:`VisibilityMode<enum_VirtualJoystick_VisibilityMode>` **get_visibility_mode**\ (\ )
The visibility mode to use.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Theme Property Descriptions
---------------------------
.. _class_VirtualJoystick_theme_style_normal_joystick:
.. rst-class:: classref-themeproperty
:ref:`StyleBox<class_StyleBox>` **normal_joystick** :ref:`🔗<class_VirtualJoystick_theme_style_normal_joystick>`
Base joystick :ref:`StyleBox<class_StyleBox>`.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_theme_style_normal_tip:
.. rst-class:: classref-themeproperty
:ref:`StyleBox<class_StyleBox>` **normal_tip** :ref:`🔗<class_VirtualJoystick_theme_style_normal_tip>`
Tip joystick :ref:`StyleBox<class_StyleBox>`.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_theme_style_pressed_joystick:
.. rst-class:: classref-themeproperty
:ref:`StyleBox<class_StyleBox>` **pressed_joystick** :ref:`🔗<class_VirtualJoystick_theme_style_pressed_joystick>`
Base joystick :ref:`StyleBox<class_StyleBox>` when pressed.
.. rst-class:: classref-item-separator
----
.. _class_VirtualJoystick_theme_style_pressed_tip:
.. rst-class:: classref-themeproperty
:ref:`StyleBox<class_StyleBox>` **pressed_tip** :ref:`🔗<class_VirtualJoystick_theme_style_pressed_tip>`
Tip joystick :ref:`StyleBox<class_StyleBox>` when pressed.
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
.. |void| replace:: :abbr:`void (No return value.)`
Reference in New Issue View Git Blame Copy Permalink