OnGainedOwnership() not called on client when SpawnWithOwnership() is called

[MisterIXI]

Description

When I use SpawnWithOwnership() to spawn an object for a player/client directly I'd expect that OnGainedOwnership() gets called either on the target client or not at all. Instead it gets called on the server only. According to #2023 the call on the server is intended behaviour.
But as I'm still new to Netcode I was very confused and thought I did something wrong. The Ownership gets assigned as expected though, and it turns out the method is just not called on one side.

In the docs for OnGainedOwnership() it states that "Gets called when the local client gains ownership of this object"
Which is misleading if this is intended, since the sole instance that calls the method doesn't even have ownership in that moment.

The feature request #1002 also touches on this problem.

Is this intended behaviour or a bug?

Reproduce Steps

1. Create a NetworkBehaviour with the OnGainedOwnership() method overridden (with a Debug.Log() e.g.)
2. Spawn it from the server with SpawnWithOwnership()
3. See that it the overridden method only gets called on the server, not the client

Actual Outcome

OnGainedOwnership() is only called on Server when an NetworkObject with SpawnWithOwnership() for a different client is used.

Expected Outcome

OnGainedOwnership() should be called on the client referenced by the clientID in the SpawnWithOwnership(). (+ on server side if intended)

Screenshots

--

Environment

• OS: Windows 10
• Unity Version: 2021.3.13f1
• Netcode Version: 1.2.0

Additional Context

I have attached the 3 files I created quickly to recreate the issue in an empty project.
SampleProject.zip

[NoelStephensUnity]

@MisterIXI
This is a documentation issue (or lack of) as change in ownership notifications only occur when the ownership changes after being spawned. When a NetworkObject is spawned it is considered "the first/original" ownership state for the NetworkObject. So, if you spawn with ownership then its "initial" ownership state is set to the client identifier that you specified. Now, if you were to change the ownership after it has been spawned, then the OnGainedOwnership and OnLostOwnership methods would be invoked (relative to who lost ownership and who gained ownership).

Does this make more sense?

I will do a pass on both the API and documentation side that better clarifies how changes in ownership notifications work.

[MisterIXI]

@NoelStephensUnity I understand, at least on the client side.
The server calls the function OnGainedOwnership and is not the Owner during the call, which makes me think that it gets called while the client gets the Ownership assigned. And this still seems kind of odd. I guess if it is a case of "every time someone gains ownership, even on spawns" it would be right, but it would not align with what you just explained. Or am I still missing something?
(Also I just tested, and OnGainedOwnership fires on the server regardless if Spawn or SpawnWithOwnership is used)

In total I'd agree that OnGainedOwnership shouldn't be called for the initial spawn. But since it fires every time on the server whenever something is spawned, it tricked me into expecting the other behaviour. Which led me to this question in the first place.

A clarification in the docs might definitely suffice. 👍