Files

T

starmen1265 68f5f91a08 docs: 添加文档导航索引与 features 范围声明

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>

2026-08-11 08:58:58 +08:00

5.4 KiB

Raw Blame History

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/ 不动

5.4 KiB Raw Blame History