User Tools

Site Tools


besiege:modding:networking

This is an old revision of the document!


Networking

The networking API can be used to make a mod multiplayer-compatible.

Note: It is possible to write multiplayer-compatible mods without using the networking API because certain things (for example placing blocks, triggering logic chains) are networked automatically by the game. For many mods it may however be necessary to transmit additional information over the network connection in multiplayer. That is what the networking API is for.

Using the networking API is generally done in three steps:

  • Creating message types
  • Sending messages
  • Acting on received messages

Message Types

Every message sent by a mod needs to follow a predefined pattern. These patterns are called message types and represented by the MessageType class. A message type defines what information messages contain.

Message types are created using ModNetworking.CreateMessageType. CreateMessageType takes any number of DataTypes as arguments. These are what ultimately defines how a message of the type looks.

Available types are: Boolean, Color, Integer, IntegerArray, Single, SingleArray, String, StringArray, Vector3, Entity, Machine, and Block.

These types are mostly for convenience purposes, the mod loader is able to convert these to a byte array and back when transmitting a message. In case something else needs to be transmitted, a ByteArray data type is also available to handle the conversion manually.

CreateMessageType should only be called once per message type, ideally during the mod's OnLoad method. It is important that, if multiple types are created, they are always created in the same order. If two instances of the game are in a multiplayer session and have had the types registered in different orders, receiving messages correctly will not be possible.

It returns a MessageType object that should be stored and can later be used to create messages of the type.

Every mod may register at most 255 message types.

Messages are limited in size. The Steam connection automatically fragments messages that are too large, but the non-Steam connection does not support this. In order to support the maximum number of players, keep messages smaller than 1440 bytes. (This figure includes possible bytes not explicitly specified, e.g. an extra 4 bytes for the length of a string or a byte array).

Sending Messages

The first step of sending a message is to create a Message object. This is done by calling the CreateMessage method of a previously-created MessageType. The method must be passed one object for each of the DataTypes passed to CreateMessageType. These must also appear in the same order as in CreateMessageType.

To send the created message, call the appropriate Send method in ModNetworking:

  • SendToAll(Message) sends the given message to all connected instances.
  • SendTo(Player, Message) sends the given message only to the given player.
  • SendInSimulation(Message) sends the message to all instance participating in the current simulation. This may mean no player (not in simulation, in local simulation) or all players that are currently not in local simulation (in global simulation).

Receiving Messages

To receive messages, a mod must register a callback to at least one of two events: ModNetworking.MessageReceived or ModNetworking.Callbacks[MessageType]. Both events require callbacks that take exactly one argument: a Message object.

The first event is fired for every message sent by the same mod.

Using the second form, it is possible to register different callbacks for different message types. If exampleType was a MessageType instance, callbacks registered to ModNetworking.Callbacks[exampleType] will be called for every message with the given type that is received. (Registering callbacks works the same way it does for normal events, i.e. ModNetworking.Callbacks[exampleType] += MyCallbackMethod; or += (msg) ⇒ {<code>};)

Either way, a callback receives a Message object. The Message object exposes who sent the message with the Sender property (of type Player) and the data attached to it with the GetData(int) method. GetData takes an index as argument, the first object passed CreateMessage has index 0, the second object has index 1 and so on. The objects are returned as simple objects but can simply be cast to their original types.

besiege/modding/networking.1529333864.txt.gz · Last modified: 2018/06/18 16:57 by von