MTT-4370: UTP 2.0 migration guide #752

simon-lemay-unity · 2022-08-25T19:21:52Z

Select the type of change:

Small Changes - Typos, formatting, slight revisions
New Content - New features, sections, pages, tutorials
Site and Tools - Updates, maintenance, and new packages for the site and Docusaurus

Purpose of the Pull Request:

This PR introduces the migration guide when updating from UTP 1.X to 2.0. The intent is to leave it as a draft for now since we might have more breaking changes to add in there as we move closer to the release.

Before merging, I'll also update the PR so that most of the APIs link to their API page. I didn't do so right away to make the markdown file easier on the eyes while we review it.

Issue Number: MTT-4370

johann-r-unity · 2022-08-26T18:44:57Z

transport_versioned_docs/version-2.0.0/migration.md

+
+It is thus recommended to ensure that clients and servers are updated at the same time, or to disallow older clients from connecting once the server is updated. Another strategy is to offer different endpoints for UTP 1.X and 2.0 servers, which could smooth the transition while older clients are updated.
+
+The reasons for this breaking change are to improve bandwidth efficiency, simplify the protocol, and (ironically) improve forward-compatibility of the protocol.


The "(Ironically)" piece contrast with the doc. Could we use something like :
and lays the foundations for better forward compatibility of the protocol.

johann-r-unity · 2022-08-26T18:47:07Z

transport_versioned_docs/version-2.0.0/migration.md

+
+## Other breaking changes
+
+  * After calling `NetworkDriver.Disconnect`, notifying the remote peer of the disconnection now requires completing a `NetworkDriver.ScheduleUpdate` job. In 1.X, `NetworkDriver.ScheduleFlushSend` used to be sufficient for this purpose but it's not the case anymore.


All the document is factual without explanation, I think this is the correct approach.
However, for this, we are adding an extra step for the user. The natural reaction will be to wonder why.
Would an explanation make sense here ?

@johann-r-unity - Forgive me for lacking context here; I'm not sure I understand entirely. Are you saying we should add an explanation around why we introduced these additional breaking changes (similar to the explanation at the end of the previous paragraphs)?

For example:

These breaking changes simplify and increase the flexibility of the interface. Please refer to this documentation section for more details on creating custom network interfaces.

Hi Larah,
My initial comment is outdated. Simon did the required modification already.

wackoisgod · 2022-08-28T00:09:49Z

transport_versioned_docs/version-2.0.0/migration.md

+  * There is no concept of `NetworkInterfaceEndPoint` anymore. It has been completely replaced with the more general `NetworkEndpoint`. Consequently, there is no need to implement conversion logic between the two anymore (so `CreateInterfaceEndPoint` and `GetGenericEndPoint` were removed from `INetworkInterface`).
+  * There is no need to provide a `NetworkSendInterface` through `CreateSendInterface` anymore. Send operations are now handled entirely by `ScheduleSend`, which gets passed a `PacketsQueue` containing the packets to be sent.
+  * The `ScheduleReceive` method doesn't use `NetworkPacketReceiver` (which is now obsolete) to propagate received packets to the rest of UTP. Instead, implementations of `ScheduleReceive` are expected to fill the `PacketsQueue` that is now passed in with the received packets.
+  * Implementations of `INetworkInterface` are now expected to be fully unmanaged. However, a managed implementation can be wrapped into an unmanaged one with the new `WrapToUnmanaged` extension method.


So the term unmanaged I think will leave folks confused. It almost sounds like the interface must be written in native code which isn't really what you are saying. What you are saying is that it must be fully burst compatible unless you are using the wrapper.

wackoisgod · 2022-09-05T16:40:44Z

Is 2.0 going to depend on 2.0 of collections? I noticed that in that version of collections DataStream and NetworkCompression are now part of collections.

johann-r-unity · 2022-09-05T17:16:34Z

@wackoisgod , yes.

wackoisgod · 2022-09-05T17:30:32Z

@wackoisgod , yes.

If that's the case then it may be worth it to call out those changes. Also if I recall collections 2.0 requires Unity 2022.2 according to the preview release. Does that mean 2.0 will require that?

johann-r-unity · 2022-09-06T03:39:50Z

You are correct. It will be available with the Editor starting 2022.2.
This migration guide is gonna be part of a larger effort to update the docs, but I agree that mentioning it on this page as well makes sense.

wackoisgod · 2022-09-06T19:03:30Z

You are correct. It will be available with the Editor starting 2022.2.

This migration guide is gonna be part of a larger effort to update the docs, but I agree that mentioning it on this page as well makes sense.

So does this mean you will continue to support 1.x and make fixes and updates for that version? My worry is that 2.0 will be out while two LTS versions are out under 1.x since it doesn't seem things are backwards compatible.

simon-lemay-unity · 2022-09-06T19:34:39Z

So does this mean you will continue to support 1.x and make fixes and updates for that version? My worry is that 2.0 will be out while two LTS versions are out under 1.x since it doesn't seem things are backwards compatible.

Yes. As long as there are supported LTS versions that only support UTP 1.X, we'll keep supporting it. Some new features may only make it in 2.0, however.

…Technologies/com.unity.multiplayer.docs into transport/migration-guide

unity-cla-assistant · 2022-09-27T22:22:48Z

All committers have signed the CLA.

* delete event loop file from TP v2.0 docs (#799) * delete event loop file from TP v2.0 docs delete event loop file from TP v2.0 docs * Removing event loop from sidebars Removing event loop from sidebars * Update NGO changelog for 1.0.1 and 1.0.2 (#774) * Fixed typo in github link (#765) https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/main/Assets/Scripts/Gameplay/ConnectionManagement/ServerGameNetPortal.css#L176 => https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/main/Assets/Scripts/Gameplay/ConnectionManagement/ServerGameNetPortal.cs#L176 * update changelog for NGO 1.0.1 and 1.0.2 * MTT-4369 Update UTP documentation to 2.0 documentation structure * Update version-2.0.0-sidebars.json * Removed .bak files * Update NGO 1.0.1 changelog Co-authored-by: Grave <[email protected]> Co-authored-by: Johann Ruwet <[email protected]> * Add changelog for UTP 1.3.0 (#801) * fix broken link to client driven sample (#804) * delete event loop file on main (#798) * delete event loop file on main delete event loop file on main, retaining on develop * Update TP v sidebars.js Update TP v sidebars.js removing from TOC * Update version-2.0.0-sidebars.json Co-authored-by: Brian Coughlin <[email protected]> * Fix broken link to client-driven sample Fix broken link to client-driven sample Co-authored-by: Brian Coughlin <[email protected]> Co-authored-by: Larah Armstrong <[email protected]> * Sync sidebar (#808) * delete event loop file on main (#798) * delete event loop file on main delete event loop file on main, retaining on develop * Update TP v sidebars.js Update TP v sidebars.js removing from TOC * Update version-2.0.0-sidebars.json Co-authored-by: Brian Coughlin <[email protected]> * Update NGO changelog for 1.0.1 and 1.0.2 (#774) * Fixed typo in github link (#765) https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/main/Assets/Scripts/Gameplay/ConnectionManagement/ServerGameNetPortal.css#L176 => https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/main/Assets/Scripts/Gameplay/ConnectionManagement/ServerGameNetPortal.cs#L176 * update changelog for NGO 1.0.1 and 1.0.2 * MTT-4369 Update UTP documentation to 2.0 documentation structure * Update version-2.0.0-sidebars.json * Removed .bak files * Update NGO 1.0.1 changelog Co-authored-by: Grave <[email protected]> Co-authored-by: Johann Ruwet <[email protected]> * delete event loop file from TP v2.0 docs (#799) * delete event loop file from TP v2.0 docs delete event loop file from TP v2.0 docs * Removing event loop from sidebars Removing event loop from sidebars * Add changelog for UTP 1.3.0 (#801) * fix broken link to client driven sample (#804) * delete event loop file on main (#798) * delete event loop file on main delete event loop file on main, retaining on develop * Update TP v sidebars.js Update TP v sidebars.js removing from TOC * Update version-2.0.0-sidebars.json Co-authored-by: Brian Coughlin <[email protected]> * Fix broken link to client-driven sample Fix broken link to client-driven sample Co-authored-by: Brian Coughlin <[email protected]> Co-authored-by: Larah Armstrong <[email protected]> * Fix sidebar Co-authored-by: Christopher Pope <[email protected]> Co-authored-by: Brian Coughlin <[email protected]> Co-authored-by: Grave <[email protected]> Co-authored-by: Johann Ruwet <[email protected]> * MTT-4370: UTP 2.0 migration guide (#752) * Preliminary version of the UTP 2.0 migration guide * Address review comments * Mention breaking change in INetworkInterface.Initialize * Add sections on editor support and collections update * Preliminary version of the UTP 2.0 migration guide * Address review comments * Mention breaking change in INetworkInterface.Initialize * Add sections on editor support and collections update * Minor adjustments to the UTP 2.0 migration guide * Minor fixes Co-authored-by: Larah Armstrong <[email protected]> Co-authored-by: Larah Armstrong <[email protected]> Co-authored-by: Larah Armstrong <[email protected]> Co-authored-by: Grave <[email protected]> Co-authored-by: Johann Ruwet <[email protected]> Co-authored-by: Brian Coughlin <[email protected]> Co-authored-by: Simon Lemay <[email protected]> Co-authored-by: Larah Armstrong <[email protected]>

Preliminary version of the UTP 2.0 migration guide

d0b22a5

simon-lemay-unity requested review from cdmazom, s-omeilia-unity and johann-r-unity August 25, 2022 19:21

johann-r-unity approved these changes Aug 26, 2022

View reviewed changes

wackoisgod reviewed Aug 28, 2022

View reviewed changes

simon-lemay-unity added 2 commits August 29, 2022 15:36

Address review comments

c7625c8

Mention breaking change in INetworkInterface.Initialize

55e87c3

simon-lemay-unity and others added 6 commits September 6, 2022 16:17

Add sections on editor support and collections update

9c9e52b

Preliminary version of the UTP 2.0 migration guide

c1606ac

Address review comments

75b5032

Mention breaking change in INetworkInterface.Initialize

56c28ad

Add sections on editor support and collections update

d9ffc5a

Merge branch 'transport/migration-guide' of https://github.com/Unity-…

b90457d

…Technologies/com.unity.multiplayer.docs into transport/migration-guide

Minor adjustments to the UTP 2.0 migration guide

4ece254

armstrongl self-assigned this Sep 27, 2022

armstrongl marked this pull request as ready for review September 27, 2022 22:40

armstrongl requested review from johann-r-unity and wackoisgod September 27, 2022 22:40

johann-r-unity approved these changes Sep 28, 2022

View reviewed changes

Minor fixes

8c083ca

armstrongl approved these changes Sep 28, 2022

View reviewed changes

Merge branch 'develop' into transport/migration-guide

e07564f

armstrongl merged commit 54d1db0 into develop Oct 4, 2022

armstrongl deleted the transport/migration-guide branch October 4, 2022 19:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

MTT-4370: UTP 2.0 migration guide #752

MTT-4370: UTP 2.0 migration guide #752

Uh oh!

simon-lemay-unity commented Aug 25, 2022 •

edited by armstrongl

Loading

Uh oh!

johann-r-unity Aug 26, 2022

Uh oh!

johann-r-unity Aug 26, 2022

Uh oh!

armstrongl Sep 27, 2022

Uh oh!

johann-r-unity Sep 28, 2022

Uh oh!

wackoisgod Aug 28, 2022 •

edited

Loading

Uh oh!

wackoisgod commented Sep 5, 2022

Uh oh!

johann-r-unity commented Sep 5, 2022

Uh oh!

wackoisgod commented Sep 5, 2022

Uh oh!

johann-r-unity commented Sep 6, 2022

Uh oh!

wackoisgod commented Sep 6, 2022

Uh oh!

simon-lemay-unity commented Sep 6, 2022

Uh oh!

unity-cla-assistant commented Sep 27, 2022 •

edited

Loading

Uh oh!

Uh oh!


		It is thus recommended to ensure that clients and servers are updated at the same time, or to disallow older clients from connecting once the server is updated. Another strategy is to offer different endpoints for UTP 1.X and 2.0 servers, which could smooth the transition while older clients are updated.

		The reasons for this breaking change are to improve bandwidth efficiency, simplify the protocol, and (ironically) improve forward-compatibility of the protocol.


		## Other breaking changes

		* After calling `NetworkDriver.Disconnect`, notifying the remote peer of the disconnection now requires completing a `NetworkDriver.ScheduleUpdate` job. In 1.X, `NetworkDriver.ScheduleFlushSend` used to be sufficient for this purpose but it's not the case anymore.

MTT-4370: UTP 2.0 migration guide #752

MTT-4370: UTP 2.0 migration guide #752

Uh oh!

Conversation

simon-lemay-unity commented Aug 25, 2022 • edited by armstrongl Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johann-r-unity Aug 26, 2022

Choose a reason for hiding this comment

Uh oh!

johann-r-unity Aug 26, 2022

Choose a reason for hiding this comment

Uh oh!

armstrongl Sep 27, 2022

Choose a reason for hiding this comment

Uh oh!

johann-r-unity Sep 28, 2022

Choose a reason for hiding this comment

Uh oh!

wackoisgod Aug 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wackoisgod commented Sep 5, 2022

Uh oh!

johann-r-unity commented Sep 5, 2022

Uh oh!

wackoisgod commented Sep 5, 2022

Uh oh!

johann-r-unity commented Sep 6, 2022

Uh oh!

wackoisgod commented Sep 6, 2022

Uh oh!

simon-lemay-unity commented Sep 6, 2022

Uh oh!

unity-cla-assistant commented Sep 27, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

simon-lemay-unity commented Aug 25, 2022 •

edited by armstrongl

Loading

wackoisgod Aug 28, 2022 •

edited

Loading

unity-cla-assistant commented Sep 27, 2022 •

edited

Loading