Modding:Network API

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!

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.