Pathoschild
commented
6 years ago A few modders implemented their own networking code, documented here for reference.
PyTK
PyTK provides net APIs for other mods to use.
APIs
-
Send/receive a string:
// send PyNet.sendMessage("SomeModChannel", "some string"); // receive string str = PyNet .getNewMessages("SomeModChannel") .LastOrDefault() .message; -
Send/receive a data model (note that both ends don't necessarily need a
PyMessenger, it can send/receive messages from the other APIs):// init (on both ends) PyMessenger<MyClass> messenger = new PyMessenger<MyClass>("SomeModChannel"); // send MyClass envelope = new MyClass(params); messenger.send(envelope, SerializationType.JSON); // receive MyClass[] messages = messenger.receive().ToArray(); -
Send a data model and optionally get a response from the destination mod:
// init (on both ends) PyResponder<bool, MyClass> responder = new PyResponder<bool, MyClass>( "SomeModChannel", (MyClass data) => { /* handle incoming sync */; return true; } ); responder.start(); // send sync value PyNet.sendRequestToAllFarmers<bool>( address: "SomeModChannel", request: new MyClass(...), callback: (bool response) => { /* handle response from destination mod */; }, serializationType: SerializationType.JSON ); -
Send game assets. This supports
Map,Dictionary<string, string>,Dictionary<int, string>, andTexture2D. The message will be received by PyTK on the other end, which will deserialize the content and inject it into the local game's content managers by patching the asset returned by SMAPI. For example:// send map to another player Map map = ...; PyNet.syncMap(map, "MapName", Game1.player);Note: since the incoming asset is patched in once, it'll be lost if the asset gets invalidated or it's loaded through a different content manager.
Notes
- Pros:
- Easy to use.
- Supports custom data models (using JSON under the hood).
- Supports syncing assets (see caveat above).
- Handles farmhand→farmhand messages automatically. PyTK will route the original message to the host player, and their PyTK instance will resend it to the destination farmhand. (Requires PyTK on the host player.)
- Resistant to version changes (e.g. added/removed message fields won't cause errors).
- Cons:
- Multiple mods can't consume the same message.
- No trace logging for issues (e.g. messages to an invalid player ID are silently discarded).
References
- Docs
- PyNet.cs (main networking logic, which includes handling incoming messages)
- ContentSyncHandler.cs (underlying logic for asset syncing)
SpaceCore
SpaceCore provides low-level net APIs for other mods to use. These are undocumented and presumably intended for spacechase0's mods (though Equivalent Exchange uses them too).
APIs
-
Send/receive bytes:
// send using (var stream = new MemoryStream()) using (var writer = new BinaryWriter(stream)) { writer.Write("some string"); writer.Write(42); Networking.BroadcastMessage("SomeModChannel", stream.ToArray()); } // receive Networking.RegisterMessageHandler("SomeModChannel", IncomingMessage message => { string str = message.Reader.ReadString(); int num = message.Reader.ReadInt32(); });
Notes
- Pros:
- Simple implementation.
- Cons:
- Low-level APIs (mods need to binary serialise/deserialise themselves).
- Doesn't allow farmhand→farmhand messages.
- Vulnerable to version changes (e.g. added/removed message fields will likely cause errors).
References
- Networking.cs (networking API + implementation)
TehPers.Core.Multiplayer
TehPers.Core.Multiplayer is an upcoming framework that provides net APIs for other mods to use.
APIs
-
Send/receive binary-serialisable fields:
// init (on both ends) IMultiplayerApi net = this.GetCoreApi().GetMultiplayerApi(); // send net.SendMessage("SomeModChannel", writer => { writer.Write("some string"); writer.Write(42); }); // receive net.RegisterMessageHandler("SomeModChannel", (sender, reader) => { string str = message.Reader.ReadString(); int num = message.Reader.ReadInt32(); }); -
Automatically synchronise a value (similar to net fields):
// create synchronised field ISynchronizedWrapper<int> field = 0.MakeSynchronized(); netApi.Synchronize("unique field name", field); // read synchronised field netApi.GetSynchronized<int>("unique field name"); // read/update value int value = field.Value; field.Value = 42;Note: values are synchronised every eighth update tick.
Notes
- Pros:
- Easy to use.
- Supports synchronised fields.
- Cons:
- Multiple mods can't consume the same message.
- Doesn't allow farmhand→farmhand messages.
- Vulnerable to version changes (e.g. added/removed message fields will likely cause errors).
Ad-hoc
A few mods use the game's underlying APIs directly.
APIs
-
Send binary-serialisable fields:
// send byte messageTypeID = 50; OutgoingMessage message = new OutgoingMessage(messageTypeID, Game1.player, new object[] { "some string", 42 }); if (Game1.IsClient) Game1.client.sendMessage(message); else if (Game1.IsServer) Game1.server.sendMessage(peerId, message); // receive (called via custom Multiplayer.processIncomingMessage patch or override) void ReceiveMapPing(IncomingMessage message) { string str = message.Reader.ReadString(); int num = message.Reader.ReadInt32(); }
Notes
- Pros:
- Nothing needed besides the game itself.
- Cons:
- Low-level APIs.
- Doesn't allow farmhand→farmhand messages.
- Vulnerable to version changes (e.g. added/removed message fields will likely cause errors).
- Vulnerable to messageID collisions (we can only have 255 unique message IDs, including game + SMAPI messages).
- Some mods use Harmony patching, which is likely to cause conflicts when multiple mods do it.
Add an API to let mods perform common multiplayer tasks, like getting a multiplayer ID or broadcasting a message.
To do
SMAPI 2.6
GetNewIDandGetActiveLocations).SMAPI 2.8-beta.6
SMultiplayerclass.SMAPI 2.8-beta.7