docs(config): 添加游戏内容配置系统文档

- 介绍面向静态游戏内容的 AI-First 配表方案
- 详细说明 YAML 配置源文件和 JSON Schema 结构描述功能
- 提供推荐目录结构和 Schema 示例配置指南
- 说明 VS Code 插件提供的配置浏览和编辑功能
- 提供运行时接入模板和强类型查询辅助使用方法
- 说明跨表引用和运行时校验行为规范
- 介绍开发期热重载功能和性能优化建议
- 说明当前限制和独立 Config Studio 评估结论
This commit is contained in:
GeWuYou 2026-04-09 17:07:29 +08:00
parent 51de7f1102
commit f5317eda01

View File

@ -12,7 +12,7 @@
- JSON Schema 作为结构描述
- 一对象一文件的目录组织
- 运行时只读查询
- Runtime / Generator / Tooling 共享支持 `minimum``maximum``exclusiveMinimum``exclusiveMaximum``minLength`、`maxLength``pattern``minItems``maxItems`
- Runtime / Generator / Tooling 共享支持 `minimum``maximum``exclusiveMinimum``exclusiveMaximum``multipleOf`、`minLength`、`maxLength``pattern``minItems``maxItems``uniqueItems`
- Source Generator 生成配置类型、表包装、单表注册/访问辅助,以及项目级聚合注册目录
- VS Code 插件提供配置浏览、raw 编辑、schema 打开、递归轻量校验和嵌套对象表单入口
@ -53,7 +53,8 @@ GameProject/
},
"hp": {
"type": "integer",
"default": 10
"default": 10,
"multipleOf": 5
},
"rarity": {
"type": "string",
@ -62,6 +63,7 @@ GameProject/
"dropItems": {
"type": "array",
"description": "掉落物品表主键。",
"uniqueItems": true,
"items": {
"type": "string",
"enum": ["potion", "slime_gel", "bomb"]
@ -650,9 +652,11 @@ var loader = new YamlConfigLoader("config-root")
- 对象数组元素结构不匹配
- 数值字段违反 `minimum` / `maximum`
- 数值字段违反 `exclusiveMinimum` / `exclusiveMaximum`
- 数值字段违反 `multipleOf`
- 字符串字段违反 `minLength` / `maxLength`
- 字符串字段违反 `pattern`
- 数组字段违反 `minItems` / `maxItems`
- 数组字段违反 `uniqueItems`
- 标量 `enum` 不匹配
- 标量数组元素 `enum` 不匹配
- 通过 `x-gframework-ref-table` 声明的跨表引用缺失目标行
@ -702,9 +706,11 @@ if (MonsterConfigBindings.References.TryGetByDisplayPath("dropItems", out var re
- `enum`供运行时校验、VS Code 校验和表单枚举选择复用
- `minimum` / `maximum`供运行时校验、VS Code 校验和生成代码 XML 文档复用
- `exclusiveMinimum` / `exclusiveMaximum`供运行时校验、VS Code 校验和生成代码 XML 文档复用
- `multipleOf`供运行时校验、VS Code 校验、表单 hint 和生成代码 XML 文档复用;当前按运行时与 JS 共用的浮点容差策略判断十进制步进
- `minLength` / `maxLength`供运行时校验、VS Code 校验和生成代码 XML 文档复用
- `pattern`供运行时校验、VS Code 校验、表单提示和生成代码 XML 文档复用;当前按 C# `CultureInvariant` 与 JS 默认分组语义解释,非法模式会在 schema 解析阶段直接报错
- `minItems` / `maxItems`供运行时校验、VS Code 校验、表单提示和生成代码 XML 文档复用
- `uniqueItems`供运行时校验、VS Code 校验、表单 hint 和生成代码 XML 文档复用;对象数组会按 schema 归一化后的结构比较重复项,而不是依赖 YAML 字段顺序
这样可以避免错误配置被默认值或 `IgnoreUnmatchedProperties` 静默吞掉。
@ -801,7 +807,7 @@ var hotReload = loader.EnableHotReload(
- 对带 `x-gframework-ref-table` 的字段提供引用 schema / 配置域 / 引用文件跳转入口
- 对空配置文件提供基于 schema 的示例 YAML 初始化入口
- 对同一配置域内的多份 YAML 文件执行批量字段更新
- 在表单和批量编辑入口中显示 `title / description / default / enum / ref-table` 元数据
- 在表单和批量编辑入口中显示 `title / description / default / enum / ref-table / multipleOf / uniqueItems` 元数据
当前表单入口适合编辑嵌套对象中的标量字段、标量数组,以及对象数组中的对象项。