DOCS: improve migration docs by duckets · Pull Request #1933 · Unity-Technologies/InputSystem

duckets · 2024-05-22T15:03:29Z

Description

https://jira.unity3d.com/browse/DOCF-5410
Clarify and simplify page so that new system does not look more complex than old system.

Changes made

Added text & screenshot explaining differences between systems (eg named axes vs actions)
Improved formatting of tables and links.
Move code samples to linked pages.
Group by theme.
Move most common API to top.
Show examples of functions with parameters.
Remove namespaces where not necessary.

Notes:

Because of the large diff, it may be easier to review the page by viewing the entire formatted page here:
https://github.com/Unity-Technologies/InputSystem/blob/8908df2e3dade953d1b3808eb1a9474d6e2f3a97/Packages/com.unity.inputsystem/Documentation%7E/Migration.md

lyndon-unity

This update is a great improvement.
I've made some suggestions but even in this form its a step forward so approving anyway.

I've love to see the updates if you agree, but can somewhat pre approve.

lyndon-unity · 2024-05-23T09:14:21Z

+
+There are various ways to discover the currently connected devices, as shown in the code samples below.
+
+To query a list of all connected devices (does not allocate; read-only access):


This isn't needed for the add/remove onDeviceChange part so could go down with the "To find all gamepads and joysticks" section

lyndon-unity · 2024-05-23T09:40:20Z

+[`Input.GetMouseButton`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButton.html)<br/>Example: `Input.GetMouseButton(0)`|Use [`isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.isPressed`
+[`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)<br/>Example: `Input.GetMouseButtonDown(0)`|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasPressedThisFrame`
+[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)<br/>Example: `Input.GetMouseButtonUp(0)`|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasReleasedThisFrame`
+[`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|Use [`Mouse.current.position.ReadValue()`](../api/UnityEngine.InputSystem.Mouse.html)<br/>__Note__: Mouse simulation from touch isn't implemented yet.


For a moment I thought the mouse simulation part might be out of date

But I've only sound the revised - "simulating touch from mouse" (rather than mouse from touch)
https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/manual/Touch.html#touch-simulation

^ so this comment is just a pointless note ;)

I'd suggest putting a code section with this bit
position = Mouse.current.position.ReadValue();

And keeping the Mouse documentation page link separate.
As I think its more clear what to cut and paste into code.

May this be relevant here? https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/api/UnityEngine.InputSystem.UI.VirtualMouseInput.html

lyndon-unity · 2024-05-23T09:41:29Z

+[`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)<br/>Example: `Input.GetMouseButtonDown(0)`|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasPressedThisFrame`
+[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)<br/>Example: `Input.GetMouseButtonUp(0)`|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasReleasedThisFrame`
+[`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|Use [`Mouse.current.position.ReadValue()`](../api/UnityEngine.InputSystem.Mouse.html)<br/>__Note__: Mouse simulation from touch isn't implemented yet.
+[`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html)|Use [`Mouse.current != null`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_current).


I'd suggest putting a code section with this bit
Mouse.current != null

And keeping the Mouse.Current link separate.
As I think its more clear what to cut and paste into code.

lyndon-unity · 2024-05-23T09:46:37Z

 |Input Manager (Old)|Input System (New)|
 |--|--|
-[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)|Use [`ButtonControl.wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button:
+[`Input.GetTouch`](https://docs.unity3d.com/ScriptReference/Input.GetTouch.html)|Use [`EnhancedTouch.Touch.activeTouches[i]`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)<br/>__Note__: Enable enhanced touch support first by calling [`EnhancedTouch.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable).


Given this is more common input for mobile I think its worth an example.

touch = Input.GetTouch(0);
touch.position

vs

EnhancedTouch.Touch.activeTouches[0].position

TBH the new input system touch page itself would benefit from giving a more explicit example (as the table covers various options but doesn't make it super clear what to type to just get the position or state)
https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/manual/Touch.html

lyndon-unity · 2024-05-23T09:52:56Z

+[`Input.compass`](https://docs.unity3d.com/ScriptReference/Input-compass.html)|No corresponding API yet.
+[`Input.compensateSensors`](https://docs.unity3d.com/ScriptReference/Input-compensateSensors.html)|[`InputSettings.compensateForScreenOrientation`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_compensateForScreenOrientation).
+[`Input.deviceOrientation`](https://docs.unity3d.com/ScriptReference/Input-deviceOrientation.html)|No corresponding API yet.
+[`Input.gyro`](https://docs.unity3d.com/ScriptReference/Input-gyro.html)|The `UnityEngine.Gyroscope` class is replaced by multiple separate sensor Devices in the new Input System:<br/>[`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) to measure angular velocity.<br/>[`GravitySensor`](../api/UnityEngine.InputSystem.GravitySensor.html) to measure the direction of gravity.<br/>[`AttitudeSensor`](../api/UnityEngine.InputSystem.AttitudeSensor.html) to measure the orientation of the device.<br/>[`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html) to measure the total acceleration applied to the device.<br/>[`LinearAccelerationSensor`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html) to measure acceleration applied to the device, compensating for gravity.


I see you have specific examples below the main section. I was wondering if you needed this line. Perhaps splitting the header links into the next few sections.

Happy to leave this bit though as its minor.

ekcoh

Looks great @duckets, a big improvement to the migration docs. Added some minor comments.

ekcoh · 2024-05-23T12:57:19Z

+[`Input.GetMouseButton`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButton.html)<br/>Example: `Input.GetMouseButton(0)`|Use [`isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.isPressed`
+[`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)<br/>Example: `Input.GetMouseButtonDown(0)`|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasPressedThisFrame`
+[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)<br/>Example: `Input.GetMouseButtonUp(0)`|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button.<br/>Example: `InputSystem.Mouse.current.leftButton.wasReleasedThisFrame`
+[`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|Use [`Mouse.current.position.ReadValue()`](../api/UnityEngine.InputSystem.Mouse.html)<br/>__Note__: Mouse simulation from touch isn't implemented yet.


May this be relevant here? https://docs.unity3d.com/Packages/com.unity.inputsystem@1.8/api/UnityEngine.InputSystem.UI.VirtualMouseInput.html

Corrected GetKey/GetButton mismatch in the joysticks section (GetButton is analogous to 'actions' and GetKey is analogous to direct device access)

lyndon-unity · 2024-06-28T12:32:01Z

We seem to lack migration info for GetPenEvent, GetLastPenContactEvent, ResetPenEvents, ClearLastPenContactEvent

All could refer to Pen.current

lyndon-unity · 2024-06-28T12:46:30Z

I also think imeCompositionMode should refer to Keyboard.current.SetIMEEnabled(true);

Currently Input.imeIsSelected refers to both Keyboard.current.imeSelected and Keyboard.current.SetIMEEnabled(true);
I think this should only refer to Keyboard.current.imeSelected

lyndon-unity · 2024-06-28T12:59:02Z

Some issues remain with KeyControl.displayName being referenced - This field is in InputControl (which KeyControl inherits from)

isPressed in Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs Line 147wasPressedThisFrame in Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs Line 185
wasReleasedThisFrame in Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs Line 21

lyndon-unity

Updates look good

duckets added 5 commits May 16, 2024 18:22

migration page improvements WIP

2186a85

More WIP for improving Migration page

ae672e7

more WIP - migrating action-based input

0f891a0

More WIP on Migration page

d8f4464

Migration page improvements WIP

8908df2

duckets requested a review from lyndon-unity May 22, 2024 15:03

Merge branch 'develop' into DOCF-5410-improve-migration-docs

4b54e02

lyndon-unity approved these changes May 23, 2024

View reviewed changes

ekcoh approved these changes May 23, 2024

View reviewed changes

Amendments from PR review comments

0d21a11

lyndon-unity reviewed May 31, 2024

View reviewed changes

Comment thread Packages/com.unity.inputsystem/Documentation~/Migration.md Outdated

duckets changed the title ~~Docf 5410 improve migration docs~~ DOCS: improve migration docs Jun 5, 2024

ekcoh and others added 5 commits June 18, 2024 16:00

Merge branch 'develop' into DOCF-5410-improve-migration-docs

2a29b1e

Merge branch 'develop' into DOCF-5410-improve-migration-docs

6fcaa9d

Merge branch 'develop' into DOCF-5410-improve-migration-docs

d1f23b7

Update Migration.md

c35ae06

Corrected GetKey/GetButton mismatch in the joysticks section (GetButton is analogous to 'actions' and GetKey is analogous to direct device access)

Merge branch 'develop' into DOCF-5410-improve-migration-docs

a4cf9e1

duckets added 2 commits June 28, 2024 14:37

Fix broken api links for KeyControl.displayName

d7acd69

Formatting fix

9bccbbc

lyndon-unity approved these changes Jun 28, 2024

View reviewed changes

duckets and others added 7 commits July 1, 2024 10:15

Updates to migration guide for Pen events

0e68c81

Updates to migration guide for Keyboard IME text composition

3c58f51

Merge branch 'develop' into DOCF-5410-improve-migration-docs

58c03f4

Removed migration info for Input.mousePresent

c6e39ff

Merge branch 'develop' into DOCF-5410-improve-migration-docs

eec1efb

Merge branch 'develop' into DOCF-5410-improve-migration-docs

50cb96d

Formatting fix

104ae35

duckets and others added 11 commits July 22, 2024 14:46

Merge branch 'develop' into DOCF-5410-improve-migration-docs

5f1972f

Merge branch 'develop' into DOCF-5410-improve-migration-docs

d42e862

Merge branch 'develop' into DOCF-5410-improve-migration-docs

c18f788

Merge branch 'develop' into DOCF-5410-improve-migration-docs

b92137b

Merge branch 'develop' into DOCF-5410-improve-migration-docs

3420074

fix xml for ButtonControl

00155ac

xml fix

127549c

xml doc fix

a375f3f

whitespace format fix

63b55f1

added para tags for example plain text

7a67b47

Merge branch 'develop' into DOCF-5410-improve-migration-docs

3735c41

lyndon-unity merged commit e72d158 into develop Aug 5, 2024

lyndon-unity deleted the DOCF-5410-improve-migration-docs branch August 5, 2024 16:46


		There are various ways to discover the currently connected devices, as shown in the code samples below.

		To query a list of all connected devices (does not allocate; read-only access):

Conversation

duckets commented May 22, 2024

Description

Changes made

Notes:

Uh oh!

lyndon-unity left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ekcoh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lyndon-unity commented Jun 28, 2024

Uh oh!

lyndon-unity commented Jun 28, 2024

Uh oh!

lyndon-unity commented Jun 28, 2024

Uh oh!

lyndon-unity left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants