300 lines
20 KiB
HTML
300 lines
20 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><!-- InstanceBegin template="/Templates/BasicTemplate.dwt" codeOutsideHTMLIsLocked="false" -->
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<!-- InstanceBeginEditable name="doctitle" -->
|
|
<title>Rewired Documentation | Map Enabler</title>
|
|
<!-- InstanceEndEditable -->
|
|
<!-- InstanceParam name="isRoot" type="boolean" value="false" -->
|
|
<!-- InstanceParam name="wide" type="boolean" value="false" -->
|
|
<link href="files/css/styles.css" rel="stylesheet" type="text/css" />
|
|
<!-- Favicons -->
|
|
<link rel="icon" type="image/x-icon" href="/projects/rewired/files/images/favicon.ico?v=1" />
|
|
<!-- Apple Icons -->
|
|
<!-- For iPad with high-resolution Retina display running iOS = 7: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="files/images/favicon_152x152.png?v=1">
|
|
<!-- For iPad with high-resolution Retina display running iOS = 6: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="files/images/favicon_144x144.png?v=1">
|
|
<!-- For iPhone with high-resolution Retina display running iOS = 7: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="120x120" href="files/images/favicon_120x120.png?v=1">
|
|
<!-- For iPhone with high-resolution Retina display running iOS = 6: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="114x114" href="files/images/favicon_114x114.png?v=1">
|
|
<!-- For the iPad mini and the first- and second-generation iPad on iOS = 7: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="76x76" href="files/images/favicon_76x76.png?v=1">
|
|
<!-- For the iPad mini and the first- and second-generation iPad on iOS = 6: -->
|
|
<link rel="apple-touch-icon-precomposed" sizes="72x72" href="files/images/favicon_72x72.png?v=1">
|
|
<!-- For non-Retina iPhone, iPod Touch, and Android 2.1+ devices: -->
|
|
<link rel="apple-touch-icon-precomposed" href="files/images/favicon_57x57.png?v=1">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
|
|
<div class="container">
|
|
|
|
<div class="google-search-bar">
|
|
<script>
|
|
(function() {
|
|
var cx = '007961148920562332911:oocvtwz5jce';
|
|
var gcse = document.createElement('script');
|
|
gcse.type = 'text/javascript';
|
|
gcse.async = true;
|
|
gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(gcse, s);
|
|
})();
|
|
</script>
|
|
<gcse:search></gcse:search>
|
|
</div>
|
|
|
|
<div class="content">
|
|
|
|
|
|
|
|
<div class="page-body">
|
|
|
|
|
|
|
|
|
|
<div class="sidebar-nav">
|
|
<h4><a href="Documentation.html">Documentation</a></h4>
|
|
<ul>
|
|
<li><a href="Overview.html">Overview</a></li>
|
|
<li><a href="ReleaseNotes.txt">Release Notes</a></li>
|
|
</ul>
|
|
<strong>Essentials:</strong>
|
|
<ol>
|
|
<li><a href="Installation.html">Installation</a></li>
|
|
<li><a href="QuickStart.html">Quick Start</a></li>
|
|
<li><a href="BasicUsage.html">Basic Usage</a></li>
|
|
<li><a href="Deployment.html">Deployment</a></li>
|
|
<li><a href="BestPractices.html">Best Practices</a></li>
|
|
<li><a href="RewiredEditor.html">Rewired Editor</a></li>
|
|
<li><a href="http://guavaman.com/projects/rewired/docs/api-reference" target="_blank">API Reference</a></li>
|
|
</ol>
|
|
<strong>Concepts:</strong>
|
|
<ul>
|
|
<li><a href="InputManager.html">Input Manager</a></li>
|
|
<li><a href="Players.html">Players</a></li>
|
|
<li><a href="Actions.html">Actions</a></li>
|
|
<li><a href="InputBehaviors.html">Input Behaviors</a></li>
|
|
<li><a href="Controllers.html">Controllers</a></li>
|
|
<li><a href="ControllerMaps.html">Controller Maps</a></li>
|
|
<li><a href="ControllerTemplates.html">Controller Templates</a></li>
|
|
<li><a href="MapCategories.html">Map Categories</a></li>
|
|
<li><a href="Layouts.html">Layouts</a></li>
|
|
<li><a href="LayoutManager.html">Layout Manager</a></li>
|
|
<li><a href="MapEnabler.html">Map Enabler</a></li>
|
|
<li><a href="CustomControllers.html">Custom Controllers</a></li>
|
|
</ul>
|
|
<strong>Extras:</strong>
|
|
<ul>
|
|
<li><a href="ControlMapper.html" title="Control Mapper">Control Mapper</a></li>
|
|
<li><a href="Glyphs.html" title="Glyphs">Glyphs</a></li>
|
|
<li><a href="TouchControls.html" title="Touch Controls">Touch Controls</a></li>
|
|
<li><a href="UnityInputOverride.html" title="Unity Input Override">Unity Input Override</a></li>
|
|
</ul>
|
|
<strong>Misc:</strong>
|
|
<ul>
|
|
<li><a href="RewiredStandaloneInputModule.html">Rewired Standalone Input Module</a></li>
|
|
<li><a href="ComponentControls.html" title="Component Controls">Component Controls</a></li>
|
|
<li><a href="PlayerControllers.html" title="Player Controllers">Player Controllers</a></li>
|
|
<li><a href="InputMapper.html" title="Input Mapper">Input Mapper</a></li>
|
|
<li><a href="UserDataStore.html" title="User Data Store">User Data Store</a></li>
|
|
<li><a href="CustomPlatforms.html" title="User Data Store">Custom Platforms</a></li>
|
|
<li><a href="Localization.html" title="Localization">Localization</a></li>
|
|
</ul>
|
|
<strong>How To's:</strong>
|
|
<ul>
|
|
<li><a href="HowTos.html">See all topics...</a></li>
|
|
</ul>
|
|
<strong>Help:</strong>
|
|
<ul>
|
|
<li><a href="SupportedControllers.html" title="Supported Controllers">Supported Controllers</a></li>
|
|
<li><a href="Overview.html#tested-platforms" title="Tested Platforms">Tested Platforms</a></li>
|
|
<li><a href="Troubleshooting.html" title="Troubleshooting">Troubleshooting</a></li>
|
|
<li><a href="KnownIssues.html">Known Issues</a></li>
|
|
<li><a href="SpecialPlatformSupport.html" title="Special Platform Support">Special Platform Support</a></li>
|
|
<li><a href="Examples.html" title="Examples">Examples</a></li>
|
|
<li><a href="Integration.html">Integrations</a></li>
|
|
<li><a href="Updating.html" title="Updating Rewired">Updating Rewired</a></li>
|
|
</ul>
|
|
<strong>FAQ</strong>
|
|
<ul>
|
|
<li><a href="FAQ.html">See all topics...</a></li>
|
|
</ul>
|
|
<strong>Unity Help:</strong>
|
|
<ul>
|
|
<li><a href="http://docs.unity3d.com/Manual/" target="_blank">Unity Manual</a></li>
|
|
<li><a href="http://docs.unity3d.com/ScriptReference/" target="_blank">Unity Script Reference</a></li>
|
|
<li><a href="http://unity3d.com/learn/tutorials/modules" target="_blank">Unity Tutorials</a></li>
|
|
</ul>
|
|
<strong>Links:</strong>
|
|
<ul>
|
|
<li><a href="http://guavaman.com/projects/rewired">Rewired Website</a></li>
|
|
<li><a href="http://guavaman.com/projects/rewired/docs">Web Documentation</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<div class="main-body">
|
|
<div class="logo"><a href="http://guavaman.com/projects/rewired" title="Rewired"><img src="files/images/rewired-logo.png" width="173" height="139" alt="Rewired" /></a></div>
|
|
|
|
<h1>
|
|
<!-- InstanceBeginEditable name="PageHeader" -->Map Enabler <!-- InstanceEndEditable -->
|
|
</h1>
|
|
|
|
<!-- InstanceBeginEditable name="MainBody" -->
|
|
|
|
<p> 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.</p>
|
|
<p>See <a href="LayoutManager.html">Layout Manager</a> to manage Controller Map Layouts.</p>
|
|
<h3>How it Works:</h3>
|
|
<p><img src="files/images/map-enabler-diagram-1.png" alt="Map Enabler Diagram" /></p>
|
|
<p> </p>
|
|
<ol>
|
|
<li>Each Player has its own Map Enabler that can be used to manage the Controller Maps for that Player.</li>
|
|
<li>The Map Enabler contains a list of <a href="#rule-sets">Rule Sets</a>.</li>
|
|
<li>Each Rule Set contains a list of <a href="#rules">Rules</a> which determine what Controller Maps are to be enabled or disabled.</li>
|
|
<li>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.</li>
|
|
</ol>
|
|
<h3>Tips:</h3>
|
|
<ul>
|
|
<li>Rule Sets can be disabled so the Rules contained within are ignored when Apply is called.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
<li>Map Enabler works in conjuction with <a href="LayoutManager.html">Layout Manager</a>. It's recommended you use both systems together to manage both Layouts and Controller Map enabled states.</li>
|
|
<li>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 <a href="RewiredEdtior.html#Players">Rewired Editor - Players</a> page.</li>
|
|
<li>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.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
<h3>Accessing from Scripts:</h3>
|
|
<pre class="code">player.controllers.maps.mapEnabler
|
|
</pre>
|
|
<h3><a name="rule-sets" id="rule-sets"></a>Rule Sets: </h3>
|
|
<p>A Rule Set is a collection of Rules.</p>
|
|
<p><strong><a name="creating-rule-sets" id="creating-rule-sets"></a>Creating Rule Sets:</strong></p>
|
|
<p>Rule Sets can be created in the <a href="RewiredEditor.html#MapEnablerRules">Rewired Editor</a> or created at runtime via scripting.</p>
|
|
<p><strong><a name="creating-rule-sets-editor" id="creating-rule-sets-editor"></a>Creating Rule Sets in the Rewired Editor:</strong></p>
|
|
<p>Rule Sets can be created in the <a href="RewiredEditor.html#MapEnablerRules">Rewired Editor on the Map Enabler Rules page</a>. After creating the rules, you must assign them to Players on the Players page or they will not be used. </p>
|
|
<p>Alternately, Rule Sets created in the Rewired Editor can be loaded via scripting and added to the Player's Map Enabler as follows:</p>
|
|
|
|
<pre class="code">
|
|
<span class="comment">// Create an instance of a Rule Set defined in the Rewired Editor</span>
|
|
var ruleSet = ReInput.mapping.GetControllerMapEnablerRuleSetInstance(ruleSetId);
|
|
|
|
<span class="comment">// Add the Rule Set to the Player's Map Enabler</span>
|
|
player.controllers.maps.mapEnabler.ruleSets.Add(ruleSet);
|
|
|
|
<span class="comment">// Apply the changes to the Player's Controller Maps</span>
|
|
player.controllers.maps.mapEnabler.Apply(); </pre>
|
|
<p>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. </p>
|
|
<p><strong><a name="creating-rule-sets-scripting" id="creating-rule-sets-scripting"></a>Creating Rule Sets via Scripting:</strong></p>
|
|
<p>Rule Sets can be created and assigned at runtime.</p>
|
|
<p>This example shows creating two Rule Sets.</p>
|
|
<pre class="code">
|
|
<span class="comment">// Exclusively enables Controller Maps in the "GameplayShared" and "Infantry" categories for all Controllers</span>
|
|
private ControllerMapEnabler.RuleSet mapEnabler_default = new ControllerMapEnabler.RuleSet() {
|
|
|
|
<span class="comment"> // Enable the Rule Set. This is unnecessary since Rule Sets start enabled by default.</span>
|
|
enabled = true,
|
|
|
|
<span class="comment"> // Create a tag if you want to find this Rule Set via scripting in the list</span>
|
|
tag = "default",
|
|
|
|
<span class="comment">// Create the list of Rules for this Rule Set</span>
|
|
rules = {
|
|
|
|
<span class="comment">// First disable all Controller Maps for all Controllers</span>
|
|
new ControllerMapEnabler.Rule() {
|
|
enable = false,
|
|
controllerSetSelector = ControllerSetSelector.SelectAll()
|
|
},
|
|
|
|
<span class="comment">// Enable Controller Maps in the "GameplayShared" and "Infantry" categories in all Layouts for all Controllers</span>
|
|
new ControllerMapEnabler.Rule() {
|
|
enable = true,
|
|
controllerSetSelector = ControllerSetSelector.SelectAll(),
|
|
categoryNames = new[] { "GameplayShared", "Infantry" }
|
|
}
|
|
}
|
|
};
|
|
|
|
<span class="comment">// Exclusively enables Controller Maps in the "GameplayShared" category in the "Leftie" Layout for Joysticks only</span>
|
|
private ControllerMapEnabler.RuleSet mapEnabler_default_leftieJoystick = new ControllerMapEnabler.RuleSet() {
|
|
|
|
tag = "leftie_joystick",
|
|
rules = {
|
|
|
|
<span class="comment">// First disable all Controller Maps for all Joysticks</span>
|
|
new ControllerMapEnabler.Rule() {
|
|
enable = false,
|
|
controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick)
|
|
},
|
|
|
|
<span class="comment">// Enable Controller Maps in the "GameplayShared" category in the "Leftie" Layout for all Joysticks</span>
|
|
new ControllerMapEnabler.Rule() {
|
|
enable = true,
|
|
controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick),
|
|
categoryName = "GameplayShared",
|
|
layoutName = "Leftie"
|
|
}
|
|
}
|
|
};</pre>
|
|
<p><strong><a name="enabling-disabling-rule-sets" id="enabling-disabling-rule-sets"></a>Enabling and disabling Rule Sets:</strong></p>
|
|
<p>Rule Sets can be enabled and disabled to control whether they are evaluated or not when <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/M_Rewired_ControllerMapEnabler_Apply.htm">ControllerMapEnabler.Apply</a> is called or whenever rules are evaluated.</p>
|
|
<p><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/P_Rewired_ControllerMapEnabler_ruleSets.htm">ControllerMapEnabler.ruleSets</a> contains a List<<a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapEnabler_RuleSet.htm">ControllerMapEnabler.RuleSet</a>> 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 <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/M_Rewired_ControllerMapEnabler_Apply.htm">ControllerMapEnabler.Apply</a> to evaluate the rules and apply the changes to the Player's Controller Maps.</p>
|
|
<pre class="code"><span class="comment">// Disable all Rule Sets</span>
|
|
foreach(var ruleSet in player.controllers.maps.mapEnabler.ruleSets) {
|
|
ruleSet.enabled = false;
|
|
}
|
|
|
|
<span class="comment">// Enable the Rule Set with the tag "UI"</span>
|
|
player.controllers.maps.mapEnabler.ruleSets.Find(item => item.tag == "UI").enabled = true;
|
|
|
|
<span class="comment">// Apply the changes to the Player's Controller Maps</span>
|
|
player.controllers.maps.mapEnabler.Apply(); </pre>
|
|
<h3><a name="rules" id="rules"></a>Rules:</h3>
|
|
<p>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.</p>
|
|
<p>Rules contain 4 pieces of information:</p>
|
|
<ol>
|
|
<li>Controller Selector - Determines which Controller(s) the Rule applies to. Only Controller Maps for the specific Controller(s) will be managed by this Rule.</li>
|
|
<li>Categories - Determines which Controller Map(s) this Rule applies to by Map Category.</li>
|
|
<li>Layouts - Determines which Controller Map(s) this Rule applies to by Layout.</li>
|
|
<li>Enabled - Determines whether the Controller Map(s) should be enabled or disabled.</li>
|
|
</ol>
|
|
<p>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.</p>
|
|
<p>Rules can be created in the <a href="RewiredEditor.html#MapEnablerRules">Rewired Editor on the Map Enabler Rules page</a> or created <a href="#creating-rule-sets-scripting">at runtime via scripting</a>.</p>
|
|
<h3><a name="faq" id="faq"></a>FAQ:</h3>
|
|
<p><strong>Q: Can I select a Rule Set or Rule at runtime using the Id instead of a Tag?</strong></p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<h3>API Reference:</h3>
|
|
<ul>
|
|
<li><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapEnabler.htm">ControllerMapEnabler</a></li>
|
|
<li><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapEnabler_RuleSet.htm">ControllerMapEnabler.RuleSet</a></li>
|
|
<li><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapEnabler_Rule.htm">ControllerMapEnabler.Rule</a></li>
|
|
</ul>
|
|
<div class="bottom-pager clearfix">
|
|
<a class="back-button" href="LayoutManager.html" title="Documentation"><span class="button-img"></span>Layout Manager</a>
|
|
<a class="forward-button" href="CustomControllers.html" title="Players"><span class="button-img"></span>Custom Controllers</a>
|
|
</div>
|
|
|
|
<!-- InstanceEndEditable -->
|
|
</div>
|
|
|
|
</div>
|
|
<div class="footer clearfix">
|
|
<p class="left">Copyright ©2014-2021 <a href="http://guavaman.com" title="Guavaman Enterprises">Guavaman Enterprises</a>. All rights reserved. No materials may be reproduced without permission.</p>
|
|
<p class="right"><a href="http://guavaman.com/projects/rewired" title="Return to Rewired Website">Return to Rewired Website</a></p>
|
|
</div>
|
|
<!-- end .content --></div>
|
|
<!-- end .container --></div>
|
|
|
|
|
|
</body>
|
|
<!-- InstanceEnd --></html>
|