PubSubLib.Client 1.1.0

Client — PubSubLib.Client

Package chạy trong game client (Unity / .NET). Tự động ping định kỳ để đồng bộ trạng thái với PubSub server, nhận event để tạo/hủy GameObject. Là một IClientModule cắm vào MyConnection client.

Mục lục

• Vai trò
• Cài đặt
• Kiến trúc
• API Reference
• Cách dùng
• Luồng xử lý nội bộ
  • Tick / Ping cycle
  • Nhận event từ server
  • MoveWatcher
  • Unit tracking với WeakReference

Vai trò

Game Client (PubSubLib.Client) ◄── TCP ──► Router ◄── NATS ──► PubSub Server

Client làm 2 nhiệm vụ:

Client không tự quản lý vị trí unit — mọi thay đổi vị trí do server authoritative quyết định và gửi về qua event.

Cài đặt

<PackageReference Include="PubSubLib.Client" Version="1.1.0" />

Package target netstandard2.1 — tương thích Unity IL2CPP.

Dependencies:

• PubSubLib.Contracts — protobuf message types
• Google.Protobuf (3.34.1) — deserialize message
• MyConnection (1.0.4) — giao tiếp TCP/UDP với Router

Kiến trúc

                         PubSubClientModule                  PubSubClient
┌──────────────┐        ┌──────────────────────┐        ┌─────────────────────┐
│ MyConnection │  TCP   │ IClientModule        │        │ IPubSubClient       │
│   IClient    │◄──────►│                      │───────►│                     │
│              │        │ SetIClient(client)   │        │ Tick()              │
│              │        │   → SubscribeTcp     │        │ MoveWatcher()       │
│              │        │     "PubSub.Evt"     │        │ AddProvider()       │
│              │        │                      │        │                     │
│              │  UDP   │                      │        │ _units: Dictionary  │
│              │◄───────│                      │        │   (Id,Type) → Unit  │
│              │        │                      │        │ _providers: Dict    │
│              │        │                      │        │   "type" → IProvider│
└──────────────┘        └──────────────────────┘        └─────────────────────┘
                                   │
                                   ▼
                            IProvider (do bạn implement)
                            ├─ HeroProvider  → CreateObject / DestroyObject
                            └─ MobProvider   → CreateObject / DestroyObject

API Reference

IPubSubClient

public interface IPubSubClient
{
    void Tick();
    void MoveWatcher(Vector2 position, float radius);
    IPubSubClient AddProvider(IProvider provider);
}

IPubSubClientModule

public interface IPubSubClientModule : IClientModule
{
    static IPubSubClientModule Create(Config config);
    IPubSubClient Get();
}

Module cắm vào MyConnection client:

IProvider

public interface IProvider
{
    string UnitType { get; }

#if UNITY_ENGINE
    UnityEngine.GameObject CreateObject(long unitId, int version, byte[] data);
    void DestroyObject(long unitId, UnityEngine.GameObject obj);
    void OnEvent(long unitId, UnityEngine.GameObject obj, string eventName, byte[] data, EventMeta meta);
#else
    GameObjectTest CreateObject(long unitId, int version, byte[] data);
    void DestroyObject(long unitId, GameObjectTest obj);
    void OnEvent(long unitId, GameObjectTest obj, string eventName, byte[] data, EventMeta meta);
#endif
}

Factory pattern cho từng loại unit. Bạn implement interface này cho mỗi UnitType:

EventMeta

public enum EventTransport { Tcp, Udp }

public readonly struct EventMeta
{
    public EventTransport Transport { get; }
    public EventMeta(EventTransport transport);
}

Dùng trong IProvider.OnEvent() để biết event đến qua kênh nào:

• EventTransport.Tcp — reliable, đảm bảo delivery
• EventTransport.Udp — best-effort, có thể mất gói

Unity build: dùng #if UNITY_ENGINE — CreateObject trả về UnityEngine.GameObject, DestroyObject nhận UnityEngine.GameObject. Test/Dev build: dùng GameObjectTest (stub class trong package).

Config

public class Config
{
    public int PingIntervalMs { get; set; } = 1000;
}

Cách dùng

Setup cơ bản

using MyConnection;
using PubSubLib.Client;

// 1. Tạo MyConnection client (kết nối đến Router)
var client = IClient.Create(new ClientConfig
{
    tcpServer = "127.0.0.1:9090",
    udpServer = "127.0.0.1:9091",
    udpPingIntervalMs = 5000,
    udpPingTimeoutMs = 15000
});

// 2. Tạo PubSub client module
var pubSubModule = IPubSubClientModule.Create(new Config
{
    PingIntervalMs = 1000  // ping mỗi 1 giây
});

// 3. Đăng ký Provider cho từng loại unit
pubSubModule.Get()
    .AddProvider(new HeroProvider())
    .AddProvider(new MobProvider())
    .AddProvider(new ItemProvider());

// 4. Gắn module vào client
client.AddModule(pubSubModule);

// 5. Login (UserId = watcherId)
await client.Login(() => new LoginBody { UserId = "player_42" });
await client.ConnectServer();

// === Game Loop ===
// Mỗi frame:
//   pubSubModule.Get().Tick();                          // ping định kỳ
//   pubSubModule.Get().MoveWatcher(playerPos, 200f);     // cập nhật vị trí watcher

Implement IProvider

public class HeroProvider : IProvider
{
    public string UnitType => "hero";

    public GameObjectTest CreateObject(long unitId, int version, byte[] data)
    {
        // Unity: Instantiate prefab, set position từ data, v.v.
        var go = new GameObjectTest();
        Console.WriteLine($"[Client] Tạo hero {unitId} v{version}, data={data?.Length ?? 0} bytes");
        return go;
    }

    public void DestroyObject(long unitId, GameObjectTest obj)
    {
        // Unity: Destroy(obj.gameObject)
        Console.WriteLine($"[Client] Hủy hero {unitId}");
    }

    public void OnEvent(long unitId, GameObjectTest obj, string eventName, byte[] data, EventMeta meta)
    {
        if (meta.Transport == EventTransport.Udp)
        {
            // Xử lý event UDP (best-effort, có thể bỏ qua nếu FPS thấp)
        }
        else
        {
            // Xử lý event TCP (reliable, luôn được gọi)
        }
    }
}

Game loop đầy đủ

// Unity MonoBehaviour
public class GameManager : MonoBehaviour
{
    private IPubSubClient _pubSubClient;

    void Start()
    {
        // ... setup client, login ...
        var module = IPubSubClientModule.Create(new Config { PingIntervalMs = 500 });
        _pubSubClient = module.Get();
        _pubSubClient.AddProvider(new HeroProvider());
        client.AddModule(module);
    }

    void Update()
    {
        // Gọi Tick() mỗi frame — nội bộ tự kiểm tra thời gian ping
        _pubSubClient.Tick();

        // Gọi MoveWatcher() mỗi frame — nội bộ tự deduplicate
        _pubSubClient.MoveWatcher(transform.position, sightRadius);
    }
}

Luồng xử lý nội bộ

1. Tick / Ping cycle

Update() mỗi frame
  │
  ▼ Tick()
  ├─ Kiểm tra _client != null?
  ├─ Kiểm tra elapsed >= _pingIntervalMs?
  │   └─ Không → return (skip ping lần này)
  │
  ├─ CleanDeadUnits()
  │   ├─ Duyệt _units, kiểm tra IsAlive
  │   ├─ Unit dead (WeakReference mất) → DestroyObject + xóa khỏi _units
  │   └─ Unit alive → tiếp tục
  │
  ├─ Build PingUnitsCmd
  │   ├─ Gom tất cả unit theo type → TypeGroup
  │   │   hero: [id=42 v=7, id=43 v=3]
  │   │   mob:  [id=100 v=1]
  │   └─ cmd.Units.Add(groups)
  │
  └─ _client.SendOnUdp("PubSub.Cmd", PubSubCommand { PingUnits = cmd })
      │
      ▼ UDP ──► Router ──► NATS ──► Server // WatcherPingUnits()

CleanDeadUnits (PubSubClient.cs:162-180):

• Mỗi lần Tick(), trước khi build ping, client duyệt toàn bộ _units
• Nếu unit.IsAlive == false (GameObject bị GC collect hoặc Destroy): gọi DestroyObject trên provider, xóa khỏi _units
• Đảm bảo ping chỉ chứa unit thực sự còn sống

Deduplication: Tick() tự kiểm tra _lastPingTimestamp — chỉ gửi ping khi đủ PingIntervalMs. Bạn có thể gọi Tick() mỗi frame mà không lo spam.

2. Nhận event từ server

Client subscribe cả TCP và UDP topic PubSub.Evt để nhận event từ server, dispatch theo loại event:

TCP/UDP "PubSub.Evt" ──► PubSubClientModule.OnEvent()
                        │
                        ▼ switch evt.EvtCase
                    ┌──────────────────────────────────────────────┐
                    │ BatchEnterMsg                                │
                    │   → HandleBatchEnter(msg)                    │
                    │   → provider.CreateObject(unitId, ver, data) │
                    │   → _units[(id, type)] = new Unit(...)       │
                    │                                              │
                    │ SyncEnterMsg                                 │
                    │   → foreach item in msg.Units                │
                    │   → HandleSyncEnter(msg)                     │
                    │   → provider.CreateObject(...)               │
                    │   → _units[(id, type)] = new Unit(...)       │
                    │                                              │
                    │ BatchLeaveMsg                                │
                    │   → HandleBatchLeave(msg)                    │
                    │   → provider.DestroyObject(unitId, target)   │
                    │   → _units.Remove((id, type))                │
                    │                                              │
                    │ SyncLeaveMsg                                 │
                    │   → foreach group in msg.Keys                │
                    │   → foreach unitId in group.UnitIds          │
                    │   → HandleSyncLeave(msg)                     │
                    │   → provider.DestroyObject(...)              │
                    │   → _units.Remove((id, type))                │
                    │                                              │
                    │ UnitEventMsg                                 │
                    │   → HandleUnitEvent(msg)                     │
                    │   → provider.OnEvent(id, go, name, data, meta)│
                    └──────────────────────────────────────────────┘

Luồng điển hình:

1. Server tạo unit → BatchEnter → Client nhận → CreateObject → GameObject xuất hiện
2. Client Tick() ping → gửi version map → Server so sánh
3. Server thấy version cũ → SyncEnter với version mới → Client cập nhật
4. Server thấy unit đã mất → SyncLeave → Client DestroyObject → GameObject biến mất

3. MoveWatcher

MoveWatcher(position, radius)
  │
  ├─ Lưu _position = position, _radius = radius
  ├─ Kiểm tra dedup: vị trí và bán kính có khác lần gửi trước?
  │   └─ Không → return (không gửi lại)
  │
  ├─ _lastSentPos = position, _lastSentRadius = radius
  └─ _client.SendOnUdp("PubSub.Cmd", PubSubCommand { MoveWatcher = cmd })
      │
      ▼ UDP ──► Router ──► NATS ──► Server // pubSub.MoveWatcher()

Deduplication: So sánh (x, y, radius) hiện tại với lần gửi trước. Chỉ gửi khi thực sự thay đổi — tránh spam network khi nhân vật đứng yên.

4. Unit tracking với WeakReference

Client _units: Dictionary<(long Id, string Type), Unit>

Unit (client-side):
  ├─ Id, Version, Type
  └─ WeakReference<object> → GameObject

Vòng đời:
  1. Nhận BatchEnter/SyncEnter → CreateObject → Unit(obj) với WeakReference
  2. Tick() → CleanDeadUnits → kiểm tra Unit.IsAlive
     ├─ Alive (WeakReference còn target) → giữ lại trong ping
     └─ Dead (GC collected / Destroy) → DestroyObject + xóa khỏi _units
  3. Nhận BatchLeave/SyncLeave → DestroyObject + xóa khỏi _units

Cơ chế an toàn GC:

• Client giữ WeakReference tới GameObject, không phải strong reference
• Nếu GameObject bị destroy từ bên ngoài (vd: scene unload), IsAlive → false
• Lần Tick() tiếp theo, CleanDeadUnits phát hiện và dọn dẹp
• Server sẽ nhận ping thiếu unit → SyncLeave (nếu unit thực sự không còn trên server) hoặc SyncEnter (re-sync nếu unit vẫn còn)

Ví dụ hoàn chỉnh

Full setup Client + Router + Server: xem PubSubTestAll.cs — test FullStack_ClientKillsUnit_ServerResyncs mô phỏng client mất unit → server re-sync.