GameFrameX Server

┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                             │
│         Unity3D / Godot / LayaBox / Cocos Creator               │
├─────────────────────────────────────────────────────────────────┤
│                        Network Layer                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │   TCP    │ │WebSocket │ │   HTTP   │ │   KCP    │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
├─────────────────────────────────────────────────────────────────┤
│                     Message Processing Layer                     │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐      │
│  │TCP Msg Handlers│ │  HTTP Handlers │ │Cross-Proc Router│     │
│  └────────────────┘ └────────────────┘ └────────────────┘      │
├─────────────────────────────────────────────────────────────────┤
│                        Actor Layer                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ Player   │ │  Server  │ │ Account  │ │  Global  │           │
│  │  Actor   │ │  Actor   │ │  Actor   │ │  Actor   │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
├─────────────────────────────────────────────────────────────────┤
│              Component-Agent Layer (Hot Update Boundary)          │
│  ┌─────────────────────┐  ┌─────────────────────────────┐      │
│  │  Apps Layer (Static) │  │ Hotfix Layer (Hot-updatable) │     │
│  │ StateComponent<T>   │←→│ StateComponentAgent<T,TState>│      │
│  │ CacheState          │  │ ComponentAgent               │      │
│  └─────────────────────┘  └─────────────────────────────┘      │
├─────────────────────────────────────────────────────────────────┤
│                       Database Layer                             │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    MongoDB                               │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Server/
├── GameFrameX.Launcher/              # Application entry point
├── GameFrameX.StartUp/               # Startup orchestration and initialization
├── GameFrameX.Core/                  # Core framework (Actor system, components, events, hot update management)
├── GameFrameX.Apps/                  # State data layer (Account, Player, Server modules) — not hot-updatable
├── GameFrameX.Hotfix/                # Business logic layer (HTTP, Player, Server handlers) — hot-updatable
├── GameFrameX.Config/                # Game configuration tables (JSON format, generated by LuBan)
├── GameFrameX.Core.Config/           # Core configuration management
├── GameFrameX.Proto/                 # ProtoBuf protocol definitions
├── GameFrameX.ProtoBuf.Net/          # ProtoBuf serialization implementation
├── GameFrameX.NetWork/               # Network core (message objects, sender, WebSocket)
├── GameFrameX.NetWork.Abstractions/  # Network interfaces (IMessage, IMessageHandler, message mapping)
├── GameFrameX.NetWork.HTTP/          # HTTP server (Swagger, Kestrel, BaseHttpHandler)
├── GameFrameX.NetWork.Kcp/           # KCP protocol support (UDP-based reliable transport)
├── GameFrameX.NetWork.Message/       # Message pipeline and codec
├── GameFrameX.NetWork.RemoteMessaging/ # Cross-process remote messaging (circuit breaker, retry, consistent hashing)
├── GameFrameX.DataBase/              # Database abstraction layer
├── GameFrameX.DataBase.Mongo/        # MongoDB implementation (health monitoring, retry, batch operations)
├── GameFrameX.Localization/          # Localization system (Keys.*.cs + .resx resource files)
├── GameFrameX.Monitor/               # OpenTelemetry + Prometheus metrics integration
├── GameFrameX.Utility/               # Utilities (logging, compression, object pool, Mapster, Harmony)
├── GameFrameX.Client/                # Test client (TCP connection)
├── GameFrameX.CodeGenerator/         # Roslyn source generator (hot update proxy wrapper classes)
├── GameFrameX.AppHost/               # .NET Aspire application host
├── GameFrameX.AppHost.ServiceDefaults/ # Aspire shared defaults (OTel, service discovery)
└── Tests/
    └── GameFrameX.Tests/             # xUnit test suite

# Minimal startup parameters
dotnet GameFrameX.Launcher.dll \
    --ServerType=Game \
    --ServerId=1000 \
    --DataBaseUrl=mongodb://127.0.0.1:27017 \
    --DataBaseName=game_db

# Full startup parameters
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();
        // Initialize component state
    }
}

// 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;
    }
}

// Get component agent via ActorManager
var bagAgent = await ActorManager.GetComponentAgent<BagComponentAgent>(playerId);
var result = await bagAgent.AddItem(1001, 10);

[HttpMessageMapping(typeof(GetPlayerInfoHandler))]
[Description("Get player info")]
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 is automatically injected by the base class
            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;
        }

        // Handle player login event
        return agent.OnLogin();
    }
}

┌───────────────────────────────────────────────────────┐
│  Apps Layer (Not hot-updatable)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │StateComponent│  │StateComponent│  │StateComponent│   │
│  │ Persist State│  │ Persist State│  │ Persist State│   │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘   │
│         │                │                │           │
├─────────┼────────────────┼────────────────┼───────────┤
│         ▼                ▼                ▼           │
│  Hotfix Layer (Hot-updatable) — Loaded via             │
│  AssemblyLoadContext                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │ComponentAgent│  │ComponentAgent│  │ComponentAgent│   │
│  │Business Logic│  │Business Logic│  │Business Logic│   │
│  └─────────────┘  └─────────────┘  └─────────────┘   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │
│  │ Msg Handler  │  │ EventHandler│  │ HttpHandler  │   │
│  └─────────────┘  └─────────────┘  └─────────────┘   │
└───────────────────────────────────────────────────────┘

# Trigger hot update (with specified version)
curl -X POST "http://localhost:28080/game/api/Reload?version=1.7.2"

# Build and start
docker compose up -d --build

# View running status
docker compose ps

# View logs
docker compose logs -f game social

# Stop
docker compose down

# Build and start
docker compose -f docker-compose.multi.yml up -d --build

# View running status
docker compose -f docker-compose.multi.yml ps

# Stop
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"
  # ...

# Build image
docker build -t gameframex/server:custom .

# Run
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

# Ensure multi-instance environment is running
docker compose -f docker-compose.multi.yml up -d --build

# Execute cross-process smoke test
./scripts/multi/smoke-cross-process.sh

# Run with default parameters
./scripts/multi/run-bots-rpc.sh

# Custom parameters
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

# View all service logs
docker compose -f docker-compose.multi.yml logs -f

# View specific service logs
docker compose -f docker-compose.multi.yml logs -f game-1 game-2 social-1 social-2

# Rebuild and start (after code changes)
docker compose -f docker-compose.multi.yml up -d --build

# Run all tests
dotnet test

# Run specific test project
dotnet test Tests/GameFrameX.Tests/GameFrameX.Tests.csproj

# Run with detailed output
dotnet test --logger "console;verbosity=detailed"