Modding:Network API: Difference between revisions
No edit summary |
|||
(One intermediate revision by the same user not shown) | |||
Line 1: | Line 1: | ||
__FORCETOC__ | __FORCETOC__ | ||
{{GameVersion|1.19. | {{GameVersion|1.19.8}} | ||
<languages/><translate> | <languages/><translate> | ||
<!--T:1--> | <!--T:1--> | ||
Line 58: | Line 58: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
The argument we pass to <code>ProtoMember</code> is a unique unsigned integer called a tag, and it's used to identify the fields flagged for serialization. When the client receives the packet containing the serialized <code>ProtoContract</code>, it won't know the type of its members, and will identify them by the tag number. | The argument we pass to <code>ProtoMember</code> is a unique unsigned integer called a tag, and it's used to identify the fields flagged for serialization. When the client receives the packet containing the serialized <code>ProtoContract</code>, it won't know the type of its members, and will identify them by the tag number. We could also use the class header <code>[ProtoContract(ImplicitFields = ImplicitFields.AllPublic)]</code> and skip all [ProtoMember] tags to flag all public fields for serialization, then tags are assigned in alphabetic order. ProtoBuf is beyond the scope of this tutorial, but you can read more about this powerful library [https://developers.google.com/protocol-buffers/docs/csharptutorial here]. | ||
The fields in these classes hold the data we wish to send through our channel. We'll use <code>NetworkApiTestMessage</code> to encase the initial message from the server, while <code>NetWorkApiTestResponse</code> will be used by the Client to send its response. | The fields in these classes hold the data we wish to send through our channel. We'll use <code>NetworkApiTestMessage</code> to encase the initial message from the server, while <code>NetWorkApiTestResponse</code> will be used by the Client to send its response. |
Latest revision as of 14:10, 13 July 2024
This page was last verified for Vintage Story version 1.19.8.
Before starting, you should have a development environment set up. If you don't have one already you should read the tutorial Setting up your Development Environment. Furthermore, we assume that you have a basic understanding of the C# language and Object Oriented Programming. Let's get started!
Hint: If you need to send data for Entities or BlockEntities, it may be more appropriate to use the inbuilt network methods for these. Check out the IServerNetworkAPI and IClientNetworkAPI interfaces for more information.
Introduction
In this example mod we will show you how to send custom data back and forth between the Server and the Client. To do this, we will set up a network channel through which string messages will be sent in a network channel.
We will create a server command that will send out a message to all clients, and if a client receives this, it will send a response back to the server; upon receiving this response, the server will display it along with the responding client's player name.
If something goes wrong, Wireshark with the vs-protocol dissector is a helpful debug tool.
Preparation
Let's start by creating a new .cs file for this mod, and adding our imports and the namespace in which we'll wrap all of our classes:
using ProtoBuf;
using Vintagestory.API.Client;
using Vintagestory.API.Common;
using Vintagestory.API.Config;
using Vintagestory.API.Server;
namespace Vintagestory.ServerMods
{
}
ProtoContracts
VintageStory uses multiple serialization formats. This tutorial uses the protobuf format. The Protobuf-net library can serialize classes declared with the ProtoContract
attribute.
Inside our namespace block, let's create 2 data packets using ProtoContract
:
[ProtoContract]
public class NetworkApiTestMessage
{
[ProtoMember(1)]
public string message;
}
[ProtoContract]
public class NetworkApiTestResponse
{
[ProtoMember(1)]
public string response;
}
The argument we pass to ProtoMember
is a unique unsigned integer called a tag, and it's used to identify the fields flagged for serialization. When the client receives the packet containing the serialized ProtoContract
, it won't know the type of its members, and will identify them by the tag number. We could also use the class header [ProtoContract(ImplicitFields = ImplicitFields.AllPublic)]
and skip all [ProtoMember] tags to flag all public fields for serialization, then tags are assigned in alphabetic order. ProtoBuf is beyond the scope of this tutorial, but you can read more about this powerful library here.
The fields in these classes hold the data we wish to send through our channel. We'll use NetworkApiTestMessage
to encase the initial message from the server, while NetWorkApiTestResponse
will be used by the Client to send its response.
NetworkApiTest
Now we will create our main class that inherits from the ModSystem
class, which is the base class for mod systems. You can read more about this here. Moreover, we'll be separating our Client and Server sides within the class with region blocks for readability purposes.
public class NetworkApiTest : ModSystem
{
public override void Start(ICoreAPI api)
{
api.Network
.RegisterChannel("networkapitest")
.RegisterMessageType(typeof(NetworkApiTestMessage))
.RegisterMessageType(typeof(NetworkApiTestResponse))
;
}
#region Client
// Client side here
#endregion
#region Server
// Server side here
#endregion
}
The Core API contains the Network property, which provides us with the RegisterChannel
method. We pass this method a string containing the name we choose for our channel, in this case we'll call our channel "networkapitest". The code in Start() is executed on the server as well as the client. We now have two connected endpoints.
The system still needs to know what kind of packages you will want to send. We do this with the RegisterMessageType
method.
Server Setup
Next, we'll set up our network channel on the Server side, and register a server command to dispatch our message.
#region Server
IServerNetworkChannel serverChannel;
ICoreServerAPI serverApi;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
serverChannel = api.Network.GetChannel("networkapitest")
.SetMessageHandler<NetworkApiTestResponse>(OnClientMessage)
;
api.ChatCommands.Create("nwtest")
.WithDescription("Send a test network message")
.RequiresPrivilege(Privilege.controlserver)
.HandleWith(new OnCommandDelegate(OnNwTestCmd));
}
#endregion
We call SetMessageHandler<T>
on our channel, which takes a delegate that will be called every time when the given type of Packet is received from a client, in this case NetworkApiTestResponse
will be handled by OnClientMessage
which we'll declare later.
Now that our channel is fully set up on the Server side, we'll want to register a server command that will broadcast a network message to all the clients listening to our "networkapitest" channel.
#region Server
IServerNetworkChannel serverChannel;
ICoreServerAPI serverApi;
public override void StartServerSide(ICoreServerAPI api)...
private TextCommandResult OnNwTestCmd(TextCommandCallingArgs args)
{
serverChannel.BroadcastPacket(new NetworkApiTestMessage()
{
message = "Hello World!",
});
return TextCommandResult.Success();
}
#endregion
The server channel gives us the BroadcastPacket
method which we'll use to send out a NetworkApiTestMessage
instance to all clients listening to the "networkapitest" channel, in this case we send "Hello World!" as the message.
Client Setup
Above the Server Side region, we'll create our Client fields and an override for the StartClientSide
, which is a Client side version of its Server side counterpart.
#region Client
IClientNetworkChannel clientChannel;
ICoreClientAPI clientApi;
public override void StartClientSide(ICoreClientAPI api)
{
clientApi = api;
clientChannel = api.Network.GetChannel("networkapitest")
.SetMessageHandler<NetworkApiTestMessage>(OnServerMessage)
;
}
#endregion
Also on the client we call SetMessageHandler
to listen for messages of type NetworkApiTestMessage
, using a delegate named OnServerMessage
.
#region Client
IClientNetworkChannel clientChannel;
ICoreClientAPI clientApi;
public override void StartClientSide(ICoreClientAPI api)...
private void OnServerMessage(NetworkApiTestMessage networkMessage)
{
clientApi.ShowChatMessage("Received following message from server: " + networkMessage.message);
clientApi.ShowChatMessage("Sending response.");
clientChannel.SendPacket(new NetworkApiTestResponse()
{
response = "RE: Hello World!"
});
}
#endregion
Here we simply show a chat message to the client with the contents of the message sent from the server.
We then let the client know that we're sending our response to the server, and call SendPacket
passing it an instance of NetworkApiTestResponse
.
Now let's go back to the Server side and create the handler for this response!
Handling Client Responses
In our Server side region, let's write a final delegate method:
#region Server
IServerNetworkChannel serverChannel;
ICoreServerAPI serverApi;
public override void StartServerSide(ICoreServerAPI api)...
private void OnNwTestCmd(IServerPlayer player, int groupId, CmdArgs args)...
private void OnClientMessage(IPlayer fromPlayer, NetworkApiTestResponse networkMessage)
{
serverApi.SendMessageToGroup(
GlobalConstants.GeneralChatGroup,
"Received following response from " + fromPlayer.PlayerName + ": " + networkMessage.response,
EnumChatType.Notification
);
}
#endregion
Message handlers on the server have an additional parameter compared to client handlers, which is the player whose client sent the message.
In this handler we simply broadcast a server-wide message containing the responding player's name and the content of the response.
Conclusion
If you followed the steps correctly, you should have the following code:
using ProtoBuf;
using Vintagestory.API.Client;
using Vintagestory.API.Common;
using Vintagestory.API.Config;
using Vintagestory.API.Server;
namespace Vintagestory.ServerMods
{
[ProtoContract]
public class NetworkApiTestMessage
{
[ProtoMember(1)]
public string message;
}
[ProtoContract]
public class NetworkApiTestResponse
{
[ProtoMember(1)]
public string response;
}
/// <summary>
/// A basic example of client<->server networking using a custom network communication
/// </summary>
public class NetworkApiTest : ModSystem
{
public override void Start(ICoreAPI api)
{
api.Network
.RegisterChannel("networkapitest")
.RegisterMessageType(typeof(NetworkApiTestMessage))
.RegisterMessageType(typeof(NetworkApiTestResponse))
;
}
#region Server
IServerNetworkChannel serverChannel;
ICoreServerAPI serverApi;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
serverChannel = api.Network.GetChannel("networkapitest")
.SetMessageHandler<NetworkApiTestResponse>(OnClientMessage)
;
api.ChatCommands.Create("nwtest")
.WithDescription("Send a test network message")
.RequiresPrivilege(Privilege.controlserver)
.HandleWith(new OnCommandDelegate(OnNwTestCmd));
}
private TextCommandResult OnNwTestCmd(TextCommandCallingArgs args)
{
serverChannel.BroadcastPacket(new NetworkApiTestMessage()
{
message = "Hello World!",
});
return TextCommandResult.Success();
}
private void OnClientMessage(IPlayer fromPlayer, NetworkApiTestResponse networkMessage)
{
serverApi.SendMessageToGroup(
GlobalConstants.GeneralChatGroup,
"Received following response from " + fromPlayer.PlayerName + ": " + networkMessage.response,
EnumChatType.Notification
);
}
#endregion
#region Client
IClientNetworkChannel clientChannel;
ICoreClientAPI clientApi;
public override void StartClientSide(ICoreClientAPI api)
{
clientApi = api;
clientChannel = api.Network.GetChannel("networkapitest")
.SetMessageHandler<NetworkApiTestMessage>(OnServerMessage)
;
}
private void OnServerMessage(NetworkApiTestMessage networkMessage)
{
clientApi.ShowChatMessage("Received following message from server: " + networkMessage.message);
clientApi.ShowChatMessage("Sending response.");
clientChannel.SendPacket(new NetworkApiTestResponse()
{
response = "RE: Hello World!"
});
}
#endregion
}
}
Testing
Let's run the mod now! Once you're ingame, try entering /nwtest
. You should be met with an initial "Hello World!" message as well as a confirmation message that the server received the response from the Client!
Code Modding | |||||||
---|---|---|---|---|---|---|---|
Basics | Code Mods • Preparing For Code Mods • Creating A Code Mod | ||||||
Tutorials |
|
||||||
Advanced | Server-Client Considerations • Setting up your Development Environment • Advanced Blocks • Advanced Items • Block and Item Interactions • Block Behavior • Block Entity • Particle Effects • World Access • Inventory Handling • Commands • GUIs • Network API • Monkey patching (Harmony) | ||||||
Data Management | VCDBS format • Savegame Moddata • ModConfig File • Chunk Moddata • Serialization Formats • TreeAttribute | ||||||
Worldgen | WorldGen API • NatFloat • EvolvingNatFloat | ||||||
Rendering | Shaders and Renderers |
![Icon Sign.png](/images/thumb/1/15/Icon_Sign.png/32px-Icon_Sign.png)
Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.
Modding | |
---|---|
Modding Introduction | Getting Started • Theme Pack |
Content Modding | Content Mods • Developing a Content Mod • Basic Tutorials • Intermediate Tutorials • Advanced Tutorials • Content Mod Concepts |
Code Modding | Code Mods • Setting up your Development Environment |
Property Overview | Item • Entity • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • World properties |
Workflows & Infrastructure | Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine |
Additional Resources | Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters Example Mods • API Docs • GitHub Repository |