Control Mapper
Control Mapper is a customizable, responsive control mapping system included with Rewired that you can use in your games. This system provides complete controller remapping including keyboard, mouse, and joystick support, axis calibration, joystick and mouse sensitivity, single or multiple players, controller maps, and much more. Control Mapper can be fully controlled with keyboard, mouse, joystick, and/or touch controls. Control Mapper uses Unity's new GUI system and therefore requires Unity 4.6+.
Control Mapper has many options which you can customize to fit your game's needs:
- Optional display of Players for multiplayer games.
- Optional multiple controllers per-player.
- Optional Input Behavior customization.
- Optional Map Category display.
- Customizable list of Actions to show per category.
- Optional display of Action category names.
- Optional Keyboard, Mouse, and Controller support.
- Choose the number of alternate fields per controller type.
- Customizable theme settings for changing colors and button styles.
- Customizable language settings for changing button and window labels and messages.
- Menu control by your choice of Rewired Player(s).
- Customizable Actions for opening, closing, and canceling.
Example screen showing multiple players, multiple controllers per-player, sensitivity settings, multiple map categories, with keyboard, mouse, and controller support.
Example screen showing a view of a simple 1-player game with only one map category, one controller, keyboard support with 1 mapping per keyboard key, and using a different theme.
The information that follows assumes you are familiar with working with input in Rewired. If you are not, read through the documentation first. Step by step basics of how to use Rewired will not be covered here.
Setup
The Control Mapper is a prefab which you can drag into your scene and use. This prefab includes the Canvas which will be used to render the UI elements.
To add Control Mapper to your scene, you can add it from either of the following menus:
- Window -> Rewired -> Create -> UI -> Control Mapper
- Game Object -> Create Other -> Rewired -> UI -> Control Mapper
Or you can add it as a live prefab by dragging it in from the project view. (Note: If using a live prefab, do not commit any changes to the prefab source or they will be overwritten the next time you update Rewired. You can, however, make a new prefab of your own out if it and modify that.)
Once the Control Mapper is in your scene, you can customize many options by changing settings in the inspector. The first thing you must do is to link your Rewired Input Manager object to the Control Mapper object in the Rewired Input Manager field in the inspector. Once you have done this, you can proceed to customize settings.
See Inspector Options for more details about the Control Mapper inspector settings.
RewiredStandaloneInputModule
Control of the UI is handled by the RewiredStandaloneInputModule. This component must be added to the EventSystem in the scene and the default StandaloneInputModule must be disabled or removed.
You can either create a normal Unity Event System and replace the Standalone Input Module with the Rewired Standalone Input Module component or you can create a Rewired Event System from either of the menu items:
- GameObject -> Create Other -> Rewired -> UI -> Rewired Event System
- Window -> Rewired -> Create -> UI -> Rewired Event System
Four Actions must be set up in the Rewired Input Manager and the RewiredStandaloneInputModule in order to control the UI. These four Actions must have names that match exactly in both the Rewired Input Manager and the RewiredStandaloneInputModule.
- Horizontal Axis - The Action that will control Left/Right movement in the UI.
- Vertical Axis - The Action that will control Up/Down movement in the UI.
- Submit - The Action that submits a button.
- Cancel - The Action that cancels.
The actual names you use are up to you. Of course these Actions must also be assigned to one or more keyboard or joystick maps and assigned to a Player to be functional.
NOTE: It is HIGHLY recommended that you create unique menu-only Actions for these UI controls in a separate controller map category from your game Actions. If you use your in-game actions such as "Move Horizonal" or "Jump" for these UI controls, you run the risk of allowing the user to render the UI unusable because they removed an assignment for one of these game Actions which was also controlling the UI.
The settings in the RewiredStandaloneInputModule will determine which Players can control the UI. If you check "Use All Rewired Game Players", all Players besides the System Player that have a map configured with these UI Actions will be able to control the UI. If you check "Use Rewired System Player", the same will be true for the System Player. If instead you only want specific Players to control the UI, you can set these Player Ids individually.
If the UI control speed with a Joystick seems too slow or fast, adjust the "Input Actions Per Second" setting.
Rewired Input Manager settings
This image shows the 4 actions that have been set up for controlling the UI.
Recommended UI control scheme
Rewired and the Control Mapper system are very flexible. As such, every possible situation cannot be "automagically" taken care of for you. You need to spend some time to plan and understand your control scheme.
It is possible to create a situation where the user is able to break his ability to control the UI by unassigning necessary Actions such as the Submit button. With a mouse available on the system, this would not be a problem as it is not dependent on Actions, but on platforms without mouse or touch input to fall back on in the case of user error, you need to consider these situations. It may not be advisable to allow users to remap everything.
Keyboard:
It is generally a good idea to have fixed keyboard UI controls that the user cannot remap, such as the arrow keys for navigation and the enter keys for submit. These can either be owned by the System Player or any/all of your Players. You can set up a separate Map Category for these protected UI controls and protect them from being replaced during reassignment excluding this Map Category from conflict checking in all your other Map Categories in the Rewired Input Manager. Also, do not add this Map Category to the list of assignable maps in the Control Mapper inspector options.
Joysticks:
Recognized joysticks should have a map created for UI control if you wish to support joystick UI navigation. If you want the user to be able to remap these menu controls, it is recommended that you create yet another separate Map Category for these user-configurable joystick controls. By making a separate Map Category for these controls, you are able to allow the user to remap these joystick controls while still keeping the keyboard controls protected. Conflict checking settings for the Map Category should exclude all game controls and vice versa if you want the user to be able to map the same elements in different categories without being warned about conflicts.
Unknown Controllers:
It is recommended that you create a map for the Unknown Controller in the UI control category. This way, if a user attaches a controller Rewired does not recognize, they should still be able to control the UI reasonably well.
There is no way to know what axes or buttons will actually be available on these controllers, but you can make some basic assumptions that should allow most controllers to control the UI.
- Axis 0: Map to your "UIHorizontal" Action. (Axis 0 is almost always the horizontal axis on the first joystick)
- Axis 1: Map to your "UIVertical" Action and Invert this axis. (Axis 1 is almost always the vertical axis on the first joystick and is always inverted.)
- Button 0: Map to your "UISubmit" Action.
- Button 1: Map to your "UICancel" Action.
Of course, the above are only recommendations. You can set up your control scheme however you decide.
Saving and Loading User Data
Saving and loading of user data is handled by the UserDataStore component on the Rewired Input Manager. By default, this component does not exist on the Rewired Input Manager. Without this component, data will never be saved or loaded and will not persist between game sessions.
If you add a UserDataStore derived component to the Rewired Input Manager, it will be used to save and load data. Rewired includes a UserDataStore_PlayerPrefs component which will use PlayerPrefs to save the controller data. Simply add this component to your Rewired Input Manager and data will be loaded and saved as needed.
If you don't want to use PlayerPrefs, you can create your own data storage system using UserDataStore. See User Data Store for more information.
Conflict Checking
Rewired's conflict checking system tries to prevent the user from cross-assigning his controls. For example, if the user tries to assign the key A to "Fire" after it has already been assigned to "Jump", a warning will be displayed asking the user whether they would like to replace the assignment or (optionally) add the new conflicting assignment anyway. (See Inspector Options for the option to allow conflicting assignments.)
The Rewired Input Manager has many options for controlling conflict checking. These are handled on a Map Category basis. You are able to set which Map Categories perform conflict checking against other Map Categories. This conflict checking is configurable independently each way, so if you want one Map Category to conflict check against another but not vice versa, this is possible. Additionally, this allows you to have categories such as "Common", "Infantry Mode", "Tank Mode", "Airplane Mode" and have all these maps configurable by the user without having conflict checking between mutually-exclusive Map Categories such as "Tank Mode" and "Infantry Mode" while all still conflict checking against "Common" and vice versa. See Rewired Editor - Map Categories for more information.
Protected controls
You may want to have certain controls protected from re-assignment. One example of this might be the ESC key if you use that for some important system control and you don't want the user removing this assignment by trying to assign ESC to another Action. In Rewired, protection of controls is handled on the Map Category level. To protect a set of System controls from ever being re-assigned, uncheck the "User Assignable" checkbox in the Map Category that contains the Action in the Rewired Input Manager.
- Map Category -> User Assignable
Note that not all "User Assignable" checkboxes in the Rewired Input Manager are equal. The "User Assignable" checkbox also appears in Action Categories and Actions themselves, but only the Map Category "User Assignable" checkbox is used in determining protected controls.
Theming
Control Mapper comes with a basic theming system to allow you to change colors, fonts, and sprites by simply editing a theme file.
The process:
- Make a copy of the DefaultTheme file in the ControlMapper/Themes directory.
- Move this copy to somewhere inside your project (outside the Rewired folder).
- On the Control Mapper game object in your scene, assign the new theme file you created to the Theme field in the inspector.
Editing the theme:
Edit the theme file in the inspector. There is no user-friendly inspector for this theming process, but the names of the fields should be self-explanatory. Make your changes and they will show up when you launch the game. (Theme setting changes can not be viewed in real-time in the editor.)
These theme options just mirror the various options available on Unity UI components such as Image, Button, Slider, etc. If you don't understand what these options mean, see the Unity UI documentation on these components.
Language
Control Mapper has a basic language system which you can use to customize button and section labels, window titles, and more.
The process:
- Make a copy of the DefaultEnglish file in the ControlMapper/Languages directory.
- Move this copy to somewhere inside your project (outside the Rewired folder).
- On the Control Mapper game object in your scene, assign the new language file you created to the Language field in the inspector.
Editing the language:
Edit the language file in the inspector. There is no user-friendly inspector for this language editing process, but the names of the fields should be self-explanatory. Make your changes and they will show up when you launch the game. (Language setting changes can not be viewed in real-time in the editor.)
Misc Notes
Opening and closing the screen
The easiest way to control the screen is by assigning Actions in the Screen Control Actions section of the inspector.
Another way is by using a Unity UI button and assigning ControlMapper.Open() to the OnClick event.
You can also control the screen through scripting:
- Opening the screen: ControlMapper.Open();
- Closing the screen: ControlMapper.Close();
Control Mapper also has events for when the screen is opened and closed should you need that information.
Changing settings through scripting
Certain Control Mapper options can be changed through scripting, but not in real-time while the screen is open. This can be useful should you need to make changes based on some criteria such as platform-specific settings. For example, before initializing the Control Mapper (before opening it), you could disable keyboard support. This may be useful if you're publishing your game on a platform that doesn't support keyboards, but you don't want to create a separate Control Mapper for this.
Screen scale
Scale of the Control Mapper by default is handled by the Canvas Scaler Fitter component on the Canvas below the main Control Mapper game object. The Canvas Scaler Fitter component controls the scale settings for the display based on the current aspect ratio of the screen. Breakpoints have been predefined to help keep the display usable at various screen aspect ratios.
Inspector Options
Many configuration options are available through the inspector. Most options have tool-tip help.
Rewired Input Manager
You must link a Rewired Input Manager to this field in the inspector. All input data will be read from the Rewired Input Manager linked here.
Screen Options
Various options for the control mapper screen.
| Open On Start | Open the control mapping screen immediately on start. Mainly used for testing. |
Player Options
Various options for Players.
| Show Players | Display a selectable list of Players. If your game only supports 1 player, you can disable this. |
| Show Players Group Label | Show the label for the Players button group? |
Controller Options
Various options for controllers.
| Show Controller | Display the Controller column for input mapping. |
| Max Controllers Per Player | The maximum number of controllers allowed to be assigned to a Player. If set to any value other than 1, a selectable list of currently-assigned controller will be displayed to the user. [0 = infinite] This field is only displayed if "Auto-Assign Joysticks" is disabled in the Rewired Input Manager -> Settings. In this case, the max number of controllers displayed per player is equal to the "Max Joysticks Per Player" setting in the Rewired Input Manager -> Settings. |
| Controller Input Field Count | The number of input fields to display for joysticks. If you want to support alternate mappings on the same device, set this to 2 or more. |
| Show Assigned Controllers | Show the Assigned Controllers group? If joystick auto-assignment is enabled in the Rewired Input Manager and the max joysticks per player is set to any value other than 1, the Assigned Controllers group will always be displayed. |
| Show Assigned Controllers Group Label | Show the label for the Assigned Controllers button group? |
| Show Controller Group Label | Show the label for the Controller button group? |
| Show Controller Name Label | Show the label for the current controller name? |
Keyboard Options
Various options for the Keyboard.
| Show Keyboard | Display the Keyboard column for input mapping. |
| Keyboard Input Field Count | The number of input fields to display for the keyboard. If you want to support alternate mappings on the same device, set this to 2 or more. |
Mouse Options
Various options for the Mouse.
| Show Mouse | Display the Mouse column for input mapping. |
| Mouse Input Field Count | The number of input fields to display for the mouse. If you want to support alternate mappings on the same device, set this to 2 or more. |
| Ignore Mouse X Axis Assignment | If checked, mouse X-axis movement will always be ignored during input assignment. Check this if you don't want the horizontal mouse axis to be user-assignable to any Actions. |
| Ignore Mouse Y Axis Assignment | If checked, mouse Y-axis movement will always be ignored during input assignment. Check this if you don't want the vertical mouse axis to be user-assignable to any Actions. |
Map Categories and Actions
Options for the Map Categories and Actions displayed to the user for input mapping.
You can define a list of Map Categories to be shown to the user for remapping. You can choose to show one or multiple Map Categories. If you define multiple Map Categories here, a new row of buttons will be shown that will allow the user to select a Map Category for which to create input assignments.
You must define a list of assignable Actions to displayed to the user for each Map Category. You can choose to show the user a list of all user-assignable Actions contained in an one or more Action Categories or a customized list of individual Actions.
| Show Action Category Labels | Display section labels for each Action Category in the input field grid. Only applies if Action Categories are used to display the Action list. |
| Show Map Categories Group Label | Show the label for the Map Categories button group? |
| Map Category | The Map Category that will be displayed to the user for mapping. |
| Action List Mode | Choose whether you want to list Actions to display for this Map Category by individual Action or by all the Actions in an Action Category. |
| Action Categories | List each Action Category you want to be displayed for this map category. This will list all user-assignable Actions in that category allowing the user to make assignments for each of these Actions. |
| Actions | List each Action you want to be displayed for this map category. This will allow the user to make assignments for each of these Actions. |
Default Layouts
The controller map Layout that will be shown to the user. This remapping system only supports a single fixed Layout per controller type.
This Layout defined here is only a suggestion. If a ControllerMap with this Layout is found in the Player, it will be used. Otherwise, the first ControllerMap in the correct category found will be used regardless of the Layout id.
| Keyboard Map Default Layout | The Layout of the Keyboard Maps to be displayed. |
| Mouse Map Default Layout | The Layout of the Mouse Maps to be displayed. |
| Joystick Map Default Layout | The Layout of the Joystick Maps to be displayed. |
Input Behaviors
Settings for user-modifiable Input Behaviors. Only certain properties are supported.
You can define a list of Input Behaviors to be shown to the user for modification. If enabled, new controls will be displayed so the user can modify these settings. This is useful if you need to allow the user to set certain per-Action sensitivity levels such as Mouse Look Sensitivity.
| Show Input Behavior Settings | If checked, controls will be displayed which will allow the user to customize certain Input Behavior settings. |
| Show Settings Group Label | Show the label for the Settings button group? |
| Input Behavior | The Input Behavior that will be displayed to the user for modification. |
| Label Language Key | If set to a non-blank value, this key will be used to look up the name in Language to be displayed as the title for the Input Behavior control set. Otherwise, the name field of the InputBehavior will be used. |
| Joystick Axis Sensitivity Label Language Key | If set to a non-blank value, this name will be displayed above the individual slider control. Otherwise, no name will be displayed. |
| Show Joystick Axis Sensitivity | If checked, a slider will be displayed so the user can change this value. |
| Joystick Axis Sensitivity Icon | The icon to display next to the slider. Set to none for no icon. |
| Joystick Axis Sensitivity Min | Minimum value the user is allowed to set for this property. |
| Joystick Axis Sensitivity Max | Maximum value the user is allowed to set for this property. |
| Mouse XY Axis Sensitivity Label Language Key | If set to a non-blank value, this name will be displayed above the individual slider control. Otherwise, no name will be displayed. |
| Show Mouse XY Axis Sensitivity | If checked, a slider will be displayed so the user can change this value. |
| Mouse XY Axis Sensitivity Icon | The icon to display next to the slider. Set to none for no icon. |
| Mouse XY Axis Sensitivity Min | Minimum value the user is allowed to set for this property. |
| Mouse XY Axis Sensitivity Max | Maximum value the user is allowed to set for this property. |
Element Assignment Options
Various options for the element assignment.
| Allow Element Assignment Conflicts | If enabled, when an element assignment conflict is found, an option will be displayed that allows the user to make the conflicting assignment anyway. |
Timer Options
Various timer options.
| Pre Input Assignment Timeout | The time in seconds the user has to press an element on a controller while waiting for axes to be centered before assigning input. |
| Input Assignment Timeout | The time in seconds the user has to press an element on a controller when assigning input. If this time elapses with no user input on the target controller, the assignment will be canceled. |
| Controller Assignment Timeout | The time in seconds the user has to press an element on a controller when assigning a controller to a Player. If this time elapses with no user input a controller, the assignment will be canceled. |
| Axis Calibration Timeout | The time in seconds the user has to press an element on a controller during calibration. |
Input Grid Layout Options
Dimensions for various elements in the input grid.
| Action Label Width | The width in relative pixels of the Action label column. |
| Keyboard Col Max Width | The width in relative pixels of the Keyboard column. |
| Mouse Col Max Width | The width in relative pixels of the Mouse column. |
| Controller Col Max Width | The width in relative pixels of the Controller column. |
| Input Row Height | The height in relative pixels of the input grid button rows. |
| Input Column Spacing | The width in relative pixels of spacing between columns. |
| Input Row Category Spacing | The height in relative pixels of the space between Action Category sections. Only applicable if Show Action Category Labels is checked. |
| Invert Toggle Width | The width in relative pixels of the invert toggle buttons. |
Popup Window Options
Various options for popup windows.
| Default Window Width | |
| Default Window Height |
|
Actions that control the mapping screen.
| Screen Open Action | An Action that when activated will close the main screen as long as no popup windows are open. |
| Screen Close Action | An Action that when activated will open the main screen if it is closed. |
| Screen Toggle Action | An Action that when activated will alternately close or open the main screen as long as no popup windows are open. |
| Universal Cancel Action | An Action that when activated will cancel and close any open popup window. Use with care because the element assigned to this Action can never be mapped by the user (because it would just cancel his assignment). |
| Universal Cancel Closes Screen | If enabled, Universal Cancel will also close the main screen if pressed when no windows are open. |
Theme Options
UI theme options.
| Use Theme Settings | If enabled, UI elements will be themed based on the settings in Theme Settings. |
| Theme Settings | Must be assigned a ThemeSettings object. Used to theme UI elements. |
Language Options
Language options.
| Language | Must be assigned a LanguageData object. Used to retrieve language entries for UI elements. |
Advanced Settings
These are internal settings like references to GameObject and Prefabs. You should not have to change these.