BladeSmith/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

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)

## Build and Development Commands

### Building the Project

From the UE5 engine directory:
```bash
# Build game target
"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.

### 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

### Testing

Unreal Engine uses the Automation System:
- **In Editor:** Window → Developer Tools → Automation Sessions
- **Command Line:** `UE5Editor.exe BladeSmith.uproject -ExecCmds="Automation RunTests"`

## Architecture Overview

### Core Systems

**1. Dynamic Mesh Deformation System**
- `ADynamicIronBlock` (Source/BladeSmith/DynamicIronBlock.h/cpp) - Main iron block actor that handles all deformation
- Uses UE5's GeometryScripting API for runtime mesh manipulation
- Implements plastic deformation with volume-preserving bulge effects
- BVH acceleration structure for efficient collision detection

**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)
        └── OnHammerImpact()
              └── ADynamicIronBlock (Iron Workpiece)
                    ├── Temperature Voxel Grid (CPU/GPU)
                    ├── Dynamic Mesh (GeometryScripting)
                    └── MiceShaders Compute Shaders
```

### Data Flow: Hammer Impact to Deformation

1. Player swings hammer (`UBladeSmithWeaponComponent::SwingHammer()`)
2. Ray-cast detects hit on `ADynamicIronBlock`
3. `OnHammerImpact()` receives: location, normal, radius, depth, force
4. Sample plasticity coefficient from temperature voxels at hit location
5. Apply plastic deformation to mesh vertices via `EditMesh()` lambda
6. Volume-preserving bulge effect applied around impact zone
7. Update vertex colors to visualize temperature
8. GPU compute shader updates temperature distribution

## 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)

**MiceShaders Plugin:**
- Core, RenderCore, RHI
- Projects (for shader path resolution)

## Code Conventions

### 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
std::atomic<bool> bGPUBuffersReady{false};

// Render thread commands
ENQUEUE_RENDER_COMMAND(CommandName)(
    [Params](FRHICommandListImmediate& RHICmdList)
    {
        // GPU operations here
    }
);
```

### 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

### 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

## 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`)

## Adding New Compute Shaders

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

**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))
{
    EnhancedInput->BindAction(HammerAction, ETriggerEvent::Triggered, this, &ThisClass::SwingHammer);
}
```

## 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)

## Content Organization

- `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

## Notes for AI Agents

- 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