282 lines
17 KiB
HTML
282 lines
17 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 | Input Mapper</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" -->Input Mapper
|
|
<!-- InstanceEndEditable -->
|
|
</h1>
|
|
|
|
<!-- InstanceBeginEditable name="MainBody" -->
|
|
|
|
<p>Input Mapper is a class that greatly simplifies the process of remapping controls. It handles listening for controller input, conflict checking, and creating Action-element assignments in a Controller Map.</p>
|
|
<p>Please see <a href="HowTos.html#controller-mapping-screen">How To's - Creating a Control Mapping Screen</a> before creating a control remapping system using Input Mapper.</p>
|
|
<p><strong>Usage</strong></p>
|
|
<p>The basic process is as follows:</p>
|
|
<ol>
|
|
<li><a href="#create">Create an Input Mapper.</a></li>
|
|
<li><a href="#options">Configure Options.</a></li>
|
|
<li><a href="#events">Subscribe to events.</a></li>
|
|
<li><a href="#context">Create a mapping Context.</a></li>
|
|
<li><a href="#listen">Start listening for input.</a></li>
|
|
<li><a href="#conflicts">Handle assignment conflicts (optional).</a></li>
|
|
<li><a href="#advanced">Advanced operations (optional).</a></li>
|
|
</ol>
|
|
<p>For additional issues, see the <a href="#faq">FAQ</a>.</p>
|
|
<p><strong><a name="create" id="create"></a>1. Create an Input Mapper</strong></p>
|
|
<p>You can either create a new instance of an Input Mapper or use the Default instance as shown below:</p>
|
|
<pre class="code"><span class="comment">// Create a new instance</span>
|
|
InputMapper inputMapper = new InputMapper();
|
|
inputMapper.Start(context);
|
|
|
|
<span class="comment">// Or you can use the Default instance instead if you only need one Input Mapper</span>
|
|
InputMapper.Default.Start(context);</pre>
|
|
<p><strong><a name="options" id="options"></a>2. Configure Options</strong></p>
|
|
<p>Each Input Mapper has an <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_InputMapper_Options.htm">Options</a> object which allows you to configure various settings to fit your needs. These settings should be configured before starting the Input Mapper. <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/T_Rewired_InputMapper_Options.htm">Each available option is described in the class documentation.</a></p>
|
|
<pre class="code">inputMapper.options.timeout = 5f; <span class="comment">// set the timeout to 5 seconds</span>
|
|
inputMapper.options.ignoreMouseXAxis = true; <span class="comment">// ignore the mouse X axis when polling for input</span>
|
|
inputMapper.options.ignoreMouseYAxis = true; <span class="comment">// ignore the mouse Y axis when polling for input</span><br /></pre>
|
|
<p><strong><a name="events" id="events"></a>3. Subscribe to events</strong></p>
|
|
<p>There are numerous events to which you can subscribe to receive notifications when important events take place such as when an input assignment is made or when an assignment conflict is found.</p>
|
|
<pre class="code">
|
|
inputMapper.InputMappedEvent += OnInputMapped;
|
|
inputMapper.ConflictFoundEvent += OnConflictFound;<span class="comment"></span><span class="comment"></span>
|
|
</pre>
|
|
<p><strong><a name="context" id="context"></a>4. Create a mapping Context</strong></p>
|
|
<p>A mapping context provides information about the current mapping session. The mapping context is just a few pieces of information that informs the Input Mapper about what is being mapped.</p>
|
|
<pre class="code">
|
|
InputMapper.Context context = new InputMapper.Context() {
|
|
actionId = action.id, <span class="comment">// the id of the Action being mapped</span><br /> controllerMap = controllerMap, <span class="comment">// the Controller Map which will have the new mapping added</span><br /> actionRange = AxisRange.Full, <span class="comment">// the range of the Action being mapped</span><br /> actionElementMapToReplace = actionElementMap <span class="comment">// the Action Element Map to be replaced (optional)</span><br />};
|
|
</pre>
|
|
<p><strong><a name="listen" id="listen"></a>5. Start listening for input</strong></p>
|
|
<pre class="code">
|
|
inputMapper.Start(context);
|
|
</pre>
|
|
<p><strong><a name="conflicts" id="conflicts"></a>6. Handle assignment conflicts (optional)</strong></p>
|
|
<p>Conflict checking is enabled by default in InputMapper.Options. <a href="HowTos.html#conflict-checking">See How To's - Conflict Checking for more information.</a></p>
|
|
<p>If you subscribed to the InputMapper.ConflictFoundEvent, you will receive a notification when a conflicting assignment was found during input mapping. The object returned contains complete information about the assignment, the conflicts that were found, and provides a callback to be used to respond to the event.</p>
|
|
<pre class="code">
|
|
private InputMapper.ConflictFoundEventData conflictData;
|
|
|
|
void OnConflictFound(InputMapper.ConflictFoundEventData data) {
|
|
conflictData = data; <span class="comment">// store the event data for use in user response</span>
|
|
|
|
if(data.isProtected) { <span class="comment">// the conflicting assignment was protected and cannot be replaced</span>
|
|
<span class="comment">// Display some message to the user asking whether to cancel or add the new assignment.
|
|
// Protected assignments cannot be replaced.
|
|
// ...</span>
|
|
|
|
<span class="comment"> // ... After the user has made a decision</span>
|
|
conflictData.responseCallback(InputMapper.ConflictResponse.Cancel); <span class="comment">// cancel polling</span>
|
|
|
|
} else {
|
|
<span class="comment">// Display some message to the user asking whether to cancel, replace the existing,
|
|
// or add the new assignment.
|
|
// ...</span>
|
|
|
|
<span class="comment"> // ... After the user has made a decision</span>
|
|
|
|
<span class="comment"> // Tell the Input Mapper to replace the conflicting assignments</span>
|
|
conflictData.responseCallback(InputMapper.ConflictResponse.Replace);
|
|
}
|
|
}</pre>
|
|
<p>If you do not subscribe to the ConflictsFoundEvent and you have left conflict checking enabled in the Options.checkForConflicts property, the default action specified in Options.defaultActionWhenConflictFound will be used to resolve the conflict(s).</p>
|
|
<p><strong><a name="advanced" id="advanced"></a>7. Advanced operations (optional)</strong></p>
|
|
<p>Ignoring certain controller elements:</p>
|
|
<pre class="code">
|
|
void Setup() {
|
|
<span class="comment">// When setting up Options, add a callback to handle element confirmation</span>
|
|
inputMapper.options.isElementAllowedCallback = OnIsElementAllowed; <span class="comment">// manually allow or ignore specific elements</span>
|
|
}
|
|
|
|
<span class="comment">// Called by InputMapper when a controller element is activated while polling</span>
|
|
bool OnIsElementAllowed(ControllerPollingInfo info) {
|
|
<span class="comment">// Ignore the Space key on the keyboard</span>
|
|
if(info.controllerType == ControllerType.Keyboard && info.keyboardKey == KeyCode.Space) return false;
|
|
<span class="comment">
|
|
// Allow all other controller elements</span>
|
|
return true;
|
|
}</pre>
|
|
<p>Using multiple Input Mappers to listen to multiple input devices at the same time:</p>
|
|
<p><a href="Examples.html#simple-combined-keyboard-mouse-remapping">See Simple Combined Keyboard Mouse Remapping example</a> for a working example.</p>
|
|
<pre class="code">// Begin listening for input on both keyboard and mouse at the same time
|
|
|
|
inputMapper_keyboard.Start(
|
|
new InputMapper.Context() {
|
|
actionId = actionId,
|
|
controllerMap = keyboardMap,
|
|
actionRange = actionRange,
|
|
actionElementMapToReplace = keyboardMap.GetElementMap(actionElementMapToReplaceId)
|
|
}
|
|
);
|
|
|
|
inputMapper_mouse.Start(
|
|
new InputMapper.Context() {
|
|
actionId = actionId,
|
|
controllerMap = mouseMap,
|
|
actionRange = actionRange,
|
|
actionElementMapToReplace = mouseMap.GetElementMap(actionElementMapToReplaceId)
|
|
}
|
|
); </pre>
|
|
<p> </p>
|
|
<hr />
|
|
<p> </p>
|
|
<h3><a name="faq" id="faq"></a>Frequently Asked Questions</h3>
|
|
<p class="question">Why is binding replacement not working?</p>
|
|
<p>You must pass the ActionElementMap to be replaced in <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/P_Rewired_InputMapper_Context_actionElementMapToReplace.htm">InputMapper.Context.actionElementMapToReplace</a> when calling <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/M_Rewired_InputMapper_Start.htm">InputMapper.Start</a>. After an ActionElementMap is replaced, a new ActionElementMap is created. If you are storing a reference to the ActionElementMap and then it is replaced, the reference to the old ActionElementMap is no longer valid because itpoints to an ActionElementMap that is no longer present in the Controller Map. If you are storing a reference to the ActionElementMap, you must update your reference to the new ActionElementMap after it is replaced.</p>
|
|
<p>In addition, whether replacement happens automatically when a mapping conflict is found is determined by <a href="https://guavaman.com/projects/rewired/docs/api-reference/html/P_Rewired_InputMapper_Options_defaultActionWhenConflictFound.htm">InputMapper.Options.defaultActionWhenConflictFound</a>. You can also <a href="#conflicts">handle conflicts manually</a> and determine what happens to conflicting bindings.</p>
|
|
<div class="bottom-pager clearfix">
|
|
<a class="back-button" href="Documentation.html" title="Actions"><span class="button-img"></span>Documentation</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>
|