com.unity.netcode.gameobjects icon indicating copy to clipboard operation
com.unity.netcode.gameobjects copied to clipboard

docs: additional order of operations and switch transform space when parented updates

Open NoelStephensUnity opened this issue 2 months ago • 0 comments

Purpose of this PR

This PR is a documentation extension PR from #3664.

Jira ticket

MTTB-1584 MTT-10092

Changelog

  • Added: TBD

Documentation Included

  • Includes new documentation sections.

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)

Functional Testing

Manual testing :

  • [ ] Manual testing done

Automated tests:

  • [ ] Covered by existing automated tests
  • [ ] Covered by new automated tests

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 PR is only for v2.x.

NoelStephensUnity avatar Oct 14 '25 20:10 NoelStephensUnity