Using the Joystick

by Jon (Updated on 2015-10-17)

NOTICE (October 2015)

We recommend using the Joystick extension over our built-in support. It's well documented, less buggy and more fully featured.

We plan to replace our built-in support with the extension in the future and will rewrite this article at that time.


  • Introduction
  • Showing the Joystick
  • Example
  • Changing the Appearance
  • Changing the Mode
  • FAQ



Some games involve moving a character around freely. Often, these games require a joystick to provide precise-enough control over that character’s movements.

Creating the logic yourself that would allow joystick input would be cumbersome. Thankfully, we’ve built this functionality into Stencyl.

Showing the Joystick

To enable the joystick and access its values, use the blocks shown below. They’re located under the User Input > Mobile category.


Joystick direction ranges from 0 to 360 degrees, inclusive.

Joystick distance equals how far the user has “stretched” the joystick relative to its center, in pixels.



The following example code, used in the Joystick example game, shows how to use the blocks to implement player movement.

Don’t panic about the math - you can find this behavior as part of your local Library when importing a behavior (From Your Library > Mobile > Joystick).

You can adjust the “-10” values shown next to the joystick distance block to tune the sensitivity and movement to your liking.

Changing the Joystick's Appearance

You can change the Joystick’s appearance and how it appears on the screen through the Settings > Mobile > Joystick page.

Access the Joystick Configuration Page

Click the Settings button, as shown, to open the dialog:

Settings Button

Next, click Mobile > User Input, as shown in #1 and #2.

Mobile joystick settings.

Changing the Appearance involves providing two graphics - one for the "background" and one for the moveable portion of the josytick.

Tip: Don't want to display the joystick at all? Provide blank graphics.


Changing the Mode

You have full control over when and where the joystick appears on the screen using blocks under User Input > Mobile category.


The Show where Pressed option shows the joystick where the user last touched the screen. This is the default.

The Fixed option shows the joystick at a fixed position on screen. To set this position, use the following block, located under the User Input > Mobile category.




Are dual joysticks supported?

In Stencyl 3.0 and above, dual joysticks are supported. As the name suggests, dual joysticks let you work with two joysticks rather than one. All of the key joystick operations can now be applied to Joystick 1, Joystick 2 or both of them.


Can I hide the joystick but still have it work?

You can "hide" the joystick but still have it work by importing blank graphics.

Disclaimer: Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!


Updated the article to refer everyone to the Joystick extension, which is way better than our built-in support.

We will replace our joystick support with this in the future.

1 1 month, 1 week ago
This works for me... but there is a problem. Ive asked on the forums but no help yet. The joystick will go to the bottom corner of the screen where i position it, but inorder to work it you have to have your finger about an inch up and a inch to the left of it to use it. Frustrating.... Ill post if i find a solution!
0 7 months, 2 weeks ago
I can't believe this is here if it DOESNT WORK!!!! UPDATEE!!!!!
0 8 months, 4 weeks ago
it does not work I have all the same emulated

0 1 year, 3 days ago
yup i have the same problem as dvfe, i would like to have a walk and run and jump actor w joystick for direction and a button for jump and a buton to fire a weapon :P that wold be awwwwesome!!!
0 1 year, 7 months ago
Ben - You could achieve it by inputting blank joystick graphics for both fields.
0 2 years, 7 months ago
Does anyone know of a way to have the joystick not be visible on the screen? I'd like to allow the movement of the joystick without it actually being visible.
0 2 years, 10 months ago
I could really use a second joystick for my game
0 3 years, 1 month ago
@ Stevetheipad:
Thank you for your response. I tried to tweak the default joystick to only follow the 4-way movement but I couldn't do it. It seems to be quite complicated to just tell it which direction to follow. There doesn't seem to be a way to do it.

0 3 years, 3 months ago
@dvfe: Just program a behavior (or work off the default) that accepts the joystick to be moved in all directions, but detects whether it's going up, down, right or left the most, and only goes in the appropriate direction.
0 3 years, 3 months ago

Sign In to Comment