User Data Store

The UserDataStore component can be used to easily save and load user control configuration data from Rewired. This component is a base class which you can extend to support any data storage format you like.

Rewired also comes with a UserDataStore_PlayerPrefs component complete with source code which you can use as a template for designing your own custom data storage system using any storage medium (database, binary files, etc.). The UserDataStore_PlayerPrefs component can also be used directly in your game and will store your user data in Unity's PlayerPrefs.

Usage

Just add a component derived from UserDataStore (such as UserDataStore_PlayerPrefs) to your Rewired Input Manager Game Object. When the Rewired Input Manager initializes, it will automatically initialize the UserDataStore component and make a reference to it accessible via the ReInput.UserDataStore property.

• To save all user data: ReInput.userDataStore.Save()
• To load all user data: ReInput.userDataStore.Load()
• UserDataStore API reference

If you need to add any custom members to your UserDataStore-based class, you can do so and simply cast the returned IUserDataStore object from ReInput.userDataStore to your concrete class and then access your custom members.

// A custom class that extends UserDataStore
public class MyUserDataStore : Rewired.Data.UserDataStore {
    // Implement all required methods...
    
    public void MyCustomMethod() {
        // do something
    }
}

// In your code that calls your custom method
(ReInuput.userDataStore as MyUserDataStore).MyCustomMethod(); // cast to concrete class and call the custom method

UserDataStore_PlayerPrefs

This is a user data storage component that uses Unity's PlayerPrefs class for storing data. Whenever a controller is attached, if any data has been saved before for that controller, it will be loaded from PlayerPrefs. If the user has customized his control mappings, these will be loaded on a per-player, per-controller basis. Controller calibration settings and customized Input Behavior settings will also be loaded. Data will be saved manually when Save() is called or automatically when a controller is disconnected from the system.

If "Load Data on Start" is checked in the inspector, all controller data will be loaded at the beginning of the session. This is useful if you want the player's last settings to be loaded automatically for any controllers already attached to the system at runtime.

Data that is saved and loaded

Saved data does not include:

1. The current list of what Controller Maps are loaded in the Player.
2. The enabled state of these Controller Maps.

UserDataStore_PlayerPrefs saves:

1. Joystick calibration settings for attached Joysticks.
2. Input Behavior settings for each Player.
3. Bindings for each Controller Map found in each Player.
4. Optionally, controller assignments for mouse, keyboard, and joysticks for each Player.

UserDataStore_PlayerPrefs loads:

1. Joystick calibration settings for attached Joysticks.
2. Input Behavior settings for each Player.
3. All saved Controller Maps found for each Player.
4. Optionally, controller assignments for mouse, keyboard, and joysticks for each Player.

When does UserDataStore_PlayerPrefs automatically load data:

1. If "Load Data on Start" is enabled, on Awake.
2. When a Joystick is connected. This only applies if Joystick Auto Assignment is enabled and the Joystick is assigned to the Player.

When does UserDataStore_PlayerPrefs automatically save data:

1. If one or more of "Load Joystick Assignments", "Load Keyboard Assignments", or "Load Mouse Assignments" and "Load Data on Start" are enabled, on Awake, controller assignments will be saved after data has been loaded.
2. When a Joystick is disconnected.

Warning:

Loading saved data is subject to the normal functioning of the Controller Map system. As is documented, Joystick Maps cannot exist in a Player unless that Joystick is connected and assigned to that Player at the time of loading. That means, if saved user data is loaded when a Joystick is not currently assigned to the Player, no saved data will be loaded for that Joystick. Only if the Joystick is first assigned to the Player will the data be loaded for that Joystick in that Player when Load is called. Joystick Maps are not automatically loaded from saved user data when you assign a Joystick to a Player or change Joystick assignments between Players.

Limitations:

UserDataStore_PlayerPrefs is not the be-all, end-all, automatic data storage system. It has limitations. It does not fully automate everything so you can just set it and forget it. It provides an interface for you to save/load data as necessary for the needs of your game. This sometimes requires manual calls to functions to make data save or load at a particular time. Functionality beyond what is described above is up to the user to implement if desired. UserDataStore_PlayerPrefs is a minimum viable product designed for the most common use case needs and was primarily designed for Control Mapper.

PlayerPrefs itself has significant limitations and negatives, for example, it isn't possible to clear only Rewired's save data from PlayerPrefs without wiping out all other PlayerPrefs data. If this is something you anticipate needing to do for whatever reason, do not use UserDataStore_PlayerPrefs and instead implement your own extension of the UserDataStore class that saves/loads data to whatever storage system you desire so you can have more control over how data is stored and managed.

If you need to save which Controller Maps are currently assigned to a Player, for example if you've manually loaded an alternate layout at some point and you want that new layout to be loaded the next time you call UserDataStore.Load instead of the default defined in the Rewired Input Manager, you will have to make a new UserDataStore class extension that can handle these special needs. Copy the UserDataStore_PlayerPrefs, change the class name, and make any modifications necessary to what data is saved and loaded.

IMPORTANT: Saved XML data is not updated when you make changes to the Rewired Input Manager

UserDataStore does not manage changes between the Rewired Input Manager and data that is already saved to XML. If you make changes to the Rewired Input Manager settings such as adding new controls to a Joystick Map, these new changes will not be preserved when loading saved XML data. The only automated solutions would be to either clear the save data by clearing Player Prefs so that the Rewired Input Manager defaults are used instead or load the default maps in the Player for the any controllers that changed and save those to XML overwriting the existing saved mappings.

Management of saved user data is up to the developer. If you have special needs beyond the basic use cases, you should extend and replace the UserDataStore_PlayerPrefs component with a new UserDataStore component that meets your specific needs.

IMPORTANT:

During development, you may run into a situation where your controls don't seem to make sense. This may happen when you make some runtime control changes, save them, and then proceed to change your mappings in the Rewired Input Manager. Because UserDataStore_PlayerPrefs is configured to save controller data on disconnect and load controller data on start and controller connect, the loaded settings will override new changes you make to the default mappings in the Rewired Input Manager.

During development, it may be useful to disable or remove the UserDataStore_PlayerPrefs component. If you've already saved controller settings and want to remove them, you can use the Clear All Player Prefs button in the Debug Options foldout on the UserDataStore_PlayerPrefs inspector. WARNING: This will clear ALL PlayerPrefs data for the current project. This is due to the limitation that there is no way to look up what keys exist in PlayerPrefs.