GameFrameX Server

┌─────────────────────────────────────────────────────────────────┐
│                          客戶端層                                │
│         Unity3D / Godot / LayaBox / Cocos Creator               │
├─────────────────────────────────────────────────────────────────┤
│                          網路層                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │   TCP    │ │WebSocket │ │   HTTP   │ │   KCP    │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
├─────────────────────────────────────────────────────────────────┤
│                       訊息處理層                                  │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐      │
│  │ TCP 訊息處理器  │ │  HTTP 處理器   │ │ 跨程序訊息路由  │      │
│  └────────────────┘ └────────────────┘ └────────────────┘      │
├─────────────────────────────────────────────────────────────────┤
│                       Actor 層                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ 玩家     │ │ 伺服器   │ │  帳戶    │ │ 全域     │           │
│  │ Actor    │ │ Actor    │ │  Actor   │ │ Actor    │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
├─────────────────────────────────────────────────────────────────┤
│                    元件-代理層（熱更新邊界）                        │
│  ┌─────────────────────┐  ┌─────────────────────────────┐      │
│  │ Apps 層 (不可熱更)   │  │ Hotfix 層 (可熱更)           │      │
│  │ StateComponent<T>   │←→│ StateComponentAgent<T,TState>│      │
│  │ CacheState          │  │ ComponentAgent               │      │
│  └─────────────────────┘  └─────────────────────────────┘      │
├─────────────────────────────────────────────────────────────────┤
│                       資料庫層                                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    MongoDB                               │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Server/
├── GameFrameX.Launcher/              # 應用入口點
├── GameFrameX.StartUp/               # 啟動編排和初始化
├── GameFrameX.Core/                  # 核心框架（Actor 系統、元件、事件、熱更新管理）
├── GameFrameX.Apps/                  # 狀態資料層（帳戶、玩家、伺服器模組）— 不可熱更
├── GameFrameX.Hotfix/                # 業務邏輯層（HTTP、玩家、伺服器處理器）— 可熱更
├── GameFrameX.Config/                # 遊戲配置表（JSON 格式，LuBan 生成）
├── GameFrameX.Core.Config/           # 核心配置管理
├── GameFrameX.Proto/                 # ProtoBuf 協議定義
├── GameFrameX.ProtoBuf.Net/          # ProtoBuf 序列化實作
├── GameFrameX.NetWork/               # 網路核心（訊息物件、傳送器、WebSocket）
├── GameFrameX.NetWork.Abstractions/  # 網路介面（IMessage、IMessageHandler、訊息映射）
├── GameFrameX.NetWork.HTTP/          # HTTP 伺服器（Swagger、Kestrel、BaseHttpHandler）
├── GameFrameX.NetWork.Kcp/           # KCP 協議支援（基於 UDP 的可靠傳輸）
├── GameFrameX.NetWork.Message/       # 訊息管道和編解碼
├── GameFrameX.NetWork.RemoteMessaging/ # 跨程序遠端訊息（斷路器、重試、一致性雜湊）
├── GameFrameX.DataBase/              # 資料庫抽象層
├── GameFrameX.DataBase.Mongo/        # MongoDB 實作（健康監控、重試、批次操作）
├── GameFrameX.Localization/          # 本地化系統（Keys.*.cs + .resx 資源檔案）
├── GameFrameX.Monitor/               # OpenTelemetry + Prometheus 指標整合
├── GameFrameX.Utility/               # 工具集（日誌、壓縮、物件池、Mapster、Harmony）
├── GameFrameX.Client/                # 測試客戶端（TCP 連線）
├── GameFrameX.CodeGenerator/         # Roslyn 原始碼生成器（熱更新代理包裝類別）
├── GameFrameX.AppHost/               # .NET Aspire 應用主機
├── GameFrameX.AppHost.ServiceDefaults/ # Aspire 共享預設配置（OTel、服務發現）
└── Tests/
    └── GameFrameX.Tests/             # xUnit 測試套件

# 最小啟動參數
dotnet GameFrameX.Launcher.dll \
    --ServerType=Game \
    --ServerId=1000 \
    --DataBaseUrl=mongodb://127.0.0.1:27017 \
    --DataBaseName=game_db

# 完整啟動參數
dotnet GameFrameX.Launcher.dll \
    --ServerType=Game \
    --ServerId=1000 \
    --ServerInstanceId=1 \
    --InnerHost=0.0.0.0 \
    --InnerPort=29100 \
    --OuterHost=0.0.0.0 \
    --OuterPort=29100 \
    --HttpPort=28080 \
    --IsEnableHttp=true \
    --HttpIsDevelopment=true \
    --IsEnableWebSocket=false \
    --DataBaseUrl=mongodb://127.0.0.1:27017 \
    --DataBaseName=gameframex \
    --IsDebug=true \
    --IsOpenTelemetry=true \
    --IsOpenTelemetryMetrics=true \
    --LogIsConsole=true \
    --LogIsWriteToFile=true

// GameFrameX.Apps/Player/BagState.cs
public class BagState : BaseCacheState
{
    public List<ItemData> Items { get; set; } = new List<ItemData>();
    public int MaxSlots { get; set; } = 50;
}

// GameFrameX.Apps/Player/BagComponent.cs
public class BagComponent : StateComponent<BagState>
{
    protected override async Task OnInit()
    {
        await base.OnInit();
        // 初始化元件狀態
    }
}

// GameFrameX.Hotfix/Logic/Player/BagComponentAgent.cs
public class BagComponentAgent : StateComponentAgent<BagComponent, BagState>
{
    public async Task<bool> AddItem(int itemId, int count)
    {
        if (State.Items.Count >= State.MaxSlots)
        {
            return false;
        }

        var item = new ItemData { Id = itemId, Count = count };
        State.Items.Add(item);

        await Save();
        return true;
    }
}

// 透過 ActorManager 取得元件代理
var bagAgent = await ActorManager.GetComponentAgent<BagComponentAgent>(playerId);
var result = await bagAgent.AddItem(1001, 10);

[HttpMessageMapping(typeof(GetPlayerInfoHandler))]
[Description("取得玩家資訊")]
public sealed class GetPlayerInfoHandler : BaseHttpHandler
{
    public override async Task<MessageObject> Action(
        string ip, string url,
        Dictionary<string, object> parameters,
        MessageObject messageObject)
    {
        var request = (GetPlayerInfoRequest)messageObject;
        var response = new GetPlayerInfoResponse();

        var agent = await ActorManager.GetComponentAgent<PlayerComponentAgent>(request.PlayerId);
        if (agent == null)
        {
            response.ErrorCode = (int)ResultCode.PlayerNotFound;
            return response;
        }

        response.PlayerInfo = await agent.GetPlayerInfo();
        return response;
    }
}

[MessageMapping(typeof(ReqChatMessage))]
internal sealed class ChatMessageHandler : PlayerComponentHandler<ChatComponentAgent, ReqChatMessage>
{
    protected override async Task ActionAsync(ReqChatMessage request)
    {
        await ComponentAgent.ProcessChatMessage(request);
    }
}

[MessageMapping(typeof(ReqAddItem))]
internal sealed class AddItemHandler : PlayerRpcComponentHandler<BagComponentAgent, ReqAddItem, RespAddItem>
{
    protected override async Task ActionAsync(ReqAddItem request, RespAddItem response)
    {
        try
        {
            // ComponentAgent 由基類自動注入
            await ComponentAgent.AddItem(request, response);
        }
        catch (Exception e)
        {
            LogHelper.Fatal(e);
            response.ErrorCode = (int)OperationStatusCode.InternalServerError;
        }
    }
}

[Event(EventId.PlayerLogin)]
internal sealed class PlayerLoginEventHandler : EventListener<PlayerComponentAgent>
{
    protected override Task HandleEvent(PlayerComponentAgent agent, GameEventArgs gameEventArgs)
    {
        if (agent == null)
        {
            return Task.CompletedTask;
        }

        // 處理玩家登入事件
        return agent.OnLogin();
    }
}

┌───────────────────────────────────────────────────────┐
│  Apps 層（不可熱更）                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │ StateComponent│  │ StateComponent│  │ StateComponent│  │
│  │   持久化狀態   │  │   持久化狀態   │  │   持久化狀態   │  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘   │
│         │                │                │           │
├─────────┼────────────────┼────────────────┼───────────┤
│         ▼                ▼                ▼           │
│  Hotfix 層（可熱更）— 透過 AssemblyLoadContext 載入     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │ComponentAgent│  │ComponentAgent│  │ComponentAgent│  │
│  │   業務邏輯    │  │   業務邏輯    │  │   業務邏輯    │  │
│  └─────────────┘  └─────────────┘  └─────────────┘   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │ Msg Handler  │  │ EventHandler│  │ HttpHandler  │   │
│  └─────────────┘  └─────────────┘  └─────────────┘   │
└───────────────────────────────────────────────────────┘

# 觸發熱更新（指定版本號）
curl -X POST "http://localhost:28080/game/api/Reload?version=1.7.2"

# 建置並啟動
docker compose up -d --build

# 檢視執行狀態
docker compose ps

# 檢視日誌
docker compose logs -f game social

# 停止
docker compose down

# 建置並啟動
docker compose -f docker-compose.multi.yml up -d --build

# 檢視執行狀態
docker compose -f docker-compose.multi.yml ps

# 停止
docker compose -f docker-compose.multi.yml down

environment:
  services__Social_2001__tcp__0: "tcp://social-1:29400"
  services__Social_2002__tcp__0: "tcp://social-2:29401"
  services__Game_1001__tcp__0: "tcp://game-1:29100"
  # ...

# 建置映像
docker build -t gameframex/server:custom .

# 執行
docker run -d \
    --name my-game-server \
    -p 29100:29100 \
    -p 28080:28080 \
    gameframex/server:custom \
    --ServerType=Game \
    --ServerId=2000 \
    --DataBaseUrl=mongodb://mongo-host:27017 \
    --DataBaseName=my_game

# 確保多實例環境已啟動
docker compose -f docker-compose.multi.yml up -d --build

# 執行跨程序冒煙測試
./scripts/multi/smoke-cross-process.sh

# 預設參數執行
./scripts/multi/run-bots-rpc.sh

# 自訂參數
BOT_COUNT=200 \
TCP_PORT=49100 \
LOGIN_URL=http://127.0.0.1:48080/game/api/ \
DISCONNECT_AFTER_LOGIN_SECONDS=20 \
RUN_SECONDS=300 \
./scripts/multi/run-bots-rpc.sh

# 檢視所有服務日誌
docker compose -f docker-compose.multi.yml logs -f

# 檢視指定服務日誌
docker compose -f docker-compose.multi.yml logs -f game-1 game-2 social-1 social-2

# 重建並啟動（程式碼變更後）
docker compose -f docker-compose.multi.yml up -d --build

# 執行所有測試
dotnet test

# 執行指定測試專案
dotnet test Tests/GameFrameX.Tests/GameFrameX.Tests.csproj

# 執行並顯示詳細輸出
dotnet test --logger "console;verbosity=detailed"