feat: 实现游戏核心功能与前端界面

- 添加游戏核心系统：战斗、任务、日志、随机数生成等 - 实现前端主界面、HUD、底部导航和各类卡片组件 - 添加用户认证系统与游戏存档持久化 - 配置项目基础架构与开发环境 - 补充文档说明与Docker部署支持
2026-04-28 22:16:58 +08:00
parent 2e1b58bada
commit e783e6e533
124 changed files with 9759 additions and 1 deletions
@@ -0,0 +1,169 @@
+# 12 前端 HUD 架构与资产管线
+
+本文档记录当前 TinyWaste Online Web 客户端的 HUD 架构落地方式，目标是让后续继续扩内容、补系统、换美术时，仍然能保持模块边界清晰、资产可追溯、状态流可解释。
+
+## 12.1 技术栈结论
+
+当前重制版继续沿用并确认以下技术栈，不做二次摇摆：
+
+- 前端：React 19 + Vite + TypeScript
+- 客户端数据层：TanStack Query
+- 后端：Fastify + TypeScript
+- 存档与账号：Session Cookie + Drizzle ORM + SQLite
+- 共享规则层：`packages/game-core`
+- 共享内容层：`packages/content`
+
+选择原因：
+
+- React + Vite 适合构建高密度单屏 HUD，开发迭代成本低。
+- React Query 负责会话、存档和行动回写，能把“在线游戏状态”与“界面状态”明确分层。
+- `game-core` 与 `content` 把规则和内容从 UI 中剥离，符合文档 08 的分层目标。
+- Fastify + Drizzle 让账号与云存档可以继续扩展为多槽、迁移、审计和反作弊校验。
+
+## 12.2 当前前端分层
+
+按照文档 08 的 Presentation / Application / Domain / Data 思路，前端当前对应如下：
+
+- Presentation：`apps/web/src/features/game/components/*`、`apps/web/src/features/auth/components/*`
+- Application：`apps/web/src/features/session/useGameSession.ts`
+- Data：`apps/web/src/api.ts`
+- Domain：`packages/game-core`、`packages/content`
+
+职责约束：
+
+- `App.tsx` 只负责入口编排，不再直接堆叠完整 HUD 细节。
+- `useGameSession.ts` 只负责编排查询、认证、建档、行动提交与错误状态。
+- HUD 组件只消费 `GameView` 和回调，不直接触碰接口实现。
+- 游戏规则与内容定义禁止回流到 `apps/web` 内硬编码。
+
+## 12.3 组件结构
+
+当前 HUD 结构：
+
+```text
+App
+├─ AuthScreen / NewGameScreen / LoadingScreen
+└─ GameHud
+   ├─ TopHud
+   ├─ RoutePanel
+   ├─ CommandCenter
+   ├─ LoadoutPanel
+   ├─ BottomDock
+   └─ ModalShell (事件 / 战斗 / 胜负)
+```
+
+卡片级组件：
+
+- `AssetThumb`
+- `StatMeter`
+- `InventoryCard`
+- `RecipeCard`
+- `QuestCard`
+- `EmptyState`
+- `PanelHeader`
+
+这样拆分后的收益：
+
+- 左、中、右、底四个 HUD 区块可以独立重做，而不需要重新读一遍整个页面。
+- 小卡片组件可被更多系统复用，例如未来的交易、仓库、NPC 商店、任务详情。
+- `GameHud` 能承载局部交互状态，比如 `commandTab`、`sideTab`，而不会污染全局会话逻辑。
+
+## 12.4 状态流
+
+当前在线游戏状态流：
+
+```text
+浏览器 -> /api/auth/me -> 用户会话
+浏览器 -> /api/game/state -> 当前云端存档
+用户动作 -> /api/game/action -> 服务端结算 -> 返回新 GameView
+UI 组件 <- Query Cache <- 最新 GameView
+```
+
+具体规则：
+
+- 认证通过后才启用 `game-state` 查询。
+- 创建新游戏、旅行、制作、战斗、交易、休息都走服务端 authoritative action。
+- Query Cache 只保存最新服务端视图，不在前端自行推演核心规则。
+- HUD 内部 tab 只属于本地展示状态，不影响云端存档。
+
+## 12.5 视觉资产组织
+
+所有当前接入的 GPT-image-2 资产位于：
+
+- `apps/web/public/generated/`：地点背景
+- `apps/web/public/generated/ui/character-preview.png`：角色立绘
+- `apps/web/public/generated/ui/item-atlas.png`：物资图集原图
+- `apps/web/public/generated/ui/equipment-atlas.png`：装备图集原图
+- `apps/web/public/generated/ui/items/*`：切分后的物资图标
+- `apps/web/public/generated/ui/equipment/*`：切分后的装备槽素材
+
+对应映射入口：
+
+- `apps/web/src/features/game/uiAssets.ts`
+
+当前资产策略：
+
+- 地点图使用整图背景，服务于中央场景和左侧路线卡。
+- 物资与装备图使用 atlas + 裁切结果，服务于快捷栏、库存卡、角色槽位。
+- 所有引用都走 `uiAssets.ts`，避免组件里散落硬编码路径。
+
+## 12.6 HUD 信息职责
+
+### 12.6.1 TopHud
+
+- 时间
+- 生存状态条
+- 风险标签
+- 账号状态
+
+### 12.6.2 RoutePanel
+
+- 当前地点摘要
+- 路线列表
+- 风险强度
+- 节点式世界图
+
+### 12.6.3 CommandCenter
+
+- 场景主视觉
+- 行动矩阵
+- 交易终端
+- 实时日志
+- 当前目标
+- 蓝图视图
+
+### 12.6.4 LoadoutPanel
+
+- 角色 / 背包 / 任务三态切换
+- 角色立绘与槽位矩阵
+- 属性与状态效果
+- 快捷栏
+- 完整库存管理
+- 任务与休整
+
+### 12.6.5 BottomDock
+
+- 游戏化底部导航
+- 当前角色标识
+- 核心补给统计
+
+## 12.7 当前与参考图的对齐策略
+
+对齐的不是“像一张网站海报”，而是“像一套可操作的游戏终端”：
+
+- 维持单屏阅读，整页不滚动，滚动只发生在内部面板。
+- 中央区优先展示场景与决策，避免全文字堆叠。
+- 右侧区优先视觉化角色与装备，而不是继续做普通列表。
+- 底部区承担模式切换和系统导航，强化“游戏 HUD”心智。
+
+## 12.8 下一步扩展建议
+
+下一轮优先项：
+
+1. 继续补 GPT-image-2 资产：
+   - 头部、侧武器、弹药、医疗、食物第二批图集
+   - 天气、辐射、事件状态专用小图标
+2. 将 `LoadoutPanel` 的 tab 与底部导航进一步联动为统一模式系统。
+3. 为 `CommandCenter` 增加战斗专属视图和事件专属视图，而不是完全依赖弹层。
+4. 为物资卡补充更精细的分类过滤和排序逻辑。
+5. 引入可配置的 HUD 主题参数，支撑不同章节或区域切换皮肤。
@@ -0,0 +1,299 @@
+# 13 运行时引擎与核心系统深化设计
+
+本文档补足“把游戏做好”所需要的核心系统设计，不只讨论 UI，而是把运行时引擎、生命周期、背包系统、生命系统、事件与在线存档串成一套完整方案。
+
+## 13.1 当前产品定位
+
+TinyWaste Online 不是网页式信息展示项目，而是一款：
+
+- 服务端权威结算的在线废土生存游戏
+- 以单屏 HUD 为常驻界面
+- 以系统弹窗/面板处理中频与低频操作
+- 以时间推进驱动状态、资源、事件和任务
+
+这意味着架构设计要同时满足：
+
+- 决策节奏像游戏
+- 数据流像在线产品
+- 规则层像可测试的模拟器
+
+## 13.2 运行时引擎分层
+
+建议把“引擎”理解为运行时规则框架，而不是 3D 图形引擎。
+
+### 13.2.1 Runtime Core
+
+职责：
+
+- 接收玩家动作
+- 推进时间
+- 执行效果链
+- 更新世界状态
+- 产出新 `GameView`
+
+当前仓库中主要由 `packages/game-core/src/engine.ts` 承担。
+
+### 13.2.2 View Model Layer
+
+职责：
+
+- 把内部 `GameState` 投影成适合 HUD 使用的 `GameView`
+- 控制哪些信息常驻、哪些信息放到弹窗层
+- 限制 UI 对领域状态的直接依赖
+
+### 13.2.3 Content Layer
+
+职责：
+
+- 维护物品、地点、敌人、任务、配方、事件定义
+- 所有玩法扩展优先靠数据增量，而不是写死分支逻辑
+
+### 13.2.4 Persistence Layer
+
+职责：
+
+- 用户身份
+- 云存档
+- 版本迁移
+- 存档校验
+
+## 13.3 游戏生命周期
+
+游戏生命周期建议明确分成 7 个阶段：
+
+1. `boot`
+   - 客户端初始化、检查账号会话、读取配置
+2. `session-ready`
+   - 已确认账号身份，开始拉取云端存档
+3. `save-ready`
+   - 存档进入内存，HUD 可以渲染
+4. `decision`
+   - 玩家阅读信息、选择动作
+5. `resolving`
+   - 服务端执行动作、推进时间、写入日志
+6. `interrupt`
+   - 战斗、事件、死亡、胜利等强制中断态
+7. `persisted`
+   - 新状态完成落库，回到下一轮 `decision`
+
+生命周期原则：
+
+- UI 永远不直接修改权威状态
+- 所有中断态都要可恢复
+- 任意动作完成后都应保证日志、时间、任务和存档状态同步
+
+## 13.4 HUD 生命周期
+
+主 HUD 只保留高频信息：
+
+- 时间
+- 生存状态
+- 当前地点
+- 行动入口
+- 角色装备摘要
+- 快捷栏
+
+中频系统改用面板弹出：
+
+- 背包
+- 蓝图
+- 任务
+- 完整日志
+
+设计原因：
+
+- 更像真实游戏而不是网页后台
+- 减少主屏认知负担
+- 保证一屏内只承载“下一步决策需要的信息”
+
+## 13.5 动作执行生命周期
+
+一条标准动作链应为：
+
+1. 玩家发起动作
+2. 服务端校验动作是否合法
+3. 推进时间
+4. 结算状态消耗
+5. 结算地点资源与热度
+6. 结算掉落/交易/配方结果
+7. 检查事件、战斗、任务推进
+8. 写入日志
+9. 写入存档
+10. 返回新 `GameView`
+
+这里最重要的是顺序一致性。只要顺序稳定，玩家就能理解“为什么会掉血、为什么这里空了、为什么事件触发了”。
+
+## 13.6 背包系统设计
+
+### 13.6.1 当前正确方向
+
+当前采用体积容量，而不是无限背包，这是对的。
+
+原因：
+
+- 废土游戏的核心就是取舍
+- 容量限制会自然驱动路线规划、补给管理和交易行为
+- 比单纯格子背包更贴合生存题材
+
+### 13.6.2 背包分层
+
+建议将背包拆成 3 层：
+
+- `Quick Slots`
+  - 高频立即使用
+  - 水、药、近战、少量工具
+- `Field Bag`
+  - 当前随身背包
+  - 受体积限制
+- `Shelter Storage`
+  - 基地仓储
+  - 用于长线积累
+
+当前项目已经有 `Quick Slots + Inventory` 雏形，下一步建议补 `Shelter Storage`。
+
+### 13.6.3 物品状态
+
+每个背包物品后续建议支持：
+
+- `itemId`
+- `count`
+- `durability`
+- `quality`
+- `boundFlag`（任务物品或不可丢弃）
+- `sourceTag`（掉落来源，便于日志和分析）
+
+### 13.6.4 背包交互原则
+
+- 主 HUD 只显示快捷栏和容量摘要
+- 完整背包在弹窗面板中查看
+- 装备/使用/整理/分类都应在背包面板完成
+- 背包面板必须优先展示“对当前生存决策有帮助的信息”
+
+## 13.7 生命系统设计
+
+生命系统不应只是一根血条，而是一组相互耦合的生存状态。
+
+### 13.7.1 核心状态
+
+- 生命 `life`
+- 饥饿 `hunger`
+- 口渴 `thirst`
+- 精力 `energy`
+- 理智 `sanity`
+- 辐射 `radiation`
+
+### 13.7.2 设计原则
+
+- 生命是最终硬失败边界
+- 饥饿与口渴是持续性压力来源
+- 精力限制连续行动长度
+- 理智影响事件与长期稳定性
+- 辐射是高风险区域的长期代价
+
+### 13.7.3 阈值式生命系统
+
+建议后续把状态效果从“单纯数值显示”升级成阈值逻辑：
+
+- `safe`
+- `strained`
+- `critical`
+- `collapsed`
+
+每个阶段绑定不同惩罚：
+
+- 命中修正
+- 额外时间成本
+- 事件风险提升
+- 治疗效率下降
+- 逃跑成功率下降
+
+### 13.7.4 生命系统与 UI
+
+主 HUD 只显示数值和条形图还不够，应该同步显示：
+
+- 当前生存威胁
+- 原因解释
+- 恢复路径提示
+
+例如：
+
+- “脱水：口渴已压缩行动余量”
+- “疲劳：建议短休或回避高风险搜刮”
+
+## 13.8 战斗系统设计
+
+战斗不应该吞掉整个游戏，而应该是风险系统的一种表现。
+
+### 13.8.1 当前定位是对的
+
+当前仓库使用“距离 + 回合 + 动作选择”的轻量模式，这是合理的。
+
+### 13.8.2 下一步建议
+
+- 加入更清晰的命中区间提示
+- 加入武器与状态联动的解释文本
+- 区分“战斗结束”和“战后结算”两个阶段
+- 把战斗弹窗升级为更完整的战斗面板
+
+### 13.8.3 战斗生命周期
+
+1. 遭遇初始化
+2. 玩家选择动作
+3. 双方结算
+4. 更新距离与生命
+5. 写入战斗日志
+6. 判断胜负/逃跑
+7. 战后掉落与任务推进
+
+## 13.9 事件系统设计
+
+事件是废土题材最重要的内容增幅器。
+
+要求：
+
+- 事件必须能解释触发原因
+- 事件必须能绑定状态、物品、任务和地点条件
+- 事件必须能写出可追溯日志
+- 事件应该偏向“抉择”而不是“随机弹窗骚扰”
+
+## 13.10 在线存档设计
+
+作为账号制在线游戏，存档系统应被视为引擎的一部分。
+
+### 13.10.1 必须保证
+
+- 动作完成后立即得到权威新状态
+- 存档和视图状态保持一致
+- 任意时刻掉线后能恢复到最近稳定节点
+
+### 13.10.2 建议增加
+
+- 多存档槽
+- 存档版本迁移日志
+- 后端动作审计
+- 非法状态回滚策略
+
+## 13.11 当前代码层面的下一批重点
+
+1. 把 `engine.ts` 继续拆成子模块：
+   - `time-system`
+   - `inventory-system`
+   - `combat-system`
+   - `event-system`
+   - `quest-system`
+   - `view-projection`
+2. 为状态阈值、背包容量、战斗结算分别补单元测试
+3. 引入基地仓库与背包转移逻辑
+4. 为背包、任务、蓝图面板补筛选与分类
+5. 为状态系统引入更明确的阶段化惩罚定义
+
+## 13.12 结论
+
+真正像游戏的关键，不是把更多信息摆上屏，而是：
+
+- 明确主循环
+- 明确系统边界
+- 明确高频与低频交互分层
+- 明确权威状态和表现层职责
+
+这也是本轮把背包、任务、蓝图、日志转成系统弹窗的原因。主 HUD 应该负责“让玩家立刻决定下一步”，而完整系统面板负责“深入管理和规划”。
@@ -15,6 +15,8 @@
  - 数值平衡：[05-数值与经济.md](./05-%E6%95%B0%E5%80%BC%E4%B8%8E%E7%BB%8F%E6%B5%8E.md)
  - 交互与界面：[07-UX%E4%B8%8E%E7%95%8C%E9%9D%A2%E4%BF%A1%E6%81%AF%E6%9E%B6%E6%9E%84.md](./07-UX%E4%B8%8E%E7%95%8C%E9%9D%A2%E4%BF%A1%E6%81%AF%E6%9E%B6%E6%9E%84.md)
  - 技术实现：[08-技术架构与代码导读.md](./08-%E6%8A%80%E6%9C%AF%E6%9E%B6%E6%9E%84%E4%B8%8E%E4%BB%A3%E7%A0%81%E5%AF%BC%E8%AF%BB.md)、[09-存档与后端.md](./09-%E5%AD%98%E6%A1%A3%E4%B8%8E%E5%90%8E%E7%AB%AF.md)、[10-本地运行与发布.md](./10-%E6%9C%AC%E5%9C%B0%E8%BF%90%E8%A1%8C%E4%B8%8E%E5%8F%91%E5%B8%83.md)
+  - 前端 HUD 实现：[12-前端HUD架构与资产管线.md](./12-%E5%89%8D%E7%AB%AFHUD%E6%9E%B6%E6%9E%84%E4%B8%8E%E8%B5%84%E4%BA%A7%E7%AE%A1%E7%BA%BF.md)
+  - 运行时与核心系统深化：[13-运行时引擎与核心系统深化设计.md](./13-%E8%BF%90%E8%A1%8C%E6%97%B6%E5%BC%95%E6%93%8E%E4%B8%8E%E6%A0%B8%E5%BF%83%E7%B3%BB%E7%BB%9F%E6%B7%B1%E5%8C%96%E8%AE%BE%E8%AE%A1.md)
  - 测试与验收：[11-QA%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E4%B8%8E%E9%AA%8C%E6%94%B6%E6%B8%85%E5%8D%95.md](./11-QA%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E4%B8%8E%E9%AA%8C%E6%94%B6%E6%B8%85%E5%8D%95.md)

 ## 图与源文件
@@ -28,4 +30,3 @@
 - 时间推进：游戏内时间前进触发状态消耗、资源生长、事件刷新等。
 - 风险收益：一次出行/探索的收益（资源/信息）与风险（伤害/污染/时间消耗）之间的平衡。
 - 数据驱动：绝大多数内容由配置定义，代码仅提供通用规则与执行器。
-