# 锤击形变系统(已交付功能说明)

> 本文档是锤击形变系统的**功能交付说明**,描述已实现的能力、参数与使用方法。
> 完整需求见 [requirements/01-锤击形变与刀刃形成需求.md](../requirements/01-锤击形变与刀刃形成需求.md);
> 完整技术设计见 [design/01-刀刃形成-各向异性流动设计.md](../design/01-刀刃形成-各向异性流动设计.md)。

## 概述

实现高真实度的锻造锤击形变，支持各向异性材料流动、边缘约束、表面磨损和网格质量维护。

## 架构

### 混合体素-顶点架构
- **体素层**: 存储全局物理场（温度、塑性系数）
- **顶点层**: 存储局部材料历史（应变、硬度、打磨度）

### 技术栈
- Unreal Engine 5.6 C++
- GeometryScripting API
- DynamicMesh3
- 自定义顶点属性系统

## 参数说明

### 材料属性

| 参数 | 类型 | 默认值 | 范围 | 说明 |
|------|------|--------|------|------|
| `FalloffExponent` | float | 2.0 | - | 控制边缘过渡的平滑度 |
| `BulgeRatio` | float | 0.8 | - | 凸起区域半径相对于压缩区域的倍数 |
| `BulgeStrength` | float | 0.5 | - | 凸起高度强度 |
| `AnisotropyRatio` | float | 3.0 | 1.0-10.0 | 各向异性比，控制材料流动方向性 |

**AnisotropyRatio 使用指南:**
- `1.0` = 均匀流动（锻造平面）
- `3.0-5.0` = 方向性流动（锻造边缘）
- `8.0-10.0` = 极端定向（精细整形）

### 边缘约束

| 参数 | 类型 | 默认值 | 范围 | 说明 |
|------|------|--------|------|------|
| `bEnableEdgeConstraint` | bool | false | - | 是否启用边缘平整约束 |
| `EdgeThreshold` | float | 0.5 | 0.1-5.0 | 边缘检测阈值（cm） |

### 性能

| 参数 | 类型 | 默认值 | 范围 | 说明 |
|------|------|--------|------|------|
| `bEnableAdaptiveOptimization` | bool | true | - | 自适应优化开关 |
| `MinSmoothingInterval` | float | 0.1 | 0.0-1.0 | 最小平滑间隔（秒） |

## 使用方法

### 基础锤击

```cpp
IronBlock->OnHammerImpact(
    HitLocation,      // 锤击位置（世界坐标）
    HitNormal,        // 锤击法线
    5.0f,            // 影响半径（cm）
    2.0f,            // 形变深度（cm）
    1.0f             // 锤击力度（0-1）
);
```

### 调试工具

```cpp
// 可视化材料流动方向
IronBlock->DebugDrawFlowDirections();

// 可视化边缘顶点
IronBlock->DebugDrawEdgeVertices();

// 输出顶点属性统计
IronBlock->DebugPrintVertexAttributes();
```

## 顶点属性系统

每个顶点存储以下属性:

| 属性 | 类型 | 说明 |
|------|------|------|
| `InitialPositionsArray` | `TArray<FVector3f>` | 初始位置，用于无漂移纹理采样 |
| `AccumulatedStrainArray` | `TArray<float>` | 累积塑性应变，记录形变历史 |
| `HardnessCoefficientArray` | `TArray<float>` | 硬度系数（预留，阶段3使用） |
| `PolishAmountArray` | `TArray<float>` | 打磨度，0=生锈，1=光亮 |

## 性能指标

| 指标 | 目标值 |
|------|--------|
| 单次锤击响应时间 | <10ms |
| 支持顶点数 | 20-50万 |
| 稳定帧率 | 60 FPS @ 连续锤击 |

## 验收标准

- [x] 各向异性材料流动正常工作
- [x] 锤击后表面颜色变化（铁锈→金属）
- [x] 边缘约束保持刀刃平整
- [x] 连续锤击100次网格质量良好
- [x] 性能达标，60 FPS稳定

## 核心算法

### 各向异性距离计算

```cpp
// 主方向的"有效距离"更小（更容易到达）→ 凸起更大
float EffectiveDistance = FMath::Sqrt(
    FMath::Square(DistAlongPrimary / AnisotropyRatio) +
    FMath::Square(DistAlongSecondary)
);
```

### Laplacian 平滑

```cpp
// 平滑更新: 新位置 = 原位置 + Alpha * (Laplacian - 原位置)
FVector3d SmoothPos = FMath::Lerp(VertexPos, Laplacian, Alpha);
```

## 调试技巧

1. **使用可视化工具**: 调用 `DebugDrawFlowDirections()` 和 `DebugDrawEdgeVertices()` 在视口中查看调试信息
2. **检查属性统计**: 调用 `DebugPrintVertexAttributes()` 查看顶点属性的统计信息
3. **调整参数**: 在编辑器中实时调整 `AnisotropyRatio` 和其他参数以观察效果

## 已知限制

1. 顶点属性使用简单数组存储，不支持网格拓扑变化（顶点ID改变）
2. 边缘约束使用简化算法，可能不适用于复杂几何形状
3. 自适应优化基于简单的时间间隔，未考虑实际负载

## 未来扩展

- **阶段2**: 硬度系数影响形变阻力
- **阶段3**: 材料疲劳和裂纹系统
- **阶段4**: 多锤叠加效果优化