Build a session with Netcode for Entities#

Build a multiplayer game with sessions using Netcode for Entities for projects using DOTS.

Similar to Build a session with Netcode for GameObjects, use the principles of Multiplayer Services sessions to create one capsule controlled by the session's host and the other capsule controlled by the joining player. However, this time, use Network for Entities, which is part of Unity's Data-Oriented Technology Stack (DOTS).

Prerequisites#

In addition to the Multiplayer Services package, ensure that you install the following packages through the Unity Registry in the Editor's Package Manager:

• Widgets (or com.unity.multiplayer.widgets): Enables you to test multiplayer services without having to write code.
• Multiplayer Play Mode (or com.unity.multiplayer.playmode): Enables you to test multiplayer functionality without leaving the Unity Editor.
• Packages required by Netcode for Entities, which include entities, entities graphics, and networking capabilities:
  • Netcode for Entities (or com.unity.netcode), version 1.3.0 or later.

    Note: This also installs the corresponding Entities package.

  • Entities Graphics (or com.unity.entities.graphics), version 1.3.0 or later.

If Netcode for GameObjects is installed, then remove the package to avoid conflicts.

Configure Multiplayer Play Mode#

To configure Play Mode for your project to test multiple players:

1. In the Unity Editor, go to Window > Multiplayer > Multiplayer Play Mode.
2. In the Multiplayer Play Mode window, enable Player 2.

After you add Player 2, you can test the project with a second window.

Configure Build Profiles and Project Settings#

You must add the current scene to the build to enter Play Mode.

To add the current scene to the build:

1. In the Unity Editor, select File > Build Profiles.
2. Select Open Scene List.
3. Select Add Open Scenes.
4. Close Build Profiles.

Your project should also run in the background to prevent dropped connections while testing, for example when switching to a different window.

To update your game to run in the background:

1. Select Edit > Project Settings > Player > Resolution and Presentation.
2. Enable Run in Background.
3. Close Project Settings.

Create an initial scene#

Set up a way to share data between the client and the server in Netcode for Entities:

1. Right-click (macOS: Ctrl+click) within the Hierarchy window in the Unity Editor.
2. Select New Sub Scene > Empty Scene.
3. Name the new scene SharedData.unity.

This new scene sets up a method for data sharing between the client and server by creating a different World for the server and each client, using the Entities package.

Create a ghost prefab#

To synchronize data across a client and server setup, create a definition of the networked object, called a ghost.

To create a ghost prefab:

1. In the Hierarchy window, right-click (macOS: Ctrl+click) on the new scene.
2. Select GameObject > 3D Object > Capsule.
3. Rename the capsule to Player Prefab.
4. In the Project tab, right-click (macOS: Ctrl+click) the Assets folder, then Create > Folder.
5. Name the new folder Prefabs.
6. Drag the Player Prefab object from the Hierarchy window into the Prefabs folder to make it into a prefab.
7. In the Hierarchy window, right-click (macOS: Ctrl+click) the capsule, then select Delete. This deletes the player from the scene.

To identify and synchronize the prefab using Netcode for Entities, you need to create an IComponent and Author for it:

1. In the Project tab, right-click (macOS: Ctrl+click) the Assets folder, then Create > Folder.

2. Name the new folder Scripts.

3. Right-click (macOS: Ctrl+click) the new Scripts folder, then Create > Scripting > Empty C# Script.

4. Rename this script PlayerAuthoring.cs.

5. Double-click the script to edit it.

6. Replace the contents of this script with the following code:

   using Unity.Entities;
   using Unity.NetCode;
   using UnityEngine;
   
   public struct Player : IComponentData
   {
   }
   
   [DisallowMultipleComponent]
   public class PlayerAuthoring : MonoBehaviour
   {
       class Baker : Baker<PlayerAuthoring>
       {
           public override void Bake(PlayerAuthoring authoring)
           {
               var entity = GetEntity(TransformUsageFlags.Dynamic);
               AddComponent<Player>(entity);
           }
       }
   }

7. In the Project tab, select Assets > Prefabs > Player Prefab so its Inspector window opens.

8. In the Project tab, select Assets > Scripts.

9. Drag the Player Authoring script to the Player Prefab Inspector window to attach it.

10. In the Inspector window, select Add component.

11. Search for Ghost Authoring Component, then select it and add it to the Prefab.

    When you attach a Ghost Authoring Component to a prefab, Unity automatically serializes the Translation and Rotation components and adds a Linked Entity Group Authoring script.

Before you can move the capsule around, you must change some settings in the newly-added Ghost Authoring Component:

1. Enable Has Owner. This setting automatically adds and checks a new property called Support Auto Command Target.
2. Change the Default Ghost Mode to Owner Predicted. Later, setting the NetworkId member of the Ghost Owner Component through code ensures that you predict your own movement.

You now have a prefab of a ghost capsule object.

Create a spawner#

To tell Netcode for Entities which ghosts to use, reference the Prefabs from the sub-scene.

First, create a new component for the spawner:

1. In the Project tab, right-click (macOS: Ctrl+click) the Scripts folder, then Create > Scripting > Empty C# Script.
2. Rename this script PlayerSpawnerAuthoring.cs.
3. Replace the contents of this script with the following code:

   using Unity.Entities;
   using UnityEngine;
   
   public struct PlayerSpawner : IComponentData
   {
       public Entity Player;
   }
   
   [DisallowMultipleComponent]
   public class PlayerSpawnerAuthoring : MonoBehaviour
   {
       public GameObject PlayerPrefab;
   
       class Baker : Baker<PlayerSpawnerAuthoring>
       {
           public override void Bake(PlayerSpawnerAuthoring authoring)
           {
               PlayerSpawner component = default(PlayerSpawner);
               component.Player = GetEntity(authoring.PlayerPrefab, TransformUsageFlags.Dynamic);
               var entity = GetEntity(TransformUsageFlags.Dynamic);
               AddComponent(entity, component);
           }
       }
   }

4. Right-click (macOS: Ctrl+click) within the Hierarchy window, then select Create Empty.
5. Rename the empty GameObject to Spawner.
6. With the empty object selected in the Hierarchy window, in its Inspector window, select Add Component.
7. Attach the Player Spawner Authoring script.
8. With the Inspector window still open, select the Assets > Prefabs folder from the Project tab.
9. Drag the Player Prefab object to the Player Prefab field in the Spawner's Inspector window.
10. In the Hierarchy window, move the Spawner into the SharedData sub-scene.

You have now created a new component for the Spawner, instructed it which ghosts to use, and ensured that both the client and the server know about these ghosts when they spawn.

Enable communication and spawn the prefab#

To enable communication between the client and server, you need to establish a connection. The Multiplayer Services SDK manages connections so you can focus on which messages are communicated. Netcode for Entities uses remote procedure calls (RPC) for its messages.

A critical concept in Netcode for Entities is InGame. When a connection is marked with InGame, it tells the simulation that it is ready to start synchronizing. You must send a GoInGame RPC when you are ready for the server to start synchronizing and to spawn the prefab.

To create an RPC that acts as a Go In Game message:

1. In the Project tab, right-click (macOS: Ctrl+click) the Scripts folder, then Create > Scripting > Empty C# Script.
2. Rename this script GoInGameSystems.cs.
3. Replace the contents of this script with the following code:

   Tip: Any class inheriting from ISystem is automatically invoked by the runtime, and the sample below combines related systems into one file for brevity.

   using UnityEngine;
   using Unity.Collections;
   using Unity.Entities;
   using Unity.NetCode;
   using Unity.Burst;
   
   /// <summary>
   /// This allows sending RPCs between a standalone build and the Editor for testing purposes in the event that, when you finish this example,
   /// you want to connect a server-client standalone build to a client-configured Editor instance.
   /// </summary>
   [BurstCompile]
   [WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation | WorldSystemFilterFlags.ServerSimulation | WorldSystemFilterFlags.ThinClientSimulation)]
   [UpdateInGroup(typeof(InitializationSystemGroup))]
   [CreateAfter(typeof(RpcSystem))]
   public partial struct SetRpcSystemDynamicAssemblyListSystem : ISystem
   {
       public void OnCreate(ref SystemState state)
       {
           SystemAPI.GetSingletonRW<RpcCollection>().ValueRW.DynamicAssemblyList = true;
           state.Enabled = false;
       }
   }
   
   // RPC request from client to server for game to go "in game" and send snapshots / inputs
   public struct GoInGameRequest : IRpcCommand
   {
   }
   
   // When client has a connection with network ID, go in game and tell server to also go in game
   [BurstCompile]
   [WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation | WorldSystemFilterFlags.ThinClientSimulation)]
   public partial struct GoInGameClientSystem : ISystem
   {
       [BurstCompile]
       public void OnCreate(ref SystemState state)
       {
           // Run only on entities with a PlayerSpawner component data
           state.RequireForUpdate<PlayerSpawner>();
   
           var builder = new EntityQueryBuilder(Allocator.Temp)
               .WithAll<NetworkId>()
               .WithNone<NetworkStreamInGame>();
           state.RequireForUpdate(state.GetEntityQuery(builder));
       }
   
       [BurstCompile]
       public void OnUpdate(ref SystemState state)
       {
           var commandBuffer = new EntityCommandBuffer(Allocator.Temp);
           foreach (var (id, entity) in SystemAPI.Query<RefRO<NetworkId>>().WithEntityAccess().WithNone<NetworkStreamInGame>())
           {
               commandBuffer.AddComponent<NetworkStreamInGame>(entity);
               var req = commandBuffer.CreateEntity();
               commandBuffer.AddComponent<GoInGameRequest>(req);
               commandBuffer.AddComponent(req, new SendRpcCommandRequest { TargetConnection = entity });
           }
           commandBuffer.Playback(state.EntityManager);
       }
   }
   
   // When server receives go in game request, go in game and delete request
   [BurstCompile]
   [WorldSystemFilter(WorldSystemFilterFlags.ServerSimulation)]
   public partial struct GoInGameServerSystem : ISystem
   {
       private ComponentLookup<NetworkId> networkIdFromEntity;
   
       [BurstCompile]
       public void OnCreate(ref SystemState state)
       {
           state.RequireForUpdate<PlayerSpawner>();
   
           var builder = new EntityQueryBuilder(Allocator.Temp)
               .WithAll<GoInGameRequest>()
               .WithAll<ReceiveRpcCommandRequest>();
           state.RequireForUpdate(state.GetEntityQuery(builder));
           networkIdFromEntity = state.GetComponentLookup<NetworkId>(true);
       }
   
       [BurstCompile]
       public void OnUpdate(ref SystemState state)
       {
           // Get the prefab to instantiate
           var prefab = SystemAPI.GetSingleton<PlayerSpawner>().Player;
   
           // Ge the name of the prefab being instantiated
           state.EntityManager.GetName(prefab, out var prefabName);
           var worldName = new FixedString32Bytes(state.WorldUnmanaged.Name);
   
           var commandBuffer = new EntityCommandBuffer(Allocator.Temp);
           networkIdFromEntity.Update(ref state);
   
           foreach (var (reqSrc, reqEntity) in SystemAPI.Query<RefRO<ReceiveRpcCommandRequest>>().WithAll<GoInGameRequest>().WithEntityAccess())
           {
               commandBuffer.AddComponent<NetworkStreamInGame>(reqSrc.ValueRO.SourceConnection);
               // Get the NetworkId for the requesting client
               var networkId = networkIdFromEntity[reqSrc.ValueRO.SourceConnection];
   
               // Log information about the connection request that includes the client's assigned NetworkId and the name of the prefab spawned.
               UnityEngine.Debug.Log($"'{worldName}' setting connection '{networkId.Value}' to in game, spawning a Ghost '{prefabName}' for them!");
   
               // Instantiate the prefab
               var player = commandBuffer.Instantiate(prefab);
               // Associate the instantiated prefab with the connected client's assigned NetworkId
               commandBuffer.SetComponent(player, new GhostOwner { NetworkId = networkId.Value});
   
               // Add the player to the linked entity group so it is destroyed automatically on disconnect
               commandBuffer.AppendToBuffer(reqSrc.ValueRO.SourceConnection, new LinkedEntityGroup{Value = player});
               commandBuffer.DestroyEntity(reqEntity);
           }
           commandBuffer.Playback(state.EntityManager);
       }
   }

You have now created an RPC that tells the simulation that it's ready to start synchronizing.

Move the prefab#

Because you used the Support Auto Command Target feature when you set up the ghost component, you can take advantage of the IInputComponentData struct for storing input data. This struct dictates what you are serializing and deserializing as the input data. You also need to create a System to fill in the input data.

To create the IInputComponentData struct:

1. In the Project tab, right-click (macOS: Ctrl+click) the Scripts folder, then Create > Scripting > Empty C# Script.
2. Rename this script PlayerInputAuthoring.cs.
3. Replace the contents of this script with the following code:

   using Unity.Burst;
   using Unity.Entities;
   using Unity.NetCode;
   using UnityEngine;
   
   public struct PlayerInput : IInputComponentData
   {
       public float Horizontal;
       public float Vertical;
   }
   
   [DisallowMultipleComponent]
   public class PlayerInputAuthoring : MonoBehaviour
   {
       class PlayerInputBaking : Unity.Entities.Baker<PlayerInputAuthoring>
       {
           public override void Bake(PlayerInputAuthoring authoring)
           {
               var entity = GetEntity(TransformUsageFlags.Dynamic);
               AddComponent<PlayerInput>(entity);
           }
       }
   }
   
   [UpdateInGroup(typeof(GhostInputSystemGroup))]
   public partial struct SamplePlayerInput : ISystem
   {
       public void OnCreate(ref SystemState state)
       {
           state.RequireForUpdate<NetworkStreamInGame>();
           state.RequireForUpdate<PlayerSpawner>();
       }
   
       public void OnUpdate(ref SystemState state)
       {
           foreach (var playerInput in SystemAPI.Query<RefRW<PlayerInput>>().WithAll<GhostOwnerIsLocal>())
           {
               playerInput.ValueRW = default;
               playerInput.ValueRW.Horizontal = Input.GetAxis("Horizontal");
               playerInput.ValueRW.Vertical = Input.GetAxis("Vertical");
           }
       }
   }

4. In the Project tab, select Assets > Prefabs > Player Prefab.
5. Attach the Player Input Authoring script to the Player Prefab Inspector window.

Finally, create a system that can read this input and move the player:

1. In the Project tab, right-click (macOS: Ctrl+click) the Scripts folder, then Create > Scripting > Empty C# Script.
2. Rename this script PlayerMovementSystem.cs.
3. Replace the contents of this script with the following code:

   using Unity.Entities;
   using Unity.Mathematics;
   using Unity.NetCode;
   using Unity.Transforms;
   using Unity.Burst;
   
   [UpdateInGroup(typeof(PredictedSimulationSystemGroup))]
   [BurstCompile]
   public partial struct PlayerMovementSystem : ISystem
   {
       [BurstCompile]
       public void OnUpdate(ref SystemState state)
       {
           var speed = SystemAPI.Time.DeltaTime * 4;
           foreach (var (input, trans) in SystemAPI.Query<RefRO<PlayerInput>, RefRW<LocalTransform>>().WithAll<Simulate>())
           {
               var moveInput = new float2(input.ValueRO.Horizontal, input.ValueRO.Vertical);
               moveInput = math.normalizesafe(moveInput) * speed;
               trans.ValueRW.Position += new float3(moveInput.x, 0, moveInput.y);
           }
       }
   }

You have now set up a way to accept user input, read that input, and then move the player's capsule object.

Create and join your session#

The following steps outline how to create and join a session using Netcode for Entities with Widgets and Multiplayer Services in the Unity Editor.

1. Right-click (macOS: Ctrl+click) in the Hierarchy window, then select Multiplayer Widgets > Create > Create Session.

   Notes:

   • If you receive a TMP Importer prompt, select Import TMP Essentials.
   • If you do not see this prompt and the widget has no label, select Window > TextMeshPro > Import TMP Essential Resources.
2. In the Hierarchy window, select Canvas > Create Session.
3. In its Inspector window, set Rect Transform > Pos Y to 50.
4. Right-click (macOS: Ctrl+click) in the Hierarchy window, then select Multiplayer Widgets > Info > Show Session Code.
5. Right-click (macOS: Ctrl+click) in the Hierarchy window, then select Multiplayer Widgets > Join and Leave > Join Session By Code.
6. In the Hierarchy window, select Canvas > Join Session By Code.
7. In its Inspector window, set Rect Transform > Pos Y to -100.
8. In the Unity Editor, select File > Save to refresh the scene for Player 2.
9. In the Toolbar, select Play to enter Play Mode.
10. In the Game window's Session Name field, enter a name and then select Create.
11. Copy the session join code.
12. In the Player 2 window's Session Code field, enter the code and then select Join.

You have now created a session in one of the Editor windows and joined it using the displayed join code from the other Editor window. After joining the session, two superimposed capsules appear in the scene.

Move the capsules#

To move the capsules in your multiplayer session:

1. Click within the Game window of the Editor.
2. Use the arrow keys on your keyboard to move the capsule around the scene. It moves in real time in both the Game window and the Player 2 window.
3. Click within the Player 2 window.
4. Use the arrow keys on your keyboard to move the capsule around the scene. Notice that the other capsule (Player 2's capsule) moves this time.

By entering Play Mode and joining the session, you now have a scene of two capsules that can only each be controlled by the owning player.

Additional resources#

• Networked cube (Unity Netcode for Entities)
• Get acquainted with DOTS (Unity Learn)
• Multiplayer Services SDK