From 66aa182baddc73d860c81f9e9f520ec15ecfd0ac Mon Sep 17 00:00:00 2001 From: Blank Date: Tue, 3 Nov 2026 01:25:47 +0800 Subject: [PATCH 1/3] =?UTF-8?q?feat(templates):=20=E6=96=B0=E5=A2=9E=20gfx?= =?UTF-8?q?-game=20=E6=B8=B8=E6=88=8F=E8=B5=B7=E7=82=B9=E5=B7=A5=E7=A8=8B?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 生成「用 GameFrameX 做一个游戏」的独立起点工程:以 2.0 NuGet 包消费 Online 能力黄金路径最小集 (Foundation+Social+Match+Assets+Leaderboard+Competition),零 JSON 配置开箱即通, 可在任意目录还原、构建与起服;nuget.config 缺省指向内部 feed(公开发布后切公开源)。 配套 Server 游戏仓 README 重定位与四子棋 Online 桥活演示。 Closes #970 --- .../gfx-game/.template.config/template.json | 45 +++++++++++ .../gfx-game/{{Name}}/EmptyPlayerDirectory.cs | 79 +++++++++++++++++++ .../templates/gfx-game/{{Name}}/Program.cs | 71 +++++++++++++++++ .../templates/gfx-game/{{Name}}/nuget.config | 9 +++ .../gfx-game/{{Name}}/{{Name}}.csproj | 24 ++++++ 5 files changed, 228 insertions(+) create mode 100644 GameFrameX.Templates/templates/gfx-game/.template.config/template.json create mode 100644 GameFrameX.Templates/templates/gfx-game/{{Name}}/EmptyPlayerDirectory.cs create mode 100644 GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs create mode 100644 GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config create mode 100644 GameFrameX.Templates/templates/gfx-game/{{Name}}/{{Name}}.csproj diff --git a/GameFrameX.Templates/templates/gfx-game/.template.config/template.json b/GameFrameX.Templates/templates/gfx-game/.template.config/template.json new file mode 100644 index 000000000..38a74a058 --- /dev/null +++ b/GameFrameX.Templates/templates/gfx-game/.template.config/template.json @@ -0,0 +1,45 @@ +{ + "$schema": "http://json.schemastore.org/template", + "author": "GameFrameX", + "classifications": [ + "GameFrameX", + "Game", + "Starter" + ], + "identity": "GameFrameX.GameStarter", + "name": "GameFrameX 游戏起点工程", + "shortName": "gfx-game", + "tags": { + "language": "C#", + "type": "project" + }, + "description": "生成「用 GameFrameX 做一个游戏」的独立起点工程:以 2.0 NuGet 包消费框架 Online 能力(缺省黄金路径最小集 Foundation+Match+Assets+Leaderboard+Competition,零配置开箱即通),可在任意目录还原、构建与起服。完整官方示例见 Server 游戏仓(四子棋接 Online 桥)。", + "symbols": { + "Name": { + "type": "parameter", + "datatype": "string", + "description": "游戏工程名(PascalCase,如 MyGame);参与工程名/目录与 Program 装配代码替换", + "isRequired": true, + "replaces": "{{Name}}", + "fileRename": "{{Name}}" + } + }, + "primaryOutputs": [ + { + "path": "{{Name}}\\{{Name}}.csproj" + } + ], + "postActions": [ + { + "id": "restore", + "condition": "(HostIdentifier != \"dotnetcli\" && HostIdentifier != \"dotnetcli-preview\") || (HostIdentifier == \"dotnetcli\" && SkipRestore != true)", + "description": "还原工程引用的 NuGet 包", + "manualInstructions": [ + { + "text": "dotnet restore" + } + ], + "actionId": "210D431B-A78B-4D2F-B762-DFEA895BB429" + } + ] +} diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/EmptyPlayerDirectory.cs b/GameFrameX.Templates/templates/gfx-game/{{Name}}/EmptyPlayerDirectory.cs new file mode 100644 index 000000000..f5c478ff0 --- /dev/null +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/EmptyPlayerDirectory.cs @@ -0,0 +1,79 @@ +// ========================================================================================== +// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利 +// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights +// 均受中华人民共和国及相关国际法律法规保护。 +// are protected by the laws and regulations of the People's Republic of China and relevant international regulations. +// +// 使用本项目须严格遵守相应法律法规与开源许可证之规定。 +// Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses. +// +// 本项目采用 MIT 许可证与 Apache License 2.0 双许可证分发, +// This project is dual-licensed under the MIT License and Apache License 2.0, +// 完整许可证文本请参见源代码根目录下的 LICENSE 文件。 +// please refer to the LICENSE file at the root of the source code for the full license text. +// +// 禁止利用本项目实施任何危害国家安全、破坏社会秩序、 +// It is prohibited to use this project to engage in any activities that endanger national security, disrupt social order, +// 侵犯其他合法权益等法律法规所禁止的行为! +// or infringe upon the legitimate rights and interests of others as prohibited by laws and regulations. +// +// 因基于本项目二次开发所产生的一切法律纠纷与责任, +// Any legal disputes or liabilities arising from secondary development of this project +// 本项目组织与贡献者概不承担。 +// shall be borne solely by the developer; the project organization and contributors assume no responsibility. +// +// GitHub 仓库:https://github.com/GameFrameX +// GitHub Repository: https://github.com/GameFrameX +// Gitee 仓库:https://gitee.com/GameFrameX +// Gitee Repository: https://gitee.com/GameFrameX +// 官方文档:https://gameframex.doc.alianblank.com/ +// Official Documentation: https://gameframex.doc.alianblank.com/ +// ========================================================================================== + +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using GameFrameX.Capability.Online.Abstractions.Contracts; + +namespace {{Name}}; + +/// +/// 最小宿主的玩家目录(满足 online-social 以 RequireHostService 声明的宿主扩展点)。 +/// +/// 维护约束:本宿主不接玩家库,搜索与查找恒返回空集合——好友搜索无结果、好友展示名为空, +/// 其余社交功能不受影响。接入真实玩家数据时替换为读取玩家库的实现,并在 Program.cs 的 Override 处更换实例。 +/// +/// +public sealed class EmptyPlayerDirectory : IOnlinePlayerDirectory +{ + /// + /// 模板缺省实现:最小 Online 宿主没有玩家存储,任何关键字搜索都返回空列表;接入真实玩家数据时须替换本类。 + /// + /// + /// Template default: the minimal Online host has no player store, so every name search returns an empty list. + /// Replace this class when wiring real player data. + /// + /// 名称关键字(未使用) / Name keyword (unused) + /// 最大返回条数(未使用) / Maximum number of entries (unused) + /// 取消令牌(未使用) / Cancellation token (unused) + /// 已完成的空列表任务 / Completed task with an empty list + public Task> SearchByNameAsync(string keyword, int limit, CancellationToken cancellationToken = default) + { + return Task.FromResult>(new List()); + } + + /// + /// 模板缺省实现:最小 Online 宿主没有玩家存储,任何 ID 查询都返回空列表;接入真实玩家数据时须替换本类。 + /// + /// + /// Template default: the minimal Online host has no player store, so every ID lookup returns an empty list. + /// Replace this class when wiring real player data. + /// + /// 玩家 ID 列表(未使用) / Player IDs (unused) + /// 取消令牌(未使用) / Cancellation token (unused) + /// 已完成的空列表任务 / Completed task with an empty list + public Task> FindAsync(IReadOnlyList playerIds, CancellationToken cancellationToken = default) + { + return Task.FromResult>(new List()); + } +} diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs b/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs new file mode 100644 index 000000000..af26bddf3 --- /dev/null +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs @@ -0,0 +1,71 @@ +// ========================================================================================== +// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利 +// GameFrameX organization and its derivative projects' copyrights, trademarks, patents and related rights +// 均受中华人民共和国及相关国际法律法规保护。 +// are protected by the laws of the People's Republic of China and international regulations. +// 使用本项目须严格遵守相应法律法规与开源许可证之规定。 +// Usage of this project must strictly comply with applicable laws, regulations, and open-source licenses. +// 本项目采用 Apache License 2.0 单协议分发, +// This project is licensed solely under the Apache License 2.0, +// 完整许可证文本请参见源代码根目录下的 LICENSE 文件。 +// please see the LICENSE file in the root directory of the source code for the full license text. +// ========================================================================================== + +using System; +using System.Text.Json; +using System.Threading; +using GameFrameX.Capability.Hosting.AdminApi; +using GameFrameX.Capability.Hosting.Core; +using GameFrameX.Capability.Online.Abstractions; +using GameFrameX.Capability.Online.Abstractions.Contracts; + +using {{Name}}; + +// {{Name}} —— 用 GameFrameX 做一个游戏的起点(gfx-game 模板生成)。 +// 独立工程:以 GameFrameX 2.0 NuGet 包消费框架能力,引啥装配啥—— +// CapabilityComposition.Compose 按 Online 族部署前缀扫描本进程加载的能力包, +// csproj 引用了哪些能力包就装配哪些能力(编译期保证)。缺省勾选黄金路径最小集: +// 开局 → 对局裁决 → 结算 → 发奖(统一资产入口)→ 默认榜上榜,零 JSON 配置开箱即通。 +// 参考:官方游戏仓 https://github.com/GameFrameX/GameFrameX.Server (四子棋完整活演示)。 + +// 授权作用域区服键(单键化:作用域只剩 ServerId;接入配置管道时改走嵌套强类型段 "Online": { ... })。 +const long serverId = 1; + +// 族配置段(零 Settings = 全部走包内默认参数)。 +var familyConfigurationSection = JsonSerializer.SerializeToElement(new +{ + ServerId = serverId, + Settings = new { }, +}); + +var options = new CapabilityCompositionOptions(familyConfigurationSection, new ConsoleCapabilityAssemblyLog()); +options.HostOptions.ServerId = serverId; + +// 管理面:admin action 注册 + 元端点(list_capability_services / list_capability_settings / query_leaderboard 等)。 +options.UseAdminApi(adminOptions => +{ + adminOptions.AdminPort = 28092; + adminOptions.AdminApiPrefix = "online/admin"; +}); + +// 宿主扩展点:能力以 RequireHostService 声明、包内无默认实现,宿主必须 Override 提供(缺失 = 装配期 fail-fast)。 +// 玩家目录供 online-social 好友搜索使用;本起点工程不接玩家库,提供空目录。 +options.Override(new EmptyPlayerDirectory()); +// 唯一组合入口:族骨架 + 机制装配(依赖检查、拓扑定序、Options 绑定、装配日志一次报全)。 +var runtime = CapabilityComposition.Compose(new OnlineCapabilityFamily(), options); +await runtime.StartAsync(); + +Console.WriteLine("[{{Name}}] 游戏宿主已启动。已装配能力(拓扑序): {0}", string.Join(", ", runtime.Report.EnabledIdsInOrder)); +Console.WriteLine("[{{Name}}] 管理面: http://127.0.0.1:28092/online/admin/{{action}}"); +Console.WriteLine("[{{Name}}] 按 Ctrl+C 退出。"); + +var shutdown = new ManualResetEventSlim(false); +Console.CancelKeyPress += (_, eventArgs) => +{ + eventArgs.Cancel = true; + shutdown.Set(); +}; +shutdown.Wait(); + +await runtime.StopAsync(); +Console.WriteLine("[{{Name}}] 已停止。"); diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config b/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config new file mode 100644 index 000000000..ac1c41992 --- /dev/null +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/{{Name}}.csproj b/GameFrameX.Templates/templates/gfx-game/{{Name}}/{{Name}}.csproj new file mode 100644 index 000000000..cba6b3181 --- /dev/null +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/{{Name}}.csproj @@ -0,0 +1,24 @@ + + + + Exe + net10.0 + + false + latest + + + + + + + + + + + + + + From 79aa4f60e2440fd76b6bb7ffdd1bd05238657eb2 Mon Sep 17 00:00:00 2001 From: Blank Date: Tue, 3 Nov 2026 03:12:05 +0800 Subject: [PATCH 2/3] =?UTF-8?q?fix(templates):=20gfx-game=20=E8=BF=98?= =?UTF-8?q?=E5=8E=9F=E6=BA=90=E5=AE=A3=E7=A7=B0=E5=A6=82=E5=AE=9E=E5=8C=96?= =?UTF-8?q?=E5=B9=B6=E7=BB=99=E5=85=AC=E5=BC=80=E5=8C=96=E5=88=87=E6=8D=A2?= =?UTF-8?q?=E6=8C=87=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除「可在任意目录还原、构建与起服」不实宣称(相对内部 feed 按生成工程目录 解析,摆放不符即 NU1301);nuget.config 注释补精确摆放规则与公开化后删除 内部源的切换说明。 Linear: GFX-1201 --- .../templates/gfx-game/.template.config/template.json | 2 +- .../templates/gfx-game/{{Name}}/nuget.config | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/GameFrameX.Templates/templates/gfx-game/.template.config/template.json b/GameFrameX.Templates/templates/gfx-game/.template.config/template.json index 38a74a058..5dfb7b37e 100644 --- a/GameFrameX.Templates/templates/gfx-game/.template.config/template.json +++ b/GameFrameX.Templates/templates/gfx-game/.template.config/template.json @@ -13,7 +13,7 @@ "language": "C#", "type": "project" }, - "description": "生成「用 GameFrameX 做一个游戏」的独立起点工程:以 2.0 NuGet 包消费框架 Online 能力(缺省黄金路径最小集 Foundation+Match+Assets+Leaderboard+Competition,零配置开箱即通),可在任意目录还原、构建与起服。完整官方示例见 Server 游戏仓(四子棋接 Online 桥)。", + "description": "生成「用 GameFrameX 做一个游戏」的独立起点工程:以 2.0 NuGet 包消费框架 Online 能力(缺省黄金路径最小集 Foundation+Match+Assets+Leaderboard+Competition,零配置开箱即通)。注意:2.0 包当前仅内部 feed 分发,nuget.config 缺省指向生成目录旁的 ../LocalPackages(需与 GameFrameX 源码仓同级摆放方可还原;公开发布后改指 nuget.org)。完整官方示例见 Server 游戏仓(四子棋接 Online 桥)。", "symbols": { "Name": { "type": "parameter", diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config b/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config index ac1c41992..f9d863478 100644 --- a/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/nuget.config @@ -2,7 +2,10 @@ - + From 1552a904256bcb8e080a69d6851a67562390dd62 Mon Sep 17 00:00:00 2001 From: Blank Date: Tue, 3 Nov 2026 03:12:06 +0800 Subject: [PATCH 3/3] =?UTF-8?q?fix(admin-api):=20=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E9=9D=A2=E5=90=AF=E5=8A=A8=E8=BE=93=E5=87=BA=E6=97=A0=E9=89=B4?= =?UTF-8?q?=E6=9D=83=E5=85=A8=E7=BD=91=E5=8D=A1=E7=9B=91=E5=90=AC=E5=91=8A?= =?UTF-8?q?=E8=AD=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AdminApiServer 启动后打印监听姿态告警(生产须置于内网或前置准入网关); gfx-game 模板管理面打印由误导性 127.0.0.1 改为全网卡无鉴权如实提示。 Linear: GFX-1201 --- .../GameFrameX.Capability.Hosting.AdminApi/AdminApiServer.cs | 3 +++ GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/Capability/GameFrameX.Capability.Hosting.AdminApi/AdminApiServer.cs b/Capability/GameFrameX.Capability.Hosting.AdminApi/AdminApiServer.cs index 17545b246..86e100fca 100644 --- a/Capability/GameFrameX.Capability.Hosting.AdminApi/AdminApiServer.cs +++ b/Capability/GameFrameX.Capability.Hosting.AdminApi/AdminApiServer.cs @@ -148,6 +148,9 @@ public async Task StartAsync(CancellationToken cancellationToken) _application = application; await application.StartAsync(cancellationToken).ConfigureAwait(false); + // 安全告警(SR-1 最小修复):管理面固定监听所有网卡且无鉴权(准入仅 body 作用域键 + IP 限流); + // 生产部署必须置于内网/可信网络或前置准入网关,根治(回环绑定 + 准入控制)另行裁决。 + Console.WriteLine("[AdminApi] 警告: 管理面正监听所有网卡(0.0.0.0:" + _options.AdminPort + ")且未启用鉴权,请勿暴露到不可信网络。"); } /// diff --git a/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs b/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs index af26bddf3..a97da1cdb 100644 --- a/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs +++ b/GameFrameX.Templates/templates/gfx-game/{{Name}}/Program.cs @@ -56,7 +56,7 @@ await runtime.StartAsync(); Console.WriteLine("[{{Name}}] 游戏宿主已启动。已装配能力(拓扑序): {0}", string.Join(", ", runtime.Report.EnabledIdsInOrder)); -Console.WriteLine("[{{Name}}] 管理面: http://127.0.0.1:28092/online/admin/{{action}}"); +Console.WriteLine("[{{Name}}] 管理面: POST http://<主机>:28092/online/admin/{{action}}(监听本机所有网卡,无鉴权,仅限内网/可信环境使用)"); Console.WriteLine("[{{Name}}] 按 Ctrl+C 退出。"); var shutdown = new ManualResetEventSlim(false);