====== Analog Joystick / Gamepad Control Sticks ======

Orx supports joysticks and gamepads. The axis (for an analog stick) usually has a value between 0 and 32768 which indicates how far along the axis the stick has been pushed. Orx scales these values to down to the range ''0.0'' to ''1.0''.

This gives you smooth multi-direction control in both the X and Y directions.

===== Axis =====

Orx provides many Axis properties for your ''Input'' config. 

{{section>en:orx:config:settings_main:input_joystick#[joystick_axes]&noheader&nofooter&noeditbutton}}

===== Stick Threshold =====

When pushing the stick in any direction, after getting past the small threshold, the value can be read using the ''orxInput_IsActive'' and ''orxInput_GetValue'' functions.

Let's work through setting this up. Firstly, ''init'' up a new project using [[en:tutorials:projects:creating_your_own_project|these instructions]].

Once you have a working project, add in the following graphic into your project's data to act as the object that will be controlled by the joystick:

{{ tutorials:physics:ball.png |}}

Next, change the default Object in the config to use the ''ball.png'' graphic, and also to use a body so that we can have some physics (and deceleration) on the object:

<code ini>
[Object]
Graphic         = @
Texture         = ball.png
Pivot           = center
Position        = (0, 0, 0)
Body            = ObjectBody

[ObjectBody]
LinearDamping = 1.5
FixedRotation = true
Dynamic       = true
AllowSleep    = false
PartList      = ObjectBodyPart

[ObjectBodyPart]
Type  = box
Solid = true
</code>

Next, we will define the joystick direction controls in the ''[MainInput]'' section:

<code ini>
[Input]
SetList          = MainInput
DefaultThreshold = 0.2

[MainInput]
JOY_LX_1   = LeftRight
JOY_LY_1   = UpDown
KEY_ESCAPE = Quit
</code>

The ''JOY_LX_1'' above means, get values from the left analog stick when it is pushed along the X axis, either left or right. No value is read until it crosses the threshold (''DefaultThreshold''), which is 0.2, After that, register a ''LeftRight'' value.

The ''_1'' at the end of ''JOY_LX_1'' means joystick #1. There can be up to 16 physical USB inputs used.

In the same way, the ''JOY_LY_1'' means that if the analog stick has been moved up or down the Y axis, it will register an ''UpDown'' value.

For more details, see: [[en:tutorials:input:analog_stick_threshold|Analog Stick Threshold]]

Finally in the ''Run()'' function, we can add the code to respond to these "movements". ''Run()'' is not normally the recommended place to put this code, but for demonstration purposes, it is fine:

<code c>
        const orxFLOAT speed = 150;

	if (orxInput_IsActive("LeftRight")) {
		orxVECTOR speedVector = orxVECTOR_0;
		orxObject_GetSpeed(object, &speedVector);

		orxFLOAT x = orxInput_GetValue("LeftRight");
		speedVector.fX = x * speed;

		orxObject_SetSpeed(object, &speedVector);
	}

	if (orxInput_IsActive("UpDown")) {
		orxVECTOR speedVector = orxVECTOR_0;
		orxObject_GetSpeed(object, &speedVector);

		orxFLOAT y = orxInput_GetValue("UpDown");
		speedVector.fY = y * -speed;

		orxObject_SetSpeed(object, &speedVector);
	}
</code>

In the above code, the ''LeftRight'' and ''UpDown'' inputs are being checked to see if they are active. If so, get the current speed and the axis position values with ''orxInput_GetValue'' and set the proper speed direction value to 150 / the axis the value. The smaller the stick movement, the smaller the object movement.

It's all pretty simple.

===== Further reading =====

{{https://steamcdn-a.akamaihd.net/steamcommunity/public/images/clans/27766192/f56593e63a2581024b98979658fb2b4e17f8d1a8.jpg?500x120}}

Steam have an interesting article on their controller usage metrics, tools and experiments in controller remapping.

{{https://steamcdn-a.akamaihd.net/steamcommunity/public/images/clans/27766192/817181596da53a62e63586af4a3334433e1e818f.jpg?500x120}}

This is a different take to Orx's use of the SDL_GameControllerDB community database.

You can read the [[https://steamcommunity.com/games/593110/announcements/detail/1712946892833213377|article on Steam here]].