NEW: 'UI vs Game Input' sample (#1377).

Author: Rene Damm

Assets/Samples/UIvsGameInput.meta

@@ -0,0 +1,4 @@
+{
+  "displayName": "UI vs. Game Input",
+  "description": "An example that shows how to deal with ambiguities that may arrise when overlaying interactive UI elements on top of a game scene."
+} 

Assets/Samples/UIvsGameInput/.sample.json

@@ -0,0 +1,114 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!1001 &100100000
+Prefab:
+  m_ObjectHideFlags: 1
+  serializedVersion: 2
+  m_Modification:
+    m_TransformParent: {fileID: 0}
+    m_Modifications: []
+    m_RemovedComponents: []
+  m_SourcePrefab: {fileID: 0}
+  m_RootGameObject: {fileID: 1050929111787496}
+  m_IsPrefabAsset: 1
+--- !u!1 &1050929111787496
+GameObject:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  serializedVersion: 6
+  m_Component:
+  - component: {fileID: 4939001955002736}
+  - component: {fileID: 33329194892259988}
+  - component: {fileID: 65754914235384544}
+  - component: {fileID: 23498649278503262}
+  - component: {fileID: 54430940299048930}
+  m_Layer: 0
+  m_Name: SimpleProjectile
+  m_TagString: Untagged
+  m_Icon: {fileID: 0}
+  m_NavMeshLayer: 0
+  m_StaticEditorFlags: 0
+  m_IsActive: 1
+--- !u!4 &4939001955002736
+Transform:
+  m_ObjectHideFlags: 1
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  m_GameObject: {fileID: 1050929111787496}
+  m_LocalRotation: {x: 0, y: 0, z: 0, w: 1}
+  m_LocalPosition: {x: 0, y: 0, z: 0}
+  m_LocalScale: {x: 0.2921129, y: 0.2921129, z: 0.2921129}
+  m_Children: []
+  m_Father: {fileID: 0}
+  m_RootOrder: 0
+  m_LocalEulerAnglesHint: {x: 0, y: 0, z: 0}
+--- !u!23 &23498649278503262
+MeshRenderer:
+  m_ObjectHideFlags: 1
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  m_GameObject: {fileID: 1050929111787496}
+  m_Enabled: 1
+  m_CastShadows: 1
+  m_ReceiveShadows: 1
+  m_DynamicOccludee: 1
+  m_MotionVectors: 1
+  m_LightProbeUsage: 1
+  m_ReflectionProbeUsage: 1
+  m_RenderingLayerMask: 4294967295
+  m_Materials:
+  - {fileID: 10303, guid: 0000000000000000f000000000000000, type: 0}
+  m_StaticBatchInfo:
+    firstSubMesh: 0
+    subMeshCount: 0
+  m_StaticBatchRoot: {fileID: 0}
+  m_ProbeAnchor: {fileID: 0}
+  m_LightProbeVolumeOverride: {fileID: 0}
+  m_ScaleInLightmap: 1
+  m_PreserveUVs: 1
+  m_IgnoreNormalsForChartDetection: 0
+  m_ImportantGI: 0
+  m_StitchLightmapSeams: 0
+  m_SelectedEditorRenderState: 3
+  m_MinimumChartSize: 4
+  m_AutoUVMaxDistance: 0.5
+  m_AutoUVMaxAngle: 89
+  m_LightmapParameters: {fileID: 0}
+  m_SortingLayerID: 0
+  m_SortingLayer: 0
+  m_SortingOrder: 0
+--- !u!33 &33329194892259988
+MeshFilter:
+  m_ObjectHideFlags: 1
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  m_GameObject: {fileID: 1050929111787496}
+  m_Mesh: {fileID: 10202, guid: 0000000000000000e000000000000000, type: 0}
+--- !u!54 &54430940299048930
+Rigidbody:
+  m_ObjectHideFlags: 1
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  m_GameObject: {fileID: 1050929111787496}
+  serializedVersion: 2
+  m_Mass: 1
+  m_Drag: 0
+  m_AngularDrag: 0.05
+  m_UseGravity: 1
+  m_IsKinematic: 0
+  m_Interpolate: 0
+  m_Constraints: 0
+  m_CollisionDetection: 0
+--- !u!65 &65754914235384544
+BoxCollider:
+  m_ObjectHideFlags: 1
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInternal: {fileID: 100100000}
+  m_GameObject: {fileID: 1050929111787496}
+  m_Material: {fileID: 0}
+  m_IsTrigger: 0
+  m_Enabled: 1
+  serializedVersion: 2
+  m_Size: {x: 1, y: 1, z: 1}
+  m_Center: {x: 0, y: 0, z: 0}

Assets/Samples/UIvsGameInput/Projectile.prefab

@@ -0,0 +1,47 @@
+# UI vs Game Input
+
+>NOTE: More information related to ambiguities between UI and game input may be found [here in the documentation](http://docs.unity3d.com/Packages/[email protected]/manual/UISupport.html#ui-and-game-input).
+
+When interactive UI elements are overlaid over a game view, ambiguity may arise for inputs.
+
+If, for example, there is a `UI.Button` on screen that can be clicked/tapped, while clicking/tapping on the scene itself also has associated functionality, clicking on the UI button should not also trigger the corresponding action on the scene.
+
+This sample demonstrates how to handle input in such a situation.
+
+## The Sample Scene
+
+![Scene Screenshot](./UIvsGameInput.png)
+
+The sample scene has a UI button in each of the corners of the screen. The camera in the scene can be rotated and projectiles can be fired while at the same time the buttons in the UI can be clicked.
+
+There are two ways to control the game:
+
+1. "Pointer", i.e. mouse (optionally combined with keyboard) or touch input, and
+2. "Navigation", i.e. gamepad input.
+
+### Mouse/Touch/Keyboard Input
+
+- When clicking any of the buttons, the "status bar" text along the bottom edge of the screen changes.
+- Left-click-dragging with the mouse or finger-dragging with touch rotates the camera (note: only when starting the drag on the background). Alternatively, when using mouse&keyboard, holding the the left control key will engage camera control.
+- Right-clicking with the mouse or tapping the second finger while rotating the camera shoots a projectile.
+- Double-clicking/tapping on the scene resets the camera orientation.
+- Pressing `Escape` will bring up the game menu. With touch input, an extra button is shown in the game UI to do that.
+
+### Gamepad Input
+
+- The right stick rotates the camera and the right trigger fires a projectile.
+- Double-pressing the A button will reset the camera to its initial orientation.
+- Holding the left trigger switch to UI focus. UI selection is now active and can be changed with the d-pad or the sticks. The A button performs a button press.
+- Pressing B while in game brings up the main menu.
+
+## How It Works
+
+### Pointer Input
+
+For the most part, input processing is done in `Update()` such that actions are processed on a per-frame basis. Responses to actions that may conflict with UI input use [`IsPointerOverGameObject`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) to determine whether the pointer is currently over UI. Since this is called from `Update()` and thus *outside* of input processing (i.e. not from within an `InputAction` callback), the method can be safely called and will return an accurate result.
+
+There are two implementations of handling the `Fire` action. One uses the same approach just mentioned where the action's response is dealt with once per frame. The second one, however, immediately creates a projectile within the callback and thus operates at sub-frame accuracy. For a low-frequency input such as the `Fire` action here, this is not generally a useful thing to do but it is done here for the sake of demonstration. We cannot call [`IsPointerOverGameObject`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) from the action callback and thus need to use the UI's public raycasting interface to determine "over UI?" state manually for the current pointer position.
+
+### Navigation Input
+
+Navigation input employs an explicit mode switch to go from gameplay to UI input. This is handled by `OnUIEngage`.