Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
* Wrapper 生成器崩溃止血与不可编译产物清理(C431,GFX-1171,GitHub #917):`[TimeOut]` 实参防御式解析(仅数值字面量可静态求值——常量名/缺参/空参/表达式/下划线开头的常量名输出 Error 诊断并降级为框架默认超时,不再令生成器整体崩溃丢失全部 wrapper);`GetFullName` 重写为向上收集命名空间与嵌套类型段(无命名空间代理返回类型链短名,顺带覆盖 struct/enum 容器形态);`Tools.GetNameSpace` 取真命名空间(首个 `+` 前最后一个 `.`,无命名空间返回空串且不发射空 using),嵌套代理基类改容器限定名 `Outer.Inner`、wrapper 类名携带容器链(同命名空间同名代理不再碰撞);partial 合并键升为完全限定名(跨命名空间同名无关类不再产生幽灵 Wrapper);async 被包装方法统一 `return await`(修复非泛型 `async Task`/`async ValueTask` 生成体不可编译);含 `ref/out/in` 参数与 `[Discard]` 返回类型非 Task/ValueTask(按类型名最后一段比较,全限定名不误报)的方法报 Error 且不进入生成面(校验先行);`[Discard]` 非 ThreadSafe 入队 lambda 改 `async ()=> await` 统一绑定 `EnqueueAsync(Func<Task>)` 重载(ValueTask 一次性消费契约不再被违反)。新增 16 例生成器测试(含独立审查 R1/R2/R3 修复钉住),既有 3 例 Discard lambda 断言随契约更新。

### Added
* 黄金路径默认开箱即通(C460,GFX-1195,GitHub #959):`OnlineLeaderboardProjectionOptions.MatchSettledBoardId` 默认值由空白(不投影)改为默认榜常量 `match-settled`(`OnlineLeaderboardProjectionOptions.DefaultMatchSettledBoardId`)——零 Online JSON 配置起服即装配 Match.Settled 投影、激活期预建默认榜,RPS 对局→结算→Grant 发奖→上榜全链默认贯通;显式置空白 / null 或配置段覆盖为空白仍可关闭投影(不装配、不预建、不报错)。`OnlineCompetitionOptions.Validate` 补投影组合校验:`LeaderboardProjection` 须为非 null 对象,榜单标识非空白(投影开启)时长度 ≤128 且不得含空白字符(装配期 fail-fast,全部问题一次报全)。端到端验收以可重跑 xunit 钉住(GameFrameX.Tests 零 Settings 组合全链 + Hotfix.Tests 桥断言:好友桥→撮合桥→对局桥→默认榜条目),`Configs/app_config.json` Game 角色移除 `Online.Settings` 空节依赖。
* 行版本条件写内存管线收口共享助手(C409,GFX-1117):新增 `GameFrameX.DataBase/Abstractions/RowVersionCasWriteHelper` 与 `RowVersionBackfillWriteHelper`——`UpdateIfRowVersionAsync`(CAS)与 `UpdateIfRowVersionIsNullAsync`(回填)两原语在 Mongo/PostgreSQL/SQLite 三 Provider 重复的内存侧样板(Id 一致性校验、版本对齐 + checked 递增、写库前 `ToBytes()` 快照、失败回滚 / 成功精确提交)收敛为单一事实源,Provider 仅保留谓词 / 语句 / 重试外壳等写库差异;语义零变化(失败回滚、异常不回滚、`long.MaxValue` 溢出写库前抛出、SQLite null 守卫现状均冻结),回归依托 `DatabaseConditionalWritePrimitivesTests` 既有套件。
* 服务器间 RPC 端点改由心跳注册表解析并退役静态引导(C304,GitHub #643):`RemoteServiceTarget`(ServerType + 可选 InstanceId)结构化拨号取代 `{Role}_{InstanceId}` 字符串拼接;`DiscoveryServiceEndpointResolver` 成为唯一端点解析器(指定实例走 Instance 视图含 Draining 并校验 Role 一致,ServerType 级取 Active 中 InstanceId 序数最小者,端点集合 = TCP 主端点 + 附加端点,偏好 kcp > ws > wss > tcp);`RemoteMessagingBuilder.WithRouteTable(IRoleRouteTableProvider)` 绑定路由表、生产注册 KCP 拨号适配器(`IsEnableInnerKcp` 时,服务器间 KCP 首次生产可用);心跳新增附加广播端点(`InstanceDescriptor.AdditionalAdvertiseEndpoints`,监听器装配成功的实例级闸门后才广播,多 ServerType 进程非首选类型披露 Warning);`UnifiedMessageSender` 实例列表改读路由表 Active 视图且仅 InstanceId 集合变化才重建哈希环;玩家路由实例直达——`player_route.InstanceId` 写真实发现层实例 Id(`PlayerRouteResolverBootstrap` 同源注入),`ForwardToRemoteServerAsync` 按 `TargetInstanceId` 投递(Instance 视图含 Draining)、`IsCurrentServer` 改 InstanceId 比较;Mongo 心跳 class map 显式忽略未知字段(含继承传递)、写路径空集合归一化为 null(默认配置文档与旧版本逐字节同形);PostgreSQL 幂等补列 `additional_advertise_endpoints text[]`(命名经 `DiscoveryStorageNaming` 推导);删除 `services__*` 环境变量契约、`EnvironmentVariableEndpointResolver`、`EnvironmentServiceInstanceDiscovery`、`docker-compose.multi.legacy.yml` 与生成器静态引导映射。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,19 @@ namespace GameFrameX.Capability.Online.Competition.Leaderboard;

/// <summary>
/// 排行榜投影选项(<see cref="OnlineCompetitionOptions.LeaderboardProjection"/> 的子对象;
/// <see cref="MatchSettledBoardId"/> 非空白才装配 Match.Settled 投影与激活期榜单预建,
/// 空白 / 缺省 = 不投影,不报错)。
/// <see cref="MatchSettledBoardId"/> 默认投影到默认榜(C460:默认值服务黄金路径开箱即通——
/// 零 JSON 配置起服即装配 Match.Settled 投影并在激活期预建默认榜);显式置空白 / null
/// 或经配置段覆盖为空白 = 关闭投影(不装配、不预建,不报错)。
/// </summary>
public sealed class OnlineLeaderboardProjectionOptions
{
/// <summary>
/// 获取或设置 Match.Settled 事件的目标榜单标识(空白 = 不投影)。
/// 默认投影目标榜单标识(Match.Settled 投影的默认榜;装配期由 Leaderboard 能力预建)。
/// </summary>
public string MatchSettledBoardId { get; set; }
public const string DefaultMatchSettledBoardId = "match-settled";

/// <summary>
/// 获取或设置 Match.Settled 事件的目标榜单标识(默认 = <see cref="DefaultMatchSettledBoardId"/>;空白 = 不投影)。
/// </summary>
public string MatchSettledBoardId { get; set; } = DefaultMatchSettledBoardId;
}
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,10 @@ namespace GameFrameX.Capability.Online.Competition;
/// 锦标赛三个 store 以懒默认描述符注册(族 / 宿主覆盖恒胜出,模块不感知);赛季 / 锦标赛对发放服务
/// (<see cref="OnlineGrantService"/>,assets 域产物)的依赖经 manifest 可选声明 + GetOptionalService,
/// 缺席(assets 能力被过滤)时不装配两者;对外产物(榜单 / 赛季 / 锦标赛服务与 LiveOps 注册表)注册回
/// 共享面。<see cref="OnlineCompetitionOptions"/> 为唯一参数面(含榜单组件参数与 Match.Settled 投影配置,
/// 后者收编族级键 <c>MatchBridgeLeaderboardId</c>):投影榜 id 非空白且对局结果存储(online-match 可选产物)
/// 在场时装配 Match.Settled 排行榜投影(机制总线订阅 + 失败重投 tick);
/// <see cref="OnlineCompetitionOptions"/> 为唯一参数面(含榜单组件参数与 Match.Settled 投影配置,
/// 后者收编族级键 <c>MatchBridgeLeaderboardId</c>):投影榜 id 非空白(C460 起默认投影到默认榜
/// <see cref="OnlineLeaderboardProjectionOptions.DefaultMatchSettledBoardId"/>,显式空白可关闭)且对局结果存储
/// (online-match 可选产物)在场时装配 Match.Settled 排行榜投影(机制总线订阅 + 失败重投 tick);
/// <c>ActivateAsync</c> 在投影榜 id 非空白时经榜单服务预建目标榜(查询-创建,见方法注释)。
/// </para>
/// </summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,17 +45,19 @@ public sealed class OnlineCompetitionOptions : ICapabilityOptions
public OnlineLeaderboardOptions Leaderboard { get; set; } = new OnlineLeaderboardOptions();

/// <summary>
/// 获取或设置 Match.Settled 写榜投影配置(<c>MatchSettledBoardId</c> 空白 = 不投影不预建)。
/// 获取或设置 Match.Settled 写榜投影配置(默认投影到默认榜;显式置空白或配置段覆盖可关闭)。
/// </summary>
public OnlineLeaderboardProjectionOptions LeaderboardProjection { get; set; } = new OnlineLeaderboardProjectionOptions();

/// <summary>
/// 校验排行榜组件选项:单次提交最大分数、限流最大提交次数、限流窗口秒数、缓存有效期秒数与最大分页大小均须为正数;投影配置不做校验(空白榜单标识表示不投影)。
/// 校验排行榜组件与投影组合选项:单次提交最大分数、限流最大提交次数、限流窗口秒数、缓存有效期秒数与最大分页大小均须为正数;
/// 投影配置须为非 null 对象,目标榜单标识非空白(投影开启)时长度不得超过上限且不得包含空白字符(装配期 fail-fast,全部问题一次报全)。
/// </summary>
/// <remarks>
/// Validates the leaderboard options: default maximum score per submission, rate-limit maximum submissions, rate-limit window
/// seconds, cache time-to-live seconds and maximum page size must all be positive. The projection settings are not validated because
/// a blank board id simply disables the projection. Failures are recorded on the validation collector.
/// seconds, cache time-to-live seconds and maximum page size must all be positive. The projection settings must be a non-null
/// object, and when the target board id is not blank (projection enabled) it must not exceed the maximum length or contain any
/// whitespace characters. All problems are collected and reported together on the validation collector.
/// </remarks>
/// <param name="validation">选项校验结果收集器 / Options validation collector</param>
public void Validate(CapabilityOptionsValidation validation)
Expand All @@ -65,5 +67,38 @@ public void Validate(CapabilityOptionsValidation validation)
validation.RequirePositive("Leaderboard.RateLimitWindowSeconds", Leaderboard.RateLimitWindowSeconds);
validation.RequirePositive("Leaderboard.CacheTtlSeconds", Leaderboard.CacheTtlSeconds);
validation.RequirePositive("Leaderboard.MaxPageSize", Leaderboard.MaxPageSize);

// 投影组合校验(C460):子对象缺席 = 代码 Configure 写坏,fail-fast;榜单 id 非空白(投影开启)时
// 校验长度与空白字符——该 id 会拼进事件幂等键与读缓存键,超长 / 含空白属于配置错误而非运行期输入。
if (LeaderboardProjection == null)
{
validation.AddError("LeaderboardProjection", "must be a non-null options object");
return;
}

var boardId = LeaderboardProjection.MatchSettledBoardId;
if (string.IsNullOrWhiteSpace(boardId))
{
return;
}

if (boardId.Length > MaxMatchSettledBoardIdLength)
{
validation.AddError("LeaderboardProjection.MatchSettledBoardId", "must be at most " + MaxMatchSettledBoardIdLength + " characters (actual: " + boardId.Length + ")");
}

for (var index = 0; index < boardId.Length; index++)
{
if (char.IsWhiteSpace(boardId[index]))
{
validation.AddError("LeaderboardProjection.MatchSettledBoardId", "must not contain whitespace characters");
break;
}
}
}

/// <summary>
/// 投影目标榜单标识的最大长度(<see cref="OnlineLeaderboardProjectionOptions.MatchSettledBoardId"/> 非空白时的上限)。
/// </summary>
public const int MaxMatchSettledBoardIdLength = 128;
}
Original file line number Diff line number Diff line change
Expand Up @@ -167,8 +167,11 @@ public void Register(CapabilityRegistrationContext context)
var eventPublisher = context.GetService<IOnlineEventPublisher>();
context.AddService<IOnlineMatchActorStore>(static _ => new InMemoryOnlineMatchActorStore());
var matchActorStore = context.GetService<IOnlineMatchActorStore>();
context.AddService<IOnlineMatchResultStore>(static _ => new InMemoryOnlineMatchSettlementStore());
context.AddService<IOnlineMatchSettlementStore>(static _ => new InMemoryOnlineMatchSettlementStore());
// 同一实例注册两接口键(C460):结算写入与投影读取必须看到同一份事实——分别 new 会造成
// 「结算落库 / 投影读空」的分裂脑(默认内存形态下黄金路径静默断链);族 / 宿主覆盖仍逐键恒胜出。
var settlementStoreInstance = new InMemoryOnlineMatchSettlementStore();
context.AddService<IOnlineMatchResultStore>(_ => settlementStoreInstance);
context.AddService<IOnlineMatchSettlementStore>(_ => settlementStoreInstance);
var matchSettlementStore = context.GetService<IOnlineMatchSettlementStore>();

var rpsGame = new OnlineRockPaperScissorsGame();
Expand Down
3 changes: 1 addition & 2 deletions Configs/app_config.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,7 @@
"EnableRuntime": true,
"EnableAdminApi": true,
"EnableRoles": ["Game"],
"UseGameDbStores": true,
"Settings": {}
"UseGameDbStores": true
},
"MinModuleId": 10,
"MaxModuleId": 9999,
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,12 @@ GameFrameX Server is a high-performance, cross-platform game server framework bu
- Health check: `http://localhost:28080/health` (liveness probe: `/alive`)
- Check console logs to confirm successful startup

**Zero-JSON golden path**: start the server without writing any `Online.Settings` and the sample
RPS chain (matchmaking → match → settlement → reward grant → leaderboard) works out of the box —
`MatchSettledBoardId` projects onto the default board `match-settled` (pre-created during
assembly). To turn the projection off, explicitly blank
`online-competition.LeaderboardProjection.MatchSettledBoardId` under `Online.Settings`.

### SQLite Provider Boundaries

SQLite (`--DatabaseProvider=Sqlite`) is positioned for quick starts, development evaluation, and
Expand Down
2 changes: 2 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,8 @@ GameFrameX Server 是基于 C# .NET 10.0 开发的高性能、跨平台游戏服
- 健康检查:`http://localhost:28080/health`(存活探针:`/alive`)
- 查看控制台日志确认启动成功

**零 JSON 默认通(黄金路径)**:不写任何 `Online.Settings` 配置直接起服,RPS 样例对局全链(撮合 → 对局 → 结算 → 发奖 → 上榜)默认贯通——`MatchSettledBoardId` 默认投影到默认榜 `match-settled`(装配期自动预建);如需关闭投影,在 `Online.Settings` 中将 `online-competition.LeaderboardProjection.MatchSettledBoardId` 显式置空即可。

---

## 使用示例
Expand Down
9 changes: 9 additions & 0 deletions Tests/GameFrameX.Hotfix.Tests/GameFrameX.Hotfix.Tests.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,15 @@
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Foundation\GameFrameX.Capability.Online.Foundation.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Operations\GameFrameX.Capability.Online.Operations.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Social\GameFrameX.Capability.Online.Social.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Matchmaking\GameFrameX.Capability.Online.Matchmaking.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Match\GameFrameX.Capability.Online.Match.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Assets\GameFrameX.Capability.Online.Assets.csproj" />
<ProjectReference Include="..\..\Capability\GameFrameX.Capability.Online.Competition\GameFrameX.Capability.Online.Competition.csproj" />
</ItemGroup>

<ItemGroup>
<ProjectReference Include="..\..\GameFrameX.Hotfix\GameFrameX.Hotfix.csproj" />
Expand Down
Loading
Loading