diff --git a/docs/requirements/01-锤击形变与刀刃形成需求.md b/docs/requirements/01-锤击形变与刀刃形成需求.md new file mode 100644 index 0000000..7b5f81c --- /dev/null +++ b/docs/requirements/01-锤击形变与刀刃形成需求.md @@ -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) \ No newline at end of file diff --git a/docs/requirements/02-表面磨损与外观需求.md b/docs/requirements/02-表面磨损与外观需求.md new file mode 100644 index 0000000..602d1fa --- /dev/null +++ b/docs/requirements/02-表面磨损与外观需求.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) \ No newline at end of file diff --git a/docs/requirements/03-网格质量与性能需求.md b/docs/requirements/03-网格质量与性能需求.md new file mode 100644 index 0000000..13ee0e5 --- /dev/null +++ b/docs/requirements/03-网格质量与性能需求.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) \ No newline at end of file