Players
Rewired features a player-centric input system. This means that generally all input is handled through the Player and not the controllers. You simply call player.GetAxis, player.GetButton, etc. or register to receive input events with player.AddInputEventDelegate to get access to all input regardless of the input sources. For example, you may need to respond to input from the keyboard, mouse, any number of joysticks, and any number of Custom Controllers. This is handled simply by assigning the controllers and the appropriate maps to the Player and then getting the input directly from the Player. The input you receive from the Player is a combination of input received from all the assigned controllers. Additionally, joysticks can (optionally) be intelligently auto-assigned to Players on connect and disconnect, so you don't have to worry about what controllers each Player owns. Instead, you simply get input for the specific Action you're looking for and Rewired handles the rest.
It may help to think of a Player as a "controller container". In other words, the Player can contain any number of controllers and controller maps. When you get input from the Player, you're really getting input from any controller owned by the Player that has an enabled Action -> Element mapping.
Creating / Editing Players
Players are created at runtime by the Input Manager in the scene. You must define Players in the Rewired Editor in order for them to be created at runtime.
Accessing Players
The ReInput.players property has methods to get access to a Player by id or name or to get a list of all Players. It's recommended you store a reference to the Player in Awake and maintain that reference for the duration of the game. See Getting a Player for an example of how to get a Player.
The System player exists as an option for handling system Actions such as Save, Load, etc. You can assign controllers and maps to the System player just as with any other player. Joysticks are never auto-assigned to the System player, but you can assign them manually to the System player through scripting.
Getting Input
In Rewired, you generally get input from the Player, not the controllers themselves. Please see How To's - Getting Input for more information.
Players and Controller Maps
Controller Maps are what associates controller elements to Actions. As Rewired is a player-centric input system, controller maps aren't stored in the controller, but rather in the Player. This has the benefit of allowing you to share controllers among as many Players as you want while each maintains its own separate set of Action mappings.
The Player class contains many methods for getting, adding, and removing all types of controller maps. (Access these methods through the Player.controllers.maps helper object.) Additionally, assignment conflict checking and saving/loading maps is handled through the Player class.
Even if a controller is assigned to a Player, if no maps are assigned, no input will be possible. You should define starting maps for joysticks, the keyboard, and the mouse for each Player in the Rewired Editor. You can also load and assign maps during runtime through scripting via the Player class.
A Player is essentially a container for controllers and Controller Maps. The Controller Maps contained in Player provide a means to associate Actions to controller elements (button, key, axis, etc.). There are some slight differences between how the different types of controllers are handled by the Player.
Rewired currently has 4 types of Controller classes:
- Joystick (a device attached to the system that is not a keyboard or mouse.)
- Keyboard
- Mouse
- Custom Controller
Before a Player can return input for a Joystick, that joystick must first be assigned to the Player. The joystick must be added to the Player's list of joysticks before it can receive input from that device. A joystick may be assigned to multiple Players and shared if desired (this would be rare).
By default, Rewired's Joystick Auto-Assignment system is enabled in the Rewired Input Manager. This ensures that each Player is assigned one joystick when it is attached to the system based on rules set in the Rewired Input Manager - Settings page. You may disable the auto-assignment system if you have special needs that are not covered by its options. See How To's - Assigning Joysticks to Players for information on how to assign Joysticks manually.
For input to be returned in a Player from a Joystick, all of the following must be true:
- The Joystick must be assigned to the Player.
- The Player must have at least one enabled Joystick Map applicable to that joystick.
- The Joystick Map must bind at least one joystick element to an Action.
Do not be confused: The fact that a Player "has a Joystick Map" in the Rewired Input Manager is not the same thing as the joystick being assigned to that Player. Maps are entirely separate from joystick assignment and do not influence what joysticks (if any) will be assigned to a Player by the joystick auto-assignment system. Joystick assignment involves adding the Joystick class object to the Player. Once the Joystick is assigned, Rewired will load the Joystick Maps for that particular Joystick in the Player (if one or more applicable Joystick Maps were created and assigned to the Player in the Rewired Editor) and then the Joystick Maps will perform the function of mapping Actions to the elements on that Joystick. If a joystick is assigned to a Player but no matching Joystick Maps are found, that Joystick will not contribute any input in that Player.
In Rewired, the keyboard is a shared controller. Similar to Joysticks, the keyboard must also be assigned to the Player(s) before it will return any input. This can be set at start in the Rewired Input Manager - Players page, or set via scripting using the player.controllers.hasKeyboard property. By default, the keyboard is assigned to all Players on start unless disabled in the Rewired Input Manager.
Just like Joysticks, the keyboard will only return input in a Player if the Player has at least one Keyboard Map that associates some Actions to keys.
Similar to Joysticks, the mouse must also be assigned to the Player(s) before it will return any input. This can be set at start in the Rewired Input Manager - Players page, or set via scripting using the player.controllers.hasMouse property. The mouse may be shared by multiple Players if desired.
Just like Joysticks and the Keyboard, the mouse will only return input in a Player if the Player has at least one Mouse Map that associates some Actions to mouse buttons and axes.
Custom Controllers are very similar to Joysticks in treatment except for the fact that they are never disconnected from the system and are always available. The same rules apply -- the Custom Controller must be assigned to a Player and have one or more valid Custom Controller Maps to return any input value.
See Also