Unification of Inputs

Some players might have a keyboard and mouse, others a touchscreen, and others a gamepad. How can you support all of these input methods without having to write separate code for each one?

You should nominate one set of inputs to be the canonical inputs for your game. All of your code should only listen to the canonical input method. Then you remap alternative input methods to the canonical input method, so that you can treat all input methods as equivalent. This process is called input unification.

Built-in Remappings

Various functions are provided to automatically remap one input method to another.

Button to Button

The ButtonRemap function programmatically maps one button to another. The buttons can be keyboard, mouse or gamepad buttons.

For example, you might choose KeySpacebar to make your character jump. Then, you can use ButtonRemap to support alternative input methods, such as ButtonRemap(Click, KeySpacebar) to support the mouse, and ButtonRemap(Click, GamepadA) to support gamepads.

We recommend you setup these remappings at the top of your Main function. This sets up all the mappings once globally and then you can forget about them for the rest of your code.

info

Button to button remappings are handled transparently by the engine. The actual key that was pressed will be translated to the remapped key and only the remapped key will be signalled. The Easel program never receives the actual key pressed and does not need to be aware of the remapping.

Keyboard to Joystick

The KeyboardVirtualJoystick function can be used to map the keyboard arrow keys to the Joystick. This is what it would look like typically:

KeyboardVirtualJoystick(up=ArrowUp, left=ArrowLeft, down=ArrowDown, right=ArrowRight)

You can choose to provide null to some of the parameters if you don't want to map all four directions.

KeyboardVirtualJoystick(left=ArrowLeft, right=ArrowRight, up=null, down=null)

Touchscreen to Joystick

The VirtualJoystick function lets you display a virtual joystick on the screen. Normally this is for touchscreen users, and so you would normally wrap it in a TouchscreenOnly UI element.

BottomLeftCommand<joystick>(offset=@(6,6)) {
    TouchscreenOnly {
        VirtualJoystick(radius=5)
    }
}

Touchscreen to Pointer

The TouchscreenVirtualPointer lets you use the touchscreen as a virtual mouse pointer. Swiping will move the pointer around the screen, and tapping will simulate a mouse click.

Manual Remapping

You may need to code more advanced remappings yourself. For example, if you would like the mouse pointer to be interpreted as a joystick, you can use the Pointer property to get the position of the mouse pointer, and then set the Joystick position yourself. This simulates joystick input directly from the mouse pointer.

Automatic Unification

Easel provides automatic remapping for some common input methods.

Click and Tap

If you use Click in your codebase but never Tap, Easel will automatically remap Tap to Click, as if you had inserted the following code at the top of your Main function:

ButtonRemap(Tap, Click)

If you use Tap in your codebase but never Click, Easel will automatically remap Click to Tap, as if you had inserted the following code at the top of your Main function:

ButtonRemap(Click, Tap)

Arrow Keys to Joystick

If you use Joystick in your codebase but never ArrowUp, ArrowDown, ArrowLeft or ArrowRight, Easel will automatically remap the arrow keys to Joystick, as if you had inserted the following code at the top of your Main function:

KeyboardVirtualJoystick(up=ArrowUp, left=ArrowLeft, down=ArrowDown, right=ArrowRight)

As soon as you refer to any one of the arrow keys in your codebase, this automatic remapping will be disabled and you will need to insert it manually.

WASD to Arrow Keys

If you use ArrowUp, ArrowDown, ArrowLeft or ArrowRight in your codebase but never KeyW, KeyA, KeyS or KeyD, Easel will automatically remap the WASD keys to the arrow keys, as if you had inserted the following code at the top of your Main function:

ButtonRemap(KeyW, ArrowUp)
ButtonRemap(KeyA, ArrowLeft)
ButtonRemap(KeyS, ArrowDown)
ButtonRemap(KeyD, ArrowRight)

As soon as you refer to any one of the WASD keys in your codebase, this automatic remapping will be disabled and you will need to insert it manually.