user input

User Input

Everything in Open Surge is hackable, and user input is no different. You can modify the controls you use to play by modifying the input configuration files.

Input maps

The input configuration files specify a set of input maps. Each input map maps generic keys (such as: up, down, left, right, fire1, fire2, etc.) to concrete keys of the keyboard and to actual buttons of a joystick. Actions such as: jump, pause and look up are mapped to generic keys, which are then mapped to concrete user input informed by the configuration files.

The example below shows an input map named default, which is used to move the player. It is located at inputs/default.in

Note

Since Open Surge 0.5.2, the inputs/ folder stores input maps used for various purposes. In older versions of the engine, all input maps were specified in config/input.def

// File: inputs/default.in  
inputmap "default"
{
    /*

    We use the following conventions for the button names in the default mapping:

        up:     directional control
        right:  directional control
        down:   directional control
        left:   directional control

        fire1:  primary action button (jump | menus: confirm)
        fire2:  secondary action button (menus: cancel)
        fire3:  start, confirm, pause
        fire4:  back, cancel, quit

        fire5:  left shoulder button (left bumper)
        fire6:  right shoulder button (right bumper)
        fire7:  left thumbstick button
        fire8:  right thumbstick button

    */

    keyboard
    {
        up              KEY_UP
        right           KEY_RIGHT
        down            KEY_DOWN
        left            KEY_LEFT

        fire1           KEY_SPACE
        fire2           KEY_LCONTROL
        fire3           KEY_ENTER
        fire4           KEY_ESC

        fire5           KEY_LSHIFT
        fire6           KEY_RSHIFT
        fire7           KEY_NONE
        fire8           KEY_NONE
    }

    // default mapping for XInput controllers in Allegro
    // (standard gamepad based on the layout of the Xbox 360 controller)
    joystick 1
    {
        up              BUTTON_14                       // D-pad
        right           BUTTON_11
        down            BUTTON_13
        left            BUTTON_12

        fire1           BUTTON_1 | BUTTON_3 | BUTTON_4  // A, X, Y
        fire2           BUTTON_2                        // B
        fire3           BUTTON_10                       // START
        fire4           BUTTON_9                        // BACK / SELECT

        fire5           BUTTON_6                        // L1
        fire6           BUTTON_5                        // R1
        fire7           BUTTON_8                        // THUMBL
        fire8           BUTTON_7                        // THUMBR
    }
}

If you'd like to change the controls of the game, all you have to do is modify the default input map. Inside it, there are two sections: keyboard and joystick. Let's see how they work.

Modifying the controls

Configuring the keyboard

When modifying the keyboard section, you have to use valid key names. The following is a list of valid key names:

KEY_A ... KEY_Z,  
KEY_0 ... KEY_9,  
KEY_0_PAD ... KEY_9_PAD,  
KEY_F1 ... KEY_F12,  
  
KEY_ESC, KEY_TILDE, KEY_MINUS, KEY_EQUALS,  
KEY_BACKSPACE, KEY_TAB, KEY_OPENBRACE, KEY_CLOSEBRACE,  
KEY_ENTER, KEY_COLON, KEY_QUOTE, KEY_BACKSLASH,  
KEY_BACKSLASH2, KEY_COMMA, KEY_STOP, KEY_SLASH,  
KEY_SPACE,  
  
KEY_INSERT, KEY_DEL, KEY_HOME, KEY_END, KEY_PGUP,  
KEY_PGDN, KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN,  
  
KEY_SLASH_PAD, KEY_ASTERISK, KEY_MINUS_PAD,  
KEY_PLUS_PAD, KEY_DEL_PAD, KEY_ENTER_PAD,  
  
KEY_PRTSCR, KEY_PAUSE,  
  
KEY_ABNT_C1, KEY_YEN, KEY_KANA, KEY_CONVERT, KEY_NOCONVERT,  
KEY_AT, KEY_CIRCUMFLEX, KEY_COLON2, KEY_KANJI,  
  
KEY_LSHIFT, KEY_RSHIFT,  
KEY_LCONTROL, KEY_RCONTROL,  
KEY_ALT, KEY_ALTGR,  
KEY_LWIN, KEY_RWIN, KEY_MENU,  
KEY_SCRLOCK, KEY_NUMLOCK, KEY_CAPSLOCK  
  
KEY_EQUALS_PAD, KEY_BACKQUOTE, KEY_SEMICOLON,  
KEY_COMMAND (macOS)  
KEY_NONE (ignore the key)

Configuring the joystick

Different joysticks have different layouts. BUTTON_1, BUTTON_2, ..., BUTTON_32 are mapped to different buttons in different hardware and different operating systems. You may find out the layout of your particular device by using a specialized tool (such as jstest if using Linux), by searching online or by trial-and-error.

The default layout is generally appropriate. If you want to change it, the layouts below, for XInput controllers on Windows, may be of help:

Xbox controller	Playstation controller
Add 1 to buttons, so that 1=A, 2=B, 3=X, 4=Y, 9=BACK, 10=START as in the example	Layout contributed by tangengot

Level editor

It's also possible to modify the keys used in the level editor. These are controlled by the editorcmd input maps. It's generally a good idea to leave them as they are.

By default, you hit the F12 key to enter the level editor. You can alter this key by modifying the entry corresponding to KEY_F12 in the input map. The example below suggests modifying F12 to F6:

// level editor  
inputmap "editorcmd1"  
{  
    keyboard  
    {  
        up              KEY_UP     
        right           KEY_RIGHT  
        down            KEY_DOWN  
        left            KEY_LEFT      
        fire1           KEY_LCONTROL  
        fire2           KEY_RCONTROL  
        fire3           KEY_LSHIFT  
        fire4           KEY_RSHIFT  
        fire5           KEY_S   
        fire6           KEY_R    
        fire7           KEY_F1   
        fire8           KEY_F12 // <-- modify this to KEY_F6  
    }  
}