IGameNetwork
public interface IGameNetwork : IPluginService
Provides a service to allow client and server side network communication in multiplayer.
Remarks
The methods are instance methods. The examples assume an instance has been retrieved and stored, e.g.:
public static readonly IGameNetwork GameNetwork = PluginServiceProvider.GetService<IGameNetwork>();
Members
| Member | Description |
|---|---|
RegisterNetworkHeaders<TEnum>() |
Registers the header enum to be used for network communication. |
RegisterAllStaticHandlers() |
Will scan the entire assembly for static methods with the NetworkHandlerAttribute<T> attribute and register them as network handlers. |
RegisterHandlers<T>() |
Will scan the object instance for methods with the NetworkHandlerAttribute<T> attribute and register them as network handlers. |
CreateEntityEvent<TSerializable>() |
Creates a network event for an entity. Write and read methods for the entity event must be registered via the respective EntityClientWrite, EntityClientRead, EntityServerWrite and EntityServerRead methods in this interface. |
CreateVanillaEntityEvent<TSerializable>() |
Creates a network event using the vanilla entity write and read methods. Useful for example if you are editing a state of a vanilla entity that doesn’t automatically create entity events. |
RegisterCustomEntityEventHandler<TEntity>() |
Registers ClientWrite, ClientRead, ServerWrite and ServerRead entity event handlers for a specific entity. |
RegisterEntityClientWrite<TSerializable>() |
Registers a client side event write handler for an entity. |
RegisterEntityClientRead<TSerializable>() |
Registers a client side event read handler for an entity. |
RegisterHandler<TEnum, TData>() |
Manually register a client side handler for a specific network header. |
Send<TEnum, TData>() |
Sends data to the server. |
RegisterEntityServerWrite<TSerializable>() |
Registers a server side event write handler for an entity. |
RegisterEntityServerRead<TSerializable>() |
Registers a server side event read handler for an entity. |
RegisterHandler<TEnum, TData>() |
Manually register a server side handler for a specific network header. |
Broadcast<TEnum, TData>() |
Sends data to all connected clients. |
SendToClient<TEnum, TData>() |
Sends data to a specific client. |
Methods
RegisterNetworkHeaders
void RegisterNetworkHeaders<TEnum>() where TEnum : Enum
Registers the header enum to be used for network communication.
| Type parameter | Description |
|---|---|
TEnum |
Enum type to register. |
| Exception | Condition |
|---|---|
InvalidOperationException |
If an enum is already registered for the plugin. |
Example
public enum MyNetworkHeaders
{
ExampleHeader1,
ExampleHeader2
}
GameNetwork.RegisterNetworkHeaders<MyNetworkHeaders>();
RegisterAllStaticHandlers
void RegisterAllStaticHandlers()
Will scan the entire assembly for static methods with the NetworkHandlerAttribute<T> attribute and register them as network handlers.
RegisterHandlers
void RegisterHandlers<T>(T module)
Will scan the object instance for methods with the NetworkHandlerAttribute<T> attribute and register them as network handlers.
| Parameter | Type | Description |
|---|---|---|
module |
T |
Object instance to register handlers from. |
Example
Create a class that contains network handlers:
public class MyNetworkHandlers
{
[NetworkHandler<MyNetworkHeaders>(MyNetworkHeaders.ExampleHeader1)]
public void ExampleHandler1(MyData data)
{
// read data from MyData
}
}
Static field:
public static readonly MyNetworkHandlers MyHandlers = new();
Plugin init:
GameNetwork.RegisterHandlers(MyHandlers);
CreateEntityEvent
void CreateEntityEvent<TSerializable>(
TSerializable serializable,
NetEntityEvent.IData? data) where TSerializable : INetSerializable
Creates a network event for an entity. Write and read methods for the entity event must be registered via the respective EntityClientWrite, EntityClientRead, EntityServerWrite and EntityServerRead methods in this interface.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing INetSerializable. |
| Parameter | Type | Description |
|---|---|---|
serializable |
TSerializable |
Entity to create the event for. |
data |
NetEntityEvent.IData? |
Extra data to pass to the entity event. Can be null if not needed. |
Example
item.GetExtraField<MyCustomData>("CustomData").Foo = Bar;
GameNetwork.CreateEntityEvent(item, null);
CreateVanillaEntityEvent
void CreateVanillaEntityEvent<TSerializable>(
TSerializable serializable,
NetEntityEvent.IData? data) where TSerializable : INetSerializable
Creates a network event using the vanilla entity write and read methods. Useful for example if you are editing a state of a vanilla entity that doesn’t automatically create entity events.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing INetSerializable. |
| Parameter | Type | Description |
|---|---|---|
serializable |
TSerializable |
Entity to create the event for. |
data |
NetEntityEvent.IData? |
Extra data to pass to the entity event. Can be null if not needed. |
RegisterCustomEntityEventHandler
void RegisterCustomEntityEventHandler<TEntity>(
ICustomSerializable<TEntity> handler) where TEntity : IClientSerializable, IServerSerializable
Registers ClientWrite, ClientRead, ServerWrite and ServerRead entity event handlers for a specific entity.
| Type parameter | Description |
|---|---|
TEntity |
Entity that registers both IClientSerializable and IServerSerializable. |
| Parameter | Type | Description |
|---|---|---|
handler |
ICustomSerializable<TEntity> |
Instance of a custom entity event handler implementing ICustomSerializable<T>. |
Example
Client project:
public class CustomItemHandler : ICustomSerializable<Item>
{
public void ClientWrite(Item item, IWriteMessage msg, NetEntityEvent.IData? extraData)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
}
public void ClientRead(Item item, IReadMessage msg, float sendingTime)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
}
}
Server project:
public class CustomItemHandler : ICustomSerializable<Item>
{
public void ServerWrite(Item item, IWriteMessage msg, Client client, NetEntityEvent.IData? extraData)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
}
public void ServerRead(Item item, IReadMessage msg, Client client)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
}
}
Register the handler in shared project:
GameNetwork.RegisterCustomEntityEventHandler<Item>(new CustomItemHandler());
RegisterEntityClientWrite
void RegisterEntityClientWrite<TSerializable>(
EntityEventClientWriteDelegate<TSerializable> handler) where TSerializable : IClientSerializable
Only available on the client.
Registers a client side event write handler for an entity.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing IClientSerializable we are registering the handler for. |
| Parameter | Type | Description |
|---|---|---|
handler |
EntityEventClientWriteDelegate<TSerializable> |
Method or delegate to call when an entity event is created. |
Remarks
The server must have corresponding ServerRead handler registered for the entity.
Example
GameNetwork.RegisterEntityClientWrite<Item>((item, msg, extraData) =>
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
});
or with a method:
GameNetwork.RegisterEntityClientWrite<Item>(WriteItem);
public void WriteItem(Item item, IWriteMessage msg, NetEntityEvent.IData? extraData)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
}
RegisterEntityClientRead
void RegisterEntityClientRead<TSerializable>(
EntityEventClientReadDelegate<TSerializable> handler) where TSerializable : IServerSerializable
Only available on the client.
Registers a client side event read handler for an entity.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing IServerSerializable we are registering the handler for. |
| Parameter | Type | Description |
|---|---|---|
handler |
EntityEventClientReadDelegate<TSerializable> |
Method or delegate to call when an entity event is received. |
Remarks
The server should have corresponding ServerWrite handler registered for the entity.
Example
GameNetwork.RegisterEntityClientRead<Item>((item, msg, sendingTime) =>
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
});
or with a method:
GameNetwork.RegisterEntityClientRead<Item>(ReadItem);
public void ReadItem(Item item, IReadMessage msg, float sendingTime)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
}
RegisterHandler
void RegisterHandler<TEnum, TData>(
TEnum header,
ClientNetworkHandlerDelegate<TData> handler) where TEnum : Enum where TData : INetSerializableStruct
Only available on the client.
Manually register a client side handler for a specific network header.
| Type parameter | Description |
|---|---|
TData |
Struct implementing INetSerializableStruct to be deserialized from the received data. |
TEnum |
Enum type registered via RegisterNetworkHeaders<TEnum>. |
| Parameter | Type | Description |
|---|---|---|
header |
TEnum |
Header to register the handler for. |
handler |
ClientNetworkHandlerDelegate<TData> |
Method or delegate to call when the header is received. |
| Exception | Condition |
|---|---|
InvalidOperationException |
A handler for the header is already registered or the enum header is not registered. |
Example
GameNetwork.RegisterHandler(MyNetworkHeaders.ExampleHeader1, (MyData myData) =>
{
// read data from MyData
});
or with a method:
GameNetwork.RegisterHandler(MyNetworkHeaders.ExampleHeader1, MyHandler);
public void MyHandler(MyData myData)
{
// read data from MyData
}
Send
void Send<TEnum, TData>(TEnum header, TData data) where TEnum : Enum where TData : INetSerializableStruct
Only available on the client.
Sends data to the server.
| Type parameter | Description |
|---|---|
TData |
Struct implementing INetSerializableStruct to be serialized and sent. |
TEnum |
Enum type registered via RegisterNetworkHeaders<TEnum>. |
| Parameter | Type | Description |
|---|---|---|
header |
TEnum |
Network header to identify the data. |
data |
TData |
Data to send. |
| Exception | Condition |
|---|---|
InvalidOperationException |
Given enum header is not registered via RegisterNetworkHeaders<TEnum>. |
Remarks
The server needs to have a handler registered for the enum header to receive the data.
Example
[NetworkSerialize]
public readonly record struct MyData(int Foo) : INetSerializableStruct;
GameNetwork.Send(MyNetworkHeaders.ExampleHeader1, new MyData(42));
RegisterEntityServerWrite
void RegisterEntityServerWrite<TSerializable>(
EntityEventServerWriteDelegate<TSerializable> handler) where TSerializable : IServerSerializable
Only available on the server.
Registers a server side event write handler for an entity.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing IServerSerializable we are registering the handler for. |
| Parameter | Type | Description |
|---|---|---|
handler |
EntityEventServerWriteDelegate<TSerializable> |
Method or delegate to call when an entity event is created. |
Remarks
The client must have corresponding ClientRead handler registered for the entity.
Example
GameNetwork.RegisterEntityServerWrite<Item>((item, msg, client, extraData) =>
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
});
or with a method:
GameNetwork.RegisterEntityServerWrite<Item>(WriteItem);
public void WriteItem(Item item, IWriteMessage msg, Client client, NetEntityEvent.IData? extraData)
{
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
msg.WriteInt32(data.Foo);
}
RegisterEntityServerRead
void RegisterEntityServerRead<TSerializable>(
EntityEventServerReadDelegate<TSerializable> handler) where TSerializable : IClientSerializable
Only available on the server.
Registers a server side event read handler for an entity.
| Type parameter | Description |
|---|---|
TSerializable |
Entity type implementing IClientSerializable we are registering the handler for. |
| Parameter | Type | Description |
|---|---|---|
handler |
EntityEventServerReadDelegate<TSerializable> |
Method or delegate to call when an entity event is received. |
Remarks
The client should have corresponding ClientWrite handler registered for the entity.
Example
GameNetwork.RegisterEntityServerRead<Item>((item, msg, client) =>
{
// check if the client is allowed to do this first
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
});
or with a method:
GameNetwork.RegisterEntityServerRead<Item>(ReadItem);
public void ReadItem(Item item, IReadMessage msg, Client client)
{
// check if the client is allowed to do this first
MyCustomData data = item.GetExtraField<MyCustomData>("CustomData");
data.Foo = msg.ReadInt32();
}
RegisterHandler
void RegisterHandler<TEnum, TData>(
TEnum header,
ServerNetworkHandlerDelegate<TData> handler) where TEnum : Enum where TData : INetSerializableStruct
Only available on the server.
Manually register a server side handler for a specific network header.
| Type parameter | Description |
|---|---|
TData |
Struct implementing INetSerializableStruct to be deserialized from the received data. |
TEnum |
Enum type registered via RegisterNetworkHeaders<TEnum>. |
| Parameter | Type | Description |
|---|---|---|
header |
TEnum |
Header to register the handler for. |
handler |
ServerNetworkHandlerDelegate<TData> |
Method or delegate to call when the header is received. |
| Exception | Condition |
|---|---|
InvalidOperationException |
A handler for the header is already registered or the enum header is not registered. |
Example
GameNetwork.RegisterHandler(MyNetworkHeaders.ExampleHeader1, (MyData myData, Client client) =>
{
// read data from MyData
});
or with a method:
GameNetwork.RegisterHandler(MyNetworkHeaders.ExampleHeader1, MyHandler);
public void MyHandler(MyData myData, Client client)
{
// read data from MyData
}
Broadcast
void Broadcast<TEnum, TData>(TEnum header, TData data) where TEnum : Enum where TData : INetSerializableStruct
Only available on the server.
Sends data to all connected clients.
| Type parameter | Description |
|---|---|
TEnum |
Enum type registered via RegisterNetworkHeaders<TEnum>. |
TData |
Struct implementing INetSerializableStruct to be serialized and sent. |
| Parameter | Type | Description |
|---|---|---|
header |
TEnum |
Network header to identify the data. |
data |
TData |
Data to send. |
| Exception | Condition |
|---|---|
InvalidOperationException |
Given enum header is not registered via RegisterNetworkHeaders<TEnum>. |
Remarks
The client needs to have a handler registered for the enum header to receive the data.
Example
[NetworkSerialize]
public readonly record struct MyData(int Foo) : INetSerializableStruct;
GameNetwork.Broadcast(MyNetworkHeaders.ExampleHeader1, new MyData(42));
SendToClient
void SendToClient<TEnum, TData>(
Client client,
TEnum header,
TData data) where TEnum : Enum where TData : INetSerializableStruct
Only available on the server.
Sends data to a specific client.
| Type parameter | Description |
|---|---|
TEnum |
Enum type registered via RegisterNetworkHeaders<TEnum>. |
TData |
Struct implementing INetSerializableStruct to be serialized and sent. |
| Parameter | Type | Description |
|---|---|---|
client |
Client |
Client to send the data to. |
header |
TEnum |
Network header to identify the data. |
data |
TData |
Data to send. |
| Exception | Condition |
|---|---|
InvalidOperationException |
Given enum header is not registered via RegisterNetworkHeaders<TEnum>. |
Remarks
The client needs to have a handler registered for the enum header to receive the data.
Example
[NetworkSerialize]
public readonly record struct MyRequest(int Foo) : INetSerializableStruct;
[NetworkSerialize]
public readonly record struct MyResponse(int Bar) : INetSerializableStruct;
Respond to client in a network handler:
GameNetwork.RegisterHandler(MyNetworkHeaders.ExampleHeader1, (MyRequest request, Client client) =>
{
MyResponse response = new(request.Foo * 2);
GameNetwork.SendToClient(client, MyNetworkHeaders.ExampleHeader2, response);
});
Related types
ClientNetworkHandlerDelegate
public delegate void ClientNetworkHandlerDelegate<in T>(T data) where T : INetSerializableStruct
Delegate for client side network handlers.
| Parameter | Type | Description |
|---|---|---|
data |
T |
Data received from the server. |
ServerNetworkHandlerDelegate
public delegate void ServerNetworkHandlerDelegate<in T>(
T data,
Client client) where T : INetSerializableStruct
Delegate for server side network handlers.
| Parameter | Type | Description |
|---|---|---|
data |
T |
Data received from the client. |
client |
Client |
Client that sent the data. |
EntityEventClientReadDelegate
public delegate void EntityEventClientReadDelegate<in TNetSerializable>(
TNetSerializable entity,
IReadMessage msg,
float sendingTime) where TNetSerializable : INetSerializable
EntityEventServerReadDelegate
public delegate void EntityEventServerReadDelegate<in TNetSerializable>(
TNetSerializable entity,
IReadMessage msg,
Client client) where TNetSerializable : INetSerializable
EntityEventClientWriteDelegate
public delegate void EntityEventClientWriteDelegate<in TNetSerializable>(
TNetSerializable entity,
IWriteMessage msg,
NetEntityEvent.IData? extraData) where TNetSerializable : INetSerializable
EntityEventServerWriteDelegate
public delegate void EntityEventServerWriteDelegate<in TNetSerializable>(
TNetSerializable entity,
IWriteMessage msg,
Client client,
NetEntityEvent.IData? extraData) where TNetSerializable : INetSerializable
ICustomSerializable
public interface ICustomSerializable<in T> where T : IClientSerializable, IServerSerializable
Interface for implementing bidirectional serialization for entities to be registered via IGameNetwork.RegisterCustomEntityEventHandler<TSerializable>.
ClientWrite
void ClientWrite(T entity, IWriteMessage msg, NetEntityEvent.IData? extraData)
Only available on the client.
ClientRead
void ClientRead(T entity, IReadMessage msg, float sendingTime)
Only available on the client.
ServerWrite
void ServerWrite(T entity, IWriteMessage msg, Client client, NetEntityEvent.IData? extraData)
Only available on the server.
ServerRead
void ServerRead(T entity, IReadMessage msg, Client client)
Only available on the server.
NetworkHandlerAttribute
public class NetworkHandlerAttribute<T>
Attribute to assign a header to a network handler method.
Example
[NetworkHandler<MyNetworkHeaders>(MyNetworkHeaders.ExampleHeader1)]
public static void ExampleHandler1(MyData data) { }