Controllers
A Controller is a virtual object that represents a physical or virtual controller of some type. Each Controller object contains a list of elements (buttons, axes, etc.) each of which represents a physical or virtual element on a controller. While you can access element input values directly from the Controller object, generally there is little reason to do this in Rewired because you normally access input through Rewired's Player-based, Action-driven input system instead.
Controller Types
The controller types in Rewired are:
Different controller types have some differences in the way they are used by Players to determine input values.
Joysticks
Joysticks are the most common Controller type and include most external non-mouse, non-keyboard USB or Bluetooth input peripherals that are connected to the system. (Certain exotic device types cannot be seen as Joysticks by Rewired.) Joysticks may come in various forms such as gamepads, flight sticks, steering wheels, balance boards, etc.
When a controller is attached to the system, Rewired will attempt to identify that controller and load a hardware definition. If a hardware definition is found, it will have human-readable element names, standardized axis directions, can have default mappings created for it in the Rewired Editor so your players can just connect and go, and even may be compatible with a Controller Template for even quicker mapping. Please see Supported Controllers for more information about recognized controllers. For all other controllers that are not recognized, see this for more information.
Joystick Assignment
In order to use a Joystick in Rewired's Player-based system, first the Player which should be in control of the Joystick must have that joystick assigned. (See Joystick Auto-Assignment.) Once the Joystick is assigned to the Player, Rewired will attempt to load any Joystick Maps for that Player from the defaults assigned to the Player in the Rewired Input Manager for the particular Joystick in question. The Player will then use that Joystick as one of its input sources when calculating the values of its input Actions provided the Player also has one or more Joystick Maps which map joystick elements to Actions. (See Controller Maps for more information.) A Player may have any number of Joysticks assigned, and Joysticks may be shared among any number of Players (this is rare.)
Joysticks can be assigned and removed from a Player via scripting (see here for more information), but it is more common to allow Rewired to automatically assign Joysticks to Players.
By default, Joysticks will be assigned to Players (excluding the System Player) automatically based on the Joystick Auto-Assignment settings in the Rewired Editor - Settings. These settings allow you to change various options for how Joysticks are auto-assigned to Players based on the needs of your game. Joystick auto-assignment can be disabled if you'd prefer to assign joysticks manually through scripting. Joystick auto-assignment can also be selectively disabled per player in the Rewired Editor and via scripting.
Note: One common issue that arises is when you connect multiple controllers and want a single Player to be able to use any of the connected controllers. Based on the default settings, Rewired will assign only one controller per-Player. In order to allow auto-assignment of multiple Joysticks to the same Player, Max Joysticks Per Player must be raised to a value greater than 1. All these settings are configurable and have descriptions as to their function.
Joystick Maps
Please see Controller Maps - Joystick Maps for more information.
Joystick Connect and Disconnect Events
You can detect when a Joystick is connected or disconnected through the use of events. See How To's - Receiving joystick connect and disconnect events for more information.
Checking for Joysticks at the Start of the Game
Please see How To's - Receiving Joystick connect and disconnect events for important information.
Please see How To's - Identifying recognized Joysticks.
Keyboard
The keyboard works similarly to Joysticks in many ways, but there are a few notable differences:
- At the present time, Rewired only supports a single, universal keyboard. Multiple keyboards attached to the system will simply act as a single keyboard.
- Keyboards do not send connect/disconnect events.
Keyboard Assignment
Similar to Joysticks, the Keyboard must be assigned to a Player before that Player can use it for input. However, the method of assigning the Keyboard to a Player differs from Joysticks.
To allow a Player access to the keyboard at the start of your game, you should ensure that "Assign Keyboard on Start" is checked in the Rewired Editor - Players page. (The keyboard is assigned to all Players on start by default.)
To assign the keyboard manually via scripting:
- player.controllers.hasKeyboard - Set to True to give the Player access to the keyboard.
Keyboard Maps
Like Joysticks, a Player will only be able to return input values for keyboard keys if the Player has one or more enabled Keyboard Maps assigned. Please see Controller Maps - Keyboard Maps for more information.
Mouse
The mouse also works similarly to Joysticks in many ways, but there are a few notable differences:
- At the present time, Rewired only supports a single, universal mouse. Multiple mice attached to the system will simply act as a single mouse.
- Mice do not send connect/disconnect events.
Mouse Assignment
Similar to Joysticks, the Mouse must be assigned to a Player before that Player can use it for input. However, the method of assigning the Mouse to a Player differs from Joysticks.
To allow a Player access to the mouse at the start of your game, you should check "Assign Mouse on Start" in the Rewired Editor - Players page.
To assign the mouse manually via scripting:
- player.controllers.hasMouse - Set to True to give the Player access to the mouse.
Mouse Maps
Like Joysticks and the Keyboard, a Player will only be able to return input values for mouse input if the Player has one or more enabled Mouse Maps assigned. Please see Controller Maps - Mouse Maps for more information.
Custom Controllers
Please see Custom Controllers for more information.
Enabling / Disabling
All Controllers can be enabled or disabled via scripting by setting the Controller.enabled property. Disabled Controllers do not generate any input.