Map Enabler

Map Enabler enforces persistent enabled states on Controller Maps in a Player. This can be used to make specific Controller Maps be enabled or disabled in a Player, for example when changing game modes that require different input schemes. These settings will persist and be inherited by new Controllers assigned to the Player based on your rules. Enabled states will be sync'd when new Controllers are added, when Controller Maps are loaded, etc.

See Layout Manager to manage Controller Map Layouts.

How it Works:

Map Enabler Diagram

Each Player has its own Map Enabler that can be used to manage the Controller Maps for that Player.
The Map Enabler contains a list of Rule Sets.
Each Rule Set contains a list of Rules which determine what Controller Maps are to be enabled or disabled.
When Apply is called on the Map Enabler (manually or when certain things happen such as when assigning a Controller to a Player or loading Controller Maps), all Rules in all enabled Rule Sets are processed one at a time in order. Controller Maps for the matching Controllers are enabled or disabled to comply with each Rule.

Tips:

Rule Sets can be disabled so the Rules contained within are ignored when Apply is called.
Only Controller Maps that are matched by one or more Rule in an enabled Rule Set will be managed. Any other Controller Maps in the Player will be unmanaged.
Controller Maps managed by Map Enabler must already be loaded in the Player. Map Enabler does not load or unload any Controller Maps. It only changes the enabled state on already-loaded Controller Maps or on Controller Maps at the time they are loaded in the Player.
One way of working with Rule Sets is to split up your Rules into many single-purpose Rule Sets, assign all the Rule Sets to your Player, starting them disabled, and selectively enable combinations of groups of Rule Sets to achieve different modes.
Another way of working with Rule Sets is to stack many Rules into a Rule Set definining an entire mode in one Rule Set and just enable or swap out the Rule Set.
You should not manually set enabled states on Controller Maps that are managed by this class, but instead change enabled state settings by changing the Rule Sets and/or Rules and applying those changes to the Map Enabler.
Map Enabler works in conjuction with Layout Manager. It's recommended you use both systems together to manage both Layouts and Controller Map enabled states.
The Map Enabler must be enabled or it will not manage Controller Maps. The Map Enabler can be enabled and disabled from a script at runtime or on start from the Rewired Editor - Players page.
After changing Rule Sets or Rules in the Map Enabler, you should call MapEnabler.Apply to make these changes commit to the Player's Controller Maps.
MapEnabler.Apply is called in the Player automatically every time Apply is called in the Layout Manager to make sure newly loaded Controller Maps are enabled or disabled as required.

Accessing from Scripts:

player.controllers.maps.mapEnabler

Rule Sets:

A Rule Set is a collection of Rules.

Creating Rule Sets:

Rule Sets can be created in the Rewired Editor or created at runtime via scripting.

Creating Rule Sets in the Rewired Editor:

Rule Sets can be created in the Rewired Editor on the Map Enabler Rules page. After creating the rules, you must assign them to Players on the Players page or they will not be used.

Alternately, Rule Sets created in the Rewired Editor can be loaded via scripting and added to the Player's Map Enabler as follows:

// Create an instance of a Rule Set defined in the Rewired Editor
var ruleSet = ReInput.mapping.GetControllerMapEnablerRuleSetInstance(ruleSetId);

// Add the Rule Set to the Player's Map Enabler
player.controllers.maps.mapEnabler.ruleSets.Add(ruleSet);

// Apply the changes to the Player's Controller Maps
player.controllers.maps.mapEnabler.Apply();

Rule Sets created in the Rewired Editor are instantiated per-Player on initialization. They are not shared among Players. A Rule Set can be modified at runtime on one Player and that change will not be reflected in the Rule Sets owned by other Players.

Creating Rule Sets via Scripting:

Rule Sets can be created and assigned at runtime.

This example shows creating two Rule Sets.

// Exclusively enables Controller Maps in the "GameplayShared" and "Infantry" categories for all Controllers
private ControllerMapEnabler.RuleSet mapEnabler_default = new ControllerMapEnabler.RuleSet() {

    // Enable the Rule Set. This is unnecessary since Rule Sets start enabled by default.
    enabled = true,

    // Create a tag if you want to find this Rule Set via scripting in the list
    tag = "default",

    // Create the list of Rules for this Rule Set
    rules = {

        // First disable all Controller Maps for all Controllers
        new ControllerMapEnabler.Rule() {
            enable = false,
            controllerSetSelector = ControllerSetSelector.SelectAll()
        },

        // Enable Controller Maps in the "GameplayShared" and "Infantry" categories in all Layouts for all Controllers
        new ControllerMapEnabler.Rule() {
            enable = true,
            controllerSetSelector = ControllerSetSelector.SelectAll(),
            categoryNames = new[] { "GameplayShared", "Infantry" }
        }
    }
};

// Exclusively enables Controller Maps in the "GameplayShared" category in the "Leftie" Layout for Joysticks only
private ControllerMapEnabler.RuleSet mapEnabler_default_leftieJoystick = new ControllerMapEnabler.RuleSet() {

    tag = "leftie_joystick",
    rules = {

        // First disable all Controller Maps for all Joysticks
        new ControllerMapEnabler.Rule() {
            enable = false,
            controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick)
        },

        // Enable Controller Maps in the "GameplayShared" category in the "Leftie" Layout for all Joysticks
        new ControllerMapEnabler.Rule() {
            enable = true,
            controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick),
            categoryName = "GameplayShared",
            layoutName = "Leftie"
        }
    }
};

Enabling and disabling Rule Sets:

Rule Sets can be enabled and disabled to control whether they are evaluated or not when ControllerMapEnabler.Apply is called or whenever rules are evaluated.

ControllerMapEnabler.ruleSets contains a List<ControllerMapEnabler.RuleSet> which can be searched and modified like any other generic list. Find the Rule Set(s) you want to change the enabled state on, change the state, then call ControllerMapEnabler.Apply to evaluate the rules and apply the changes to the Player's Controller Maps.

// Disable all Rule Sets
foreach(var ruleSet in player.controllers.maps.mapEnabler.ruleSets) {
    ruleSet.enabled = false;
}

// Enable the Rule Set with the tag "UI"
player.controllers.maps.mapEnabler.ruleSets.Find(item => item.tag == "UI").enabled = true;

// Apply the changes to the Player's Controller Maps
player.controllers.maps.mapEnabler.Apply();

Rules:

Rules are individual commands that are evaluated and applied to all matching Controller Maps in the Player to determine which Controller Maps should be enabled or disabled. Each Rule in a Rule Set is evaluated in sequence.

Rules contain 4 pieces of information:

Controller Selector - Determines which Controller(s) the Rule applies to. Only Controller Maps for the specific Controller(s) will be managed by this Rule.
Categories - Determines which Controller Map(s) this Rule applies to by Map Category.
Layouts - Determines which Controller Map(s) this Rule applies to by Layout.
Enabled - Determines whether the Controller Map(s) should be enabled or disabled.

When Map Enabler evaluates the Rules, for the specified Controller(s), it will enable or disable any Controller Maps in the Player that match the specified criteria in the Rule.

Rules can be created in the Rewired Editor on the Map Enabler Rules page or created at runtime via scripting.

FAQ:

Q: Can I select a Rule Set or Rule at runtime using the Id instead of a Tag?

A: The Id cannot be used to select a Rule Set or Rule in a Player at runtime. Rule Sets can be defined entirely in code and can also be duplicated at runtime, in which case they would not have an id that would correspond to the other Rule Set definitions that exist in the Rewired Input Manager.

The Id constant which can be exported for rule sets exists only for the purpose of instantiating that Rule Set (loading it from the Rewired Input Manager) into a Player. That is not a common thing to do since most of the time you will assign these Rule Sets to your Player in the Rewired Editor and they will be loaded for you when the application starts. Once the application starts, Rule Sets are instantiated for each Player, after which point they have no connection anymore to the parent Rule Set definition from which they came.

Documentation