Keyboard, mouse, touch and joystick

Two layers of input: named actions you can rebind, and raw device events.

9 min read

Actions come first

A project maps actions to keys — jump is Space and W, left is Left Arrow and A. Behaviours ask for actions, never for keys. Use On Input for anything a player might reasonably want rebound, and for anything that should also work from the on-screen joystick.

Edit the mapping under Assets → Input.

Raw device events

When you want one specific key or button rather than a rebindable action, use the Input category:

Node Fires when
On Key A chosen key is pressed, released, or is being held
On Any Key Any key at all — for "press any key to start"
Key Is Down A branch: is this key held right now?
On Mouse Button Left, middle or right button, pressed or released
On Mouse Move The mouse moves
On Mouse Wheel The wheel turns up or down
Store Pointer Position Writes the cursor into two variables
On Touch A finger lands, moves or lifts
On Tap A quick tap, or a long press
On Swipe A finger is dragged far and fast in one direction
On Joystick The on-screen stick is pushed or released
Read Joystick Writes the stick position into variables
On Button Click A tagged, clickable entity is pressed or released
On Button Hover The pointer enters or leaves a tagged, clickable entity

Held keys

On Key set to held fires every frame the key is down. Set to pressed it fires once, and ignores the operating system's auto-repeat — so holding a key does not machine-gun the node.

Buttons and menus

Unlike the raw mouse and touch events above, On Button Click and On Button Hover only fire for entities carrying a specific tag — nothing else in the scene becomes clickable, so these never steal a tap meant for something underneath. Three steps make a working menu button:

  • Generate a button image asset (Assets → Generate → Image → button) — pick a shape, style, colours and label text.
  • Place it as an entity and give it a tag, e.g. start-button.
  • Add an On Button Click node with that same tag, set to released for a normal click. Wire its exec output to whatever the button should do — Go To Scene for a Play button, a variable write for a settings toggle, and so on.

Set tag to any on either node to catch clicks or hovers from every clickable entity in the scene at once — read self to tell which one fired. Use Set Button Enabled (in the UI category) to grey out and disable a button — a Continue button before there is a save to continue from, for example — rather than hiding it outright.

Playing on a phone

Add the virtualJoystick behaviour to any entity and a thumbstick appears on touch devices. In its default swipe mode there is no fixed base — the stick appears wherever the thumb lands.

The important part: the joystick answers the mapped actions. Pushing it left is indistinguishable from holding the left arrow, as far as every behaviour is concerned — so an existing keyboard game becomes playable on a phone without touching its logic.

Behaviour: virtualJoystick
  mode      swipe | fixed
  side      left | right   (which half of the screen it claims)
  radius    68              (pixels)
  deadzone  0.22            (how far before it counts as a direction)
  show      auto | always   (auto = touch devices only)