Skip to main content

MLAPI 0.1.0 - 2021-03-23

The Multiplayer v0.1.0 Experimental release contains features, updates, bug fixes, and refactoring for the first release of MLAPI for Unity.

ProductVersionStatusRelease DateSupported Unity Versions
MLAPI0.1.0ExperimentalMarch 23, 20212019.4 and later
note

Unity MLAPI supports Windows and MacOS versions of Unity Editor and Player.

New features#

This release provides the following new features and APIs:

  • Refactored a new standard for Remote Procedure Call (RPC) in MLAPI which provides increased performance, significantly reduced boilerplate code, and extensibility for future-proofed code. MLAPI RPC includes ServerRpc and ClientRpc to execute logic on the server and client-side. This provides a single performant unified RPC solution, replacing MLAPI Convenience and Performance RPC (see here). For information on compatibility and deprecations, see RPC Migration and Compatibility.

  • Added standarized serialization types, including built-in and custom serialization flows. See About Serialization for details.

  • INetworkSerializable interface replaces IBitWritable.

  • Added NetworkSerializer..., which is the main aggregator that implements serialization code for built-in supported types and holds NetworkReader and NetworkWriter instances internally.

  • Added a Network Update Loop infrastructure that aids Netcode systems to update (such as RPC queue and transport) outside of the standard MonoBehaviour event cycle. See Network Update Loop and the following details:

    • It uses Unity's low-level Player Loop API and allows for registering INetworkUpdateSystems with NetworkUpdate methods to be executed at specific NetworkUpdateStages, which may also be before or after MonoBehaviour-driven game logic execution.
    • You will typically interact with NetworkUpdateLoop for registration and INetworkUpdateSystem for implementation.
    • NetworkTickSystem tracks time through network interactions and syncs NetworkVariables, used in this update loop.
  • Added message batching to handle consecutive RPC requests sent to the same client. RpcBatcher sends batches based on requests from the RpcQueueProcessing, by batch size threshold or immediately.

  • GitHub 494: Added a constraint to allow one NetworkObject per GameObject, set through the DisallowMultipleComponent attribute.

  • Integrated MLAPI with the Unity Profiler for versions 2020.2 and later:

    • Added new profiler modules for MLAPI that report important network data.

    • Attached the profiler to a remote player to view network data over the wire.

    • When installed you will see the following modules in the Unity UI:

tip

A test project is available for building and experimenting with MLAPI features. This project is available in the MLAPI GitHub testproject folder.

We also provide a new Hello World example to walk through installation to building your first networked game.

MLAPI Community Contributions is a new GitHub repository open to the MLAPI community for extensions. Current extensions include moved MLAPI features for lag compensation (useful for Server Authoritative actions) and TrackedObject.

Changes#

This release includes the following updates:

  • MLAPI now uses the Unity Package Manager for installation management.
  • Added functionality and usability to NetworkVariable, previously called NetworkVar. Updates enhance options and fully replace the need for SyncedVars.
  • GitHub 507: Reimplemented NetworkAnimator, which synchronizes animation states for networked objects.

Refactored API names#

For users of previous versions of MLAPI, this release renames APIs due to refactoring. All obsolete marked APIs have been removed as per GitHub 513.

Previous MLAPI VersionsV 0.1.0 Name
NetworkingManagerNetworkManager
NetworkedObjectNetworkObject
NetworkedBehaviourNetworkBehaviour
NetworkedClientNetworkClient
NetworkedPrefabNetworkPrefab
NetworkedVarNetworkVariable
NetworkedTransformNetworkTransform
NetworkedAnimatorNetworkAnimator
NetworkedAnimatorEditorNetworkAnimatorEditor
NetworkedNavMeshAgentNetworkNavMeshAgent
SpawnManagerNetworkSpawnManager
BitStreamNetworkBuffer
BitReaderNetworkReader
BitWriterNetworkWriter
NetEventTypeNetworkEventType
ChannelTypeNetworkDelivery
ChannelNetworkChannel
TransportNetworkTransport
NetworkedDictionaryNetworkDictionary
NetworkedListNetworkList
NetworkedSetNetworkSet
MLAPIConstantsNetworkConstants

Refactoring includes the following changes:

  • GitHub 444 and 455: Channels are now represented as bytes instead of strings.

  • GitHub 514: Refactored and updated code to use the following:

    • Apply Unity C# standards across the entire MLAPI framework.
    • Use string interpolation over string concatenation with + (plus) operator.
    • Use var instead of full types when it is obvious from the right side of the statement. For example: var targetScript = scriptProperty.objectReferenceValue as MonoScript; instead of MonoScript targetScript
    • Use nameof operator when possible. For example: Debug.LogError($"{nameof(ILPostProcessor)} Error - {message.MessageData} {message.File}:{message.Line}");
    • Use explicit access modifiers.

Removed features#

With a new release of MLAPI in Unity, some features have been removed:

  • SyncVars have been removed from MLAPI. Use NetworkVariables in place of this functionality.

  • GitHub 527: Lag compensation systems and TrackedObject have moved to the new MLAPI Community Contributions repo.

  • GitHub 509: Encryption has been removed from MLAPI. The Encryption option in NetworkConfig on the NetworkingManager is not available in this release. This change will not block game creation or running. A current replacement for this functionality is not available, and may be developed in future releases. See the following changes:

    • Removed SecuritySendFlags from all APIs.
    • Removed encryption, cryptography, and certificate configurations from APIs including NetworkManager and NetworkConfig.
    • Removed "hail handshake", including NetworkManager implementation and NetworkConstants entries.
    • Modified RpcQueue and RpcBatcher internals to remove encryption and authentication from reading and writing.
  • Removed the previous MLAPI Profiler editor window from Unity versions 2020.2 and later.

  • Removed previous MLAPI Convenience and Performance RPC APIs with the new standard RPC API.

  • GitHub 520: Removed the MLAPI Installer.

  • Fixed an issue with NetworkSceneManager, where users received a “soft synch” exception typically followed by a null reference exception on the client side when the host or server invoked the NetworkSceneManager.SwitchScene method. Transitioning between in-game session scenes, where the scene being transitioned into contains one or more manually placed GameObject(s) with the NetworkObject component attached, should no longer cause MLAPI to throw exceptions. This fix should improve the overall stability of scene-to-scene transitions for the user.

Fixes#

This release includes the following issue fixes:

  • GitHub 460: Fixed an issue for RPC where the host-server was not receiving RPCs from the host-client and vice versa without the loopback flag set in NetworkingManager.
  • Fixed an issue where data in the Profiler was incorrectly aggregated and drawn, which caused the profiler data to increment indefinitely instead of resetting each frame.
  • Fixed an issue the client soft-synced causing PlayMode client-only scene transition issues, caused when running the client in the editor and the host as a release build. Users may have encountered a soft sync of NetworkedInstanceId issues in the NetworkSpawnManager.ClientCollectSoftSyncSceneObjectSweep method.
  • GitHub 458: Fixed serialization issues in NetworkList and NetworkDictionary when running in Server mode.
  • GitHub 498: Fixed numerical precision issues to prevent not a number (NaN) quaternions.
  • GitHub 438: Fixed booleans by reaching or writing bytes instead of bits.
  • GitHub 519: Fixed an issue where calling Shutdown() before making NetworkManager.Singleton = null is null on NetworkManager.OnDestroy().
  • Fixed an issue with NetworkSceneManager, where users received a “soft synch” exception typically followed by a null reference exception on the client side when the host or server invoked the NetworkSceneManager.SwitchScene method. Transitioning between in-game session scenes, where the scene being transitioned into contains one or more manually placed GameObject(s) with the NetworkObject component attached, should no longer cause MLAPI to throw exceptions. This fix should improve the overall stability of scene-to-scene transitions for the user.

Known issues#

Review the following known issues with this release:

  • NetworkNavMeshAgent does not synchronize mesh data, Agent Size, Steering, Obstacle Avoidance, or Path Finding settings. It only synchronizes the destination and velocity, not the path to the destination.
  • For RPC, methods with a ClientRpc or ServerRpc suffix which are not marked with [ServerRpc] or [ClientRpc] will cause a compiler error.
  • For NetworkAnimator, Animator Overrides are not supported. Mechanism trigger parameters (such as auto resetting tools) do not work.
  • For NetworkVariable, the NetworkDictionary List and Set must use the reliableSequenced channel.
  • NetworkObjectss are supported but when spawning a prefab with nested child network objects you have to manually call spawn on them
  • NetworkTransform has the following issues:
    • Replicated objects may have jitter.
    • The owner is always authoritative about the object's position.
    • Scale is not synchronized.
  • Connection Approval is not called on the host client.
  • For NamedMessages, always use NetworkBuffer as the underlying stream for sending named and unnamed messages.
  • NetworkManager have the following issues:
    • Connection management is limited. Use IsServer, IsClient, IsConnectedClient, or other code to check if MLAPI connected correctly.
    • Adding a GameObject with a NetworkObject component as a child to a GameObject that is assigned the NetworkManager component will cause a soft synchronization error. Avoid assigning NetworkObjects to a GameObject with the NetworkManager.

Upgrade guide#

If using UNet, see the Migrating From UNet to MLAPI.

If using previous versions of MLAPI, see Updating to the Unity Package.

Learn more#

See the Unity Multiplayer MLAPI repository to learn more about contributing, open issues, and in-progress development.

To provide feedback and content on documentation, see the links at the bottom of each page.