JoystickControllerHUD

The JoystickControllerHUD element provides an input controller for a virtual joystick for moving entities, also called a virtual D-pad. More...

Import Statement:	import Felgo 4.0
Inherits:	Image

List of all members, including inherited members

Properties

backgroundImageSource : alias
controllerXPosition : real
controllerYPosition : real
joystickRadius : real
pressed : bool
thumbRadius : real
thumbSource : alias

Detailed Description

This component provides a virtual joystick for moving entities from player input. You can customize this component's visual appearance by setting the images for the joystick background with the backgroundImageSource property, and the thumb image with the thumbSource property.

The output of this component is the controllerXPosition and controllerYPosition. You can connect these with movement components like MovementAnimation, CircleCollider or BoxCollider. The output is normalized between [-1 +1] and can take any values in between these ranges for both axis. When the user is not pressing anywhere, both axis values are 0. When the right-most position is pressed, the controllerXPosition will have the value 1. When the top-most position is pressed, the controllerYPosition is 1.

This image shows the virtual joystick at the default position 0/0.

This image shows the virtual joystick at the right position 1/0, where controllerXPosition is +1 and controllerYPosition is 0.

Dragging Support

The joystickControllerHUD also supports dragging the thumb image and modifying the output properties controllerXPosition and controllerYPosition based on the new position. It automatically limits the image positioning to the defined thumbRadius. So even if the user drags outside the background image, the position is snapped to the thumbRadius.

Combining the JoystickControllerHUD with a TwoAxisController

To support games for the desktop with keyboard control and for mobiles with a virtual joystick, you can also connect the controller position properties with the TwoAxisController. In that way, you can use the same source code for both input methods, on desktop and mobile.

Example Usage

The following example shows how to use both a TwoAxisController and a JoystickControllerHUD to change the force and torque of the entity's physics component. The JoystickControllerHUD can be set to invisible on desktop platforms, because the preferred input method is the keyboard there. However, for testing you can set it visible in debug builds for quick testing of the behavior.

 import Felgo

 GameWindow {

   JoystickControllerHUD {
     id: joystickController

     anchors.bottom: top.bottom
     width: 50; height: 50

     // only show the HUD when in debug build or on desktop
     visible: system.debugBuild || system.desktopPlatform

     source: "img/joystick_background.png"
     thumbSource: "img/joystick_thumb.png"
   }

   Scene {
     focus: true
     Keys.forwardTo: twoAxisController

     EntityBase {

       TwoAxisController {
           id: twoAxisController

           // whenever the thumb position changes, update the twoAxisController
           xAxis: joystickController.controllerXPosition
           yAxis: joystickController.controllerYPosition
       }

       BoxCollider {
           width: 60; height: 40

           force: Qt.point(twoAxisController.yAxis*8000, 0)
           torque: twoAxisController.xAxis*2000
       }
     }
   }
 }

Property Documentation

backgroundImageSource : alias

The source of the background image for the joystick. You can use the one provided with the Felgo SDK (see image below).

Alternatively you can create your own graphic based on the image above. Navigate to the CarChallenge Demo directory for the image joystick_background.png.

See also thumbSource.

controllerXPosition : real

This property holds the x axis position of the thumb. The value is between -1 and +1. A positive value means the thumb is right of the center, a negative one means to the left. This is a read-only property and defaults to 0.

You can connect this output property to properties of other components like TwoAxisController or movement components. See the Example Usage section for an example.

controllerYPosition : real

This property holds the y axis position of the thumb. The value is between -1 and +1. A positive value means the thumb is on top of the center, a negative value means below the center. This is a read-only property and defaults to 0.

You can connect this output property to properties of other components like TwoAxisController or movement components. See the Example Usage section for an example.

joystickRadius : real

The radius in pixels for the background joystick image which is also used internally for the logic of snapping to this radius. By default, it is set to 50 px.

The size of the background image is set to this doubled radius, i.e. the default size for the background image is 100*100 pixels. If you want to change the image size to be decoupled from the logical radius, you can set the width & height property directly, and the joystickRadius independently.

See also thumbRadius.

[since Felgo 2.5.0] pressed : bool

This read-only property holds whether the controller is pressed. Default value is false.

This property was introduced in Felgo 2.5.0.

thumbRadius : real

The radius of the thumb image. The default is half of the joystickRadius. So the size is a quarter of the joystick image by default.

See also joystickRadius.

thumbSource : alias

The source of the thumb image for the joystick. You can use the one provided with the Felgo SDK (see image below).

Alternatively you can create your own graphic based on the image above. Navigate to the CarChallenge Demo directory for the image joystick_thumb.png.

Contents