✎ Input [Dynamic Water Physics 2 Documentation]

Edit the page and hit Save. See syntax for Wiki syntax. Please edit the page only if you can improve it. If you want to test some things, learn to make your first steps on the playground.

====== Input ======

* Ships retrieve user input through ''Input'' class which retrieves input from active ''InputProvider'' and fills the ''InputStates'' struct with the retrieved data.\\
  * ''InputProvider''s are split into //ShipInputProviders// and //SceneInputProviders//. //ShipInputProviders// relay ship input (throttle, brakes, etc.) while //SceneInputProviders// take care of scene input (ship changing, camera changing, camera movement and the rest of the inputs not directly related to ship. One of each needs to be present (e.g. ''InputSystemShipInputProvider'' and ''InputSystemSceneInputProvider'').
  * Multiple different ''InputProvider''s can be present in the scene (v1.0 or newer required). E.g. InputSystemProviders and MobileInputProviders can be used in the same scene. The resulting input will be a sum of inputs from all ''InputProvider''s in case of numeric inputs and logical OR operation of all inputs in case of boolean inputs. 
  * Input is stored inside ''InputStates'' object and can be copied over from one ship to another.
  * To manually set the ''InputStates'' make sure ''Auto Settable'' is set to false.
\\
All input providers inherit from either ''ShipInputProviderBase'' or ''SceneInputProviderBase'', but differ in their implementation.
\\
\\
== Input System Warning ==
When importing the asset for the first time this message will pop up:
[{{:pasted:20210409-155653.png}}]
Both ''Yes'' or ''No'' can be selected but it is important to set the //Project Settings => Player => Input Handling// to ''Both'' afterwards. This way both new InputSystem and the old InputManager will work. If this setting is set to ''InputManager'' only errors might appear as the demo scenes of the asset rely on InputSystem.\\
If a message //This Unity Package has Package Manager dependencies.// appears, click ''Install/Upgrade''.
\\
\\

==== Available Bindings ====

==== Input Manager (old/classic) ====
  * Type of ''InputProvider'' for handling user input on desktop devices through keyboard and mouse or gamepad.
  * Uses classic/old Unity Input Manager. It is recommended to use the Unity's new Input System instead for new projects.
\\
<wrap round info>InputSystem package is required even if not used. If using the old/classic Unity input set Project Settings => Player => Input Handling to ''Both'' and proceed as normal. InputSystem package being present installed will not interfere with old/classic Unity input / InputManager.</wrap>
\\

== Installation ==
When first importing Dynamic Water Physics 2 the project will be missing required bindings. There are two ways to add those:
  - Manually adding each entry to the //Project Settings => Input// following the input bindings table.
  - Copying the contents of //InputBindings.txt// and appending them to the contents of the ''[UnityProjectPath]/ProjectSettings/InputManager.asset'' file. To do so:
    * Close Unity.
    * Open //InputManager.asset// in Notepad/Notepad++/Visual Studio or any other text editor of your choice.
    * Copy the contents of the provided InputBindings.txt file (//Scripts => ShipController => Input => InputProviders => InputManagerProvider => InputBindings.txt//) and paste them at the end of the //InputManager.asset//. Make sure there are no empty lines between the existing content and the pasted content. Also make sure that all the indents are correct (Unity will detect end of file if indent is off). Save the file.
    * Open Unity. Check //Project Settings => Input//. The input bindings for Dynamic Water Physics will appear towards the bottom of the list.

== Scene Setup ==
To set up InputManager-based input in the scene add the following components to the scene:
  - 'InputManagerShipInputProvider'
  - 'InputManagerSceneInputProvider'
Any ship that is present in the scene will now receive input from these providers.

==== Input System (new) ====

* InputSystem v1.0 or higher is required. This is available in Unity 2019.3 or newer.

<wrap round important>When using DS4Windows, InputSystem will detect button presses twice.</wrap>

== Installation ==

* Install 'Input System' package through Window => Package Manager
  * Under Edit => Project Settings => Player => Other Settings => ''Active Input Handling select'' ''Input System Package (New)'' or ''Both'' - the latter in case your project still uses ''UnityEngine.Input'' somewhere.

== Scene Setup ==
  * Add ''InputSystemShipInputProvider'' and ''InputSystemSceneInputProvider'' to any object in your scene.
  * Default bindings can be modified by double clicking on ''.inputactions'' files. ''Save Asset'' must be clicked for the changes to take effect.

==== Mobile Input Provider ====
  * Add ''MobileShipInputProvider'' and ''MobileSceneInputProvider'' to the scene.
  * Create a few UI => Button objects inside your canvas. Make sure that they are clickable.
  * Remove the ''UnityEngine.UI.Button'' component and replace it with ''MobileInputButton''. ''MobileInputButton'' inherits from ''UnityEngine.UI.Button'' and adds ''hasBeenClicked'' and ''isPressed'' fields which are required for ''Mobile Input Provider''
  * Drag the buttons to the corresponding fields in the ''MobileShipInputProvider'' and ''MobileSceneInputProvider'' inspectors. Empty fields will be ignored.

==== Scripting ====

== Retrieving Input ==
Since v1.0 multiple ''InputProvider''s can be present in the scene, meaning that their input has to be combined to get the final input result. To get the combined input use:
<code>
float throttle = InputProvider.CombinedInput(i => i.Throttle());
bool engineStartStop = InputProvider.CombinedInput(i => i.EngineStartStop());
</code>
//
Or to get the input from individual ''InputProvider''s (say to find out if a button was pressed on a keyboard):
<code>float throttle = InputProvider.Instances[0].Throttle;</code>
//
When using input generated by code (i.e. AI) it is usually handy to have access to a single axis throttle/brake. This can be done like so:
<code>
shipController.input.Throttle = 0.5f;
shipController.input.Throttle = -0.5f;
</code>
//
<wrap round important>shipController.input.states.throttle is equal to shipController.input.Throttle. The latter is just a getter/setter for convenience.</wrap>
//
== Manually Setting Input ==
Input in each ship is stored in ''InputStates'' struct:\\
<code>myShipController.input.states</code>
In case input should not be retrieved from user but from another script - as is the case when AI is used - ''AutoSettable'' should be set to ''false''. This will disable automatic input fetching from the active ''InputProvider''.\\
Input now can be set from any script:
<code>myShipController.input.Horizontal = myFloatValue; // Using getter/setter.</code>
<code>myShipController.input.states.horizontal = myFloatValue; // Directly accessing states.</code>

== Custom InputProvider ==
If a custom ''InputProvider'' is needed it can easily be written. Custom ''InputProviders'' allow for new input methods or for modifying the existing ones. E.g. if the ''MobileInputProvider'' does not fit the needs of the project a copy of it can be made and modifications done on that copy. That way it will not get overwritten when the asset is updated.
\\
\\
Steps to create a new ''InputProvider'':
  * Create a new class, e.g. ''ExampleInputProvider'' and make it inherit from ''InputProvider'' class:
<code>public class ExampleInputProvider : InputProvider {}</code>
  * Implement missing methods. Most IDEs can do this automatically.
  * The required methods are //abstract// and will need to be implemented. There are also //virtual// methods such as ''ToggleGUI()'' which are optional and will be ignored if not implemented.
  * Methods that are not used should return ''false'', ''0'' or ''-999'' in case of ''ShiftInto()'' method.

Edit summary