virtheart
5c41eb410b
- 新增HUD图标、面板和状态指示器资产 - 实现HUD图标组件和错误边界组件 - 重构顶部状态栏和底部导航栏 - 更新路线面板样式和交互 - 添加HUD资产清单和切片脚本 - 移除未使用的资产文件 - 调整API安全配置和生产环境设置
179 lines
6.3 KiB
Markdown
179 lines
6.3 KiB
Markdown
# 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/item-atlas.png`：物资图集原图
|
||
- `apps/web/public/generated/ui/equipment-atlas.png`：装备图集原图
|
||
- `apps/web/public/generated/ui/status-atlas.png`：生存状态图集原图
|
||
- `apps/web/public/generated/ui/items/*`：切分后的物资图标
|
||
- `apps/web/public/generated/ui/equipment/*`：切分后的装备槽素材
|
||
- `apps/web/public/generated/ui/status/*`：切分后的生存状态图标
|
||
- `apps/web/public/generated/hud/reference/tinywaste-hud-reference.png`：当前唯一 HUD 参考图（无右侧人物）
|
||
- `apps/web/public/generated/hud/atlases/*`：HUD chrome / icon atlas 原图与透明版
|
||
- `apps/web/public/generated/hud/chrome/*`：切分后的 HUD 框体素材
|
||
- `apps/web/public/generated/hud/icons/*`：切分后的 HUD 功能图标
|
||
- `apps/web/public/generated/hud/manifest.json`：HUD 资产清单
|
||
|
||
对应映射入口：
|
||
|
||
- `apps/web/src/features/game/uiAssets.ts`
|
||
|
||
当前资产策略：
|
||
|
||
- 地点图使用整图背景，服务于中央场景和左侧路线卡。
|
||
- 物资与装备图使用 atlas + 裁切结果，服务于快捷栏、库存卡、角色槽位。
|
||
- 生存状态图使用 atlas + 裁切结果，服务于状态效果卡和后续中断提示。
|
||
- HUD chrome 与 HUD icon 统一走 `apps/web/public/generated/hud/`，并通过 `uiAssets.ts` 暴露。
|
||
- 所有引用都走 `uiAssets.ts`，避免组件里散落硬编码路径。
|
||
- HUD atlas 的透明化与切分流程由 `scripts/slice_hud_atlas.py` 和 `remove_chroma_key.py` 组合完成。
|
||
|
||
## 12.6 HUD 信息职责
|
||
|
||
### 12.6.1 TopHud
|
||
|
||
- 时间
|
||
- 生存状态条
|
||
- 风险标签
|
||
- 账号状态
|
||
|
||
### 12.6.2 RoutePanel
|
||
|
||
- 当前地点摘要
|
||
- 路线列表
|
||
- 风险强度
|
||
- 节点式世界图
|
||
|
||
### 12.6.3 CommandCenter
|
||
|
||
- 场景主视觉
|
||
- 行动矩阵
|
||
- 交易终端
|
||
- 实时日志
|
||
- 当前目标
|
||
- 蓝图视图
|
||
|
||
### 12.6.4 LoadoutPanel
|
||
|
||
- Equipment terminal 头部与负载状态
|
||
- 2x3 装备槽矩阵
|
||
- 生存能力指标（防护 / 潜行 / 机动）
|
||
- 生存告警条
|
||
- Ready pack 资源终端（快速补给 + 仓储摘要）
|
||
- 打开背包 / 仓储弹层入口
|
||
|
||
### 12.6.5 BottomDock
|
||
|
||
- 游戏化底部导航
|
||
- 当前角色标识
|
||
- 核心补给统计
|
||
|
||
## 12.7 当前与参考图的对齐策略
|
||
|
||
对齐的不是“像一张网站海报”，而是“像一套可操作的游戏终端”：
|
||
|
||
- 维持单屏阅读，整页不滚动，滚动只发生在内部面板。
|
||
- 中央区优先展示场景与决策，避免全文字堆叠。
|
||
- 右侧区不再展示人物立绘，改为装备、警报与资源终端。
|
||
- 底部区承担模式切换和系统导航，强化“游戏 HUD”心智。
|
||
- HUD chrome 资产只重点压在小模块和导航件上，大面板只保留轻量纹理，避免再次出现网页卡片感。
|
||
|
||
## 12.8 下一步扩展建议
|
||
|
||
下一轮优先项：
|
||
|
||
1. 继续补 GPT-image-2 资产：
|
||
- 第二批 HUD chrome（战斗态、事件态、模态终端）
|
||
- 天气、辐射、事件状态专用小图标
|
||
2. 为 `CommandCenter` 增加战斗专属视图和事件专属视图，而不是完全依赖弹层。
|
||
3. 为物资卡补充更精细的分类过滤和排序逻辑。
|
||
4. 引入可配置的 HUD 主题参数，支撑不同章节或区域切换皮肤。
|