# CLAUDE.md

> **💡 会话管理提示**: 开始新任务前,建议使用 `/rename <名称>` 命令命名当前会话。
> - 使用 `/session-namer` 技能获取会话命名帮助
> - 使用 `/resume <名称>` 恢复历史会话
> - 使用 `/continue` 查看最近会话列表

本文件提供 Claude Code (claude.ai/code) 在此仓库中工作的指导。

## 项目概述

**BladeSmith** 是一款虚幻引擎 5.6 C++ 铁匠模拟游戏，玩家通过真实的物理过程锻造刀剑武器。核心特性是使用计算着色器实现 GPU 加速的金属塑性形变，结合基于体素的温度系统来决定材料塑性。

**引擎版本**: UE 5.6
**语言**: C++ + Blueprint 混合开发
**开发平台**: Windows
**目标帧率**: 60 FPS

## 核心设计原则

### 游戏娱乐级精度
- 简化物理模型，保持真实感，同时确保 60 FPS 性能
- 参考真实冶金学原理，但使用经验公式替代复杂计算

### 渐进式实现
- 分阶段开发，每阶段可独立运行和验收
- 阶段 1: 各向异性形变 + 表面磨损 + 网格质量（已完成）
- 阶段 2: 淬火退火相变系统（规划中）
- 阶段 3: 应力累积系统（规划中）
- 阶段 4: 疲劳累积与耐久度系统（规划中）

### 混合体素-顶点架构
- **体素层**: 存储全局物理场（温度、冷却速率、相态）
- **顶点层**: 存储局部材料历史（应变、硬度、打磨度、疲劳）

## 构建与开发

### 编译项目

```bash
# 从 UE5 引擎目录编译游戏目标
"C:\Program Files\Epic Games\UE_5.6\Engine\Build\BatchFiles\Build.bat" BladeSmith Win64 Development "E:\MiceCola\work\BladeSmith\BladeSmith.uproject"

# 或编译编辑器目标
"C:\Program Files\Epic Games\UE_5.6\Engine\Build\BatchFiles\Build.bat" BladeSmithEditor Win64 Development "E:\MiceCola\work\BladeSmith\BladeSmith.uproject"
```

或在 Visual Studio 中打开 `BladeSmith.sln` 编译。

### 运行项目

1. 在 UE5.6 编辑器中打开 `BladeSmith.uproject`
2. 按 Alt+P 或点击 Play 按钮在编辑器中运行
3. 使用 Ctrl+F11 进行 C++ 代码修改后的热重载

### 测试

UE5 使用自动化系统进行测试：
- **编辑器内**: Window → Developer Tools → Automation Sessions
- **命令行**: `UE5Editor.exe BladeSmith.uproject -ExecCmds="Automation RunTests"`

## 架构概览

### 核心系统

```
ABladeSmithCharacter (玩家)
  └── UBladeSmithWeaponComponent (锤子工具)
        └── OnHammerImpact()
              └── ADynamicIronBlock (铁块工件)
                    ├── 温度体素网格
                    ├── 顶点属性数组
                    │   ├── InitialPositionsArray
                    │   ├── AccumulatedStrainArray
                    │   ├── HardnessCoefficientArray
                    │   └── PolishAmountArray
                    ├── 动态网格
                    │   ├── 各向异性流动方向
                    │   ├── 边缘约束
                    │   └── Laplacian 平滑
                    └── MiceShaders 计算着色器
```

### 锤击到形变的数据流

1. 玩家挥动锤子 (`UBladeSmithWeaponComponent::SwingHammer()`)
2. 射线检测命中 `ADynamicIronBlock`
3. `OnHammerImpact()` 接收: 位置、法线、半径、深度、力度
4. **计算材料流动方向** (各向异性)
   - `FindNearestFreeEdgeDirection()` - 查找最近边缘
   - `CalculatePrimaryFlowDirection()` - 计算主流动方向
   - `CalculateSecondaryFlowDirection()` - 计算次流动方向
5. 从温度体素采样塑性系数
6. 应用塑性形变到网格顶点
   - **各向异性距离计算** - 材料沿主方向更容易流动
   - **更新顶点属性** - 累积应变、打磨度
7. **边缘约束** (如果启用) - `ApplyEdgeLinearConstraint()`
8. **Laplacian 平滑** - `ApplyLaplacianSmoothing()` (自适应)
9. 重新计算网格法线
10. 更新顶点颜色 (温度 × 打磨度)
11. GPU 计算着色器更新温度分布 (如果启用)

### 关键类和关系

| 类 | 文件 | 用途 |
|---|---|---|
| `ADynamicIronBlock` | [DynamicIronBlock.h](Source/BladeSmith/DynamicIronBlock.h) | 动态铁块，支持各向异性形变 |
| `FTemperatureVoxel` | [DynamicIronBlock.h:14-35](Source/BladeSmith/DynamicIronBlock.h) | 温度体素结构 |
| `UBladeSmithWeaponComponent` | [BladeSmithWeaponComponent.h](Source/BladeSmith/BladeSmithWeaponComponent.h) | 第一人称锤子工具 |
| `ABladeSmithCharacter` | [BladeSmithCharacter.h](Source/BladeSmith/BladeSmithCharacter.h) | 玩家角色 |

## 模块依赖

**BladeSmith 模块** [Source/BladeSmith/BladeSmith.Build.cs](Source/BladeSmith/BladeSmith.Build.cs):

```cpp
PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject",
    "Engine",
    "InputCore",
    "GeometryScriptingCore",     // 动态网格操作
    "GeometryFramework",          // 几何框架
    "DynamicMesh",                // FDynamicMesh3
    "GeometryCore",               // 几何算法
    "GeometryAlgorithms",         // 几何算法库
    "ModelingComponents",         // 建模组件
    "RenderCore",                 // 渲染核心
    "RHI",                        // 渲染硬件接口
    "Renderer",                   // 渲染器
    "PhysicsCore",                // 物理核心
    "EnhancedInput",              // 增强输入系统
    "AudioExtensions",
    "AudioMixer",
    "AudioPlatformConfiguration",
    "MiceShaders"                 // 自定义计算着色器插件
});
```

## 代码规范

### 文件头

所有源文件必须以 Epic 版权声明开头（UE5 许可要求）。

### 命名规范

| 类型 | 命名 | 示例 |
|---|---|---|
| Actors | `A` 前缀 + PascalCase | `ADynamicIronBlock` |
| Components | `U` 前缀 + PascalCase | `UBladeSmithWeaponComponent` |
| Structs | `F` 前缀 + PascalCase | `FTemperatureVoxel` |
| Enums | `E` 前缀 + PascalCase | `EPhaseState` |
| Functions | PascalCase | `OnHammerImpact()` |
| Variables | PascalCase (属性), camelCase (局部) | `BoxSize`, `localHitPos` |
| Constants | PascalCase | `ForgeTemperatureMin` |

### 类型使用

- 使用 UE5 类型: `TArray<T>`, `TMap<K,V>`, `TSet<T>`, `FVector`, `FString`, `int32`, `uint8`
- 使用 `float` (而非 `double`)
- 智能指针: 依赖 UObject 垃圾回收；非 UObjects 使用 `TSharedPtr<T>`
- 字符串字面量: 使用 `TEXT()` 宏

### 缩进和格式

- **4 空格** 缩进（不使用制表符）
- **Allman 风格大括号**（左大括号另起一行）
- 行长度限制 120 字符

### 线程和 GPU 操作

```cpp
// 线程安全标志（用于 GPU 缓冲区状态）
std::atomic<bool> bGPUBuffersReady{false};

// 渲染线程命令
ENQUEUE_RENDER_COMMAND(CommandName)(
    [Params](FRHICommandListImmediate& RHICmdList)
    {
        // GPU 操作
    }
);
```

### 注释

- 中文注释用于领域特定逻辑（如 "锤击组件", "温度体素结构"）
- 英文注释用于通用算法和标准库使用

## 顶点属性系统

### 数据结构

每个顶点存储以下属性 (使用简单数组，索引与顶点 ID 对应):

| 属性 | 类型 | 说明 | 用途 |
|---|---|---|---|
| `InitialPositionsArray` | `TArray<FVector3f>` | 初始局部位置 | 无漂移纹理采样 |
| `AccumulatedStrainArray` | `TArray<float>` | 累积塑性应变 | 记录形变历史 |
| `HardnessCoefficientArray` | `TArray<float>` | 硬度系数 (0-1) | 影响形变阻力 |
| `PolishAmountArray` | `TArray<float>` | 打磨度 (0-1) | 0=生锈，1=光亮 |

### 顶点颜色编码

顶点颜色 (RGBA) 通道分配:

| 通道 | 用途 | 范围 | 更新频率 |
|---|---|---|---|
| **R** | 温度可视化 | 0-1 | 每帧 |
| **G** | 打磨度 | 0-1 | 锤击时 |
| **B** | 噪声种子 | 0-1 | 初始化 |
| **A** | 硬度/应变 | 0-1 | 锤击时 |

## 锤击形变参数

### 材料属性

| 参数 | 默认值 | 范围 | 说明 |
|---|---|---|---|
| `FalloffExponent` | 2.0 | - | 控制边缘过渡平滑度 |
| `BulgeRatio` | 0.8 | - | 凸起半径/压缩半径比 |
| `BulgeStrength` | 0.5 | - | 凸起高度强度 |
| `AnisotropyRatio` | 3.0 | 1.0-10.0 | 各向异性比 |

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

### 边缘约束

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

### 性能

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

## 温度-塑性关系

- **塑性 = 0**: 温度 < `ForgeTemperatureMin` (800°C)
- **塑性 = 1**: 温度 > `ForgeTemperatureMax` (1200°C)
- **线性插值**: 介于最小和最大温度之间
- **形变深度**: 乘以塑性系数

## 性能目标

| 指标 | 目标值 |
|---|---|
| 单次锤击响应时间 | <10ms |
| 支持顶点数 | 20-50 万 |
| 稳定帧率 | 60 FPS @ 连续锤击 |
| 体素分辨率 | 50×50×50 (可配置) |

## 内存预算

| 数据 | 大小 | 说明 |
|---|---|---|
| 网格顶点 (20万) | ~13.6 MB | 68 字节/顶点 |
| 网格三角形 (40万) | ~4.8 MB | 3×4 字节索引 |
| BVH 结构 | ~5 MB | 加速结构 |
| 温度体素 (50³) | ~0.3 MB | 24 字节/体素 |
| GPU 缓冲区 | ~2 MB | Ping-Pong 温度缓冲 |
| **单铁块总计** | **~26 MB** | 可接受 |

## 自定义计算着色器插件

### 位置

[Plugins/MiceShaders/](Plugins/MiceShaders/)

### 着色器文件

- **HLSL**: `Shaders/Private/*.usf`
- **C++**: `Source/MiceShaders/Private/*.cpp`

### 现有着色器

| 着色器 | 文件 | 用途 |
|---|---|---|
| `FDeformComputeShader` | DeformComputeShader.usf | 塑性形变计算 |
| `FTemperatureComputeShader` | TemperatureComputeShader.usf | 热传导和冷却 |

### 添加新计算着色器

1. 在 `Plugins/MiceShaders/Source/MiceShaders/Public|Private/` 创建 `.h` 和 `.cpp`
2. 在 `Plugins/MiceShaders/Shaders/Private/` 创建对应 `.usf` HLSL 着色器
3. 使用 `IMPLEMENT_GLOBAL_SHADER()` 宏注册
4. 通过 RDG 在 Actor 的 Tick 或专用函数中调度

## UE5 模式使用

### 动态网格编辑

```cpp
DynamicMesh->EditMesh([&](FDynamicMesh3& EditMesh)
{
    // 修改网格顶点/三角形
}, EDynamicMeshChangeType::GeneralEdit);
```

### 材质参数更新

```cpp
DynamicMaterialInstance->SetScalarParameterValue(TEXT("AvgTemperature"), AvgTemp);
DynamicMaterialInstance->SetVectorParameterValue(TEXT("Color"), FLinearColor(R,G,B,A));
```

### 增强输入绑定

```cpp
if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(InputComponent))
{
    EnhancedInput->BindAction(HammerAction, ETriggerEvent::Triggered, this, &ThisClass::SwingHammer);
}
```

## 开发阶段

### 阶段 1: 核心形变增强 ✅

**完成状态**: 已完成
- [x] 各向异性材料流动
- [x] 顶点打磨度属性系统
- [x] 初始位置存储（无漂移采样）
- [x] 材质扩展（铁锈/金属混合）
- [x] 基础 Laplacian 平滑

**文档**: [docs/features/hammer-deformation-system.md](docs/features/hammer-deformation-system.md)

### 阶段 2: 淬火退火相变系统

**规划状态**: 待实现

**核心机制**:
- 温度区间判定 (800-1200°C)
- 冷却速率计算（快速/中速/慢速）
- 硬度倍数映射（基于 Sigmoid 函数）
- 脆性系数增加
- 相态标记永久保留

**可视化**:
- 三阶段可视化：过程高辨识度 → 冷却过渡 → 真实物理表现
- 真实回火色系统
- 氧化层表现

**文档**: [docs/plans/2026-01-23-淬火退火相变系统设计.md](docs/plans/2026-01-23-淬火退火相变系统设计.md)

### 阶段 3: 应力累积系统

**规划状态**: 待实现

**应力来源**:
- 塑性形变应力
- 热应力
- 相变应力
- 残余应力

**物理表现**:
- 弯曲/扭曲（应力梯度导致）
- 裂纹起始与扩展
- 应力松弛（温度驱动）

**文档**: [docs/plans/2026-01-23-应力累积系统设计.md](docs/plans/2026-01-23-应力累积系统设计.md)

### 阶段 4: 疲劳累积与耐久度系统

**规划状态**: 待实现

**疲劳机制**:
- 累积式疲劳值（每次锻打增加）
- 应力和温度影响疲劳率
- 疲劳裂纹起始与扩展

**耐久度系统**:
- 基于平均疲劳、裂纹数量、最大应力
- 使用中的损伤累积
- 回火部分恢复耐久度

**文档**: [docs/plans/2026-01-23-疲劳累积与耐久度系统设计.md](docs/plans/2026-01-23-疲劳累积与耐久度系统设计.md)

## 调试工具

### Blueprint 可调用函数

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

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

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

// 输出顶点颜色信息
IronBlock->DebugPrintVertexColors();
```

### Unreal Insights 性能分析

- 启用 Unreal Insights 进行性能分析
- 目标: 锤击响应时间 <10ms

## 文档索引

### 功能文档
- [锤击形变系统](docs/features/hammer-deformation-system.md)

### 设计文档
- [高真实度锻造系统设计](docs/plans/2026-01-22-高真实度锻造系统设计.md)
- [刀刃形成技术细节](docs/plans/2026-01-22-刀刃形成技术细节.md)
- [表面磨损系统细节](docs/plans/2026-01-22-表面磨损系统细节.md)
- [网格质量优化细节](docs/plans/2026-01-22-网格质量优化细节.md)
- [物理模拟架构细节](docs/plans/2026-01-22-物理模拟架构细节.md)
- [淬火退火相变与应力疲劳系统总览](docs/plans/2026-01-23-淬火退火相变与应力疲劳系统总览.md)
- [淬火退火相变系统设计](docs/plans/2026-01-23-淬火退火相变系统设计.md)
- [应力累积系统设计](docs/plans/2026-01-23-应力累积系统设计.md)
- [疲劳累积与耐久度系统设计](docs/plans/2026-01-23-疲劳累积与耐久度系统设计.md)
- [锤击形变系统增强计划](docs/plans/2026-01-23-hammer-deformation-enhancement.md)

### 测试文档
- [锤击形变测试结果](docs/tests/hammer-deformation-test-results.md)

## 已知限制

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

### 未来扩展
- **阶段 2**: 淬火退火相变系统
- **阶段 3**: 应力累积系统
- **阶段 4**: 疲劳累积与耐久度系统
- 多材料支持（铜、青铜、钛合金）
- 焊接系统
- VR 支持

## 参考资料

### 物理基础
- 《金属塑性成形原理》（清华大学出版社）
- 《材料科学基础》（上海交通大学出版社）
- *Metals Handbook: Forging and Forming* (ASM International)

### 技术参考
- Unreal Engine 5 Geometry Scripting 文档
- *Real-Time Collision Detection* by Christer Ericson
- *GPU Gems 3* - Chapter 39 (Parallel Prefix Sum)

### 游戏案例
- *My Summer Car* - 机械装配真实度
- *BeamNG.drive* - 动态网格形变
- *Dwarf Fortress* - 材料属性系统