GameFrameX.NetWork.HTTP 1.13.7

<div align="center">

GameFrameX Server

High-Performance, Cross-Platform Game Server Framework

📖 Documentation • 🚀 Quick Start • 💬 QQ Group: 467608841

🌐 Language: English | 简体中文 | 繁體中文 | 日本語 | 한국어

</div>

Table of Contents

• Introduction
• Core Features
• Architecture
• Project Structure
• Quick Start
• Configuration Management
• Business Logic Development
• Hot Update Mechanism
• Docker Deployment
• Multi-Process Cross-Process Debugging
• Monitoring & Observability
• Testing
• Contributing
• License
• Related Links

Introduction

GameFrameX Server is a high-performance, cross-platform game server framework built with C# .NET 10.0, designed with the Actor model and supporting hot update mechanisms. Designed for multiplayer online game development, it supports integration with various client platforms including Unity3D, Godot, and LayaBox.

Design Philosophy: Simplicity is the ultimate sophistication

Core Features

High-Performance Architecture

• Actor Model: Lock-free high-concurrency system built on TPL DataFlow, avoiding traditional lock performance overhead through message passing
• Full Asynchronous Programming: Complete async/await asynchronous programming model
• Zero-Lock Design: Actor internal state is accessed through message queue serialization, no locking required
• Batch Persistence: Supports batch database writes with configurable batch size and timeout
• Snowflake ID Generation: Built-in distributed unique ID generator with worker node and data center configuration

Hot Update System

• Zero-Downtime Updates: Runtime loading of new logic assemblies without stopping the service
• State-Logic Separation: Strict separation between persistent state data (Apps layer) and hot-updatable business logic (Hotfix layer)
• Graceful Transition: Old assemblies retain a 10-minute grace period, waiting for in-progress requests to complete before unloading
• Version Management: Supports loading specific versions via HTTP endpoint

Multi-Protocol Network Communication

• TCP: High-performance TCP server based on SuperSocket, primary game communication protocol
• UDP: Optional UDP protocol support
• WebSocket: Bidirectional communication based on SuperSocket WebSocket
• HTTP/HTTPS: HTTP service based on Kestrel, supporting Swagger documentation, CORS, health checks
• KCP: UDP reliable transport based on KCP protocol (experimental)
• Cross-Process Messaging: Built-in RemoteMessaging module with circuit breaker, retry strategy, and consistent hashing sharding

Database & Persistence

• MongoDB Primary Database: Complete MongoDB integration with health state machine (Healthy → Degraded → Unhealthy → Recovering)
• Transparent Persistence: StateComponent automatic serialization/deserialization, persisted through timed batch ReplaceOne operations
• Connection Pool Management: Configurable connection pool and retry strategy
• OpenTelemetry Integration: Database operation metrics (latency, retry count, health status)

Monitoring & Observability

• OpenTelemetry: Comprehensive metrics, tracing, and logging
• Prometheus: Native metrics export endpoint
• Grafana Loki: Log aggregation output support
• Serilog: Structured logging with console, file, and Loki multi-output

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         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                               │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Project Structure

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.Architecture.Analyzers/         # Roslyn architecture analyzers
├── GameFrameX.Hotfix.WrapperGenerator/ # 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

Quick Start

Requirements

• .NET 10.0 SDK only. .NET 8/9 are not supported.
• MongoDB 4.x+
• Visual Studio 2022 or JetBrains Rider (recommended)

Installation Steps

1. Clone the Repository

   git clone https://github.com/GameFrameX/GameFrameX.git
   cd GameFrameX/Server
   

2. Restore Dependencies

   dotnet restore
   

3. Build the Project

   dotnet build
   

4. Start MongoDB

   # Local installation
   mongod --dbpath /path/to/data
   
   # Or use Docker
   docker run -d -p 27017:27017 --name mongo mongo:8.2
   

5. Run the Server

   dotnet run --project GameFrameX.Launcher -- \
       --ServerType=Game \
       --ServerId=1000 \
       --OuterPort=29100 \
       --HttpPort=28080 \
       --DataBaseUrl=mongodb://127.0.0.1:27017 \
       --DataBaseName=gameframex
   

6. Verify Startup

   • Health check: http://localhost:28080/game/api/health
   • Check console logs to confirm successful startup

Configuration Management

GameFrameX uses command-line arguments (--Key=Value) for configuration. All configuration items are defined in the StartupOptions class.

Server Configuration

Network Configuration

Database Configuration