docs: 添加玩家行为侧需求(锤击/表面磨损/网格质量)

三个对应玩家直接可见行为的需求文档。锤击形变涵盖各向异性流动与边缘平整;表面磨损涵盖铁锈脱落与无漂移;网格质量承诺连续锻打 50+ 次后无明显退化。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-08-11 08:58:06 +08:00
parent 4633e866ec
commit f31518d7e3
3 changed files with 515 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 锤击形变与刀刃形成需求
+
+**项目**: BladeSmith
+**文档类型**: 需求文档(专题)
+**版本**: 2.0
+**最后更新**: 2026-08-11
+**状态**: 整合自原 `2026-01-22-刀刃形成技术细节.md`
+
+> 本文档从玩家视角描述锤击形变与刀刃形成的需求。技术实现见 [design/01-刀刃形成-各向异性流动设计.md](../design/01-刀刃形成-各向异性流动设计.md)。总体需求见 [00-锻造系统总体需求.md](00-锻造系统总体需求.md)。
+
+---
+
+## 1. 玩家可见行为
+
+### 1.1 材料流动方向
+
+玩家用锤子敲击锻材时，材料会优先沿着"阻力最小的方向"流动，而不是均匀向四周扩散。
+
+在边缘附近锻打时，材料会沿着边缘方向延展，逐渐形成平整锐利的刀刃。这符合真实锻造的物理直觉。
+
+### 1.2 锻造过程可视化
+
+从玩家视角看，锻造刀刃的形变过程如下：
+
+```
+初始状态：圆柱形铁块
+███████████
+███████████
+
+第一次锻打：
+  ▼锤击
+███████████  ← 受击处变扁
+████████████  ← 材料向侧面流动
+
+多次锻打：
+  ██  ← 继续变薄
+██████
+███████████  ← 逐渐形成锥形
+
+最终成刃：
+   ▲   ← 边缘平整锐利
+ █████
+████████
+```
+
+关键视觉特征：材料优先沿着边缘方向流动（垂直于锤击方向 + 朝向边缘）。
+
+### 1.3 边缘平整效果
+
+锻造形成的刀刃应当保持平整锐利，而不是波浪状凸起：
+
+```
+理想边缘:      ▲
+              ████
+             ██████
+
+实际边缘:     ▲▲▲
+             ████
+            ██████  ← 波纹状（不理想）
+```
+
+玩家不应看到明显的波纹或不规则边缘。
+
+### 1.4 形变连续性
+
+连续锻打能逐步把铁块变形成目标形状。每次锤击的形变应当是连续的、可预测的，不会出现突变或奇怪形状。
+
+---
+
+## 2. 玩家可调参数
+
+| 参数功能名 | 默认值 | 范围 | 玩家感受 |
+|-----------|--------|------|---------|
+| 材料流动方向强度 | 3.0 | 1.0-10.0 | 控制材料沿边缘流动的程度。值越大，边缘拉伸越明显 |
+| 凸起高度强度 | 0.5 | 0.1-2.0 | 控制锤击处材料凸起的高度。需要配合影响半径调整 |
+| 锤击影响半径 | 5.0 | 1.0-20.0 | 单次锤击影响到的区域大小（单位：厘米） |
+| 边缘过渡平滑度 | 2.0 | 1.0-4.0 | 控制形变边界过渡的平滑程度。值越大，边界越锐利 |
+| 边缘平整约束开关 | 关闭 | 开启/关闭 | 是否启用边缘平整约束，保证刀刃锐利 |
+| 边缘检测范围 | 1.0 | 0.5-2.0 | 距离边界多少厘米内的顶点被视为边缘顶点 |
+
+### 推荐参数配置
+
+**锻造平面（打铁块顶面）**:
+- 材料流动方向强度 = 1.0（均匀流动）
+- 锤击影响半径 = 5.0 cm
+- 凸起高度强度 = 0.5
+- 边缘平整约束开关 = 关闭
+
+**锻造边缘（形成刀刃）**:
+- 材料流动方向强度 = 4.0（强方向性）
+- 锤击影响半径 = 3.0 cm（小范围）
+- 凸起高度强度 = 0.3（较小凸起）
+- 边缘平整约束开关 = 开启
+- 边缘检测范围 = 1.0 cm
+
+**精细整形（最后修整）**:
+- 材料流动方向强度 = 8.0（极端定向）
+- 锤击影响半径 = 1.5 cm（很小范围）
+- 凸起高度强度 = 0.1（微调）
+- 边缘平整约束开关 = 开启
+- 边缘检测范围 = 0.5 cm
+
+---
+
+## 3. 视觉/听觉反馈
+
+### 3.1 视觉反馈
+
+- **形变实时可见**: 锤击瞬间，受击处材料立即产生形变
+- **方向性流动**: 在边缘附近锻打时，玩家能清楚看到材料沿着边缘方向流动
+- **边缘锐利度**: 刀刃区域保持平整锐利，无明显波纹
+
+### 3.2 听觉反馈
+
+- **金属撞击声**: 锤击时发出真实的金属撞击声
+- **形变强度提示**: 不同形变程度可能伴随不同音效
+
+---
+
+## 4. 边界与限制(玩家不应期望的行为)
+
+### 4.1 形变限制
+
+- **极端形变**: 当边缘厚度 < 1mm 时，材料流动的假设可能失效，形变效果可能不符合直觉
+- **拓扑变化**: 当前系统无法处理网格撕裂或融合（如锻打折叠金属）
+- **复杂形状**: 对于叉状等复杂形状，方向检测可能不够准确
+
+### 4.2 不可达效果
+
+- 玩家不能期待系统支持"熔化后重新塑形"等超出现实锻造范围的行为
+- 系统不会自动"修复"玩家不当锻打造成的形状错误
+
+---
+
+## 5. 验收清单
+
+- [ ] 锤击处材料被压紧、向四周流动
+- [ ] 材料优先沿"最小阻力方向"流动（而非均匀扩散）
+- [ ] 在边缘附近锻打时，材料沿边缘延展，逐渐形成平整锐利的刀刃
+- [ ] 连续锻打能逐步把铁块变形成目标形状
+- [ ] 刀刃边缘平整锐利，无明显波纹（锯齿长宽比不超过 10:1）
+- [ ] 形变实时可见，无延迟
+- [ ] 锤击期间帧率稳定 60 FPS
+- [ ] 玩家能通过调整参数控制材料流动方向强度
+- [ ] 边缘平整约束功能可有效改善边缘质量
+
+---
+
+## 6. 引用
+
+- 对应技术设计: [../design/01-刀刃形成-各向异性流动设计.md](../design/01-刀刃形成-各向异性流动设计.md)
+- 总体需求: [00-锻造系统总体需求.md](00-锻造系统总体需求.md)
+- 原始设计文档(归档): [../_archive/plans/2026-01-22-刀刃形成技术细节.md](../_archive/plans/2026-01-22-刀刃形成技术细节.md)
@@ -0,0 +1,183 @@
+# 表面磨损与外观需求
+
+**项目**: BladeSmith
+**文档类型**: 需求文档(专题)
+**版本**: 2.0
+**最后更新**: 2026-08-11
+**状态**: 整合自原 `2026-01-22-表面磨损系统细节.md`
+
+> 本文档从玩家视角描述表面磨损与外观的需求。技术实现见 [design/02-表面磨损-顶点属性与无漂移采样设计.md](../design/02-表面磨损-顶点属性与无漂移采样设计.md)。总体需求见 [00-锻造系统总体需求.md](00-锻造系统总体需求.md)。
+
+---
+
+## 1. 玩家可见行为
+
+### 1.1 表面状态变化
+
+锻材的表面状态会随锻造过程自然演变：
+
+- **新铁块**: 表面是生锈/氧化层，颜色呈橙红色，表面粗糙
+- **锤击区域**: 铁锈脱落，露出光亮金属本体
+- **金属光泽**: 打磨后金属度增加（从哑光到镜面），粗糙度降低
+- **表面状态**: 支持铁锈、氧化层、酸蚀痕迹、划痕等多种表面状态
+
+### 1.2 铁锈的物理特性（玩家可感知）
+
+真实铁锈层的视觉特征：
+
+| 特性 | 表现 | 玩家可感知度 |
+|------|------|------------|
+| 厚度 | 0.1-2mm（可视严重程度） | 厚铁锈显得更深色、更粗糙 |
+| 成分 | 红锈、黑锈混合 | 颜色从橙红到深褐 |
+| 附着强度 | 低，易被机械摩擦去除 | 锤击时铁锈容易脱落 |
+| 颜色 | 橙红到深褐 | 不同锈蚀程度颜色不同 |
+| 粗糙度 | 高（微观凹凸不平） | 表面摸起来粗糙不平 |
+
+锻造去锈原理（玩家可见）：
+- 锤击压力产生摩擦力，铁锈层破碎脱落
+- 塑性形变暴露新鲜金属表面
+- 高温时部分氧化层会还原
+
+### 1.3 表面特征跟随性（关键要求）
+
+**表面特征必须随形变一起移动，不能"漂移"或"贴在屏幕上"。**
+
+这是玩家最容易察觉的问题：
+- 铁锈图案应该"锁定"在材料上，随材料一起移动
+- 锻打前某个位置的铁锈，锻打后仍应在该材料部位（只是位置随形变改变）
+- 不能出现铁锈"滑走"或原地消失又突然出现的情况
+
+正确行为示例：
+```
+锻打前:  位置A有铁锈（表面颜色深）
+锻打后:  位置A移动到新位置B，铁锈仍在该材料部位
+```
+
+错误行为示例（玩家会感到不自然）：
+```
+锻打前:  位置A有铁锈
+锻打后:  位置A移动了，但铁锈还在原地（漂移）
+        或铁锈突然消失（表面颜色变亮）
+```
+
+### 1.4 高级表面效果
+
+#### 大马士革花纹
+
+支持大马士革钢的层状花纹：
+- 高碳钢层：深色
+- 低碳钢层：浅色
+- 层状分布：基于材料结构
+
+#### 划痕系统
+
+表面可见方向性划痕：
+- 沿着锤击方向的划痕
+- 划痕在未打磨区域更明显
+- 划痕影响表面粗糙度和反光
+
+#### 水渍和氧化
+
+淬火时的水渍痕迹：
+- 蓝绿色氧化色调
+- 油渍、灰尘等表面污渍
+- 时间累积的氧化层变化
+
+---
+
+## 2. 玩家可调参数
+
+| 参数功能名 | 默认值 | 范围 | 玩家感受 |
+|-----------|--------|------|---------|
+| 铁锈粗糙度 | 0.9 | 0.5-1.0 | 铁锈表面的粗糙程度。值越大，铁锈越粗糙 |
+| 金属粗糙度 | 0.2 | 0.1-0.5 | 打磨后金属表面的粗糙程度。值越小，金属越光滑 |
+| 铁锈基色 | (0.6, 0.3, 0.1) | RGB颜色 | 铁锈的基本颜色 |
+| 金属基色 | (0.8, 0.8, 0.85) | RGB颜色 | 金属本体（钢材）的颜色 |
+| 铁锈金属度 | 0.0 | 0.0-0.3 | 铁锈的金属反射程度。0为完全不反光 |
+| 金属金属度 | 1.0 | 0.8-1.0 | 打磨后金属的反射程度。1为完全反光 |
+| 大马士革图层开关 | 关闭 | 开启/关闭 | 是否启用大马士革层状花纹 |
+
+### 推荐参数配置
+
+**新铁块（完全生锈）**:
+- 铁锈粗糙度 = 0.95
+- 金属粗糙度 = 0.15
+- 铁锈基色 = 橙红色 (0.7, 0.35, 0.15)
+- 金属基色 = 钢铁色 (0.75, 0.75, 0.8)
+
+**半旧铁块（部分打磨）**:
+- 铁锈粗糙度 = 0.85
+- 金属粗糙度 = 0.25
+- 铁锈基色 = 深褐色 (0.5, 0.25, 0.1)
+- 金属基色 = 亮钢铁色 (0.8, 0.8, 0.85)
+
+**高碳钢（大马士革）**:
+- 铁锈粗糙度 = 0.9
+- 金属粗糙度 = 0.2
+- 铁锈基色 = 深色层 (0.3, 0.15, 0.1)
+- 金属基色 = 浅色层 (0.6, 0.55, 0.5)
+- 大马士革图层开关 = 开启
+
+---
+
+## 3. 视觉/听觉反馈
+
+### 3.1 视觉反馈
+
+- **实时表面变化**: 锤击时，受击区域铁锈实时脱落，露出金属光泽
+- **颜色渐变**: 从生锈的橙红色 → 打磨后的钢灰色，颜色过渡自然
+- **粗糙度变化**: 从粗糙的哑光表面 → 平滑的金属表面，视觉质感明显
+- **金属反光**: 打磨后表面能反射环境光，有真实的金属质感
+
+### 3.2 表面细节
+
+- **铁锈图案**: 随机的铁锈斑块分布，自然不重复
+- **划痕细节**: 方向性划痕，增加真实感
+- **氧化层**: 蓝绿色调的氧化痕迹
+- **水渍**: 淬火后可见的水渍图案
+
+### 3.3 听觉反馈
+
+- **摩擦声**: 锤击时金属与金属的摩擦声
+- **铁锈脱落声**: 可选的铁锈破碎声效
+
+---
+
+## 4. 边界与限制(玩家不应期望的行为)
+
+### 4.1 表面细节限制
+
+- **顶点密度瓶颈**: 当前系统使用顶点属性存储表面状态，细节程度受限于网格密度（20-50万顶点）
+- **无物理反射**: 打磨效果通过粗糙度模拟，无法达到光线追踪级别的真实反射
+- **纹理细节**: 表面细节（铁锈图案、划痕）是程序化生成的，不是真实纹理贴图
+
+### 4.2 不可达效果
+
+- 玩家不能期待系统支持"油污涂层"、"漆面"等超出锻造范围的表面处理
+- 系统不会模拟"长期户外氧化"等时间跨度极大的效果
+- 表面特征跟随性依赖于顶点属性，极端形变时可能出现轻微不连续
+
+---
+
+## 5. 验收清单
+
+- [ ] 锤击后表面从"生锈"变"光亮"，露出金属本体
+- [ ] 金属度从 0.0 增加到 1.0（可视化）
+- [ ] 粗糙度从 0.9 降低到 0.2（可视化）
+- [ ] 支持铁锈、氧化层、酸蚀痕迹、划痕等多种表面状态
+- [ ] **表面特征随形变一起移动，无漂移现象**（关键验收点）
+- [ ] 铁锈图案自然不重复，空间连续
+- [ ] 支持大马士革钢的层状花纹（可选）
+- [ ] 支持方向性划痕效果（可选）
+- [ ] 支持水渍和氧化痕迹（可选）
+- [ ] 锤击期间帧率稳定 60 FPS
+- [ ] 玩家能通过调整参数控制铁锈颜色、粗糙度等外观
+- [ ] 不同材质（新铁块、半旧、高碳钢）有明显的视觉差异
+
+---
+
+## 6. 引用
+
+- 对应技术设计: [../design/02-表面磨损-顶点属性与无漂移采样设计.md](../design/02-表面磨损-顶点属性与无漂移采样设计.md)
+- 总体需求: [00-锻造系统总体需求.md](00-锻造系统总体需求.md)
+- 原始设计文档(归档): [../_archive/plans/2026-01-22-表面磨损系统细节.md](../_archive/plans/2026-01-22-表面磨损系统细节.md)
@@ -0,0 +1,179 @@
+# 网格质量与性能需求
+
+**项目**: BladeSmith
+**文档类型**: 需求文档(专题)
+**版本**: 2.0
+**最后更新**: 2026-08-11
+**状态**: 整合自原 `2026-01-22-网格质量优化细节.md`
+
+> 本文档从玩家视角描述网格质量与性能的需求。技术实现见 [design/03-网格质量-增量式优化设计.md](../design/03-网格质量-增量式优化设计.md)。总体需求见 [00-锻造系统总体需求.md](00-锻造系统总体需求.md)。
+
+---
+
+## 1. 玩家可见行为
+
+### 1.1 正常网格质量
+
+玩家应该看不到网格退化现象。连续锻打后，金属表面应当保持平滑、连续，不会出现奇怪形状。
+
+```
+初始均匀网格（良好，玩家看不见网格，只看到平滑表面）：
+  /\  /\  /\
+ /__\/__\/__\
+  /\  /\  /\
+ /__\/__\/__\
+```
+
+### 1.2 网格退化现象（玩家不应看到）
+
+如果网格质量下降，玩家会直接感受到以下问题：
+
+#### 视觉影响
+
+| 现象 | 玩家感受 | 严重度 |
+|------|---------|--------|
+| 着色异常 | 表面出现条纹、色块 | 高 |
+| 闪烁问题 | 出现"空洞"或闪烁 | 高 |
+| 边缘锯齿 | 刀刃呈锯齿状不平整 | 高 |
+| 法线扭曲 | 表面反光不自然 | 中 |
+
+```
+锤击后网格退化（玩家看到的是视觉缺陷）：
+  /\    /|\    /\  ← 细长三角形导致条纹
+ /__\  /_|_\  /__\
+
+     ^^ 过小 ^^  ← 极小三角形导致闪烁
+```
+
+#### 性能影响
+
+| 现象 | 玩家感受 | 严重度 |
+|------|---------|--------|
+| 帧率下降 | 锤击时掉帧，操作延迟 | 高 |
+| 响应变慢 | 锤击到形变有明显延迟 | 高 |
+| 碰撞检测失效 | 锤击检测不准确，"打空" | 高 |
+
+#### 数值稳定性问题（影响碰撞）
+
+| 现象 | 玩家感受 | 严重度 |
+|------|---------|--------|
+| 浮点误差累积 | 形变计算不准确 | 中 |
+| 碰撞检测不稳定 | 锤击位置判定错误 | 高 |
+
+### 1.3 玩家承诺
+
+**连续锻打 50-100 次后，网格质量仍应保持良好。**
+
+具体表现为：
+- 刀刃仍然平整，无明显锯齿
+- 表面着色无条纹、无闪烁、无"空洞"
+- 锻打不会让金属"莫名其妙"地出现奇怪形状
+- 锤击响应时间 < 10ms（玩家不可察觉）
+- 锤击期间帧率稳定 60 FPS
+
+---
+
+## 2. 玩家可调参数
+
+| 参数功能名 | 默认值 | 范围 | 玩家感受 |
+|-----------|--------|------|---------|
+| 自动网格优化开关 | 开启 | 开启/关闭 | 是否自动优化网格质量 |
+| 优化区域范围倍数 | 1.5 | 1.0-2.0 | 锤击影响区域的多少倍范围会被优化 |
+| 边缘过渡平滑强度 | 0.5 | 0.1-1.0 | 控制顶点平滑的强度。值越大，表面越平滑 |
+| 平滑迭代次数 | 2 | 1-5 | 平滑操作的重复次数。次数越多，效果越好但越慢 |
+| 重网格频率 | 5 | 3-20 | 每几次锤击执行一次完整重网格。值越小质量越好但越慢 |
+| 平滑优化总耗时预算 | 2.0 | 1.0-5.0 | 单次锤击的网格优化时间预算（毫秒） |
+
+### 推荐参数配置
+
+**锻造平面（大范围形变）**:
+- 优化区域范围倍数 = 2.0（大范围优化）
+- 边缘过渡平滑强度 = 0.5
+- 平滑迭代次数 = 2
+- 重网格频率 = 10（低频重网格）
+
+**锻造边缘（精细形变）**:
+- 优化区域范围倍数 = 1.2（局部优化）
+- 边缘过渡平滑强度 = 0.5
+- 平滑迭代次数 = 3
+- 重网格频率 = 5（高频重网格）
+
+**性能优先模式**:
+- 优化区域范围倍数 = 1.0
+- 边缘过渡平滑强度 = 0.3
+- 平滑迭代次数 = 1
+- 重网格频率 = 20（极低频重网格）
+
+### 自动调参
+
+系统会根据当前帧率自动调整优化强度：
+- **帧率低（< 30 FPS）**: 降低优化频率，扩大优化区域
+- **帧率高（> 55 FPS）**: 提高优化质量，增加优化频率
+
+---
+
+## 3. 视觉/听觉反馈
+
+### 3.1 视觉反馈
+
+- **平滑形变**: 网格优化是透明的，玩家只看到平滑的形变
+- **无闪烁**: 表面不会出现闪烁或空洞
+- **无条纹**: 表面颜色连续，无明显条纹或色块
+
+### 3.2 性能反馈
+
+- **响应迅速**: 锤击到形变响应时间 < 10ms
+- **帧率稳定**: 锤击期间帧率保持 60 FPS
+
+### 3.3 调试模式（可选）
+
+开发者可启用调试视图：
+- **退化三角形热图**: 显示网格质量低下的区域（红色）
+- **质量热图**: 显示网格质量分布（蓝色=好，红色=差）
+- **性能统计**: 显示每次锤击的优化耗时
+
+---
+
+## 4. 边界与限制(玩家不应期望的行为)
+
+### 4.1 网格质量限制
+
+- **极端形变**: 当形变超过 50% 时，优化效果显著下降，玩家可能看到表面质量下降
+- **拓扑变化**: 系统无法处理网格撕裂、融合等拓扑变化（如锻打折叠金属）
+- **细节损失**: 重网格化时，顶点属性需要插值，可能有轻微精度损失
+
+### 4.2 性能限制
+
+- **内存占用**: 高网格密度（100万+顶点）会增加内存占用
+- **硬件依赖**: 低端硬件可能需要降低重网格频率或优化质量
+
+### 4.3 不可达效果
+
+- 玩家不能期待系统支持"无限形变"而不产生网格质量下降
+- 系统不会在低端硬件上保持 60 FPS（需要自动降低质量）
+- 网格优化是自动的，玩家不能手动控制每个顶点的移动
+
+---
+
+## 5. 验收清单
+
+- [ ] 连续锻打 50 次后网格质量仍良好
+- [ ] 无明显细长三角形（长宽比 > 10:1）
+- [ ] 刀刃边缘无明显锯齿
+- [ ] 表面着色无条纹、无闪烁、无"空洞"
+- [ ] 锻打不会让金属"莫名其妙"地出现奇怪形状
+- [ ] 锤击响应时间 < 10ms（玩家不可察觉）
+- [ ] 锤击期间帧率稳定 60 FPS
+- [ ] 网格优化过程透明，不影响形变视觉效果
+- [ ] 玩家能通过调整参数控制优化强度和频率
+- [ ] 系统能根据帧率自动调整优化设置
+- [ ] 单次锤击总耗时（形变+优化）≤ 7ms
+- [ ] 碰撞检测稳定，不会出现"打空"或检测错误
+
+---
+
+## 6. 引用
+
+- 对应技术设计: [../design/03-网格质量-增量式优化设计.md](../design/03-网格质量-增量式优化设计.md)
+- 总体需求: [00-锻造系统总体需求.md](00-锻造系统总体需求.md)
+- 原始设计文档(归档): [../_archive/plans/2026-01-22-网格质量优化细节.md](../_archive/plans/2026-01-22-网格质量优化细节.md)