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

 

  1. Each Player has its own Map Enabler that can be used to manage the Controller Maps for that Player.
  2. The Map Enabler contains a list of Rule Sets.
  3. Each Rule Set contains a list of Rules which determine what Controller Maps are to be enabled or disabled.
  4. 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:

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:

    // Load an instance of the Rule Set
    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(); 

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"
        }
    }
};

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:

  1. Controller Selector - Determines which Controller(s) the Rule applies to. Only Controller Maps for the specific Controller(s) will be managed by this Rule.
  2. Categories - Determines which Controller Map(s) this Rule applies to by Map Category.
  3. Layouts - Determines which Controller Map(s) this Rule applies to by Layout.
  4. 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.

API Reference: