# 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，无业务逻辑 |

### 设计原则

1. **业务包不依赖框架包以外的东西**：自家包之间只允许 `cn.xt.* → cn.xt.*invoke`，禁止业务直接 ref 业务实现。
2. **Mongo 服务端 + Memory 客户端**：`MongoDBComponent` 用 `#if DOTNET || UNITY_EDITOR || UNITY_STANDALONE_*` 包住，客户端打包自动落到 `MemoryDBComponent`。
3. **持久化走脏写**：`DBSaveComponent.MarkDirty(player)` 标脏，固定节奏 Flush，玩家下线/进程退出时也 Flush。
4. **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 几个零依赖契约包）
```

---

## 四、快速集成

1. 把整个 `Packages/` 目录的内容拷进新工程的 `Packages/`（保持目录名）  
2. 从 ET 官方拉取 `cn.etetet.*` 框架包，放在同一 `Packages/` 下
3. 在 `Packages/manifest.json` 里把这些包都登记进去（或用 `file:` 引用本地路径）
4. Unity 打开工程 → 等 UPM 解析 → 编译  
5. 跑工程：登录后用 `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/` 等）