Networking
Plugins send their own data between the server and clients with the IGameNetwork service. This page shows you how to write some basic code to send messages and sync over the network in multiplayer.
Authoritative server-client network model
Barotrauma uses an authoritative server-client network model, meaning that in multiplayer you have a server and multiple client instances that connect to that server, with the server holding the “true” state of the game and having the final say in every action.
This means that net messages must always go to the server or originate from the server. A client can’t send net messages directly to other clients.
Singleplayer, client and server
Your plugin’s code can run in three situations:
| Situation | Build that runs | GameMain.NetworkMember |
|---|---|---|
| Singleplayer | Client | null |
| Multiplayer, on a client | Client | IsClient is true |
| Multiplayer, on the server | Server | IsServer is true |
In multiplayer, the server is always a separate server process, even when a player hosts the game from their own client. That player’s game is a client like any other.
In singleplayer, only the client build runs and there is no server. Code inside #if SERVER never runs, and Send and Broadcast do nothing. So don’t put game logic only in #if SERVER blocks, or it won’t work in singleplayer. Put it in shared code, and skip it on multiplayer clients if it’s something that should only run on whoever has authority over the logic.
public void DoSomething()
{
if (GameMain.NetworkMember is { IsClient: true })
{
return;
}
// Runs in singleplayer and on the server
// ...change the game state...
#if SERVER
// Tell the clients about the change
GameNetwork.Broadcast(FooBarHeader.FooBar, new FooBar(42, true));
#endif
}
The item component example below follows the same pattern.
Sending network messages
To send network messages in your plugin, you must first create an enum containing the different types of messages your plugin can send:
public enum FooBarHeader
{
FooBar,
RequestFooBar
}
Then to use this you also need to define the data that the network message will contain:
[NetworkSerialize]
public readonly record struct FooBar(float Foo, bool Bar) : INetSerializableStruct;
[NetworkSerialize]
public readonly record struct RequestFooBar() : INetSerializableStruct;
And then to receive these net messages and send them:
public static readonly IGameNetwork GameNetwork = PluginServiceProvider.GetService<IGameNetwork>();
public void Init()
{
GameNetwork.RegisterNetworkHeaders<FooBarHeader>();
#if SERVER
GameNetwork.RegisterHandler<FooBarHeader, RequestFooBar>(FooBarHeader.RequestFooBar, OnFooBarRequested);
#elif CLIENT
GameNetwork.RegisterHandler<FooBarHeader, FooBar>(FooBarHeader.FooBar, OnFooBarReceived);
#endif
}
#if SERVER
private static void OnFooBarRequested(RequestFooBar request, Client client)
{
if (!client.HasPermission(ClientPermissions.ManageRound))
{
return;
}
DebugConsole.Log($"FooBar requested by {client.Name}");
GameNetwork.Broadcast(FooBarHeader.FooBar, new FooBar(42, true));
}
#endif
#if CLIENT
private static void OnFooBarReceived(FooBar data)
{
DebugConsole.Log($"FooBar received {data.Foo} {data.Bar}");
}
// Call this on the client to ask the server for a FooBar
public static void RequestFooBarFromServer()
{
GameNetwork.Send(FooBarHeader.RequestFooBar, new RequestFooBar());
}
#endif
The server sends with Broadcast or SendToClient (for specific clients), and clients send with Send.
Network serializable structs
[NetworkSerialize] on a struct serializes all its fields and properties. You can also put it on individual members, with settings such as MinValueInt/MaxValueInt, MinValueFloat/MaxValueFloat, NumberOfBits and ArrayMaxSize to make the message smaller. Supported types are:
- the numeric types,
boolandstring Identifier,Color,Vector2andAccountId- enums
- other
INetSerializableStructtypes - arrays and
ImmutableArray<T> Option<T>and nullable structs
To refer to an item or a character, send its ID and look it up with Entity.FindEntityByID.
Clients joining mid-round
If you ever need to sync state to mid-round joining clients, you can use the PluginClientJoinedRoundDelegate hook:
public static readonly ISimpleHookService HookService = PluginServiceProvider.GetService<ISimpleHookService>();
// In Init()
#if SERVER
HookService.RegisterHook<PluginClientJoinedRoundDelegate>(client =>
GameNetwork.SendToClient(client, FooBarHeader.FooBar, new FooBar(42, true)));
#endif
PluginClientDisconnectedDelegate (server) and PluginMidRoundSyncReceiveCompletedDelegate (client) are also useful here.
Item components
A custom item component can implement IServerSerializable and/or IClientSerializable to allow the component to emit network events.
public class ChargeCounter : ItemComponent, IServerSerializable
{
[Serialize(0, IsPropertySaveable.Yes, "How many charges the item has.")]
public int Charges { get; set; }
public ChargeCounter(Item item, ContentXElement element) : base(item, element) { }
public void AddCharge()
{
if (GameMain.NetworkMember is { IsClient: true })
{
return;
}
Charges++;
#if SERVER
item.CreateServerEvent(this);
#endif
}
#if SERVER
public void ServerEventWrite(IWriteMessage msg, Client c, NetEntityEvent.IData? extraData = null)
{
msg.WriteInt32(Charges);
}
#elif CLIENT
public void ClientEventRead(IReadMessage msg, float sendingTime)
{
Charges = msg.ReadInt32();
}
#endif
}
ServerEventWrite is called when the event is sent, so it always writes the current state, and clients that join mid-round receive it too. ClientEventRead must read exactly what was written. For requests from the client, implement IClientSerializable the same way (ClientEventWrite and ServerEventRead, sent with item.CreateClientEvent(this)).