User Tools

Site Tools


besiege:modding:networking

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
besiege:modding:networking [2018/06/18 16:57]
von created
besiege:modding:networking [2018/07/24 16:02] (current)
spaar [Receiving Messages]
Line 13: Line 13:
 ===== Message Types ===== ===== Message Types =====
  
-Every message sent by a mod needs to follow ​predefined pattern. These patterns ​are called message types and represented by the ''​MessageType'' ​class. A message type defines what information messages contain.+Every message sent must conform ​to a pre-defined type. These are created using the ''​ModNetworking.CreateMessageType''​ function, which returns a ''​MessageType'' ​object.
  
-Message types are created ​using ''​ModNetworking.CreateMessageType''​''​CreateMessageType'' ​takes any number of ''​DataType''​s as arguments. These are what ultimately defines how a message of the type looks.+Message types are global in your mod and it is important that they are always ​created ​by the mod in the same orderThe recommended way is to create them in ''​OnLoad'' ​or ''​OnPrefabCreation'' ​and then store them in static variables to access throughout ​the mod.
  
-Available types are: ''​Boolean'',​ ''​Color'',​ ''​Integer'',​ ''​IntegerArray'',​ ''​Single'',​ ''​SingleArray'',​ ''​String'',​ ''​StringArray'',​ ''​Vector3'',​ ''​Entity'',​ ''​Machine'', ​and ''​Block''​.+Example of creating ​and storing a message type:
  
-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.+<code csharp>​ 
 +using Modding; 
 +using Modding.Blocks;
  
-''​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.+public static class Messages { 
 +    public static MessageType Example; 
 +}
  
-It returns a ''​MessageType''​ object that should be stored and can later be used to create messages of the type.+public class YourEntryPoint : ModEntryPoint { 
 +    public override void OnLoad() { 
 +        Messages.Example = ModNetworking.CreateMessageType(DataType.Single,​ DataType.Block);​ 
 +    } 
 +
 +</​code>​
  
-Every mod may register at most 255 message types.+As you can see, you can pass a list of ''​DataType''​ values to the ''​CreateMessageType''​ method. This is necessary for sending any kind of data along with the message ​and determines what types of objects and in what order they can be sent and received.
  
-Messages are limited in sizeThe Steam connection automatically fragments messages that are too large, but the non-Steam connection does not support thisIn order to support the maximum number of players, keep messages smaller than 1440 bytes(This figure includes possible bytes not explicitly specified, e.gan extra 4 bytes for the length of string or a byte array).+List of available ''​DataType''​s and their corresponding types: 
 + 
 +^ ''​DataType''​ ^ Type ^ Other accepted types ^ 
 +| ''​Boolean''​ | ''​bool''​ | | 
 +| ''​Color''​ | ''​UnityEngine.Color''​ | | 
 +| ''​Integer''​ | ''​int''​ | | 
 +| ''​IntegerArray''​ | ''​int[]''​ | | 
 +| ''​Single''​ | ''​float''​ | | 
 +| ''​SingleArray''​ | ''​float[]''​ | | 
 +| ''​String''​ | ''​string''​ | | 
 +| ''​StringArray''​ | ''​string[] ''​ | | 
 +| ''​ByteArray''​ | ''​byte[]''​ | | 
 +| ''​Vector3''​ | ''​UnityEngine.Vector3''​ | ''​Modding.Serialization.Vector3''​ | 
 +| ''​Block''​ | ''​Modding.Blocks.Block''​ | ''​BlockBehaviour''​ | 
 +| ''​Entity''​ | ''​Modding.Levels.Entity''​ | ''​LevelEntity''​ | 
 +| ''​Machine''​ | ''​Modding.Blocks.PlayerMachine''​ | ''​Machine''​ | 
 + 
 +Types in the "Other accepted types" column can be passed when sending ​message but, regardless of what type was passed in, you will always receive objects from the "​Type"​ column. 
 + 
 +Every mod may register at most 255 message types.
  
 ===== Sending Messages ===== ===== Sending Messages =====
Line 38: Line 66:
   * ''​SendTo(Player,​ Message)''​ sends the given message only to the given player.   * ''​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).   * ''​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).
 +
 +Continuing the example from above:
 +
 +<code csharp>
 +float x = <compute some float>;
 +Block b = <get some block>;
 +
 +Message message = Messages.Example.CreateMessage(x,​ b);
 +ModNetworking.SendToAll(message);​
 +</​code>​
  
 ===== Receiving Messages ===== ===== Receiving Messages =====
Line 43: Line 81:
 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. 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.+The first event is fired for every message sent by the 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>​%%};''​) 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 0the second object has index 1 and so on. The objects are returned as simple ​''​object''​s but can simply be cast to their original types.+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. 
 + 
 +Indices passed to ''​GetData'' ​correspond to the position of the objects in the ''​CreateMessage'' ​(or, equivalently, ''​CreateMessageType''​) call. 
 + 
 +Concluding the example: 
 + 
 +<code csharp>​ 
 +public override void OnLoad() { 
 +    Messages.Example = ...; 
 +    ModNetworking.Callbacks[Messages.Example] = msg => { 
 +        float x = (float)msg.GetData(0);​ 
 +        Block b = (Block)msg.GetData(1);​ 
 +        Debug.Log("​Received a message from " + msg.Sender.Name 
 +            + ", x = " + x 
 +            + ", b = " + b.Guid + "​!"​);​ 
 +    }; 
 +
 +</​code>​
besiege/modding/networking.1529333864.txt.gz · Last modified: 2018/06/18 16:57 by von