starmen1265
e8cbf61eba
更改内容： - 删除 Content/Dark_Knight/ 示例资产（不需要的示例内容） - 更新 CLAUDE.md 为中文版本并扩展内容 - 添加会话管理提示 - 完善核心设计原则说明 - 扩展架构概览和数据流说明 - 添加调试工具和文档索引 - 更新 .claude/settings.local.json 配置 - 更新 BladeSmith.sln.DotSettings.user 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude (glm-4.7) <noreply@anthropic.com>
462 lines
15 KiB
Markdown
462 lines
15 KiB
Markdown
# 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* - 材料属性系统
|