by Jon (Updated on 2014-12-07)

Looking for our article on Gamepad / External Controllers? We now support those starting in Stencyl 3.2.


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

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.


Text Input (Stencyl 3.1 and later)

Sometimes the player input is not limited to a specific set of keys, but rather the player should be able to enter arbitrary text. For example, when you want the player to enter their name, or in a word game where the player has to enter letters.

Starting with Stencyl 3.1, you can use the "when any key is pressed/released" event for this kind of user input.

The event is triggered when any key is pressed or released respectively. The "character" block returns the character that has been generated by the event, for example if the player presses the A key, the character "a" is generated. The block also takes modifier keys into account, so pressing A while holding the SHIFT key, generates the upper-case character "A".

Some keys don't generate a character, like the ENTER key, or the BACKSPACE key. To check if such a key has been pressed, use the "key code" block, which returns a unique number for each keyboard key. For the most important keys, compare the "key code" of the event with the "key code of [___]" block. If you need to check if a different key has been pressed, the full list of key codes can be looked up here.

The following is a basic example of how to store user input in a text attribute:


Mini-Challenge: Create a Text Field for the player's name

  • When the player clicks on the text field, wait for user input.
  • Store the input in a text attribute.
  • Draw the text that the player has entered.
  • When the enter key is pressed, stop waiting for input.
  • Extra Challange: Draw a blinking cursor when the text field is focused.


  • 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!


how to force move mouse pointer to desired location ????
0 2 months, 5 days ago
I'm new, how do you get the "set text" value?
0 1 year, 2 weeks ago
Hey guys, I'm new to Stencyl, and so far I think it's great! For future control implementation, I'm praying you will add MIDI support. I just want to make music games. Or just implement a way to allow Stencyl to detect input signals and then allow the user to define them as input controls.
0 1 year, 2 months ago
You're awesome!

0 1 year, 3 months ago
Thanks to captaincomic, we now have a section on text input.
1 1 year, 3 months ago
i cant find the settings tab

0 1 year, 9 months ago
0 2 years, 1 month ago
0 2 years, 5 months ago

Sign In to Comment