WorldPositionStays update

[NoelStephensUnity]

The update to this documentation should not be merged until NGO v1.1.0 is available.

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:
PR-2146 WorldPositionStays and parenting fixes/updates.

Issue Number:
MTT-4616

[armstrongl]

• Setting the parent of a child's Transform directly (for example, transform.parent = childTransform;) will always use the default WorldPositionStays value of true.

I'm not sure I understand what this sentence is saying. Are you saying that if you directly set the parent of a child's Transform, the WorldPositionStays value will always be true?

[NoelStephensUnity]

Yes.

// WorldPositionStays defaults to true, clients are not synchronized but since this is the default it is the same as if it was synchronized
NetworkObject.transform.parent = parent.transform;  
// WorldPoisitonStays defaults to true, clients are not synchronized but since this is the default it is the same as if it was synchronized
NetworkObject.transform.SetParent(parent.transform);  
// WorldPositionStays will be false, but will not synchronize clients
NetworkObject.transform.SetParent(parent.transform, false); 
// WorldPositionStays will always be true (like the transform.SetParent), but NGO will synchronize this with clients
NetworkObject.TrySetParent(parent); 
// WorldPositionStays is false and NGO will synchronize this with clients
NetworkObject.TrySetParent(parent, false); 

[armstrongl]

It is recommended to always use the NetworkObject.TrySetParent method when parenting if you plan on changing the WorldPositionStays default value.

I'm not a huge fan of this phrasing because it starts by saying that the user should always use the NetworkObject.TrySetParent method, then continues to say that they shouldn't always; only if they plan to change the default value of WorldPositionStays

How does this sound?

It's best practice to use the NetworkObject.TrySetParent method when parenting if you anticipate changing the default value of WorldPositionStays.

[NoelStephensUnity]

I like that better too!

[armstrongl]

When a server parents a spawned NetworkObject under another spawned NetowrkObject during a netcode game session, this parent-child relationship is replicated across the network to all connected and future late-joining clients.

Side question: what replicates the parent-child relationship across all clients?

[NoelStephensUnity]

The server sends a ParentSyncMessage to all clients when a NetworkObject's parenting status changes.
Really, now that I am reading over all of this...I think we should possibly have a couple of sections on parenting. Possibly an introduction section that describes how a server synchronizes clients with parenting changes (which we could dive into these kinds of details there), another that uses a very simple parenting walk through, and then a section that describes more advanced topics like how a child's scale is impacted by its parent and how WorldPositionStays impacts position, rotation, and scale.... perhaps that too could be broken into two or more sections.

[armstrongl]

I think that's a great idea! if you start a draft, I'm more than happy to help :)

[armstrongl]

If you nest an in-scene placed NetworkObjects under a GameObject without a NetworkObject component, that hierarchy is preserved until the parent is removed.

Or

If you nest an in-scene placed NetworkObjects under a GameObject without a NetworkObject component, NGO preserves that hierarchy until the parent is removed.

[NoelStephensUnity]

I see your point on the grammar/flow... I was trying to convey that "while you are in the editor if you nest an in-scene placed..."
The fact that you think it needs rephrasing means that my attempt to convey that in as short of a sentence possible failed...
😄
So, the idea is:
If, while editing a scene, a user nests an in-scene placed NetworkObject under a GameObject with no NetworkObject component then that parenting relationship will be preserved until the user removes (during runtime) the GameObject parent from the child NetworkObject.

[NoelStephensUnity]

It seems complex...but Unity parenting is complex... just it isn't noticeable until you try to synchronize other instances...then it becomes a complex (using the NGO v1.x.x architecture) topic. 😿

[armstrongl]

If, while editing a scene, a user nests an in-scene placed NetworkObject under a GameObject with no NetworkObject component then that parenting relationship will be preserved until the user removes (during runtime) the GameObject parent from the child NetworkObject.

This sounds much better, actually! I might just make a few tweaks:

If, while editing a scene, a user nests an in-scene placed NetworkObject under a GameObject with no NetworkObject component, then NGO preserves that parenting relationship until the user (during runtime) removes the GameObject parent from the child NetworkObject.

[armstrongl]

Netcode for GameObjects does not allow you to re-parent the NetworkObject under the same or another GameObject that has no NetworkObject component.

[NoelStephensUnity]

That works too!

[armstrongl]

NGO immediately reverts invalid or unsupported NetworkObject parenting to the original parenting status.

[NoelStephensUnity]

That is simpler, less to read, and conveys the same point.
I like it!

[armstrongl]

You must synchronize clients before parenting players with in-scene placed NetworkObject. Because a server can only perform parenting-related actions, the server must have already received the NetworkSceneManager generated SceneEventType.SynchronizeComplete message before the server can parent the client's player NetworkObject.

I'm not sure about the correctness of this revision. I leave it to your expertise 😄 .

[NoelStephensUnity]

Uh...yeah that whole section I still am not happy with.

Basically this is what I am trying to convey:
Since in-scene placed NetworkObjects are spawned after the scene they are placed within has loaded, parenting of in-scene placed NetworkObjects under players requires that the clients first load the scene containing the in-scene placed NetworkObject before it can be parented under a player NetworkObject. As such, the server-side should receive the client's SceneEventType.SynchronizeComplete or SceneEventType.LoadComplete event before attempting to parent the in-scene placed NetworkObject under the player.

[armstrongl]

Dang, NetworkObject parenting is complicated. I had to step away and come back to this 😅

Let me try to break this down...

• NetworkObjects you place in-scene spawn after the scene (that they are placed in) loads.
• As a result:
  • The player's client must load the scene (containing the in-scene NetworkObject) before making the player the parent of the in-scene NetworkObject.
  • As a result:
    • You should (must?) receive the client's SceneEventType.SynchronizeComplete or SceneEventType.LoadComplete event server-side before you attempt to make the player the parent of the in-scene NetworkObject.

Am I getting it?

[armstrongl]

When using the NetworkObject.TrySetParent or NetworkObject.TryRemoveParent methods, the WorldPositionStays parameter is synchronized with currently connected and late-joining clients. You should use the same WorldPositionStays value that was used to parent the child when removing a child from its parent. More specifically, when WorldPositionStays is set to false, this applies, but if you are using the default value of true, then this is not required (because it is the default).

[NoelStephensUnity]

Yeah... that adjustment in the middle has a better flow to it.

[armstrongl]

When the WorldPositionStays parameter in NetworkObject.TrySetParent is the default value of true, NGO preserves the world space values of the child NetworkObject relative to the parent. However, sometimes you might want only to preserve the local space values (that is, pick up an object that only has some initial changes to the child's transform when parented). You can accomplish this without needing a NetworkTransform through a combination of NetworkObject.TrySetParent and NetworkBehaviour.OnNetworkObjectParentChanged. To better understand how this works, it is important to understand the order of operations for both of these two methods:

[NoelStephensUnity]

We are allowed to use NGO?

[armstrongl]

That's a good question - one I've been wondering, too. In the gaming service documentation (e.g., Relay), we refer to Netcode for GameObjects as NGO (after introducing the acronym). Maybe that's not how we want to refer to it, though. Especially since we called it "netcode" everywhere else, this confused me a bit when I first started working with netcode.

Do you know who might be able to say authoritatively what we should and shouldn't use to refer to netcode?

[armstrongl]

Server-Side

• NetworkObject.TrySetParent invokes NetworkBehaviour.OnNetworkObjectParentChanged.
  • You can adjust the child's position, rotation, and scale in the overridden OnNetworkObjectParentChanged method.
• The ParentSyncMessage is generated, the transform values are added to the message, and the message is sent.
  • ParentSyncMessage includes the child's position, rotation, and scale
    • NGO synchronizes currently-connected and late-joining clients with the parenting and the child's associated transform values.

When to use a NetworkTransform
If you anticipate the child NetowrkObject moving around, rotating, or scaling independently (when parented or not), you should use a NetworkTransform.
If you only plan on making a one-time adjustment to the child NetworkObject's transform when parented, you do not need NetworkTransform (if you set WorldPositionStays to false when parenting the child).

[NoelStephensUnity]

Yeah... that is nice too.