GameFrameX.Capability.Hosting.Abstractions
2.0.0-preview.1
dotnet add package GameFrameX.Capability.Hosting.Abstractions --version 2.0.0-preview.1
NuGet\Install-Package GameFrameX.Capability.Hosting.Abstractions -Version 2.0.0-preview.1
<PackageReference Include="GameFrameX.Capability.Hosting.Abstractions" Version="2.0.0-preview.1" />
<PackageVersion Include="GameFrameX.Capability.Hosting.Abstractions" Version="2.0.0-preview.1" />
<PackageReference Include="GameFrameX.Capability.Hosting.Abstractions" />
paket add GameFrameX.Capability.Hosting.Abstractions --version 2.0.0-preview.1
#r "nuget: GameFrameX.Capability.Hosting.Abstractions, 2.0.0-preview.1"
#:package GameFrameX.Capability.Hosting.Abstractions@2.0.0-preview.1
#addin nuget:?package=GameFrameX.Capability.Hosting.Abstractions&version=2.0.0-preview.1&prerelease
#tool nuget:?package=GameFrameX.Capability.Hosting.Abstractions&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.Localization (>= 2.0.0-preview.1)
NuGet packages (4)
Showing the top 4 NuGet packages that depend on GameFrameX.Capability.Hosting.Abstractions:
| Package | Downloads |
|---|---|
|
GameFrameX.Capability.Hosting.AdminApi
GameFrameX.Capability.Hosting.AdminApi,GFX 能力组件管理面 HTTP 管道:独立 Kestrel 监听/双层信封/去域化 action 调度器/list_capabilities 元端点,零能力逻辑. Capability hosting admin HTTP pipeline: standalone Kestrel listener, double envelope, domain-free action dispatcher and list_capabilities meta endpoint. Documentation: https://gameframex.doc.alianblank.com |
|
|
GameFrameX.Capability.Hosting.Core
GameFrameX.Capability.Hosting.Core,GFX 能力组件机制实现:能力注册表与拓扑装配(显式链式+程序集扫描)/闭包校验 fail-fast/注册制调度壳(间隔+逐滴答+事件驱动三类 job)/启动能力报告. Capability hosting core: registry, manifest topological assembly with closure validation, registration-based scheduler shell (interval/tick/event-driven jobs) and startup capability report. Documentation: https://gameframex.doc.alianblank.com |
|
|
GameFrameX.Capability.Online.Abstractions
GameFrameX.Capability.Online.Abstractions,GFX Online 平台能力脊柱:公共契约/错误码/作用域/幂等 Server 侧/Token 契约/事件总线抽象. Platform spine abstractions for the GFX Online capability family: contracts, error codes, scope, server-side idempotency, token contracts and the event bus abstraction. Documentation: https://gameframex.doc.alianblank.com |
|
|
GameFrameX.Capability.Online.ServerLifecycle
GameFrameX.Capability.Online.ServerLifecycle,GFX Online 区服生命周期能力包:开服锚点(ServerId 登记/开服日历/ServerOpened 能力事件)+ 合服原语(幂等可 dry-run 的归并计划/PlayerRoute 重指向/区服域行键重写/榜单封档/在途对局强制结算/资产归属列重写 + IServerMergeParticipant 玩法钩子)+ admin handlers(register_server_open/query_server_calendar/plan_server_merge/dry_run_server_merge/execute_server_merge). Server lifecycle capability package for the GFX Online family: server-open anchors with calendar and the ServerOpened capability event, plus idempotent dry-run-first server-merge primitives (merge plan, player-route repointing, server-domain row-key rewrite, leaderboard sealing, in-flight match settlement, asset home-server column rewrite) with the IServerMergeParticipant gameplay hook 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 | 51 | 11/21/2026 |