Difference between revisions of "User Input"

From Open Surge Engine Wiki
Jump to: navigation, search
m (Input maps)
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
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 file. This is a text file located at '''config/input.def'''.
+
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 ==
 
== Input maps ==
  
The input configuration file specifies a set of '''input maps'''. Each input map maps generic keys (such as: ''up'', ''down'', ''left'', ''right'', ''fire1'', ''fire2'', etc.) to concrete keys of a 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 file.
+
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:
+
The example below shows an input map named '''default''', which is used to move the player. It is located at '''inputs/default.in'''<ref>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</ref>.
  
  // File: config/input.def
+
  // File: inputs/default.in
+
// this inputmap is used by Open Surge by default.
+
// this will accept commands issued from the keyboard and from the first joystick (joystick 0), if it is connected.
+
// DO NOT ERASE THIS INPUTMAP!
+
 
  inputmap "default"
 
  inputmap "default"
 
  {
 
  {
Line 28: Line 24:
 
         fire7          KEY_NONE      // available
 
         fire7          KEY_NONE      // available
 
         fire8          KEY_NONE      // available
 
         fire8          KEY_NONE      // available
     }                                                                                                                                                                          
+
     }
                                                                                                                                                                               
+
 
     joystick 0                                                                                                                                                                
+
     joystick 0
     {                                                                                                                                                                          
+
     {
         fire1          BUTTON_3       // jump
+
         fire1          BUTTON_2 | BUTTON_3 | BUTTON_4  // jump
         fire2          BUTTON_4      // switch character
+
         fire2          BUTTON_5 | BUTTON_6  // switch character
         fire3          BUTTON_2      // pause, confirm
+
         fire3          BUTTON_10    // pause, confirm
         fire4          BUTTON_1       // quit, cancel
+
         fire4          BUTTON_1     // quit, cancel
         fire5          BUTTON_5                                                                                                                                               
+
         fire5          BUTTON_NONE  // available
         fire6          BUTTON_6                                                                                                                                               
+
         fire6          BUTTON_NONE  // available
         fire7          BUTTON_7                                                                                                                                               
+
         fire7          BUTTON_NONE  // available
         fire8          BUTTON_8                                                                                                                                               
+
         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.
+
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.
 +
 
 +
<references/>
  
 
== Modifying the controls ==
 
== Modifying the controls ==

Revision as of 21:04, 19 January 2021

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[1].

// 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
    }
 
    joystick 0
    {
        fire1           BUTTON_2 | BUTTON_3 | BUTTON_4  // jump
        fire2           BUTTON_5 | BUTTON_6  // switch character
        fire3           BUTTON_10    // pause, confirm
        fire4           BUTTON_1     // 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.

  1. 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

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. 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:

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