BladeSmith/CLAUDE.md

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: 疲劳累积与耐久度系统（规划中）

混合体素-顶点架构

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

构建与开发

编译项目

# 从 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	动态铁块，支持各向异性形变
FTemperatureVoxel	DynamicIronBlock.h:14-35	温度体素结构
UBladeSmithWeaponComponent	BladeSmithWeaponComponent.h	第一人称锤子工具
ABladeSmithCharacter	BladeSmithCharacter.h	玩家角色

模块依赖

BladeSmith 模块 Source/BladeSmith/BladeSmith.Build.cs:

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 操作

// 线程安全标志（用于 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/

着色器文件

• 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 模式使用

动态网格编辑

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

材质参数更新

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

增强输入绑定

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

开发阶段

阶段 1: 核心形变增强 ✅

完成状态: 已完成

• 各向异性材料流动
• 顶点打磨度属性系统
• 初始位置存储（无漂移采样）
• 材质扩展（铁锈/金属混合）
• 基础 Laplacian 平滑

文档: docs/features/hammer-deformation-system.md

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

规划状态: 待实现

核心机制:

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

可视化:

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

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

阶段 3: 应力累积系统

规划状态: 待实现

应力来源:

• 塑性形变应力
• 热应力
• 相变应力
• 残余应力

物理表现:

• 弯曲/扭曲（应力梯度导致）
• 裂纹起始与扩展
• 应力松弛（温度驱动）

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

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

规划状态: 待实现

疲劳机制:

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

耐久度系统:

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

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

调试工具

Blueprint 可调用函数

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

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

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

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

Unreal Insights 性能分析

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

文档索引

功能文档

• 锤击形变系统

设计文档

• 高真实度锻造系统设计
• 刀刃形成技术细节
• 表面磨损系统细节
• 网格质量优化细节
• 物理模拟架构细节
• 淬火退火相变与应力疲劳系统总览
• 淬火退火相变系统设计
• 应力累积系统设计
• 疲劳累积与耐久度系统设计
• 锤击形变系统增强计划

测试文档

• 锤击形变测试结果

已知限制

当前限制

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 - 材料属性系统