XelerateV2 1.0.0

XelerateV2

<div align="center"> <p><strong>Hệ thống quản lý và đồng bộ không gian thế giới 3D hiệu năng cao dành cho các tựa game và ứng dụng nhiều người chơi (Multiplayer/MMO).</strong></p> </div>

🎯 Mục tiêu dự án

• Quản lý không gian thế giới: Tiếp nhận và quản lý các đối tượng (Unit) từ Unity gửi lên.
• Đồng bộ thời gian thực: Đồng bộ trạng thái của các đối tượng giữa các client với không gian thế giới chung một cách trơn tru.
• Tối ưu hiệu năng tối đa: Phân chia không gian thế giới thành các khu vực lớn (Region) và cắt nhỏ tiếp thành các ô tọa độ (Tile) nhằm tối ưu thuật toán tìm kiếm và lọc đối tượng.

💻 Ngôn ngữ & Công nghệ sử dụng

• C# .NET 9.0 (Kế thừa .NET Standard 2.0): Cung cấp tính tương thích ngược mạnh mẽ, đáp ứng được các dự án legacy lẫn modern.
• Tích hợp linh hoạt với Unity:
  • Sử dụng macro #if UNITY_5_3_OR_NEWER để chống lỗi môi trường khi build backend riêng biệt.
  • Tự động dùng Vector3 gốc của Unity nếu chạy trong engine, hoặc fallback về định nghĩa riêng nếu ở C# thuần.

🧩 Các thực thể cốt lõi

1. Unit: Các thực thể hiện diện trong thế giới 3D (Nhân vật, Quái vật, Đồ vật, NPC...).
2. Watcher: Thực thể đóng vai trò "Camera" hoặc "Người chơi", quan sát các sự kiện xảy ra trong một phạm vi (bán kính) cụ thể.
3. Region: Một vùng không gian lớn độc lập.
4. Tile: Phân vùng cực nhỏ bên trong Region để tối ưu hóa tính toán không gian.

📦 Các module phụ thuộc (Dependencies)

• Natify: Thư viện giao tiếp Socket/RPC hiệu năng siêu cao dựa trên NATS.
• Protobuf: Định dạng mã hóa dữ liệu nhị phân (Binary Serialization) nhỏ nhẹ, tốc độ cao.
• TimeSortedSet: Cấu trúc dữ liệu lên lịch (được đính kèm trong Natify) chuyên giải quyết các bài toán "hẹn giờ chuyển Tile" cho Unit trong quá trình di chuyển.

🏗 Kiến trúc hệ thống

Dự án xoay quanh 3 class trụ cột chính, tương tác lẫn nhau qua nền tảng trung gian Natify.

1. XelerateServer (Máy chủ trung tâm)

• Bọc quanh NatifyServer để xử lý routing và event.
• Tự động mở rộng (Auto-scaling): Tự động khởi tạo Region mới khi XelerateUnityClient hoặc XelerateClient push data vào một Region chưa tồn tại.
• An toàn luồng (Thread-safe): Mỗi Region sử dụng 1 luồng duy nhất duyệt tuần tự qua Channel để xử lý input từ tất cả Client, ngăn chặn triệt để race-condition.
• Cấu hình (Configuration):
  • NatsUrl: Chuỗi kết nối tới NATS (Mặc định: nats://localhost:4222).
  • TileSize: Kích thước thực của từng Tile (Mặc định: 20).
  • PingTimeExpired: Thời gian Timeout để dọn dẹp các Unit mất kết nối/không ping (Mặc định: 10 giây).

2. XelerateUnityClient (Client dành cho Game Engine)

• Bọc quanh NatifyClient, thiết kế riêng cho Main Thread của Unity.
• Đa luồng (Multi-threading): Mọi tác vụ Serialize Protobuf và Send Data đều tống qua một luồng phụ để giải phóng luồng chính.
• Dispatcher Main Thread: Gói tin trả về được giải mã ở luồng phụ, sau đó xếp hàng (Queue). Unity sẽ gọi Tick() bên trong Update() để pop lần lượt tối đa 100 tác vụ/frame trả về lại Main Thread.
• Các phương thức chính:
  • SendUnitEnter: Gửi thông tin khởi tạo, vị trí, đường đi (path 3D), tốc độ, data và version. Server sẽ tự nội suy điểm giao cắt Tile (mặt phẳng X, Z) để lên lịch chuyển ô.
  • SendUnitUpdate: Cập nhật Data cho Unit (tự động đè version mới nhất).
  • SendUnitUpdatePath: Cập nhật lộ trình di chuyển. Lịch trình cũ bị hủy, thay bằng lộ trình mới.
  • SendUnitLeave: Báo cáo xóa Unit hoặc rời khu vực.
  • PingUnit: Heartbeat duy trì sự sống (khuyến cáo 1 giây/lần).
  • OnRequire: Lắng nghe yêu cầu "Gửi lại Data" từ server khi xảy ra lỗi đồng bộ lệch version.

3. XelerateClient (Client C# thuần cho Backend/Bot)

• Sử dụng NatifyClientFast, không bị gò bó bởi khái niệm Main Thread (Không cần gọi Tick()).
• Các phương thức & Event:
  • RegisterWatcher / UnRegisterWatcher: Đăng ký/Hủy theo dõi một vùng hình tròn tâm (X, Y) bán kính Radius.
  • Move: Liên tục cập nhật lại tâm (X, Y) khi Watcher di chuyển.
  • WatcherPing: Heartbeat cho Watcher.
  • WatcherPingUnit: Đối soát trạng thái các Unit mà Watcher đang nhìn thấy với Server. Server sẽ tự động chữa lỗi (Heal) bằng cách bù thêm Unit thiếu, yêu cầu xóa Unit thừa, hoặc cập nhật Unit sai version.
• Lắng nghe sự kiện:
  • OnUnitEnterRegion: Kích hoạt khi có 1 Unit bước vào vùng nhìn thấy.
  • OnUnitLeaveRegion: Unit đi ra khỏi vùng, hoặc bị xóa trên server.
  • OnUnitUpdateRegion: Unit thay đổi dữ liệu hoặc trạng thái bên trong vùng.

📡 Giao thức & Protobuf Messages

Hệ thống tận dụng tối đa việc tái sử dụng message để giảm bớt file sinh ra, dùng các trường optional để xác định ngữ cảnh gửi nhận. (Mỗi topic trên Natify được thiết kế rõ ràng theo cơ chế Single-Responsibility).

🛠 API Debug & Monitor (Chỉ đọc)

XelerateServer cung cấp một bộ API cho phép Backend theo dõi sức khỏe của hệ thống:

• GetActiveRegion(): Xuất toàn bộ snapshot hệ thống (Danh sách Region, danh sách ID của Watcher, số lượng Unit theo Type...).
• GetSizeChannel(string regionId): Trả về số lượng tin nhắn đang ùn ứ trong Channel của Region. Dùng để monitor nghẽn cổ chai.
• GetCurrentUnitCount(string regionId, string unitType): Thống kê số lượng Unit hiện hành.
• GetExpriredCount(string regionId): Lượng Unit đã bị vứt bỏ do Timeout.
• GetWatcherInfo(...), GetUnitInfo<T>(...): Xem thông tin chi tiết từng thực thể.

🧪 Kiểm thử Tự động (Unit Testing)

Tích hợp XelerateV2Test bằng thư viện NUnit với các kịch bản thực tế khắt khe:

1. Đảm bảo Watcher được phân bổ chính xác vào ma trận 9 Tile cạnh nhau (khu vực 3x3).
2. Khi UnityClient nhồi Unit vào phạm vi của Watcher, Event OnUnitEnterRegion phải trigger chuẩn xác.
3. Cơ chế Timeout 10 giây nếu không ping sẽ bắn Event OnUnitLeaveRegion.
4. Logic đường đi liên khu vực (Inter-Tile movement): Unit di chuyển qua nhiều Tile nhưng vẫn trong tầm nhìn của Watcher thì không bị bắn Event Enter/Leave thừa thãi.
5. Sự kiện Update chỉ được phân phối (Broadcasting) đến đúng các Watcher đang đứng gần Unit đó.
6. Auto-Healing: Watcher ping lên 1 danh sách Unit rác, hệ thống tự động trả về lệnh xóa. Watcher ping thiếu Unit, hệ thống tự chèn thêm. Watcher gửi sai Version, hệ thống tự động Override bằng Data đúng.