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.

// File: inputs/default.in
inputmap "default"
{
    keyboard
    {
        up              KEY_UP         // up
        right           KEY_RIGHT      // right
        down            KEY_DOWN       // down
        left            KEY_LEFT       // left
        fire1           KEY_SPACE      // jump
        fire2           KEY_LCONTROL   // switch character
        fire3           KEY_ENTER      // pause, confirm
        fire4           KEY_ESC        // quit, cancel
        fire5           KEY_NONE       // available
        fire6           KEY_NONE       // available
        fire7           KEY_NONE       // available
        fire8           KEY_NONE       // available
    }
 
    // default mapping for XInput controllers in Allegro
    joystick 0
    {
        up              BUTTON_14      // d-pad
        right           BUTTON_11
        down            BUTTON_13
        left            BUTTON_12
        fire1           BUTTON_1 | BUTTON_2 | BUTTON_3 | BUTTON_4  // jump
        fire2           BUTTON_5 | BUTTON_6   // switch character
        fire3           BUTTON_10      // start, pause, confirm
        fire4           BUTTON_9       // back, quit, cancel
        fire5           BUTTON_NONE    // available
        fire6           BUTTON_NONE    // available
        fire7           BUTTON_NONE    // available
        fire8           BUTTON_NONE    // available
    }
}

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, BUTTON2, ..., 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 gallery below may be of help. Please contribute with your particular joystick layout if it's not listed (sign up to contribute).

Click on a picture to expand:

• Error creating thumbnail: File missing

  Playstation controller (clone). Layout contributed by tangengot.

• Error creating thumbnail: File missing

  Xbox controller on Windows. Add 1 to buttons, so that 1=A, 2=B, 3=X, 4=Y, 9=BACK, 10=START... FIXME: upload schematic picture of a controller.

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
    }
}