Struct NetworkStreamDriver

Singleton that can hold a reference to the NetworkDriverStore and that should be used to easily listening for new connection or connecting to server. Provide also other shortcut for retrieving the remote address of a NetworkStreamConnection or its underlying transport state.

Implements

IComponentData

IQueryTypeParameter

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Unity.NetCode

Assembly: Unity.NetCode.dll

Syntax

public struct NetworkStreamDriver : IComponentData, IQueryTypeParameter

Properties

ConcurrentDriverStore

A reference to the concurrent version of the NetworkDriverStore (ConcurrentDriverStore), used for send/receiving messages in jobs.

Declaration

public ref ConcurrentDriverStore ConcurrentDriverStore { get; }

Property Value

Type	Description
ConcurrentDriverStore

ConnectionEventsForTick

Stores all NetCodeConnectionEvents raised by Netcode for this Unity.Entities.SimulationSystemGroup tick, which allows user code to subscribe to connection and disconnection events (including Handshake and Approval, if applicable). Refer to the Network connection page (https://docs.unity3d.com/Packages/com.unity.netcode@latest?subfolder=/manual/network-connection.html) for more details.

It's a self-cleaning list and therefore has no consume API (in other words, there's no need to explicitly remove entries from this collection, which is why it's read-only). This also means that events are only valid for a single Unity.Entities.SimulationSystemGroup tick, and therefore must be polled inside this group.

This collection is cleared and repopulated in the NetworkGroupCommandBufferSystem, which is also the ECB playback that creates and destroys NetworkStreamConnection 'NetworkConnection' entities. Therefore, if you query this collection after the `NetworkGroupCommandBufferSystem` system (via the Unity.Entities.UpdateAfterAttribute), you'll get the current tick's event data, but if you poll before it, your event data will always be one tick out of date.

[BurstCompile]
void ISystem.OnUpdate(ref SystemState state)
{
    foreach (var evt in SystemAPI.GetSingleton<NetworkStreamDriver>().ConnectionEventsForTick)
    {
        UnityEngine.Debug.Log($"[{state.WorldUnmanaged.Name}] {evt.ToFixedString()}!");
    }
}

Declaration

public readonly NativeArray<NetCodeConnectionEvent>.ReadOnly ConnectionEventsForTick { get; }

Property Value

Type	Description
NativeArray<NetCodeConnectionEvent>.ReadOnly

Remarks

This collection can be safely passed into jobs, as long as the NetworkStreamDriver singleton is fetched as read/write.

These events are raised on client worlds as well, but only for your own client world. I.e. Each client does not receive events regarding other clients. Refer to the PlayerList NetcodeSamples sample (https://github.com/Unity-Technologies/EntityComponentSystemSamples/tree/master/NetcodeSamples/Assets/Samples/PlayerList) for an example implementation of RPC logic that actually communicates player join and leave events (with display names and NetworkStreamDisconnectReasons).

DriverStore

A pointer to the underlying DriverStore, giving access to raw Transport APIs.
Warning: You MUST fetch NetworkStreamDriver as RW access when performing Driver operations!

Declaration

public ref NetworkDriverStore DriverStore { get; }

Property Value

Type	Description
NetworkDriverStore

Remarks

NetworkDriverStore has specific usage patterns (see for loop use-cases below). Use with care!
Copying such a large struct is expensive, prefer ref var driverStore = ref networkStreamDriver.RefRW.DriverStore; syntax.

LastEndPoint

Convenience. Records the DriverStore used in the latest call to Listen(NetworkEndpoint) or Connect(EntityManager, NetworkEndpoint, Entity).

Declaration

public readonly NetworkEndpoint LastEndPoint { get; }

Property Value

Type	Description
NetworkEndpoint

Remarks

Note that the actual Endpoint used by each NetworkStreamDriver may be different, due to Unity.Networking.Transport.IPCNetworkInterface.

See SanitizeConnectAddress(in NetworkEndpoint, int) and SanitizeListenAddress(in NetworkEndpoint, int).

RequireConnectionApproval

Require all incoming connections to all the drivers in the driver store to go through the connection approval process. If turned off the connections are immediately approved and go from connecting to the handshake state.
Server-only. Always false on the client.

Declaration

public bool RequireConnectionApproval { get; set; }

Property Value

Type	Description
bool

Methods

Connect(EntityManager, NetworkEndpoint, Entity)

Initiate a connection to the remote endpoint address.

Declaration

public Entity Connect(EntityManager entityManager, NetworkEndpoint endpoint, Entity ent = default)

Parameters

Type	Name	Description
EntityManager	entityManager	The entity manager to use to create the new entity, if ent equals Unity.Entities.Entity.Null
NetworkEndpoint	endpoint	The remote address we want to connect
Entity	ent	An optional entity to use to create the connection. If not set, a new entity will be create instead

Returns

Type	Description
Entity	The entity that hold the NetworkStreamConnection. If the endpoint is not valid

Exceptions

Type	Condition
InvalidOperationException	Throw an exception if the driver is not created or if multiple drivers are register

GetConnectionState(NetworkStreamConnection)

The current state of the internal transport connection.

Declaration

public NetworkConnection.State GetConnectionState(NetworkStreamConnection connection)

Parameters

Type	Name	Description
NetworkStreamConnection	connection

Returns

Type	Description
NetworkConnection.State

Remarks

Is different from the ConnectionState.State and it is less granular.

GetLocalEndPoint()

Get the local endpoint (the endpoint remote peers will use to reach this driver) used by the first driver inside NetworkDriverStore. This is similar to calling GetLocalEndPoint(int) with NetworkDriverStore.FirstDriverId as argument.

Declaration

public NetworkEndpoint GetLocalEndPoint()

Returns

Type	Description
NetworkEndpoint	The local endpoint of the first driver.

GetLocalEndPoint(int)

Get the local endpoint used by the driver (the endpoint remote peers will use to reach this driver).
When multiple drivers exist, e.g. when using both IPC and Socket connection, multiple drivers will be available in the NetworkDriverStore.

Declaration

public NetworkEndpoint GetLocalEndPoint(int driverId)

Parameters

Type	Name	Description
int	driverId	Id of the driver. See GetDriverRO(int).

Returns

Type	Description
NetworkEndpoint	The local endpoint of the driver.

GetRemoteEndPoint(NetworkStreamConnection)

The remote connection address. This is the seen public ip address of the connection.

Declaration

public NetworkEndpoint GetRemoteEndPoint(NetworkStreamConnection connection)

Parameters

Type	Name	Description
NetworkStreamConnection	connection

Returns

Type	Description
NetworkEndpoint	When relay is used, the current relay host address. Otherwise the remote endpoint address.

Remarks

Be aware that this method work sliglty differnetly than the NetworkDriver.GetRemoteEndpoint. The Unity.Networking.Transport.NetworkDriver.GetRemoteEndpoint(Unity.Networking.Transport.NetworkConnection) does not always return a valid address when used with relay (once the connection is established it become the RelayAllocationId). We instead wanted a consistent behaviour for this method: always return the address to which this connection is is connected/connecting to.

Listen(NetworkEndpoint)

Tell all the registered NetworkDriverStore drivers to start listening for incoming connections.

Declaration

public bool Listen(NetworkEndpoint endpoint)

Parameters

Type	Name	Description
NetworkEndpoint	endpoint	The local address to use. This is the address that will be used to bind the underlying socket.

Returns

Type	Description
bool

ResetDriverStore(WorldUnmanaged, ref NetworkDriverStore)

Reset the current DriverStore by disposing the current instance and its associated ConcurrentDriverStore. This method can be used to re-create and re-configure the driver after world has been created and before either Listen(NetworkEndpoint) or Connect(EntityManager, NetworkEndpoint, Entity) has been called.

Declaration

public void ResetDriverStore(WorldUnmanaged world, ref NetworkDriverStore driverStore)

Parameters

Type	Name	Description
WorldUnmanaged	world	The world the NetworkStreamDriver singleton is part of.
NetworkDriverStore	driverStore	The new driver store to use.

Examples

var driverStore = new NetworkDriverStore();
var constructor = NetworkStreamReceiveSystem.DriverConstructor;
constructor.CreateServerDriver(serverWorld, ref driverStore, netDebug);
var driver = EntityManager.CreateEntityQuery(typeof(NetworkStreamDriver)).GetSingleton<NetworkStreamDriver>();
driver.ResetDriverStore(driverStore);
var listenEndPoint = NetworkEndpoint.AnyIpv4.WithPort(MyPort);
driver.Listen(listenEndPoint);

UseRelay(NetworkStreamConnection)

Check if the given connection is using relay to connect to the remote endpoint

Declaration

public bool UseRelay(NetworkStreamConnection connection)

Parameters

Type	Name	Description
NetworkStreamConnection	connection

Returns

Type	Description
bool	Either if the connection is using the relay or not.

Implements

Unity.Entities.IComponentData

Unity.Entities.IQueryTypeParameter