fix: networktransform SwitchTransformSpaceWhenParented forces updates when InLocalSpace is true

[NoelStephensUnity]

Purpose of this PR

This PR resolves the issue where setting SwitchTransformSpaceWhenParented to true and then setting InLocalSpace to true will force the motion authority to continually send updates each tick (whether there is a delta or not).

Jira ticket

MTTB-1584

fix: #3653
fix: #3646
fix: #3645

Changelog

• Added: NetworkRigidbody documentation section.
• Fixed: NetworkTransform state synchronization issue when NetworkTransform.SwitchTransformSpaceWhenParented is enabled and the associated NetworkObject is parented multiple times in a single frame or within a couple of frames.
• Fixed: Issue when spawning, parenting, and immediately re-parenting.
• Changed: NetworkTransform now synchronizes NetworkTransform.SwitchTransformSpaceWhenParented when it is updated by the motion model authority.
• Changed: NetworkObjects pending to be shown to clients can now occur on partial network ticks. If any pending NetworkObjects pending to be shown to clients happens to be ready on a new network tick they still are shown after network variable deltas have been processed.
• Changed: The default NetworkDelivery used by all messages is now reliable fragmented sequenced with the exception of named, unnamed, and any messages sent with a user specified network delivery type. This assures certain order of operations to be preserved when same call-stack changes are applied to a newly spawned, authority side, NetworkObject.
• Changed: NetworkTransform documentation to better reflect the Teleport methods intended usage along with updates to NetworkObject and physics areas of the documentation.

Pending Changelog Update

• Changed: NetworkShow will now send a message at the end of the frame and will force a NetworkVariable synchronization prior to generating the CreateObjectMessage as opposed to waiting until the next network tick to synchronize the show with the update to NetworkVariables.

Documentation (WIP)

• Includes documentation for existing public API entry points:
  • Updates to the SwitchTransformSpaceWhenParented XML API that provides additional information about usage.
  • Updates to the SetState and Teleport for more clarity on intended usage for both network topologies.
  • Updates to NetworkObject.SpawnWithOwnership to call out how spawning with ownership can impact things like NetworkTransform during the spawning sequence when using a client-server topology.
• Includes updates to existing documentation:
  • Updates to NetworkTransform regarding the use of SwitchTransformSpaceWhenParented.
    • Add section covering spawning, order of operations, and how timing and network topology can impact the end result.
      • Include SetState/Teleport, spawning (with or without) ownership, and the authority motion model.
  • Updates to the NetworkObject spawning section
    • Expand the coverage to include:
      • Spawning then changing ownership vs SpawnWithOwnership
      • Spawning, NetworkTransform, and parenting.
  • Updated physics
    • Includes parenting physics objects using attachables.
  • Added a first pass (still could use some additions in the future) NetworkRigidbody section (pulled this part out of physics).

WIP Documentation

• Add a "Netcode best practices" section (covers message delivery, order, states & events, timing, and cost).
• Order of operations (under Netcode best practices)
  • Message delivery
    • Reliable Fragmented Sequenced
      • The sequenced portion assures messages are received in order
    • Add note about using a different network delivery can impact the order of operations.
      • Include some example scenarios of how changing the network delivery can impact the order of operations (include references to NeworkTransform, Rpcs, named, and unnamed messages).
  • Message queue order
    • What it is and when messages are queued vs deferred to be generated at the end of the frame.
  • Netcode script & message order
    • State updates and events
      • Everything boils down to messages
      • Local vs netcode states and events
    • Script order dictates message order
      • Messages are sent in the order they were created.
        • Messages are received in the order they were created on the sender's side.
    • Examples of how script can cause issues:
      • Add NetworkBehaviourReference and NetworkObjectReference example
        • Order of operations example that covers issues when sending a reference to a same frame locally spawned (with no observers) NetworkObject, changing ownership, showing, and then invoking an RPC (targeting client to show the object to) on an already spawned NetworkObject that uses a NetworkObjectReference and/or NetworkBehaviourReference as a parameter.
      • Add RPC order of operations documentation and the NetworkTransforms, parenting, ownership, and more.
      • Provide examples of issues with the solutions to resolving the issues.
  • Message cost
    • Observer vs no observer spawning and message cost.
    • Netcode design approach & message cost.
• Look for areas in existing documentation that makes sense to link back to appropriate sections in the Order of operations section.
• Update NetworkTransform unreliable delivery documentation and xml api to call out that it will impact the NetworkTransform's order of operations (when applied vs things like parenting, owenrship, etc).

Testing & QA (How your changes can be verified during release Playtest)

• Includes an integration test to validate the fix (NetworkTransformAutoParenting)
• Includes several additional integration tests to validate other edge case scenarios (WIP).
• Includes a manual test (need to import this small test into our manual tests)

Functional Testing

Manual testing :

• [ X ] Manual testing done
  • The original CharacterControllerMovingBodies project.
    • This verifies the existing functionality was not broken.
  • The manual test mentioned above that was used to replicate the user's issues and fix them.
    • This verifies (n) parenting events can occur on a single frame and it will be synchronized.

Automated tests:

• Covered by existing automated tests
• [ X ] Covered by new automated tests
  • (wip)

Does the change require QA team to:

• Review automated tests?
• Execute manual tests?
• Provide feedback about the PR?

If any boxes above are checked the QA team will be automatically added as a PR reviewer.

Backports

This is an NGO v2.x.x specific issue. No backport is required.

[jabbacakes]

Left suggestions on the smaller changes - have pushed a commit with changes to the larger new additions to the NetworkTransform page, mostly just trying to improve clarity and reduce verbiage.

This page is getting very long, might break it up at some point, but will do that in a separate PR.

[NoelStephensUnity]

/ci ngo

[NoelStephensUnity]

/ci ngo

[NoelStephensUnity]

/ci ngo

[NoelStephensUnity]

/ci ngo