UnityAI/modules/frameworks/数据配置框架.md

数据 / 配置框架

分类

• 核心框架

目的

管理 XLSX 配置表源、解析、生成运行时数据和读取 API。

---

核心路径

• 配置源：XLSX_SRC/CN/、XLSX_SRC/EN/
• 生成设置：ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset
• Resolve Asset：Assets/Editor/XLSX_SRC/Resolve/ZYXlsx/
• 输出数据：Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/
• 输出代码：Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/

---

常见配置表

表名	用途
Constants.xlsx	常量配置
EntityConfig.xlsx	实体配置
Gift.xlsx	礼包/奖励配置
Resource.xlsx	资源/道具配置
SkillGroup.xlsx	技能组配置
SkillReleaser.xlsx	技能释放器配置
SkillTrigger.xlsx	技能触发器配置
SkillUp.xlsx	技能升级配置
Sounds.xlsx	音效配置
Wave.xlsx	波次配置（业务示例）

---

运行时加载调用链

HFGameStart.LoadDB()
  -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.instance.LoadAllXlsx(OnLoadDbFinish)
  -> 遍历 enZYXlsxSheet
  -> GetExistsDataLang / GetSheetMemoryPackBufferFilePath
  -> HFFunCatalogue.Asset.LoadDBHelper(path.GetHashCode(), path, callback)
  -> 缓存 sheet bytes 到 mDicLangSheetBytes

---

运行时读取 API

// 按主键读取单条
HFFunCatalogue.NDB.ds_xxx.ReadTableByPK(pk);

// 读取全表
HFFunCatalogue.NDB.ds_xxx.ReadTableList();

// 读取行列式数据
HFFunCatalogue.NDB.ds_xxx.ReadTableDeterminant();

---

使用规则

• 改表后必须重新生成。
• 配置读取必须在 LoadAllXlsx 完成后。
• 主键/全表/常量分别用对应 API。
• 禁止高频全表读取。
• id 优先来自表/协议/常量，禁止魔法数字。
• 高频配置在 manager 初始化或窗口打开时缓存。
• 多语言字段需补齐。

---

变更清单

1. 修改源表（XLSX_SRC/CN/、XLSX_SRC/EN/）。
2. 确认 ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset 与 Resolve 配置。
3. 通过 Unity 菜单 StrayFog → XLSX → Generate Runtime Data（或对应 MCP 白名单命令）重新生成。
4. 检查输出数据目录 Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/。
5. 检查输出代码目录 Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/。
6. 编译 GameGeneral、GameHF、SFMono 等受影响程序集。
7. 运行时验证：确认 HFGameStart.LoadDB() 成功且读取 API 返回预期。
8. 更新本文档与 模块索引。

验证

• 生成器执行无 Error。
• 受影响程序集编译通过。
• 运行时 LoadAllXlsx 回调正常触发。
• 关键表（如 EntityConfig、SkillGroup）按主键读取结果正确。

当前状态

• 待验证

---

相关模块

• 实体系统
• 技能系统
• 资源管理

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
modules/模块索引.md	模块索引是项目知识总入口
modules/frameworks/实体系统/README.md	实体配置来自配置表
modules/frameworks/技能系统/README.md	技能配置来自配置表
modules/frameworks/资源管理/README.md	配置资源加载依赖资源管理
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径