starmen1265
68f5f91a08
docs/README.md 作为顶层导航,提供阅读路径推荐(新人/策划/工程师/考古)、需求-设计对应表、边界约定、7 大子系统索引、性能目标。features/hammer-deformation-system.md 顶部加导航头,明确本文档为已交付功能说明,完整需求/设计见对应专题文档。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
BladeSmith 文档索引
BladeSmith 是基于 Unreal Engine 5.6 的真实打铁模拟游戏。本目录存放所有设计文档,按 需求侧(玩家/体验视角)与 设计侧(技术实现视角)分层组织。
项目概述见仓库根目录 README.md。
目录结构
docs/
├── README.md (本文件)
├── requirements/ 需求文档(玩家视角,无代码)
│ ├── 00-锻造系统总体需求.md
│ └── 01~07 专题需求
├── design/ 技术设计(算法/代码/性能)
│ ├── 00-锻造系统总体技术架构.md
│ └── 01~07 专题设计
├── features/ 已交付功能说明
│ └── hammer-deformation-system.md
├── impl/ 实施记录(Task 清单)
│ └── 2026-01-23-hammer-deformation-enhancement.md
├── tests/ 测试文档
│ └── hammer-deformation-test-results.md
└── _archive/plans/ 原始设计文档归档(2026-01 批次)
阅读路径
| 角色 | 推荐阅读顺序 |
|---|---|
| 新人了解项目 | requirements/00 → 各专题需求 → design/00 |
| 策划验收功能 | requirements/00 → 对应专题需求 → features/ 已交付功能 |
| 工程师实现 | design/00 → 对应专题设计 → impl/ 实施记录 |
| 考古(看历史决策) | _archive/plans/ 原始文档 |
需求/设计对应表
每个主题同时有"需求文档"(玩家可见行为)和"技术设计文档"(算法/代码),一一对应:
| # | 主题 | 需求文档 | 技术设计文档 |
|---|---|---|---|
| 00 | 总体 | requirements/00 | design/00 |
| 01 | 锤击形变 / 各向异性流动 | requirements/01 | design/01 |
| 02 | 表面磨损 / 无漂移采样 | requirements/02 | design/02 |
| 03 | 网格质量 / 增量式优化 | requirements/03 | design/03 |
| 04 | 加工硬化 / 晶粒演化 | requirements/04 | design/04 |
| 05 | 淬火退火相变 | requirements/05 | design/05 |
| 06 | 应力累积 / 开裂 | requirements/06 | design/06 |
| 07 | 疲劳 / 刀具耐久度 | requirements/07 | design/07 |
边界约定
为保证"需求"与"设计"清晰分离:
requirements/下严禁出现代码、UE 宏(UPROPERTY/UFUNCTION)、算法名(Laplacian/Sigmoid/PCA)、变量名、技术概念(Compute Shader/BVH/Ping-Pong)。只用玩家可感知的语言。design/下聚焦算法、公式、C++/HLSL 代码、数据结构、性能分析、调试工具。需求部分仅用 1-2 句话引用对应需求文档,不重复。features/是已交付能力的功能清单,供策划与 QA 验收。impl/是 Step-by-step 实施记录,供工程师追溯历史决策。_archive/是 2026-01 批次的原始设计文档(当时需求与设计混杂),保留作为决策考古用途,不再更新。
7 大玩家可见子系统
锻造系统要让玩家直观感知以下 7 类冶金学物理现象(详见 requirements/00 §3):
- 锤击形变与刀刃形成 — 材料优先沿最小阻力方向流动,边缘附近形成锐利刀刃
- 表面磨损与外观 — 锤击去锈、纹路随形变移动不漂移、大马士革花纹
- 网格质量(隐形) — 连续锻打 50+ 次后刀刃仍平整无锯齿
- 加工硬化与晶粒演化 — 越打越硬、加热软化、晶粒影响性能
- 淬火退火相变 — 温度区间+冷却速率共同决定硬度/脆性,三阶段可视化
- 应力累积与开裂 — 不均匀形变累积应力,超阈值产生裂纹,可弯曲/扭曲/断裂
- 疲劳与刀具耐久度 — 反复使用累积疲劳,刀具最终可失效
性能目标
| 指标 | 目标 |
|---|---|
| 锤击期间帧率 | 稳定 60 FPS |
| 单次锤击响应 | < 10 ms |
| 总锤击开销上限 | ≤ 7 ms |
| 单铁块顶点数 | 20-50 万(刀刃加密到 100 万/cm²) |
| 单铁块内存 | ~30 MB |
详细预算见 design/00 §6。
维护
- 新增需求 → 在
requirements/下新增文档,更新本 README 的对应表 - 新增技术决策 → 在
design/下新增或更新对应专题,在design/00的子系统映射表中登记 - 实施完成的 Task → 实施清单存入
impl/,功能说明存入features/ - 文档重组或重大调整 → 原 2026-01 批次文档保留在
_archive/plans/不动