GameFrameX.Capability.Online.Foundation 2.0.0-preview.1

This is a prerelease version of GameFrameX.Capability.Online.Foundation.
dotnet add package GameFrameX.Capability.Online.Foundation --version 2.0.0-preview.1
                    
NuGet\Install-Package GameFrameX.Capability.Online.Foundation -Version 2.0.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GameFrameX.Capability.Online.Foundation" Version="2.0.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="GameFrameX.Capability.Online.Foundation" Version="2.0.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="GameFrameX.Capability.Online.Foundation" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add GameFrameX.Capability.Online.Foundation --version 2.0.0-preview.1
                    
#r "nuget: GameFrameX.Capability.Online.Foundation, 2.0.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package GameFrameX.Capability.Online.Foundation@2.0.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=GameFrameX.Capability.Online.Foundation&version=2.0.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=GameFrameX.Capability.Online.Foundation&version=2.0.0-preview.1&prerelease
                    
Install as a Cake Tool

<div align="center">

<img src="https://download.alianblank.com/gameframex/gameframex_logo_320.png" alt="Game Frame X Logo" width="160" />

GameFrameX Server

License Version .NET Documentation

Discord GitHub Bilibili Gitee

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams

<br />

Documentation · Quick Start · QQ Group: 467608841 / 233840761

<br />

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

</div>

Project Overview

GameFrameX Server is a C# .NET 10 game server framework for a single process. One host runs client connections, local player sessions, Actors, hotfix logic and optional capability modules. The current game and Online business modules remain part of the application.

Features

  • Actor and components: serialized execution, state persistence, events and timers, with generated agent wrappers.
  • Hotfix: loadable business assemblies and local lifecycle management, separate from persistent state definitions.
  • Client networking: TCP, WebSocket (WS/WSS) and KCP, request/response messages, session authentication and disconnect cleanup.
  • HTTP/HTTPS: handlers, signature validation, TLS and optional development documentation.
  • Persistence: MongoDB, SQLite and PostgreSQL adapters, named connections, conditional writes, transactions and retries within each provider’s supported semantics.
  • Capability.Hosting: in-process registration, dependency resolution, scheduling, module lifecycle and a generic management API.
  • Supporting libraries: configuration loading, serialization, localization, diagnostics, architecture analyzers and tests.

Quick Start

Installation

Use the .NET 10 SDK selected by global.json and run the commands below from this repository. Prepare Configs/app_config.json for one host before starting; the database fields below belong to the application settings. SQLite needs no separate database service. MongoDB and PostgreSQL require reachable database instances. The copy command is for macOS/Linux; on Windows copy the same directory with the shell’s equivalent.

dotnet restore Server.slnx
dotnet build Server.slnx --no-restore --no-incremental -warnaserror:CS9057
dotnet build GameFrameX.Hotfix/GameFrameX.Hotfix.csproj -o bin/app_debug/hotfix --no-restore
cp -R GameFrameX.Config/json bin/app_debug/
cp -R Configs bin/app_debug/
cd bin/app_debug
dotnet GameFrameX.Launcher.dll

Configure the selected provider in the application settings. Use Mongo with a MongoDB connection string or PostgreSql with a PostgreSQL connection string to select the other adapters. DataBaseName names the connection/database. Named connections remain available through GameDatabase and the database registry; switching the provider does not migrate existing data.

{
  "DatabaseProvider": "Sqlite",
  "DataBaseUrl": "Data Source=data/gameframex.db",
  "DataBaseName": "gameframex"
}

SQLite file mode persists to the configured path; Data Source=:memory: is ephemeral. SQLite serializes writes and some queries evaluate in memory, so large queries may scan the table. MongoDB transactions require a replica set; PostgreSQL uses its EF Core provider. Provider behavior and supported query shapes must be checked against the relevant contract tests.

Usage Examples

Client connections and HTTP

Configure TCP with IsEnableTcp, OuterHost and OuterPort; WS with IsEnableWebSocket and WsPort; WSS additionally requires WssPort and WssCertFilePath. For PEM certificates set WssCertificateKeyPath; use WssCertificatePassword for protected keys. Client KCP uses IsEnableKcp and KcpPort.

HTTP uses IsEnableHttp, HttpPort and HttpUrl. HTTPS uses HttpsPort, HttpsCertPath, and, for PEM, HttpsCertificateKeyPath; the password field is HttpsCertPassword. Keep HTTPS and WSS certificates configured separately. When signature checks are enabled, supply HttpSignSecret and choose HttpSignVersion to match the client; version 2 includes request data and nonce replay protection.

Business logic and hotfix

Keep state and components in GameFrameX.Apps, and agents and message handlers in GameFrameX.Hotfix. Access another Actor through its component agent. Use the current Network, PlayerSession/PlayerId, MessageHandler and asynchronous API names; asynchronous operations use the Async suffix.

The gfx-role template adds a local business slice to the server Actor. Its existing ServerRole directory name describes business organization. gfx-online creates a separate minimal host for in-process capability composition. Installation and limitations are documented in GameFrameX.Templates.

Hotfix assemblies are loaded by the local host. The Online management operations require a configured executor and available artifacts; the minimal Online template deliberately rejects version switching because it does not host that runtime. Hotfix failure recovery is not a transactional rollback guarantee.

Diagnostics and verification

Logs and diagnostics remain available. /health and /alive are mapped by default only in development mode (HttpIsDevelopment); production exposure requires explicit configuration. Existing database instrumentation does not imply that all three providers have complete host health-check and meter wiring.

dotnet test Tests/GameFrameX.Tests/GameFrameX.Tests.csproj --no-build
dotnet test Tests/GameFrameX.Hotfix.Tests/GameFrameX.Hotfix.Tests.csproj --no-build

These are verification commands, not a declaration that this rebuild has passed them. MongoDB and PostgreSQL integration suites require GAMEFRAMEX_TEST_MONGODB_CONNECTION_STRING and GAMEFRAMEX_TEST_POSTGRESQL_CONNECTION_STRING. Check their presence and run against real databases: some tests return early without those variables. SQLite tests cover file persistence and transactions.

Architecture

The Launcher composes one host. StartUp owns client listeners and the host lifecycle; Core owns local Actors, sessions, components, events, timers and hotfix execution. Hosting composes optional modules in the same process. Current business modules are preserved independently of this framework restructuring.

Configuration loading and hot reload remain available. ConfigComponent is still a static singleton; reload does not promise a transaction across multiple tables. Shutdown coordinates local work draining, state saving and resource disposal.

Dependencies

Runtime projects target net10.0; generators keep their declared target frameworks. SDK selection is in global.json; package versions are in the project files and Version.props. Core dependencies include GameFrameX.Foundation, SuperSocket, MongoDB.Driver, Microsoft.Data.Sqlite and Npgsql/Entity Framework Core. This rebuild does not publish packages or change existing tags.

Documentation & Resources

Community & Support

GitHub Discord <img src="https://cdn.jsdelivr.net/npm/devicon@2/icons/linkedin/linkedin-original.svg" height="28" alt="LinkedIn" /> Reddit X YouTube Bluesky Bilibili Gitee QQ

Changelog

See CHANGELOG.md for the unreleased rebuild summary and retained earlier history.

License

See LICENSE for license information.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on GameFrameX.Capability.Online.Foundation:

Package Downloads
GameFrameX.Capability.Online.Operations

GameFrameX.Capability.Online.Operations,GFX Online 运营聚合能力包(分析面冻结:游戏事件/总览/时间线不删除、不演进,数据面契约留服务端,查询 UI 归运营台;Hotfix 回滚为遗留活面):统一审计/Hotfix 回滚 + 事件桥与审计桥装配(机制事件总线逐主题订阅)+ 自装配模块(OnlineOperationsCapabilityModule,Options=OnlineOperationsOptions)+ admin handlers(Console 三 action). Operations aggregate capability package for the GFX Online family (frozen analysis face: game events, overview and timeline are neither removed nor evolved; hotfix rollback remains the active surface): unified audit, hotfix rollback and the event/audit bridge wiring over the mechanism event bus, the self-assembling capability module and admin handlers. Documentation: https://gameframex.doc.alianblank.com

GameFrameX.Capability.Online.Persistence

GameFrameX.Capability.Online.Persistence,GFX Online 分级持久化适配包(C249,D3=3A):Identity/PlayerStorage/资产账本/资产交易/好友关系五域一级 store 的 GameDb 适配(物化复合键唯一索引 + C247 条件写原语 + 序列接管),Session/Presence 保持易失;宿主组合根经能力服务 Override 预置,InMemory 默认不变. Graded-persistence adapter package for the GFX Online family (C249, D3=3A): GameDb adapters for the five level-one stores (identity, player storage, the asset ledger, asset transactions and friendships) built on materialized composite-key unique indexes, the C247 conditional-write primitives and sequence take-over, while sessions and presence stay volatile; composition roots pre-seed them through capability service overrides and the in-memory default is unchanged. Documentation: https://gameframex.doc.alianblank.com

GameFrameX.Capability.Online.Social

GameFrameX.Capability.Online.Social,GFX Online 社交能力包:好友/群组/聊天/通知/处罚/举报裁决六域 + 聊天审计投影(InMemory 默认存储,描述符服务面 Override 替换)+ admin handlers(kick/revoke/mute/查询族). Social capability package for the GFX Online family: friends, groups, chat, notifications, punishments and report adjudication plus the chat-audit projection with in-memory default stores and admin handlers. Documentation: https://gameframex.doc.alianblank.com

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.0-preview.1 40 11/21/2026