chore: 清理示例资产和更新项目文档

更改内容： - 删除 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>
2026-03-24 00:23:21 +08:00
parent c787beee89
commit e8cbf61eba
343 changed files with 433 additions and 186 deletions
@@ -1,27 +1,18 @@
 {
  "permissions": {
    "allow": [
-      "Bash(\"C:\\Program Files\\Epic Games\\UE_5.4\\Engine\\Build\\BatchFiles\\Build.bat\" BladeSmithEditor Win64 Development -Project=\"E:\\MiceCola\\work\\BladeSmith\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
      "Bash(\"E:\\MiceCola\\work\\UE_5_6\\Engine\\Build\\BatchFiles\\Build.bat\" BladeSmithEditor Win64 Development \"-Project=E:\\MiceCola\\work\\BladeSmith\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
-      "Bash(\"E:\\MiceCola\\work\\UE_5_6\\Engine\\Build\\BatchFiles\\Build.bat\" BladeSmithEditor Win64 Development -Project=\"E:\\MiceCola\\work\\BladeSmith\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
      "Bash(dir:*)",
      "Bash(git add:*)",
-      "Bash(git commit -m \"$(cat <<''EOF''\n实现DynamicIronBlock温度体素系统基础功能\n\n新增功能：\n- 添加FTemperatureVoxel结构体（温度、塑性系数、表面标志）\n- 实现自适应温度网格（5mm体素精度，基于BoxSize计算分辨率）\n- 实现三线性插值温度/塑性系数采样\n- 实现黑体辐射温度可视化（顶点颜色）\n- 添加HeatRegion蓝图测试函数\n- 添加OnHammerImpact锤击形变函数（体积守恒）\n\n技术细节：\n- Phase 1: CPU侧温度网格初始化，支持10cm-100cm+可变尺寸\n- Phase 3: 温度可视化系统（20°C灰色 → 1200°C白色）\n- 内存占用：30×30×30cm ≈ 1.7MB（60×60×60体素）\n\n待实现：Phase 2 GPU热传导计算\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n)\")",
      "Bash(git commit:*)",
-      "Bash(\"E:\\MiceCola\\work\\UE_5_6\\Engine\\Build\\BatchFiles\\Build.bat\" BladeSmithEditor Win64 Development -Project=\"C:\\MiceCola\\Indi\\BladeSmith\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
-      "Bash(cmd /c:*)",
-      "Bash(\"C:\\MiceCola\\Indi\\UE_5.6\\Engine\\Build\\BatchFiles\\Build.bat\" BladeSmithEditor Win64 Development \"-Project=C:\\MiceCola\\Indi\\BladeSmith\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
-      "Skill(superpowers:brainstorming)",
-      "Skill(superpowers:writing-plans)",
-      "Skill(superpowers:executing-plans)",
+      "Skill(gsd:*)",
      "Bash(findstr:*)",
      "Bash(powershell:*)",
-      "Bash(\"C:\\\\Program Files\\\\Epic Games\\\\UE_5.6\\\\Engine\\\\Build\\\\BatchFiles\\\\Build.bat\" BladeSmith Win64 Development \"E:\\\\MiceCola\\\\work\\\\BladeSmith\\\\BladeSmith.uproject\" -WaitMutex -FromMsBuild)",
-      "Bash(Select-String -Pattern \"error|warning|succeeded|failed\")",
-      "Bash(Select-Object -Last 20)"
+      "Bash(Select-Object -Last 20)",
+      "WebSearch"
    ],
    "deny": [],
    "ask": []
  },
-  "outputStyle": "default"
+  "outputStyle": "Explanatory"
 }
@@ -0,0 +1,49 @@
+---
+name: session-namer
+description: 会话命名管理工具 - 在开始新任务前帮助命名或恢复会话
+---
+
+# 会话命名管理
+
+当您开始新的工作会话时,此技能帮助您管理会话命名。
+
+## 当前会话状态
+
+请检查是否需要命名当前会话:
+
+### 可用操作
+
+1. **命名当前会话**
+   使用命令: `/rename <会话名称>`
+   例如: `/rename 实现各向异性形变`
+
+2. **恢复历史会话**
+   使用命令: `/resume <会话名称>`
+   或在 REPL 中使用: `/continue`
+
+3. **继续当前会话**
+   如果不需要命名,直接开始工作即可
+
+## BladeSmith 项目常用会话命名建议
+
+基于项目结构,建议的会话命名模式:
+
+- **功能开发**: `feat-功能名称` (如 `feat-温度系统`)
+- **Bug 修复**: `fix-问题描述` (如 `fix-边缘约束问题`)
+- **代码重构**: `refactor-模块名称` (如 `refactor-GPU着色器`)
+- **性能优化**: `perf-优化目标` (如 `perf-网格简化`)
+- **文档编写**: `docs-文档主题` (如 `docs-API文档`)
+- **测试相关**: `test-测试内容` (如 `test-形变系统`)
+
+## 最近的 Git 分支作为参考
+
+当前分支: hammer-deformation-phase1
+
+如果需要查看更多分支或上下文,我可以帮您:
+- 列出最近的 git 分支
+- 查看最近的提交历史
+- 查看未完成的工作
+
+---
+
+**是否需要我帮助您命名当前会话?** 请告诉我您计划做什么,或者直接使用 `/rename` 命令。
@@ -1,4 +1,9 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=436DC2F9_002D640A_002D357F_002D8A01_002D8B10A58FB273_002Fdl_003ASource_003AD_0021_003FProgram_0020Files_003FEpic_0020Games_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003ARenderCore_002Fd_003APublic_002Ff_003AGlobalShader_002Eh/@EntryIndexedValue">ForceIncluded</s:String>
+	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=436DC2F9_002D640A_002D357F_002D8A01_002D8B10A58FB273_002Fdl_003ASource_003AD_0021_003FProgram_0020Files_003FEpic_0020Games_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003ARenderCore_002Fd_003APublic_002Ff_003ARenderGraphBuilder_002Einl/@EntryIndexedValue">ForceIncluded</s:String>
+	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=436DC2F9_002D640A_002D357F_002D8A01_002D8B10A58FB273_002Fdl_003ASource_003AD_0021_003FProgram_0020Files_003FEpic_0020Games_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003ARenderCore_002Fd_003APublic_002Ff_003ARenderGraphUtils_002Eh/@EntryIndexedValue">ForceIncluded</s:String>
+	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=436DC2F9_002D640A_002D357F_002D8A01_002D8B10A58FB273_002Fdl_003ASource_003AD_0021_003FProgram_0020Files_003FEpic_0020Games_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003ARenderCore_002Fd_003APublic_002Ff_003AShader_002Eh/@EntryIndexedValue">ForceIncluded</s:String>
+	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=436DC2F9_002D640A_002D357F_002D8A01_002D8B10A58FB273_002Fdl_003ASource_003AD_0021_003FProgram_0020Files_003FEpic_0020Games_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003ARenderCore_002Fd_003APublic_002Ff_003AShaderParameterStruct_002Eh/@EntryIndexedValue">ForceIncluded</s:String>
 	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=657466D1_002D2409_002D3196_002D8BA9_002D4914CBD968CC_002Fdl_003ASource_003A_002E_002E_003F_002E_002E_003F_002E_002E_003FUE_005F5_002E6_003FEngine_003FSource_002Fd_003ARuntime_002Fd_003AEngine_002Fd_003APublic_002Fd_003AMaterials_002Ff_003AMaterialExpressionBlackBody_002Eh/@EntryIndexedValue">ForceIncluded</s:String>
 	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=7020124F_002D9FFC_002D4AC3_002D8F3D_002DAAB8E0240759_002Ff_003ADanyxuq_002Easm_002Fl_003AC_0021_003FUsers_003Fstarm_003FAppData_003FLocal_003FTemp_003FSandboxFiles_003FRewuwer_003FDanyxuq_002Easm/@EntryIndexedValue">ForceIncluded</s:String>
 	<s:String x:Key="/Default/CodeInspection/ExcludedFiles/FilesAndFoldersToSkip2/=7020124F_002D9FFC_002D4AC3_002D8F3D_002DAAB8E0240759_002Ff_003ADycuvaq_002Easm_002Fl_003AC_0021_003FUsers_003Fstarm_003FAppData_003FLocal_003FTemp_003FSandboxFiles_003FWoqosub_003FDycuvaq_002Easm/@EntryIndexedValue">ForceIncluded</s:String>
@@ -1,231 +1,319 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+> **💡 会话管理提示**: 开始新任务前,建议使用 `/rename <名称>` 命令命名当前会话。
+> - 使用 `/session-namer` 技能获取会话命名帮助
+> - 使用 `/resume <名称>` 恢复历史会话
+> - 使用 `/continue` 查看最近会话列表

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

-BladeSmith is an Unreal Engine 5.6 C++ blacksmith simulation game where players forge bladed weapons through realistic physical processes. The core feature is GPU-accelerated plastic deformation of metal using compute shaders, combined with a voxel-based temperature system that determines material plasticity.
+## 项目概述

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

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

-### Building the Project
+## 核心设计原则
+
+### 游戏娱乐级精度
+- 简化物理模型，保持真实感，同时确保 60 FPS 性能
+- 参考真实冶金学原理，但使用经验公式替代复杂计算
+
+### 渐进式实现
+- 分阶段开发，每阶段可独立运行和验收
+- 阶段 1: 各向异性形变 + 表面磨损 + 网格质量（已完成）
+- 阶段 2: 淬火退火相变系统（规划中）
+- 阶段 3: 应力累积系统（规划中）
+- 阶段 4: 疲劳累积与耐久度系统（规划中）
+
+### 混合体素-顶点架构
+- **体素层**: 存储全局物理场（温度、冷却速率、相态）
+- **顶点层**: 存储局部材料历史（应变、硬度、打磨度、疲劳）
+
+## 构建与开发
+
+### 编译项目

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

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

-Alternatively, open `BladeSmith.sln` in Visual Studio and build from there.
+或在 Visual Studio 中打开 `BladeSmith.sln` 编译。

-### Running the Project
+### 运行项目

-1. Open `BladeSmith.uproject` in UE5.6 Editor
-2. Press Alt+P or click Play to run in editor
-3. Use Ctrl+F11 for hot reload after C++ changes
+1. 在 UE5.6 编辑器中打开 `BladeSmith.uproject`
+2. 按 Alt+P 或点击 Play 按钮在编辑器中运行
+3. 使用 Ctrl+F11 进行 C++ 代码修改后的热重载

-### Testing
+### 测试

-Unreal Engine uses the Automation System:
- **In Editor:** Window → Developer Tools → Automation Sessions
- **Command Line:** `UE5Editor.exe BladeSmith.uproject -ExecCmds="Automation RunTests"`
+UE5 使用自动化系统进行测试：
+- **编辑器内**: Window → Developer Tools → Automation Sessions
+- **命令行**: `UE5Editor.exe BladeSmith.uproject -ExecCmds="Automation RunTests"`

-## Architecture Overview
+## 架构概览

-### Core Systems (阶段1更新后)
-
-**1. Dynamic Mesh Deformation System (增强)**
- `ADynamicIronBlock` (Source/BladeSmith/DynamicIronBlock.h/cpp) - 支持各向异性材料流动
- 顶点属性层: 初始位置、累积应变、硬度系数、打磨度
- 边缘检测与约束: 保持刀刃平整锐利
- 表面磨损可视化: 基于打磨度的颜色混合
- 各向异性材料流动（AnisotropyRatio控制方向性）
- 锤击时自动更新打磨度（表面从生锈到光亮）
- Laplacian平滑维护网格质量
- 自适应优化策略
-
-**2. Voxel-Based Temperature System**
- 3D temperature voxel grid (`FTemperatureVoxel`) stores temperature and plasticity coefficients
- Temperature affects material plasticity: 800-1200°C is the forging range
- Heat conduction simulation with surface cooling
- Per-vertex color visualization of temperature (black body radiation approximation)
- GPU-accelerated temperature computation using ping-pong buffers
-
-**3. GPU Compute Pipeline (MiceShaders Plugin)**
- Custom compute shaders for physics simulation
- `FDeformComputeShader` - Plastic deformation calculations
- `FTemperatureComputeShader` - Heat conduction and cooling
- Located in `Plugins/MiceShaders/`
- Shaders written in HLSL (`.usf` files in `Shaders/Private/`)
- Uses RDG (Render Dependency Graph) for GPU dispatch
-
-**4. Hammer Interaction System**
- `UBladeSmithWeaponComponent` (Source/BladeSmith/BladeSmithWeaponComponent.h/cpp) - First-person hammer tool
- Ray-cast based collision detection
- Enhanced Input system integration
- Triggers deformation on `ADynamicIronBlock` via `OnHammerImpact()`
-
-### Key Classes and Their Relationships
+### 核心系统

 ```
-ABladeSmithCharacter (Player)
-  └── UBladeSmithWeaponComponent (Hammer Tool)
+ABladeSmithCharacter (玩家)
+  └── UBladeSmithWeaponComponent (锤子工具)
        └── OnHammerImpact()
-              └── ADynamicIronBlock (Iron Workpiece)
-                    ├── Temperature Voxel Grid (CPU/GPU)
-                    ├── Vertex Attribute Arrays (CPU)
+              └── ADynamicIronBlock (铁块工件)
+                    ├── 温度体素网格
+                    ├── 顶点属性数组
                    │   ├── InitialPositionsArray
                    │   ├── AccumulatedStrainArray
                    │   ├── HardnessCoefficientArray
                    │   └── PolishAmountArray
-                    ├── Dynamic Mesh (GeometryScripting)
-                    │   ├── Anisotropic Flow Direction
-                    │   ├── Edge Constraint
-                    │   └── Laplacian Smoothing
-                    └── MiceShaders Compute Shaders
+                    ├── 动态网格
+                    │   ├── 各向异性流动方向
+                    │   ├── 边缘约束
+                    │   └── Laplacian 平滑
+                    └── MiceShaders 计算着色器
 ```

-### Data Flow: Hammer Impact to Deformation (阶段1更新)
+### 锤击到形变的数据流

-1. Player swings hammer (`UBladeSmithWeaponComponent::SwingHammer()`)
-2. Ray-cast detects hit on `ADynamicIronBlock`
-3. `OnHammerImpact()` receives: location, normal, radius, depth, force
+1. 玩家挥动锤子 (`UBladeSmithWeaponComponent::SwingHammer()`)
+2. 射线检测命中 `ADynamicIronBlock`
+3. `OnHammerImpact()` 接收: 位置、法线、半径、深度、力度
 4. **计算材料流动方向** (各向异性)
   - `FindNearestFreeEdgeDirection()` - 查找最近边缘
   - `CalculatePrimaryFlowDirection()` - 计算主流动方向
   - `CalculateSecondaryFlowDirection()` - 计算次流动方向
-5. Sample plasticity coefficient from temperature voxels at hit location
-6. Apply plastic deformation to mesh vertices via `EditMesh()` lambda
+5. 从温度体素采样塑性系数
+6. 应用塑性形变到网格顶点
   - **各向异性距离计算** - 材料沿主方向更容易流动
   - **更新顶点属性** - 累积应变、打磨度
 7. **边缘约束** (如果启用) - `ApplyEdgeLinearConstraint()`
 8. **Laplacian 平滑** - `ApplyLaplacianSmoothing()` (自适应)
-9. Recompute mesh normals
-10. Update vertex colors (温度 × 打磨度)
-11. GPU compute shader updates temperature distribution (如启用)
+9. 重新计算网格法线
+10. 更新顶点颜色 (温度 × 打磨度)
+11. GPU 计算着色器更新温度分布 (如果启用)

-## Module Dependencies
+### 关键类和关系

-**BladeSmith Module (Source/BladeSmith/BladeSmith.Build.cs):**
- GeometryScriptingCore, GeometryFramework, DynamicMesh
- GeometryCore, GeometryAlgorithms, ModelingComponents
- RenderCore, RHI, Renderer, PhysicsCore
- EnhancedInput
- AudioExtensions, AudioMixer, AudioPlatformConfiguration
- **MiceShaders** (custom plugin)
+| 类 | 文件 | 用途 |
+|---|---|---|
+| `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) | 玩家角色 |

-**MiceShaders Plugin:**
- Core, RenderCore, RHI
- Projects (for shader path resolution)
+## 模块依赖

-## Code Conventions
+**BladeSmith 模块** [Source/BladeSmith/BladeSmith.Build.cs](Source/BladeSmith/BladeSmith.Build.cs):

-### File Headers
-All source files must start with Epic copyright notice (as required by UE5 licensing).
-
-### Naming Conventions
- **Actors:** `AClassName` (e.g., `ADynamicIronBlock`)
- **Components:** `UClassName` (e.g., `UBladeSmithWeaponComponent`)
- **Structs:** `FStructName` (e.g., `FTemperatureVoxel`)
- **Enums:** `EEnumName`
- **Functions:** PascalCase (e.g., `OnHammerImpact()`)
- **Variables:** PascalCase for properties, camelCase for locals
- **Constants:** PascalCase
-
-### Type Usage
- Use UE5 types: `TArray<T>`, `TMap<K,V>`, `TSet<T>`, `FVector`, `FString`, `int32`, `uint8`
- Use `float` by default (not `double`)
- Smart pointers: rely on UObject garbage collection; use `TSharedPtr<T>` for non-UObjects
- String literals: wrap in `TEXT()` macro
-
-### Indentation and Formatting
- **4 spaces** (no tabs)
- **Allman style braces** (opening brace on new line)
- Line length under 120 characters
-
-### Threading and GPU Operations
 ```cpp
-// Atomic flags for thread-safe GPU buffer status
+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};

-// Render thread commands
+// 渲染线程命令
 ENQUEUE_RENDER_COMMAND(CommandName)(
    [Params](FRHICommandListImmediate& RHICmdList)
    {
-        // GPU operations here
+        // GPU 操作
    }
 );
 ```

-### Documentation
-Comments use Chinese for domain-specific logic (e.g., "锤子组件", "温度体素结构").
+### 注释

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

-### Temperature-Plasticity Relationship
- Plasticity = 0 below `ForgeTemperatureMin` (800°C by default)
- Plasticity = 1 above `ForgeTemperatureMax` (1200°C by default)
- Linear interpolation between min and max
- Deformation depth is multiplied by plasticity coefficient
+## 顶点属性系统

-### Deformation Parameters
- `FalloffExponent`: Controls edge transition smoothness (default: 2.0)
- `BulgeRatio`: Bulge radius relative to compression zone (default: 0.8)
- `BulgeStrength`: Bulge height intensity (default: 0.5)
- These simulate realistic plastic flow and volume conservation
+### 数据结构

-### Vertex Color Mapping
- Each vertex samples temperature from voxel grid via trilinear interpolation
- Temperature is converted to color using black body radiation approximation
- Updated every frame when temperature changes occur
+每个顶点存储以下属性 (使用简单数组，索引与顶点 ID 对应):

-### GPU Buffer Management
- Uses ping-pong double buffering for temperature compute shader
- `TemperatureBufferA` and `TemperatureBufferB` alternate as read/write buffers
- Separate `PlasticityBuffer` stores derived plasticity coefficients
- `SurfaceVoxelFlagsBuffer` marks surface voxels for cooling calculations
- Buffers created on render thread, accessed via UAV/SRV
+| 属性 | 类型 | 说明 | 用途 |
+|---|---|---|---|
+| `InitialPositionsArray` | `TArray<FVector3f>` | 初始局部位置 | 无漂移纹理采样 |
+| `AccumulatedStrainArray` | `TArray<float>` | 累积塑性应变 | 记录形变历史 |
+| `HardnessCoefficientArray` | `TArray<float>` | 硬度系数 (0-1) | 影响形变阻力 |
+| `PolishAmountArray` | `TArray<float>` | 打磨度 (0-1) | 0=生锈，1=光亮 |

-## Performance Targets
+### 顶点颜色编码

- **Frame time budget:** <7ms for deformation calculations
- **Target FPS:** 60 FPS during hammer operations
- **Mesh complexity:** Tested with ~100k vertices using GPU acceleration
- **Voxel resolution:** 50x50x50 typical (configurable via `TemperatureVoxelSize`)
+顶点颜色 (RGBA) 通道分配:

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

-1. Create `.h` and `.cpp` in `Plugins/MiceShaders/Source/MiceShaders/Public|Private/`
-2. Define shader class inheriting from `FGlobalShader`
-3. Create corresponding `.usf` HLSL shader in `Plugins/MiceShaders/Shaders/Private/`
-4. Use `IMPLEMENT_GLOBAL_SHADER()` macro to register
-5. Dispatch via RDG in actor's Tick or specialized function
-6. Reference existing shaders: `FDeformComputeShader`, `FTemperatureComputeShader`
+## 锤击形变参数

-## Key UE5 Patterns Used
+### 材料属性
+
+| 参数 | 默认值 | 范围 | 说明 |
+|---|---|---|---|
+| `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 模式使用
+
+### 动态网格编辑

-**Dynamic Mesh Editing:**
 ```cpp
 DynamicMesh->EditMesh([&](FDynamicMesh3& EditMesh)
 {
-    // Modify mesh vertices/triangles here
+    // 修改网格顶点/三角形
 }, EDynamicMeshChangeType::GeneralEdit);
 ```

-**Material Parameter Updates:**
+### 材质参数更新
+
 ```cpp
 DynamicMaterialInstance->SetScalarParameterValue(TEXT("AvgTemperature"), AvgTemp);
 DynamicMaterialInstance->SetVectorParameterValue(TEXT("Color"), FLinearColor(R,G,B,A));
 ```

-**Enhanced Input Binding:**
+### 增强输入绑定
+
 ```cpp
 if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(InputComponent))
 {
@@ -233,27 +321,141 @@ if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(Input
 }
 ```

-## Plugin Structure
+## 开发阶段

-**Enabled Plugins (BladeSmith.uproject):**
- GeometryScripting (UE5 built-in)
- ModelingToolsEditorMode (UE5 built-in)
- HDRIBackdrop (UE5 built-in)
- RiderLink (in repository, for JetBrains Rider integration)
- MiceShaders (custom plugin)
+### 阶段 1: 核心形变增强 ✅

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

- `Content/BP/` - Blueprint actors and components
- `Content/Res/` - Game resources (meshes, materials, textures)
- `Content/Maps/` - Level maps
- `Content/Input/` - Enhanced Input assets
- `Content/FirstPersonArms/`, `Content/FPWeapon/` - First-person character assets
+**文档**: [docs/features/hammer-deformation-system.md](docs/features/hammer-deformation-system.md)

-## Notes for AI Agents
+### 阶段 2: 淬火退火相变系统

- The AGENTS.md file contains comprehensive coding style guidelines; refer to it for detailed conventions
- When modifying deformation logic, always consider the temperature-plasticity coupling
- GPU buffer operations must be thread-safe; use atomic flags and render thread commands
- Test deformation with varying temperatures to ensure plasticity affects results correctly
- Voxel resolution trades off between accuracy and performance; adjust `TemperatureVoxelSize` accordingly
+**规划状态**: 待实现
+
+**核心机制**:
+- 温度区间判定 (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* - 材料属性系统
--- a/Show More
+++ b/Show More