Controller Maps
One of the most unique and powerful features of Rewired is the Controller Map system. A Controller Map is a map of controller elements to Actions.
All maps are owned by a Player, so changes you make to one Player's maps don't affect the others even if it's assigned to the same controller.
You can create pre-defined controller maps for known controller types and controller templates and load the maps at runtime. Pre-defined maps for controllers are created in the Rewired Editor. For more information about how to create maps, see Creating and Editing Controller Maps.
If you create a user control assignment screen, the user can customize his controller maps for any joystick or controller. (See Creating a controller mapping screen for information.)
Maps stack so you can have as many maps for each controller as you need. For example: If you have multiple game modes such as Infantry, Tank, Airplane, you can have shared controls on one map, and mode-specific controls each on its own map. You can have even more maps as needed: A Menu map for when you're in the menus, a system map for controls like Save/Load and Quit, multiple maps for different players on the keyboard, etc. All the maps can co-exist simultaneously and can be enabled or disabled as needed, for example, when changing game modes.
A shared controller (the keyboard for example) can be mapped by any number of players with any number of maps.
Maps can be saved to XML. (See Saving and loading controller maps for more information.)
Creating and Editing Controller Maps:
Controller Maps are created and edited in the Rewired Editor.
Rewired Editor - Joystick Maps
Rewired Editor - Keyboard Maps
Rewired Editor - Mouse Maps
Rewired Editor - Custom Controller Maps
When a controller (excluding mouse and keyboard) is attached to the system, Rewired will attempt to identify that controller and load a map for it if you have created a pre-defined map that is compatible with that controller. (You can see the the current list of recognized controllers with extended support here.)
If you want your players to be able to plugin in a controller and have it "just work", you should create a joystick map for each controller you want to explicitly support. To save time, you can create a joystick map for a Controller Template that includes the controller you wish to support.
Joystick input returned by a Player is determined by the buttons and axes bound to Actions in one or more Joystick Maps assigned to a Player. When a button or axis is activated that is bound to an Action, the Player will return a value for that Action. You create these maps in the Rewired Input Manager and assign them to each Player and they will be loaded at start. You can also enable, disable, remove, add, load, and save Joystick Maps at runtime.
A joystick must both be assigned to a Player and have at least one Joystick Map with valid button/axis mappings before any input will be returned through the Player.
Keyboard input returned by a Player is determined by the keys bound to Actions in one or more Keyboard Maps assigned to a Player. When a key is pressed that is bound to an Action, the Player will return a value for that Action. You create these maps in the Rewired Input Manager and assign them to each Player and they will be loaded at start. You can also enable, disable, remove, add, load, and save Keyboard Maps at runtime.
Keyboards are different than Joysticks in that all Players share the keyboard. The keyboard cannot be assigned to or unassigned from a Player. Instead, all input from the keyboard is determined only by the Keyboard Maps assigned to each Player.
Mouse input returned by a Player is determined by the axes and buttons bound to Actions in one or more Mouse Maps assigned to a Player. When a button or axis is activated that is bound to an Action, the Player will return a value for that Action. You create these maps in the Rewired Input Manager and assign them to each Player and they will be loaded at start. You can also enable, disable, remove, add, load, and save Mouse Maps at runtime.
The mouse is similar to a Joystick in that it must be assigned to a Player before you can receive input from it. (This can be set in the Rewired Input Manager or through the player.controllers.hasMouse property.)
Controller Templates (Applies only to "Joysticks"):
A Controller Template represents a generalized controller layout that matches a number of supported controllers. When you create a map for a Template, any controller that is included in the Template will inherit that map automatically without the need for you to create a map specifically for that controller. For example, Rewired comes with a Dual Analog Gamepad Template. When you create a map for this Dual Analog Gamepad Template, you do not need to create individual maps specifically for any of the gamepads listed on this page because they are all covered by the Dual Analog Gamepad Template. This makes is much quicker to create pre-defined controller maps for a huge variety of controllers. Additionally, as more controllers are added to the Template in the future, the map you've already created will work with these new controllers as well.
If you have created a map in a Template but still want to make a map for a specific controller that is already part of the Template, just create the map for the specific controller and it will override the map defined in the Template.
Dual Analog Gamepad Template Element Naming:
The element names of the Dual Analog Gamepad Template are generalized because not all gamepads use the same names for all elements. Note that even though the Template element names are generalized, during gameplay, Rewired will use the controller's element's actual name instead of the generalized name. For example, an XBox 360 controller will report "A" instead of "Action Bottom Row 1" for the green button.
To avoid confusion when mapping the Dual Analog Gamepad Template, refer to the following element naming guide:
Controllers without Templates:
For the other controllers like flight sticks, steering wheels, light guns, etc. that do not currently have Templates, you have to create a map for each you want supported out of the box (meaning you don't want the user to manually have to map them before playing). If you don't create a map and you want the user to be able to use that controller, you'll have to make a remapping screen where the user can map his controls manually (see Creating a Controller Mapping Screen for more information).
For unrecognized controllers (controllers not listed here), Rewired will use the Unknown Controller map (whether you define a map for this or not). This is a generic map that is just a sequential list of axes and buttons, each corresponding to an axis and button on the controller in the order they are defined by the controller hardware. You can create a map for Unknown Controller if you like, but there's no way for you to know which axis or button corresponds to which element on the controller the user plugs in, so it's generally better just to leave it without a map and provide the user with a remapping screen where they can set up their unknown controllers how they see fit. See Creating a Controller Mapping Screen for more information.
Note that even though a controller is unknown to Rewired, XML mapping data can still be saved and loaded for these controllers. This means that if your users make custom control mappings for unrecognized controllers, they can still save their configurations and continue off with the same controller layouts after quitting and restarting the game. All saving and loading of controller data is up to the developer to implement. See Saving and Loading Controller Maps for more information.
How Input Is Processed by Controller Maps:
This diagram illustrates how input received from controllers gets mapped to Actions by the Player class. This diagram shows one possible example of a more advanced input scheme that you can create with Rewired.
The maps in this diagram are based on an input scheme which allows you to switch among various game modes. Only one game mode is active at any one time. The purpose for this is to allow for different control sets based on the current state of the game. For example, when the user opens a menu, the game mode would change to Menu and all maps with controls no longer valid in the Menu mode would be disabled. This is achieved through the use of Map Categories. See Enabling and Disabling Controller Maps for information on how to manage game mode switching.
- Gameplay Shared represent controls that are common to all gameplay modes: Infantry, Vehicle, and Airplane. This might include actions such as Fire.
- Vehicle represents controls specific to vehicle control.
- System represents system controls such as switching to Menu mode, Save, Load, Pause, etc.
In this example, the current game mode is Vehicle, so only maps in the categories Vehicle, Gameplay Shared, and System are currently active.
The two diagrams below show how input from a source controller element is processed by the Controller Maps in Player, returning a result to the calling script. Note that some controller maps are disabled, while others are enabled (disabled maps are greyed out). When a Controller Map is disabled, input is not passed through.
Enabling and Disabling Controller Maps
How To's - Enabling and Disabling Controller Maps
Loading Default Controller Maps
player.controllers.maps.LoadMap
player.controllers.maps.LoadDefaultMaps
Saving and Loading Controller Maps
How To's - Saving and Loading Controller Maps
See Also
API Reference - Joystick Map
API Reference - Keyboard Map
API Reference - Mouse Map
API Reference - Custom Controller Map