Mttdoc309 object pool updates (#269)

* refactor and updates

This updates the object pooling example to reflect the changes from PR-977:
Unity-Technologies/com.unity.netcode.gameobjects#977

* additional notes

This adds additional information about using more than one prefab with an override.
This also adds a link to the to-be-existing folder in the master branch.

* refactor

Removed some code from advanced example that was not being used.

* refactor 

Updating to most recent changes from PR-955 (yet to be merged)

* MTTDOC-317 initial page creation

* #MTTDOC-317 update to main page

* refactor

making changes to reflect the final version that was merged into the develop branch.

* MTTDOC-317 updating to ensure successful build

* MTTDOC-317 fixing some typos and naming

* update

Ran through this one more time removing any references to MLAPI.
I also tried to improve upon the text copy flow (might need a second pair of eyes)

* update 

minor language tweak and italicized the reference to object pooling link

* update

left out the trailing *

* Update object-pooling.md

* Update object-pooling.md

* Update object-pooling.md

* Delete networktime-ticks.md

Co-authored-by: Brian Coughlin <brian.coughlin@unity3d.com>
Co-authored-by: Briancoughlin <76997526+Briancoughlin@users.noreply.github.com>

Author: NoelStephensUnity

docs/advanced-topics/object-pooling.md

@@ -3,23 +3,33 @@ id: object-pooling
 title: Object Pooling
 ---
 
-The MLAPI provides built-in support for Object Pooling, which allows you to override the default MLAPI destroy and spawn handlers with your own logic.  This allows you to store destroyed network objects in a pool to reuse later. This is useful for frequently used objects, such as projectiles, and is a way to increase the application's overall performance by decreasing the amount of objects being created over time.
+Object pooling is useful for frequently used objects, such as projectiles, and is a way to increase the application's overall performance by decreasing the amount of objects being created over time.  Netcode for GameObjects (Netcode) provides built-in support for Object Pooling where a `NetworkObject`'s default destroy and instantiate handlers can be overridden.  
 
 See [Introduction to Object Pooling](https://learn.unity.com/tutorial/introduction-to-object-pooling) to learn more about the importance of pooling objects.
 
 ## NetworkPrefabInstanceHandler
 
-You can register your own spawn handlers by including the `INetworkPrefabInstanceHandler` interface and registering with the `NetworkPrefabHandler`.  
+You can create your own spawn handler by implementing the `INetworkPrefabInstanceHandler` interface and registering it with the `NetworkPrefabHandler`.
+
 ```csharp
     public interface INetworkPrefabInstanceHandler
     {
         NetworkObject Instantiate(ulong ownerClientId, Vector3 position, Quaternion rotation);
         void Destroy(NetworkObject networkObject);
     }
 ```
-MLAPI will use the `Instantiate` and `Destroy` methods in place of default spawn handlers for the `NetworkObject` used during spawning and despawning.  Because the message to instantiate a new `NetworkObject` originates from a Host or Server, both will not have the Instantiate method invoked. All clients (excluding a Host) will have the instantiate method invoked if the `INetworkPrefabInstanceHandler` implementation is  registered with `NetworkPrefabHanlder` (`NetworkManager.PrefabHandler`) and a Host or Server spawns the registered/associated `NetworkObject`.
+
+Once your implementation is registered, Netcode will use your implementation's `Instantiate` and `Destroy` methods in place of the default spawn handlers for the `NetworkObject` prefab you specify during the registration process. Your `NetworkObject` prefab is uniquely identified by its `GlobalObjectIdHash` value. Because a Server (or host) controls the spawning and despawning of `NetworkObject`s, the instantiate method will not be invoked.  All clients (excluding a Host) will have the `Instantiate` method invoked if the `INetworkPrefabInstanceHandler` implementation is registered with `NetworkPrefabHanlder` (`NetworkManager.PrefabHandler`) and a Host or Server spawns the registered/associated `NetworkObject` that is uniquely identified by its `GlobalObjectIdHash` value.
+
+## Basic Pooling Example
 
 In the following basic pooling example, the `m_ObjectToPool` property is the prefab we want to pool.  We register the `NetworkPrefabHandlerObjectPool` class (that implements the `INetworkPrefabInstanceHandler` interface) using the `m_ObjectToPool`'s `GameObject` with a reference to the current instance of `NetworkPrefabHandlerObjectPool`.  We also take into account any `NetworkManager` defined `NetworkPreab` overrides by calling `NetworkManager.GetNetworkPrefabOverride` while both assigning and passing in our `m_ObjectToPool`.  
+
+<details open>
+<summary>Click to show/hide the Code.
+
+</summary>
+
 ```csharp
 using System.Collections;
 using System.Collections.Generic;
@@ -151,23 +161,28 @@ public class NetworkPrefabHandlerObjectPool : NetworkBehaviour, INetworkPrefabIn
 }
 
 ```
+</details>
+
+## Advanced Pooling Example
+
+The next example is more advanced.  The `m_ObjectToOverride` property is the prefab we will replace with one of the `m_ObjectOverrides` prefabs.  As such, we register the `NetworkPrefabHandlerObjectPoolOverride` class (that implements the `INetworkPrefabInstanceHandler` interface) using the `m_ObjectToOverride`.  We then have to handle a special case scenario.  
+
+Since a Host is actually both a client and a server, we need to pre-register the link (association) between the `m_ObjectToOverride` prefab and the `m_ObjectOverrides` prefabs.  We do this by calling `NetworkManager.PrefabHandler.RegisterHostGlobalObjectIdHashValues` and passing in the `m_ObjectToOverride` and the `m_ObjectOverrides` list.  For both the Client and Host, we will create a pool for each prefab type in the m_ObjectOverrides list. If we are just a server (i.e. not a Host), then we only need to create a large pool containing only one prefab type:  `m_ObjectToOverride`. 
+
+ We included this example in order to show that the common link between all instances is the `m_ObjectToOverride`'s GlobalObjectIdHash value.  The `m_ObjectToOverride`'s GlobalObjectIdHash value is always used to signal the creation or destruction for all messages pertaining this prefab handler override.      
+
+<details open>
+<summary>Click to show/hide the Code.
+
+</summary>
 
-In the next more advanced example, the `m_ObjectToOverride` property is the prefab we will replace with one of the `m_ObjectOverrides` prefabs.  As such, we register the `CustomPrefabHandlerObjectPoolOverride` class (that implements the `INetworkPrefabInstanceHandler` interface) using the `m_ObjectToOverride` with a reference to the current instance of `CustomPrefabHandlerObjectPoolOverride`.  We then have to handle a special case scenario.  Since a Host is actually both a client and a server, we need to pre-register the link (association) between the `m_ObjectToOverride` prefab and the `m_ObjectOverrides` prefabs.  We do this by calling `NetworkManager.PrefabHandler.RegisterHostGlobalObjectIdHashValues` and passing in the `m_ObjectToOverride` and the `m_ObjectOverrides` list.  For both the Client and Host, we will create a pool for each prefab type in the m_ObjectOverrides list. If we are just a server (i.e. not a Host), then we only need to create a large pool containing only one prefab type:  `m_ObjectToOverride`.  We included this example in order to show that the common link between all instances is the `m_ObjectToOverride`'s GlobalObjectIdHash value.  The `m_ObjectToOverride`'s GlobalObjectIdHash value is always used to signal the creation or destruction for all messages pertaining this prefab handler override.      
 
 ```csharp
 using System.Collections;
 using System.Collections.Generic;
 using UnityEngine;
 using Unity.Netcode;
 
-/// <summary>
-/// This is an example of using more than one Network Prefab override when using a custom handler
-/// USAGE NOTE: When using more than one network prefab, it is important to understand that each
-/// client determines what prefab they will be using and will not be synchronized across other clients.
-/// This feature is primarily to be used for things like platform specific Network Prefabs where
-/// things like collision models or graphics related assets might need to vary between platforms.
-/// The usage of different visual assets used is strictly for example purposes only.
-/// </summary>
 public class NetworkPrefabHandlerObjectPoolOverride : NetworkBehaviour, INetworkPrefabInstanceHandler
 {
     private GameObject m_ObjectToPool;
@@ -344,10 +359,20 @@ public class NetworkPrefabHandlerObjectPoolOverride : NetworkBehaviour, INetwork
     }
 }
 ```
+</details>
+
+Registering `INetworkPrefabInstanceHandler` implementations with the `NetworkPrefabHandler` simplifies object pooling.  It also provides the option to have different versions for the same `NetworkObject` instance as it is viewed by Clients (including the Host). Additionally, you do not need to register the network prefabs assigned to the `m_ObjectOverrides` list with the `NetworkManager` since each local overriding prefab instance is linked by the `NetworkObject.NetworkObjectId`.  
+
+:::caution
+
+You **must** register the prefab to be overridden (i.e. `m_ObjectToOverride` in the above example).  While this provides many possibilities, you must also take caution when using multiple prefabs as overrides by making sure that every variation has the same associated `NetworkVariables` and `RPC` implementations as all variations **must be identical** in this regard when it comes to anything that could be communicated between the client(s) and server. Otherwise, you could end up with messages being sent to override instances that don't know how to handle them!  
 
-Using `INetworkPrefabInstanceHandler` implementations simplifies object pooling while also providing the ability to have different versions for the same NetworkObject instance as it is viewed by Clients (including the Host). Additionally, you do not need to register the network prefabs assigned to the `m_ObjectOverrides` list with the NetworkManager since each local overriding prefab instance is linked by the `NetworkObject.NetworkObjectId`.  However, you **do** need to register the prefab to be overridden (i.e. `m_ObjectToOverride` in the above example).  While this provides many possibilities, you must take caution when using multiple prefabs as overrides by making sure that every variation has the same associated `NetworkVariables` and `RPC` implementations as all variations **must be identical** in this regard when it comes to anything that could be communicated between the client(s) and server. Otherwise, you could end up with messages being sent to override instances that don't know how to handle them!  
+:::
 
 When using more than one network prefab, it is important to understand that each client determines what prefab they will be using and will not be synchronized across other clients. This feature is primarily to be used for things like platform specific Network Prefabs where things like collision models or graphics related assets might need to vary between platforms.
 
-You can find full working versions of the above two examples in the [testproject/Assets/Samples/PrefabPool](https://github.com/Unity-Technologies/com.unity.multiplayer.mlapi/tree/master/testproject/Assets/Samples/PrefabPool) repository directory.
+You can find full working versions of the above two examples in the [testproject/Assets/Samples/PrefabPool](https://github.com/Unity-Technologies/com.unity.multiplayer.mlapi/tree/develop/testproject/Assets/Samples/PrefabPool) repository directory.
 
+:::contribution Special Thanks
+This guide would not have been possible without the hard work and support of Noel Stephens, Unity. 
+:::

docs/getting-started/maxnumberplayers.md

@@ -0,0 +1,32 @@
+---
+id: max-players
+title: Limiting the maximum number of players
+---
+
+
+Netcode for Gameobjects (Netcode) provides a way to implement a [connection approval delegate](../mlapi-api/MLAPI.NetworkManager.ConnectionApprovedDelegate.md) that can reject incoming connections based on custom logic.
+​
+
+
+Boss Room provides an example of such delegate
+
+```csharp reference
+https://github.com/Unity-Technologies/com.unity.multiplayer.samples.coop/blob/63ecd92e1c72b87cd87cc3cbc1de77da4271b720/Assets/BossRoom/Scripts/Server/Net/ServerGameNetPortal.cs#L242
+```
+​
+The code below shows an example of an over-capacity check that would prevent more than a certain pre-defined numebr of players from connecting.
+​
+```csharp
+if( m_ClientData.Count >= CharSelectData.k_MaxLobbyPlayers )
+{
+    gameReturnStatus = ConnectStatus.ServerFull;
+}
+```
+​
+:::tip**SUIBJECT TO CHANGE:**
+​
+In connection approval delegate Netcode does not support an ability to send anything more than a boolean back. 
+Boss Room demonstrates a way to provide meaningful error code to the client by invoking a client RPC in the same channel that Netcode uses for its connection callback.
+This will become unneccessary in the future.
+:::
+

docs/reference/glossary/network-latency-management.md

@@ -34,7 +34,7 @@ Extrapolation is an attempt to estimate a future game state. On receipt of a pac
 
 The client will normally assume that a moving object will continue in the same direction. When a new packet is received, the position may be updated.
 
-For MLAPI, extrapolation is used in [`NetworkTransform`](../../components/networktransform.md) and is estimated between the time a tick advances in server-side animation and the update of the frame on the client-side. The game object extrapolates the next frame's values based on the ratio. 
+For Netcode for Gameobjects (Netcode), extrapolation is used in [`NetworkTransform`](../../components/networktransform.md) and is estimated between the time a tick advances in server-side animation and the update of the frame on the client-side. The game object extrapolates the next frame's values based on the ratio. 
 
 ## Interpolation Period
 
@@ -152,4 +152,5 @@ A tick or simulation rate of 60Hz will cause less delay than a tick rate of 30Hz
 
 When a server gets close to the limit, or even fails to process a tick inside that timeframe, then you will instantly notice the results: all sorts of strange gameplay issues like rubber banding, players teleporting, hits getting rejected, and physics failing.
 
+
 import ImageSwitcher from '@site/src/ImageSwitcher.js';

sidebars.js

@@ -89,6 +89,10 @@ module.exports = {
         "type": "doc",
         "id": "getting-started/connection-approval"
       },
+      {
+        "type": "doc",
+        "id": "getting-started/max-players"
+      },
       {
         "type": "doc",
         "id": "mlapi-basics/networkobject"

versioned_docs/version-0.1.0/reference/glossary/network-latency-management.md

@@ -34,7 +34,7 @@ Extrapolation is an attempt to estimate a future game state. On receipt of a pac
 
 The client will normally assume that a moving object will continue in the same direction. When a new packet is received, the position may be updated.
 
-For MLAPI, extrapolation is used in [`NetworkTransform`](../../mlapi-api/MLAPI.Prototyping.NetworkTransform.md) and is estimated between the time a tick advances in server-side animation and the update of the frame on the client-side. The game object extrapolates the next frame's values based on the ratio. 
+For Netcode for Gameobjects (Netcode), extrapolation is used in [`NetworkTransform`](../../mlapi-api/MLAPI.Prototyping.NetworkTransform.md) and is estimated between the time a tick advances in server-side animation and the update of the frame on the client-side. The game object extrapolates the next frame's values based on the ratio. 
 
 ## Interpolation Period