292 lines
22 KiB
HTML
292 lines
22 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 | Layout Manager</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" -->Layout Manager <!-- InstanceEndEditable -->
|
|
</h1>
|
|
|
|
<!-- InstanceBeginEditable name="MainBody" -->
|
|
|
|
<p> Layout Manager can be used to manage loading and unloading of <a href="ControllerMaps.html">Controller Maps</a> in a <a href="Players.html">Player</a> to force the specified Layouts to be used. This can be used to make specific Controller Maps be loaded in a Player with specific <a href="Layouts.html">Layouts</a>, for example when changing Controller Maps for a "Left-Handed" input scheme. These settings will persist and be inherited by new Controllers assigned to the Player based on your rules. This will enforce a single Layout per managed <a href="MapCategories.html">Map Category</a> be loaded in the Player. Layout Manager cannot manage mutliple simultaneous Layouts in the same Map Category being loaded in the Player.</p>
|
|
<p>This does not manage enabled state of the Controller Maps. It only manages loading and unloading of Controller Maps. See <a href="MapEnabler.html">Map Enabler</a> to manage Controller Map enabled states. Normally, you would use both systems together.</p>
|
|
<h3>How it Works:</h3>
|
|
<p><img src="files/images/layout-manager-diagram-1.png" alt="Layout Manager Diagram" /></p>
|
|
<p> </p>
|
|
<ol>
|
|
<li>Each Player has its own Layout Manager that can be used to manage the Controller Maps for that Player.</li>
|
|
<li>The Layout Manager 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 loaded and/or unloaded.</li>
|
|
<li>When Apply is called on the Layout Manager (manually or when certain things happen such as when assigning a Controller to a Player), all Rules in all enabled Rule Sets are processed one at a time in order. Controller Maps for the matching Controllers are unloaded or loaded as needed 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>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>
|
|
<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>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>If a Rule designates that maps for a Controller should be loaded in a specific Map Category and Layout but no Controller Map is found that matches those settings, a blank Controller Map with that Map Category and Layout will be created, resulting in no input through that Controller Map. For example, if you create a "Left-Handed" Layout for Joysticks in the "Default" Map Category, you should create a "Default", "Left-Handed" Controller Map for every Joystick you want to support (Controller Template Maps can be used to cover all the Controllers to which they apply.)</li>
|
|
<li>Do not assign multple Controller Maps in the same Map Category but different Layouts to the Player if those Controller Maps are to be managed by Layout Manager. Layout Manager will keep only one Controller Map loaded per Controller, per Map Category if that Controller Map is managed.</li>
|
|
<li>Layout Manager works in conjuction with <a href="MapEnabler.html">Map Enabler</a>. It's recommended you use both systems together to manage both Layouts and Controller Map enabled states.</li>
|
|
|
|
<li>The Layout Manager must be enabled or it will not manage Layouts. The Layout Manager 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>The Load From User Data Store setting in the Layout Manager (set in the Rewired Editor or via scripting) determines whether loaded Controller Maps should first search the <a href="UserDataStore.html">UserDataStore</a> before loading from the Rewired Input Manager defaults. This allows saved user mappings created by <a href="ControlMapper.html">Control Mapper</a> or other custom control mapping systems to be loaded by Layout Manager when loading Controller Maps. Note that the UserDataStore implementation must implement the Rewired.Interfaces.IControllerMapStore interface in order for this to function.</li>
|
|
<li>After changing Rule Sets or Rules in the Layout Manager, you should call LayoutManager.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. (The opposite is not true.)</li>
|
|
</ul>
|
|
<h3>Accessing from Scripts:</h3>
|
|
<pre class="code">player.controllers.maps.layoutManager</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#LayoutManagerRules">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#LayoutManagerRules">Rewired Editor on the Layout Manager Rules page</a>. After creating the Rule Sets, you must assign them to Players on the <a href="RewiredEditor.html#Players">Players</a> 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 Layout Manager as follows:</p>
|
|
|
|
<pre class="code">
|
|
<span class="comment">// Load an instance of the Rule Set</span>
|
|
var ruleSet = ReInput.mapping.GetControllerMapLayoutManagerRuleSetInstance(ruleSetId);
|
|
|
|
<span class="comment">// Add the Rule Set to the Player's Layout Manager</span>
|
|
player.controllers.maps.layoutManager.ruleSets.Add(ruleSet);
|
|
|
|
<span class="comment">// Apply the changes to the Player's Controller Maps</span>
|
|
player.controllers.maps.layoutManager.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 Layout Manager Rule Sets that could be used to switch between the "Default" Layout and the "Leftie" Layout for Joysticks in the Map Categories "GameplayShared", "Airplane", and "Infantry." All other Controller Maps for other Controllers are unmanaged in this example and will not be affected by the Layout Manager.</p>
|
|
<pre class="code">
|
|
private ControllerMapLayoutManager.RuleSet layoutManager_joysticks_default = new ControllerMapLayoutManager.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">// Load Default Layout for GameplayShared, Airplane, and Infantry categories in all Joysticks</span>
|
|
new ControllerMapLayoutManager.Rule() {
|
|
|
|
<span class="comment">// Create the Controller Set Selector to determine which Controller(s) this applies to</span>
|
|
controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick),
|
|
|
|
<span class="comment">// Set which Map Catetories of the Controller Maps to be loaded</span>
|
|
categoryNames = new[] { "GameplayShared", "Airplane", "Infantry" },
|
|
|
|
<span class="comment">// Set the Layout of the Controller Maps to be loaded</span>
|
|
layoutName = "Default"
|
|
}
|
|
}
|
|
};
|
|
|
|
private ControllerMapLayoutManager.RuleSet layoutManager_joysticks_leftie = new ControllerMapLayoutManager.RuleSet() {
|
|
|
|
tag = "leftie",
|
|
rules = {
|
|
|
|
<span class="comment">// Load Leftie Layout for GameplayShared, Airplane, and Infantry categories in all Joysticks</span>
|
|
new ControllerMapLayoutManager.Rule() {
|
|
controllerSetSelector = ControllerSetSelector.SelectControllerType(ControllerType.Joystick),
|
|
categoryNames = new[] { "GameplayShared", "Airplane", "Infantry" },
|
|
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_ControllerMapLayoutManager_Apply.htm">ControllerMapLayoutManager.Apply</a> is called or whenever rules are evaluated.</p>
|
|
<p><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/P_Rewired_ControllerMapLayoutManager_ruleSets.htm">ControllerMapLayoutManager.ruleSets</a> contains a List<<a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapLayoutManager_RuleSet.htm">ControllerMapLayoutManager.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_ControllerMapLayoutManager_Apply.htm">ControllerMapLayoutManager.Apply</a><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/M_Rewired_ControllerMapEnabler_Apply.htm"></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.layoutManager.ruleSets) {
|
|
ruleSet.enabled = false;
|
|
}
|
|
|
|
<span class="comment">// Enable the Rule Set with the tag "leftie"</span>
|
|
player.controllers.maps.layoutManager.ruleSets.Find(item => item.tag == "leftie").enabled = true;
|
|
|
|
<span class="comment">// Apply the changes to the Player's Controller Maps</span>
|
|
player.controllers.maps.layoutManager.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 loaded or removed. Each Rule in a Rule Set is evaluated in sequence.</p>
|
|
<p>Rules contain 3 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 Map Categories are managed by this Rule.</li>
|
|
<li>Layout - Determines the Layout of the Controller Map(s) to load / maintain.</li>
|
|
</ol>
|
|
<p>When Layout Manager evaluates the Rules, for the specified Controller(s), it will unload any Controller Maps in Map Categories that match the specified Catgories in the Rule but do not match the specified Layout in the Rule. Then it will load Controller Maps in the specified Map Categories in the specified Layout.</p>
|
|
<p>Rules can be created in the <a href="RewiredEditor.html#LayoutManagerRules">Rewired Editor on the Layout Manager 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_ControllerMapLayoutManager.htm">ControllerMapLayoutManager</a></li>
|
|
<li><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapLayoutManager_RuleSet.htm">ControllerMapLayoutManager.RuleSet</a></li>
|
|
<li><a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_ControllerMapLayoutManager_Rule.htm">ControllerMapLayoutManager.Rule</a></li>
|
|
</ul>
|
|
<div class="bottom-pager clearfix">
|
|
<a class="back-button" href="Layouts.html" title="Documentation"><span class="button-img"></span>Layouts</a>
|
|
<a class="forward-button" href="Players.html" title="Players"><span class="button-img"></span>Map Enabler</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>
|