122 lines
6.2 KiB
Markdown
122 lines
6.2 KiB
Markdown
# 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/` 等）
|