NetSquare.Client 1.0.5

NetSquare.Client

NetSquare.Client is the client-side package for NetSquare. It provides a TCP client with optional UDP messaging, request/reply callbacks, dispatcher-based message routing, server time synchronization, and world synchronization helpers.

The package targets .NET Standard 2.0, .NET 8, and .NET Framework 4.8. It includes NetSquareClient.dll plus NetSquareCore.dll.

Installation

NuGet\Install-Package NetSquare.Client -Version 1.0.4

or:

dotnet add package NetSquare.Client --version 1.0.4

Basic Client

using System;
using NetSquare.Client;
using NetSquare.Core;

public enum GameMessage : ushort
{
    Chat = 1,
    Ping = 2,
    Welcome = 3
}

public static class Program
{
    public static void Main()
    {
        NetSquareClient client = new NetSquareClient(autoBindNetsquareActions: false);

        client.OnConnected += clientID =>
        {
            Console.WriteLine("Connected as " + clientID);
            client.SendMessage(new NetworkMessage(GameMessage.Chat).Set("Hello server"));
        };

        client.OnDisconected += () => Console.WriteLine("Disconnected");
        client.OnConnectionFail += () => Console.WriteLine("Connection failed");
        client.OnException += ex => Console.WriteLine(ex);

        client.Dispatcher.AddHeadAction(GameMessage.Welcome, "Welcome", message =>
        {
            string text = message.Serializer.GetString();
            uint assignedClientID = message.Serializer.GetUInt();
            Console.WriteLine(text + " - assigned ID: " + assignedClientID);
        });

        client.Dispatcher.AddHeadAction(GameMessage.Chat, "Chat", message =>
        {
            uint senderID = message.Serializer.GetUInt();
            string text = message.Serializer.GetString();
            Console.WriteLine(senderID + ": " + text);
        });

        client.Connect("127.0.0.1", 5555, NetSquareProtocoleType.TCP_AND_UDP);

        Console.WriteLine("Press Enter to disconnect.");
        Console.ReadLine();
        client.Disconnect();
    }
}

Sending Messages

Use NetworkMessage to write values in the order the receiver will read them.

client.SendMessage(
    new NetworkMessage(GameMessage.Chat)
        .Set("hello")
        .Set(123)
        .Set(true));

Read values from message.Serializer in the same order:

string text = message.Serializer.GetString();
int number = message.Serializer.GetInt();
bool enabled = message.Serializer.GetBool();

Supported helpers include numeric primitives, strings, chars, booleans, byte arrays, numeric arrays, INetSquareSerializable objects, lists, and dictionaries.

Request and Reply

Use the callback overload of SendMessage when the server should answer a specific request.

client.SendMessage(new NetworkMessage(GameMessage.Ping).Set("ping"), reply =>
{
    string response = reply.Serializer.GetString();
    Console.WriteLine("Server replied: " + response);
});

The server must call server.Reply(originalMessage, replyMessage) for this callback to run.

TCP and UDP

TCP is reliable and ordered:

client.SendMessage(new NetworkMessage(GameMessage.Chat).Set("reliable payload"));

UDP is faster but unreliable:

client.SendMessageUDP(new NetworkMessage(GameMessage.Chat).Set("unreliable payload"));

Connect with NetSquareProtocoleType.TCP_AND_UDP to enable both transports:

client.Connect("127.0.0.1", 5555, NetSquareProtocoleType.TCP_AND_UDP);

If world synchronization should use UDP, keep synchronizeUsingUDP enabled:

client.Connect("127.0.0.1", 5555, NetSquareProtocoleType.TCP_AND_UDP, synchronizeUsingUDP: true);

Dispatcher

Register callbacks manually:

client.Dispatcher.AddHeadAction(GameMessage.Chat, "Chat", message =>
{
    string text = message.Serializer.GetString();
});

Or auto-bind public static methods with NetSquareActionAttribute:

using NetSquare.Core;

public static class ClientHandlers
{
    [NetSquareAction(GameMessage.Chat)]
    public static void OnChat(NetworkMessage message)
    {
        string text = message.Serializer.GetString();
    }
}

Enable auto-binding by constructing the client with autoBindNetsquareActions: true.

Main Thread Dispatching

Callbacks can run from NetSquare worker threads. UI frameworks and Unity usually require work to run on the main thread. Use SetMainThreadCallback to marshal dispatch callbacks.

using System;
using System.Collections.Concurrent;

ConcurrentQueue<Action> mainThreadQueue = new ConcurrentQueue<Action>();

client.Dispatcher.SetMainThreadCallback((action, message) =>
{
    mainThreadQueue.Enqueue(() => action(message));
});

// Run this from your UI loop or Unity Update method.
while (mainThreadQueue.TryDequeue(out Action callback))
{
    callback();
}

Server Time Synchronization

SyncTime estimates server time from client time and round-trip delay.

client.SyncTime(
    getClientTime: () => (float)DateTime.UtcNow.TimeOfDay.TotalSeconds,
    precision: 5,
    timeBetweenSyncs: 1000,
    onServerTimeGet: serverTime => Console.WriteLine("Server time: " + serverTime),
    onLog: Console.WriteLine);

float synchronizedTime = client.GetServerTime((float)DateTime.UtcNow.TimeOfDay.TotalSeconds);

SmoothServerTimeOffset is enabled by default so offset changes are applied gradually.

World Synchronization

Join a server world and send transform frames:

client.WorldsManager.TryJoinWorld(1, new NetsquareTransformFrame(0, 0, 0), joined =>
{
    Console.WriteLine("Joined world: " + joined);
});

client.WorldsManager.OnClientJoinWorld += (clientID, transform, message) =>
{
    Console.WriteLine("Client joined world: " + clientID + " at " + transform);
};

client.WorldsManager.OnClientLeaveWorld += clientID =>
{
    Console.WriteLine("Client left world: " + clientID);
};

client.WorldsManager.OnReceiveSynchFrames += (clientID, frames) =>
{
    foreach (INetSquareSynchFrame frame in frames)
        Console.WriteLine("Frame from " + clientID + ": " + frame.SynchFrameType);
};

client.WorldsManager.SendSynchFrame(
    new NetsquareTransformFrame(_x: 10, _y: 0, _z: 5, _time: 1.25f));

You can queue frames and send them as a batch:

client.WorldsManager.StoreSynchFrame(new NetsquareTransformFrame(_x: 1, _y: 0, _z: 0));
client.WorldsManager.StoreSynchFrame(new NetsquareTransformFrame(_x: 2, _y: 0, _z: 0));
client.WorldsManager.SendFrames();

Useful Client Properties

• ClientID: current server-assigned ID.
• IsConnected: whether the TCP socket is connected.
• NbSendingMessages: pending outgoing messages.
• NbProcessingMessages: queued incoming messages waiting for dispatch.
• ServerTimeOffset: current estimated server time offset.
• WorldsManager: world membership and synchronization API.

License

MIT