Realot StudioDocs
Components

Joystick

Realot Studio Joystick component reference: fields, script API, behavior and examples.

View as Markdownllms.txt
ScopeThis page documents the Joystick component in Realot Studio. Runtime fields are serialized scene data; the Script API section lists only members intentionally exposed to game scripts.
Where to find it in the editorTop UI → Joystick, or Inspector → Add Component → Joystick.

#What it does

Virtual touch joystick for mobile and pointer-driven control schemes.

Component setup & editor toolsJoystick provides a touch/drag virtual control for mobile-oriented input.

#How to add and use Joystick

Editor path: Select the target entity in the Hierarchy (left side) → look at the Inspector (right side) → click Add Component at the bottom of the Inspector → search for Joystick → click the component row. The Add Component picker is a centered modal with a search box; it only lists components not already attached.

For components with a dedicated editor tool, the tool is opened or activated from the location described below. Do not assume that adding the component alone activates its editor; some systems require a separate window, panel, or viewport tool.

#Component setup & editor tools

  • GameObject → UI → Joystick creates a joystick entity. You can also select an entity → Inspector → Add Component → Joystick.

#What you should see after adding it

The component appears as its own section in the Inspector. Its serialized settings are listed in the Component data table below. If a field is conditional, it appears only when the relevant mode/type is selected. If a field is a runtime state field (for example grounded or resolved velocity), treat it as read-only diagnostic state unless the API reference explicitly documents it as writable.

#How to read the settings

For every setting below, the documentation distinguishes type, default, meaning, and tuning direction where behavior is known. When a value represents a direction, use the engine's coordinate convention documented in Coordinate system; do not substitute Unity/Godot conventions.

#Component data

FieldTypePurposeDefault
positionModeJoystickPositionMode enum: Fixed | DynamicFixed or pointer-positioned joystick.Fixed
regionXnumberDynamic-mode touch region — the screen-space rectangle (in the same pixel convention Transform.x/y already use for screen-space UI, see TextInput.js's file header) that a press must land inside to claim this joystick.0
regionYnumberRegion Y.0
regionWidthnumberRegion width.640
regionHeightnumberRegion height.720
baseRadiusnumberVisuals60
knobRadiusnumberKnob radius.28
baseColorhex color stringBase color.#ffffff
baseOpacitynumberBase opacity.0.25
knobColorhex color stringKnob color.#ffffff
knobOpacitynumberKnob opacity.0.6
outlineColorhex color stringOutline color.#ffffff
outlineWidthnumberOutline width.2
deadZonenumberBehavior 0-1: fraction of baseRadius the knob must move before x/y leaves 00.1
returnToCenterbooleantrue = knob snaps back to center on release; false = holds last positiontrue
hideWhenIdlebooleantrue = invisible until actively being dragged (works in both position modes)false
idleOpacityMultipliernumberwhen hideWhenIdle is false, how much to dim the whole stick while not in use (1 = no dimming)0.35
xnumberLive state — see the file header for why these live here rather than in JoystickSystem's private state.0
ynumber-1..1, vertical knob offset (down = positive), after dead zone0
magnitudenumber0..1, distance of the knob from center after dead zone0
anglenumberdegrees, 0 = right, 90 = down (screen-space convention, matches Transform.rotation's clockwise-positive sense)0
activebooleantrue while a finger/pointer is currently dragging this joystickfalse
baseScreenXnumbercurrent drawn base center, in screen px — equals Transform.x/y in Fixed mode, or the recentered touch point in Dynamic mode0
baseScreenYnumberInspector field stored on this component.0

#Tuning behavior

These are the practical direction-of-change rules for the most important controls on this component.

SettingWhat changing it does
deadZone0 means even tiny stick displacement is reported; increasing it keeps small movements at zero until the knob moves farther.
baseRadius / knobRadiusLarger values make the on-screen joystick physically larger.
idleOpacityMultiplierLower makes an idle joystick more transparent when hideWhenIdle is false.
returnToCenterTrue snaps back on release; false preserves the last knob position.

#Script API

MemberKindDescription
activeProperty (read-only)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
angleProperty (read-only)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
baseColorProperty (read/write)Exposed by this script module.
baseOpacityProperty (read/write)Exposed by this script module.
baseRadiusProperty (read/write)Base radius.
deadZoneProperty (read/write)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
hideWhenIdleProperty (read/write)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
idleOpacityMultiplierProperty (read/write)Exposed by this script module.
knobColorProperty (read/write)Exposed by this script module.
knobOpacityProperty (read/write)Exposed by this script module.
knobRadiusProperty (read/write)Knob radius.
magnitudeProperty (read-only)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
outlineColorProperty (read/write)Exposed by this script module.
outlineWidthProperty (read/write)Exposed by this script module.
positionModeProperty (read/write)Joystick positioning mode.
regionHeightProperty (read/write)Region height.
regionWidthProperty (read/write)Region width.
regionXProperty (read/write)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
regionYProperty (read/write)Touch/pointer region Y.
returnToCenterProperty (read/write)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
xProperty (read-only)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).
yProperty (read-only)The `this.joystick` sub-object exposed to user scripts (see scripting/ScriptAPI.js).

#Examples

js
this.rigidbody.velocityX = this.joystick.x * 250;
Need the full workflow?Components: complete workflow covers adding, configuring, testing, combining, and removing components.