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/ 等）

6.2 KiB Raw Permalink Blame History Unescape Escape