Difference between revisions of "User Input"

From Open Surge Engine Wiki
Jump to: navigation, search
(Created User Input)
 
(Configuring the joystick)
 
(11 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.
  
== Modifying the controls ==
+
== 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 in the keyboard and to actual buttons in 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 example below shows an input map named '''default''', which is used to move the player:
+
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.
  
// File: config/input.def
+
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>.
+
 
// this inputmap is used by Open Surge by default.
+
  // File: inputs/default.in
// 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 26: Line 24:
 
         fire7          KEY_NONE      // available
 
         fire7          KEY_NONE      // available
 
         fire8          KEY_NONE      // available
 
         fire8          KEY_NONE      // available
     }                                                                                                                                                                          
+
     }
                                                                                                                                                                               
+
 
     joystick 0                                                                                                                                                                
+
    // default mapping for XInput controllers in Allegro
     {                                                                                                                                                                          
+
     joystick 0
         fire1          BUTTON_1       // fire1 (jump) is the first button of the joystick                                                                                     
+
     {
         fire2          BUTTON_2      // fire2 (switch character) is the second button of the joystick                                                                       
+
        up              BUTTON_14      // d-pad
         fire3          BUTTON_3      // and so on...                                                                                                                         
+
        right          BUTTON_11
         fire4          BUTTON_4                                                                                                                                               
+
        down            BUTTON_13
         fire5          BUTTON_5                                                                                                                                               
+
        left            BUTTON_12
         fire6          BUTTON_6                                                                                                                                               
+
         fire1          BUTTON_1 | BUTTON_2 | BUTTON_3 | BUTTON_4  // jump
         fire7          BUTTON_7                                                                                                                                               
+
         fire2          BUTTON_5 | BUTTON_6  // switch character
         fire8          BUTTON_8                                                                                                                                               
+
         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. You should leave the joystick section as it is. However, you may modify the keyboard section to suit your preferences.
+
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 ==
 +
 
 +
=== 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 ([[Special:UserLogin|sign up]] to contribute).
  
When modifying the keyboard section, the following is a list of valid key names:
+
Click on a picture to expand:
  
//      KEY_A ... KEY_Z,
+
<gallery widths=256px heights=256px>
//      KEY_0 ... KEY_9,
+
File:Controller-outline-tangengot.png|Playstation controller (clone). Layout contributed by tangengot.
//      KEY_0_PAD ... KEY_9_PAD,
+
File:Xinput-controller-mapping-code.png|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.
//      KEY_F1 ... KEY_F12,
+
</gallery>
//
+
//      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 (Mac OS X)
+
//      KEY_NONE (ignore the key)
+
//
+
  
== Modifying the level editor ==
+
=== 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.
 
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.
Line 103: Line 125:
 
  }
 
  }
  
 +
[[Category:Users]]
 
[[Category:MODs]]
 
[[Category:MODs]]
[[Category:Misc]]
 

Latest revision as of 00:09, 22 September 2022

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

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

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