by Jon (Updated on 2014-01-26)


  • Keyboard (Controls)
  • Mouse
  • Mouse over Actor
  • The Cursor
  • Mobile Controls
  • Example: 4 Way Motion
  • The Future

Keyboard (Controls)

Detecting keyboard input works differently in Stencyl than it does in other systems. We use the notion of a Control to make your keyboard controls flexible and easy to remap.

A Control is simply a name that pertains to an action, or a “button” if you will, on a controller.

For example, if we were designing a control scheme for a Mario game, it would look like this.


The same idea applies to Stencyl, through a game’s Controls Page. To set Controls, click the Settings button, shown below, to open that dialog.

Stenyl Settings Button

Next, click the Controls button to view the Controls pane. From there, you tell us the name of the Control and the button it maps to.

Setting up Controls in Stencyl

Now, when you check whether a key is pressed, released or down, instead of checking directly on a certain key (such as spacebar), you check the state of the Control.



Why do we make you go through this? Why can’t you just say the key directly?

- What if you decide to change your control scheme? You’d have to change it everywhere.

- What if you wanted to make your control scheme configurable? That would be a mess. With Controls, you just change what key the Control is mapped to.

Note: To reduce the amount of setup, all Stencyl games come pre-shipped with a default set of controls. You’re free to edit them, delete them, etc.



Mouse input is detected through 3 different states.

  • Pressed
  • Released
  • Down

Pressed and Released are one-off “events” - they fire once per that action, whereas “down” is a constant state that can be checked.

You can also grab the (x,y) location of the mouse on screen or any recent presses/releases.



Mouse over Actor

Similarly, mouse input over an actor involves 4 different states.

  • Pressed on Actor
  • Released on Actor
  • Down on Actor
  • Over Actor

Over Actor is our term for hovering the mouse over the actor.


The Cursor

Sometimes, you want to hide the cursor or display a custom cursor. How do you do this?

To show or hide the cursor, use this block.


Mini-Challenge: How would you create a custom cursor? One method is to hide the cursor and create a dummy actor that continually follows the mouse but does not collide with anything.


Mobile Controls

Starting in Stencyl 3, mouse input is equivalent to (single) touch input. You no longer and no longer should use the separate touch blocks for this. Read our Touch article for further details and examples.

Other mobile input topics are covered separately.


Example: 4 Way Motion

This example shows a simple use-case for Keyboard controls.

Up/Down/Left/Right are pre-defined controls that come with each game - they are not to be mixed up with the actual, literal keys by the same name.



  • One drawback of this simple approach is that you can walk diagonally. How would you fix this?
  • In this version, the player stops immediately after you lift the keys. Implement a version where the player slows down gradually.


The Future

Although abstracting keys is powerful and flexible, some developers have expressed a desire to work with fixed keys. In a future version of Stencyl, we’ll add the ability to choose a key directly, rather than an abstract control.

Other commonly requestd improvements include gamepad support and built in configurable control support.


  • Detect key events by creating abstract controls and checking the state those controls.
  • Controls let you change the control scheme for your game from one place.


Challenge: Button

Create a button that responds to Mouse controls but goes beyond just a one liner "when pressed, do something".

The button should work just like a regular button. Specifically, don’t register a button click unless the gesture was both started and completed on the button.

Food for Thought: Think of scenarios where simply detecting a release would be incorrect.

Challenge: Cutscenes

There’s a nifty block for simulating key presses and releases. It’s useful for creating on-screen buttons in mobile games that can act as if they were physical keyboard buttons.


It’s also useful for creating cutscenes. Make a cutscene using this block.

Disclaimer: All articles are geared towards Stencyl 3.0 and above. 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!


i cant find the settings tab

0 4 months, 4 weeks ago
0 8 months, 3 weeks ago
0 1 year, 4 weeks ago

Sign In to Comment