XtGameKit
基于 ET 9.0 + YIUI 框架的 SLG/养成业务包集合，包含：英雄系统、酒馆（抽卡）、通用背包、配置加载、数据持久化、跨模块 Invoke 契约。
本仓库只放自研业务包与设计文档，不放 ET 框架本体（用户拉到本地后请自行从 ET 框架仓库拉取 cn.etetet.*）。
一、仓库目录
XtGameKit/
├── Packages/ # 8 个自研 cn.xt.* 包
│ ├── cn.xt.hero/ # 英雄系统（召唤/升级/培养）
│ ├── cn.xt.heroinvoke/ # 英雄系统跨包 Invoke 契约
│ ├── cn.xt.bag/ # 通用背包（万物皆 Item）
│ ├── cn.xt.baginvoke/ # 背包跨包 Invoke 契约
│ ├── cn.xt.gacha/ # 酒馆（抽卡） = Tavern
│ ├── cn.xt.gachainvoke/ # 酒馆跨包 Invoke 契约
│ ├── cn.xt.config/ # 配置加载占位（Luban 接入点）
│ └── cn.xt.db/ # 数据持久化（Mongo/Memory 双实现 + 脏写）
│
├── Doc/ # 设计与移植规格文档
│ ├── Hero-System-Guide.md # 英雄系统使用指南
│ ├── Bag-System-Guide.md # 背包系统使用指南
│ ├── GM-Commands.md # GM 指令一览（含 YIUI GM 面板）
│ ├── Item-Design-Rule.md # Universal Item 设计准则
│ ├── Logging-Guide.md # 三层日志（Business / Audit / Error）
│ ├── Luban-Guide.md # Luban 配置接入流程
│ ├── ROK-Hero-Spec.md # ROK Hero 1:1 业务规则规格
│ ├── ROK-Bag-Spec.md # ROK Bag 业务规则规格
│ ├── ROK-Equip-Spec.md # ROK 装备业务规则规格
│ ├── ROK-HeroAcquire-Spec.md # ROK 英雄获取业务规则规格
│ ├── ROK-Spec-Index.md # ROK 规格总入口
│ ├── ROK-Config-Source.md # ROK 配置来源审计
│ ├── ROK-Luban-Field-Mapping.md # ROK→Luban 字段映射
│ ├── ET-Packages-Audit.md # ET 现有包审计（避免造轮子）
│ └── Server-Setup.md # 服务端部署
│
├── openspec/
│ └── changes/
│ └── port-rok-hero-bag-system/ # OpenSpec 提案 / 设计 / specs / tasks
│
└── .cursor/
└── skills/
└── et-framework-dev/ # ET 框架开发指南（分析器规则 / 程序集分层 / Proto 工作流）
二、模块概览
| 包 | 作用 | 关键入口 |
|---|---|---|
cn.xt.hero |
英雄获取/升级/属性 | HeroComponent, GM Hero-召唤 |
cn.xt.bag |
通用 Item 仓库（万物皆 Item） | BagComponent.AddItem / RemoveItem |
cn.xt.gacha |
抽卡 = 酒馆 | GachaComponent, C2G_GachaDraw |
cn.xt.config |
Luban 配置占位 + 加载 fallback | cfg.Tables |
cn.xt.db |
数据持久化（玩家加载/脏写/Flush） | IDBComponent, MongoDBComponent, MemoryDBComponent, DBSaveComponent |
cn.xt.*invoke |
跨包调用契约 | Pure interface/types，无业务逻辑 |
设计原则
- 业务包不依赖框架包以外的东西：自家包之间只允许
cn.xt.* → cn.xt.*invoke，禁止业务直接 ref 业务实现。 - Mongo 服务端 + Memory 客户端：
MongoDBComponent用#if DOTNET || UNITY_EDITOR || UNITY_STANDALONE_*包住，客户端打包自动落到MemoryDBComponent。 - 持久化走脏写：
DBSaveComponent.MarkDirty(player)标脏，固定节奏 Flush，玩家下线/进程退出时也 Flush。 - GM 双轨：服务器
cn.etetet.console+ 客户端cn.etetet.yiuigm，所有 GM 命令都两侧可用。
三、依赖（框架包不在本仓库）
8 个 cn.xt.* 包在 package.json 里都依赖了 ET 框架包；你需要在自己工程的 Packages/ 同级目录下，从 ET 官方仓库拉到这些包：
cn.xt.* 需要的依赖 |
出处 |
|---|---|
cn.etetet.core (>= 3.0.3) |
ET 官方 |
cn.etetet.login (>= 3.0.0) |
ET 官方 |
cn.etetet.console (>= 3.0.0) |
ET 官方 |
cn.etetet.logging (>= 0.0.1) |
ET 官方 |
cn.etetet.yiuigm (>= 3.0.4) |
ET 官方（仅 cn.xt.hero/bag/gacha 需要） |
拉取方式：建议把 ET 官方仓库整体 clone 到
Packages/同级（典型路径形如Packages/cn.etetet.*/），或在manifest.json里以file:/ git 形式引用。
包间依赖（自家 → 自家）
cn.xt.hero ──> cn.xt.bag, cn.xt.config
cn.xt.gacha ──> cn.xt.bag
其余 cn.xt.* 包 之间无依赖（含 *invoke 几个零依赖契约包）
四、快速集成
- 把整个
Packages/目录的内容拷进新工程的Packages/（保持目录名） - 从 ET 官方拉取
cn.etetet.*框架包，放在同一Packages/下 - 在
Packages/manifest.json里把这些包都登记进去（或用file:引用本地路径） - Unity 打开工程 → 等 UPM 解析 → 编译
- 跑工程：登录后用
Hero-召唤GM 命令验证
五、文档怎么读
- 新人入门 →
Doc/Hero-System-Guide.md+Doc/Bag-System-Guide.md - 改业务 →
Doc/ROK-Spec-Index.md进ROK-*-Spec.md - 接 Luban →
Doc/Luban-Guide.md+Doc/ROK-Luban-Field-Mapping.md - 改 GM →
Doc/GM-Commands.md - 改持久化 / 日志 →
Doc/Logging-Guide.md - 看决策史 →
openspec/changes/port-rok-hero-bag-system/proposal.md与design.md - 避免 ET 踩坑 →
.cursor/skills/et-framework-dev/SKILL.md
六、未推送内容（明确说明）
- ET 框架本体
cn.etetet.*（请到 ET 官方 git 拉） - 服务器密钥/密码（
server_connect.md已显式排除） - 包名迁移工具
tools/package-namespace-migrator.py（属本机一次性脚本） - 项目工程（Unity 主工程
Assets/、Library/等）