init

2026-02-26 13:21:43 +08:00
parent a118803f1a
commit 4daefa17d5
1259 changed files with 290021 additions and 1 deletions
@@ -0,0 +1,63 @@
+# 《几何塔防》
+
+## 游戏定位
+塔防肉鸽
+
+## 游戏主循环
+1. 进入游戏选择初始的塔防配件，组装初始的防御塔开始游戏
+2. 在关卡中玩家选择不同的节点推进关卡：
+   - 战斗节点：布置防御塔抵御敌人进攻并收集防御塔组件与配件
+   - 事件节点：随机事件（不含战斗）
+   - 商店节点：购买/出售防御塔配件/组件，购买关卡内道具
+3. 节点后调整：玩家可使用组件和配件自由组装防御塔以抵御更强的敌人进攻
+4. 开始新一轮关卡
+
+## 具体说明
+### 一、战前准备：
+1. 选择 3 种组件任意两个以完成 2 个防御塔的组装
+
+### 二、节点：
+1. 游戏内有多种主题地图，每种主题地图视为一大关，不同的主题地图敌人掉落以及关卡奖励的组件/配件属性偏好不同，玩家在完成一大关后可自由选择下一大关的主题地图，关卡难度由玩家攻略的顺序决定，与主题地图本身没有太大关系
+2. 主题地图示例：
+   - 火山：高温（战斗节点中会随机触发火山喷发在地图上生成岩浆格）
+     - 对于防御塔：部分组件在该高温下能发挥更强/更弱性能，若岩浆生成在防御塔上将会进一步强化高温对组件性能的影响
+     - 对于敌人：敌人多具有火焰抗性，部分敌人能在岩浆格上更快的行走
+   - 山地：地势起伏（地图格子有额外的高度条件，悬崖格子）
+     - 对于防御塔：不同高度的攻击会有攻击范围变化，高打低范围加强，低打高范围缩小
+     - 对于敌人：不同高度会有移动速度的差异，高往低走移速加快，低往高走移速降低，陆地敌人被击退到悬崖格子立即死亡
+3. 每个大关有 10 个节点，最后一个节点固定为 Boss 战斗格，完成胜利波次后就会结束该大关，选择并进入下一大关
+
+#### 1. 战斗节点
+1. 玩家携带一定数量的防御塔进入关卡，在关卡内规定的位置布置防御塔，具体的游戏逻辑与一般的塔防游戏类似：
+   - 关卡开始有一些资源用于布置防御塔，击杀敌人获取资源来布置或升级防御塔。
+   - 敌人会选择最短路径由出怪口向玩家基地前进（部分防御塔配件可以阻挡道路，以延长怪物的行进路线）
+2. 击杀敌人除了获取关卡内使用的资源外，还有概率掉落防御塔组件/配件，每个小关卡以及大关卡结束后也会奖励防御塔组件/配件以及一些金币用于商店购买
+3. 关卡内设定一个胜利波次，当玩家存活的波次达到后会根据基地生命产生不同的事件：
+   - = 100% ：获得额外 30% 的金币，以及额外 1 次组件 3 选 1
+   - >= 80% ：获得额外 10% 的金币
+   - >= 50% ：无加成
+   - < 50%：损失携带防御塔耐久
+4. 胜利后可以选择直接结束该关卡，也可以继续关卡以获得更多的组件/配件掉落，胜利波次后的波次将会迅速提升敌人的强度，同时较小幅度地提高爆率
+
+#### 2. 事件节点
+玩家经历一些有选项的随机事件，获取额外的奖励/惩罚。
+
+示例：
+1. 玩家花费 100 金币赌马，有两个选择：(1) 30% 赢，赢了获得 250 金币。(2) 70% 赢，赢了获得 150 金币
+2. 玩家提供 2 个防御塔组件，获得 1 个不低于原来品质的防御塔组件
+3. 消耗 2 个随机防御塔所有配件的耐久获得 150 金币
+
+#### 3. 商店节点
+1. 玩家购买防御塔组件/配件，高品质的商品要价更高，售出价格为购买价格的一半，出售防御塔时价格为其所有配件价格之和再加10%，出售配件时耐久度会影响配件的价格
+2. 玩家购买道具，道具包含各种各样的效果，比如提高关卡内初始金币，提高敌人掉落金币倍率……
+
+### 三、节点后的调整
+1. 组装防御塔：每个防御塔都必须有枪口（攻击组件）、轴承（旋转组件）、底座（功能组件）三个组件，防御塔的品质由组件决定。品质不仅决定了防御塔的基础属性，还可以为防御塔提供配件槽位（配件也能为防御塔提供额外的属性）以及 Tag 数量与品质
+   - 组件功能（某些组件还有全局性的属性倍率，比如高伤害穿透攻击的枪口会绑一个 0.5x攻击速度 的属性倍率来约束防御塔性能）：
+     - 枪口（攻击组件）：决定攻击伤害，攻击方式（普通子弹、范围伤害、穿透激光……）
+     - 轴承（旋转组件）：决定枪口转速（某些攻击方式只有对准敌人后才能进行攻击），攻击范围
+     - 底座（功能组件）：决定攻击频率，攻击属性（火焰、毒素、冰……）
+   - 品质计算：每个组件提供一定的品质权重（白：1，绿：2，蓝：3，紫：4，红：5），比如三个配件是 2 绿 1 白，那么防御塔的品质是 (2+2+1)/3=1.67，四舍五入后为 2 也就是绿色品质。
+   - 各品质的配件槽：白/绿：0，蓝：1，紫：2，红：3。
+   - 组件 Tag：不同的品质随机出现的 Tag 等级与数量不同，例如白色组件有 50% 不出 Tag，40% 出 1 级 Tag，10% 出 2 级 Tag
+2. 拆解防御塔：组件/配件有耐久属性，组件/配件的耐久与其提供的属性相关，50% 耐久时就只能提供原来一半的属性值，当耐久为 0 时将会直接销毁
@@ -0,0 +1,71 @@
+# GeometryTD 可执行 Todo List
+
+> 来源：`docs/GameDesign.md`  
+> 目标：先做出可完整游玩的 MVP，再逐步补齐深度与打磨。
+
+## 执行规则
+1. 按里程碑顺序执行，不跨阶段提前开发。
+2. 每项任务必须同时满足“交付物路径”和“验收标准”才可打勾。
+3. 数据驱动优先：数值、掉落、商店、事件都优先落到 `DataTables`。
+
+## 里程碑 M1（P0）- 最小可玩闭环
+
+| 状态 | ID | 任务 | 交付物路径 | 验收标准 |
+| --- | --- | --- | --- | --- |
+| [ ] | P0-01 | 冻结 MVP 范围（只保留：战斗节点/事件节点/商店节点/节点后组装） | `docs/MVP-Scope.md` | 明确“做/不做”清单，团队评审通过 |
+| [ ] | P0-02 | 补齐数据表：组件、配件、敌人、波次、节点、事件、商店商品 | `Assets/GameMain/DataTables/*.txt` | 游戏启动可无报错加载全部新增表 |
+| [ ] | P0-03 | 新增/完善 DataRow 解析类 | `Assets/GameMain/Scripts/DataTable/*.cs` | 每个新增表都有对应 DR 类并成功解析 |
+| [ ] | P0-04 | 建立单局 Run 状态模型（金币、生命、库存、当前节点） | `Assets/GameMain/Scripts/Procedure/` | 进入/退出节点时状态可持续传递 |
+| [ ] | P0-05 | 实现 10 节点地图生成（最后节点固定 Boss） | `Assets/GameMain/Scripts/Scene/` | 每局都生成 10 节点且第 10 节点为 Boss |
+| [ ] | P0-06 | 实现节点选择与跳转流程（战斗/事件/商店） | `Assets/GameMain/Scripts/Procedure/` | 节点完成后可返回地图并进入下个节点 |
+| [ ] | P0-07 | 战斗节点基础玩法：放置塔、出怪、基地扣血、胜负判定 | `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/Scripts/Scene/` | 可完整打一场并得到胜利/失败结果 |
+| [ ] | P0-08 | 胜利波次与结算规则（100/80/50/<50） | `Assets/GameMain/Scripts/Procedure/` | 结算奖励与惩罚严格匹配设计文档 |
+| [ ] | P0-09 | 敌人掉落与关卡奖励（组件/配件/金币） | `Assets/GameMain/Scripts/Entity/` | 战斗结束能发放掉落并写入库存 |
+| [ ] | P0-10 | 节点后组装：枪口/轴承/底座三组件约束 | `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 未满足三组件时禁止出战 |
+| [ ] | P0-11 | 品质/槽位/Tag 计算落地（白绿蓝紫红） | `Assets/GameMain/Scripts/Definition/` `Assets/GameMain/Scripts/Entity/` | 计算结果可复现并与规则一致 |
+| [ ] | P0-12 | 组件/配件耐久生效与 0 耐久销毁 | `Assets/GameMain/Scripts/Entity/` | 耐久影响属性，归零后物品移除 |
+
+## 里程碑 M2（P1）- 核心深度
+
+| 状态 | ID | 任务 | 交付物路径 | 验收标准 |
+| --- | --- | --- | --- | --- |
+| [ ] | P1-01 | 事件节点系统（选项、概率、奖励/惩罚执行器） | `Assets/GameMain/Scripts/Procedure/` `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 可配置并执行至少 10 个事件 |
+| [ ] | P1-02 | 落地设计中的 3 个示例事件（赌马/组件交换/耐久换金币） | `Assets/GameMain/DataTables/*.txt` | 三个事件可在局内完整触发与结算 |
+| [ ] | P1-03 | 商店节点：购买/出售组件与配件 | `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 买卖后库存与金币实时正确更新 |
+| [ ] | P1-04 | 商店定价规则：买价、半价回收、卖塔+10%、耐久折价 | `Assets/GameMain/Scripts/Utility/` `Assets/GameMain/Scripts/Entity/` | 各种交易结果符合公式 |
+| [ ] | P1-05 | 道具系统（影响初始金币、掉金倍率等） | `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/DataTables/*.txt` | 至少 5 个道具可叠加生效 |
+| [ ] | P1-06 | 战斗后“继续挑战”机制（高强度高爆率） | `Assets/GameMain/Scripts/Procedure/` | 选择继续后敌人强度明显提升且爆率提升 |
+| [ ] | P1-07 | 火山主题规则（高温、岩浆格、抗火敌人） | `Assets/GameMain/Scripts/Scene/` `Assets/GameMain/Scripts/Entity/` | 岩浆效果可视且会改变战斗结果 |
+| [ ] | P1-08 | 山地主题规则（高度、悬崖、位移致死） | `Assets/GameMain/Scripts/Scene/` `Assets/GameMain/Scripts/Entity/` | 高低地形影响攻防与移速，悬崖击退生效 |
+| [ ] | P1-09 | 主题地图掉落偏好（按主题偏置组件/配件） | `Assets/GameMain/DataTables/*.txt` `Assets/GameMain/Scripts/Entity/` | 不同主题统计掉落分布显著不同 |
+| [ ] | P1-10 | 大关完成后可选下一主题地图 | `Assets/GameMain/Scripts/Procedure/` `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 通关后至少可在 2 个主题间选择 |
+
+## 里程碑 M3（P2）- 打磨与上线准备
+
+| 状态 | ID | 任务 | 交付物路径 | 验收标准 |
+| --- | --- | --- | --- | --- |
+| [ ] | P2-01 | HUD 完整信息（波次、基地血量、金币、节点进度） | `Assets/GameMain/Scripts/UI/Templates/GameScene/View/` | 关键信息在战斗中可实时观测 |
+| [ ] | P2-02 | 3 选 1 奖励 UI 与结果回放 | `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 奖励选择流程无阻塞，结果可追溯 |
+| [ ] | P2-03 | 组装/拆解交互优化（预览属性变化） | `Assets/GameMain/Scripts/UI/Templates/GameScene/` | 改装前后差异可视化展示 |
+| [ ] | P2-04 | 存档与读档（局外货币、库存、解锁进度） | `Assets/GameMain/Scripts/Utility/` `Assets/GameMain/Scripts/Procedure/` | 重启游戏后进度一致恢复 |
+| [ ] | P2-05 | 平衡性首轮调参（敌人曲线、经济曲线、掉落曲线） | `Assets/GameMain/DataTables/*.txt` | 3 局平均时长与胜率落在预期区间 |
+| [ ] | P2-06 | 最低限度自动化测试（公式与关键流程） | `Assets/` 下新增 `Editor`/`Runtime` 测试 | 关键计算与流程回归可自动验证 |
+| [ ] | P2-07 | 性能与稳定性检查（长局、内存、异常日志） | `docs/PerformanceReport.md` | 连续游玩 30 分钟无阻断性问题 |
+
+## 本周建议开工顺序
+1. `P0-01` ~ `P0-04`（先把范围与数据基础打稳）
+2. `P0-05` ~ `P0-09`（打通节点到战斗再到结算）
+3. `P0-10` ~ `P0-12`（完成组装与耐久闭环）
+
+## 设计优化 Backlog（新增）
+
+| 状态 | ID | 优先级 | 任务 | 交付物路径 | 验收标准 |
+| --- | --- | --- | --- | --- | --- |
+| [ ] | D-01 | P0 | 新手前 15 分钟分阶段解锁复杂度（组装/节点/商店） | `docs/NewPlayerFlow.md` `Assets/GameMain/Scripts/Procedure/` `Assets/GameMain/Scripts/UI/` | 新玩家首局可在 15 分钟内完成完整流程且无关键机制卡死 |
+| [ ] | D-02 | P0 | 路径阻挡合法性校验（永远保留至少一条可行路径） | `Assets/GameMain/Scripts/Scene/` `Assets/GameMain/Scripts/Entity/` | 任意放置行为都不会导致敌人无路可走 |
+| [ ] | D-03 | P1 | “胜利后继续”风险收益曲线重做（危险快速上升+保底收益） | `Assets/GameMain/DataTables/*.txt` `Assets/GameMain/Scripts/Procedure/` | 连续继续挑战时，敌人强度阶梯上升且每波都有可感知保底收益 |
+| [ ] | D-04 | P1 | 耐久惩罚去滚雪球（改为维修成本或临时失效） | `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/Scripts/Procedure/` `Assets/GameMain/DataTables/*.txt` | 低血量通关后不会直接导致下一节点战力崩溃 |
+| [ ] | D-05 | P1 | 品质槽位断层平滑（降低白/绿到蓝的跳变） | `Assets/GameMain/Scripts/Definition/` `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/DataTables/*.txt` | 品质提升曲线更连续，玩家不会因单级品质差出现极端强度断层 |
+| [ ] | D-06 | P1 | 事件池按期望值分层（高风险/低风险/功能型） | `docs/EventDesign.md` `Assets/GameMain/DataTables/*.txt` | 三类事件都可稳定出现，且选择差异明显 |
+| [ ] | D-07 | P1 | 主题地图反制机制（每主题至少 2 个可用对策） | `Assets/GameMain/Scripts/Entity/` `Assets/GameMain/Scripts/Scene/` `Assets/GameMain/DataTables/*.txt` | 火山与山地都存在明确反制构筑，UI 有可读提示 |
+| [ ] | D-08 | P0 | 先定义数值预算（经济/敌强/掉落）再调参 | `docs/NumericBudget.md` `Assets/GameMain/DataTables/*.txt` | 关键曲线有目标区间，3 局测试结果可与目标对比复盘 |
@@ -0,0 +1,182 @@
+# UI 五层架构设计规范（RawData / Controller / View / Context / UseCase）
+
+## 1. 适用范围
+
+- 适用目录：`Assets/GameMain/Scripts/UI/*`
+- 重点对象：采用五层拆分的 UI 模块（`MenuScene`、`GameScene`、`General` 下的分层 UI）
+- 本文不展开 Unity GameFramework 底层实现细节，仅约束项目内 UI 代码组织与协作方式
+
+## 2. 架构总览
+
+UI 模块采用“输入数据 -> 业务编排 -> 展示数据 -> 渲染表现”的分层方式，核心链路如下：
+
+1. 外部流程（Procedure/GameState）创建并绑定 UseCase
+2. 通过 `GameEntry.UIRouter` 打开指定 UI
+3. Controller 从 UseCase 取 RawData，并转换为 Context
+4. View 使用 Context 渲染
+5. View 通过事件回传交互，Controller 处理后驱动 UseCase 更新，再刷新 View
+
+简化关系图：
+
+```text
+Procedure/GameState
+   -> UIRouter
+      -> Controller <-> UseCase
+      -> Context -> View
+View --(CustomEvent)--> Controller
+```
+
+## 3. 五层职责定义
+
+### 3.1 RawData 层
+
+职责：承载“业务原始数据”，作为 UseCase 到 Controller 的传输模型。
+
+约束：
+
+- 命名：`XXXFormRawData`
+- 只描述数据，不包含 UI 渲染行为
+- 可保留领域对象或数据表对象（例如 `DRLevelUpReward`、`WeaponBase`）
+- 不依赖具体 View 组件
+
+参考：
+
+- `Assets/GameMain/Scripts/UI/Template/GameScene/RawData/ShopFormRawData.cs`
+- `Assets/GameMain/Scripts/UI/Template/GameScene/RawData/LevelUpFormRawData.cs`
+- `Assets/GameMain/Scripts/UI/Template/MenuScene/RawData/SelectRoleFormRawData.cs`
+
+### 3.2 UseCase 层
+
+职责：封装 UI 对应业务用例，负责业务规则、状态推进、数据生成。
+
+约束：
+
+- 实现 `IUIUseCase`
+- 命名：`XXXFormUseCase`
+- 对外提供 `CreateInitialModel / TryRefresh / Select / Confirm` 等语义化方法
+- 返回 RawData（或结果对象），不直接操作具体 View
+
+参考：
+
+- `Assets/GameMain/Scripts/UI/Template/GameScene/UseCase/ShopFormUseCase.cs`
+- `Assets/GameMain/Scripts/UI/Template/GameScene/UseCase/LevelUpFormUseCase.cs`
+- `Assets/GameMain/Scripts/UI/Template/MenuScene/UseCase/SelectRoleFormUseCase.cs`
+
+### 3.3 Controller 层
+
+职责：UI 编排层，连接 UseCase 与 View，管理 UI 生命周期、事件订阅、数据转换。
+
+约束：
+
+- 继承 `UIFormControllerCommonBase<TContext, TForm>`
+- 命名：`XXXFormController`
+- 通过 `BindUseCase(IUIUseCase)` 注入用例并做类型校验
+- `OpenUI(object userData = null)` 支持：`Context`、`RawData`、`null`
+- 负责 RawData -> Context 的转换（常见 `BuildContext`）
+- 在 `SubscribeCustomEvents / UnsubscribeCustomEvents` 成对管理事件
+- 可做局部刷新（避免整窗重建）
+
+参考：
+
+- `Assets/GameMain/Scripts/UI/Template/GameScene/Controller/ShopFormController.cs`
+- `Assets/GameMain/Scripts/UI/Template/GameScene/Controller/LevelUpFormController.cs`
+- `Assets/GameMain/Scripts/UI/Template/MenuScene/Controller/SelectRoleFormController.cs`
+
+### 3.4 Context 层
+
+职责：承载“可直接驱动 UI 展示”的上下文数据。
+
+约束：
+
+- 继承 `UIContext`
+- 命名：`XXXFormContext` 或 `XXXItemContext`
+- 字段以展示友好为目标（标题、描述、图标、稀有度、列表等）
+- 允许组合子 Context（例如列表区 + 条目）
+
+参考：
+
+- `Assets/GameMain/Scripts/UI/Template/GameScene/Context/ShopFormContext.cs`
+- `Assets/GameMain/Scripts/UI/Template/GameScene/Context/DisplayListAreaContext.cs`
+- `Assets/GameMain/Scripts/UI/Template/MenuScene/Context/SelectRoleFormContext.cs`
+
+### 3.5 View 层
+
+职责：纯表现层，负责控件绑定、显示刷新、交互事件抛出。
+
+约束：
+
+- Form 类继承 `UGuiForm`，子组件通常继承 `MonoBehaviour`
+- 命名：`XXXForm` / `XXXItem` / `XXXArea`
+- 提供 `RefreshUI(Context)`、`OnInit(Context)`、`OnReset()` 等渲染入口
+- 用户交互通过 `GameEntry.Event.Fire(...)` 通知 Controller
+- 不承载业务规则（计算、流程推进、数据筛选应在 UseCase）
+
+参考：
+
+- `Assets/GameMain/Scripts/UI/Template/GameScene/View/ShopForm.cs`
+- `Assets/GameMain/Scripts/UI/Template/GameScene/View/DisplayListArea.cs`
+- `Assets/GameMain/Scripts/UI/Template/MenuScene/View/SelectRoleForm.cs`
+
+## 4. 标准交互流程
+
+### 4.1 初始化与绑定
+
+1. Procedure/GameState 创建 UseCase
+2. 调用 `GameEntry.UIRouter.BindUIUseCase(UIFormType.X, useCase)`
+
+### 4.2 打开 UI
+
+1. 调用 `GameEntry.UIRouter.OpenUI(UIFormType.X)`
+2. Controller 从 UseCase 取 RawData（或接收外部 RawData/Context）
+3. Controller 构建 Context 后打开/刷新 Form
+4. View 在 `OnOpen` 中校验 Context 类型并执行 `RefreshUI`
+
+### 4.3 用户交互到刷新
+
+1. View 触发事件（如购买、刷新、选择）
+2. Controller 监听事件并调用 UseCase
+3. UseCase 返回新数据或操作结果
+4. Controller 更新 Context 并刷新全部或局部 UI
+
+### 4.4 关闭 UI
+
+1. 调用 `GameEntry.UIRouter.CloseUI(UIFormType.X)`
+2. Controller 解除事件订阅并关闭窗体
+3. View `OnClose` 清理本地状态
+
+## 5. 目录与命名规范
+
+- 目录：`UI/<SceneDomain>/RawData|UseCase|Controller|Context|View`
+- 五层同名前缀保持一致：`ShopForm*`、`LevelUpForm*`、`SelectRoleForm*`
+- 子组件上下文命名：`RoleItemContext`、`DisplayItemContext`、`LevelUpRewardItemContext`
+- 新增 UI Form 时优先建立完整五层；仅纯静态展示可降级为 View-only
+
+## 6. 依赖方向约束
+
+允许依赖：
+
+- `UseCase -> RawData / 领域对象`
+- `Controller -> UseCase + RawData + Context + View + Event`
+- `View -> Context + Event`
+
+禁止依赖：
+
+- `View -> UseCase`
+- `View -> 领域状态修改`
+- `Context/RawData -> View`
+
+## 7. 新增一个五层 UI 的落地步骤
+
+1. 在目标场景目录创建 `RawData / UseCase / Context / Controller / View` 对应类型
+2. 在 UseCase 中实现模型创建与交互方法
+3. 在 Controller 中实现 `BindUseCase`、`OpenUI`、`BuildContext`、事件订阅
+4. 在 View 中实现 `RefreshUI` 和交互事件抛出
+5. 在对应 Procedure/GameState 里完成 UseCase 绑定与 Open/Close 调用
+6. 自测三条主链路：首次打开、交互刷新、关闭重开
+
+## 8. 项目当前实践说明
+
+- `ShopForm`、`LevelUpForm`、`SelectRoleForm` 是当前五层模式的主要样板
+- `DialogForm` 也有 Controller/Context/RawData，但 UseCase 为可选
+- `HudForm`、`StartMenuForm` 当前为轻用例场景，可不强制 UseCase
+- `SettingForm`、`AboutForm` 属于历史直连型 UI，不属于五层完整样板