GameFrameX.Capability.Online.Foundation
2.0.0-preview.1
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
<PackageReference Include="GameFrameX.Capability.Online.Foundation" Version="2.0.0-preview.1" />
<PackageVersion Include="GameFrameX.Capability.Online.Foundation" Version="2.0.0-preview.1" />
<PackageReference Include="GameFrameX.Capability.Online.Foundation" />
paket add GameFrameX.Capability.Online.Foundation --version 2.0.0-preview.1
#r "nuget: GameFrameX.Capability.Online.Foundation, 2.0.0-preview.1"
#:package GameFrameX.Capability.Online.Foundation@2.0.0-preview.1
#addin nuget:?package=GameFrameX.Capability.Online.Foundation&version=2.0.0-preview.1&prerelease
#tool nuget:?package=GameFrameX.Capability.Online.Foundation&version=2.0.0-preview.1&prerelease
<div align="center">
<img src="https://download.alianblank.com/gameframex/gameframex_logo_320.png" alt="Game Frame X Logo" width="160" />
GameFrameX Server
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
<img src="https://cdn.jsdelivr.net/npm/devicon@2/icons/linkedin/linkedin-original.svg" height="28" alt="LinkedIn" />
Changelog
See CHANGELOG.md for the unreleased rebuild summary and retained earlier history.
License
See LICENSE for license information.
| Product | Versions 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. |
-
net10.0
- GameFrameX.Capability.Hosting.Core (>= 2.0.0-preview.1)
- GameFrameX.Capability.Online.Abstractions (>= 2.0.0-preview.1)
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 |