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:

# 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

// 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:

DynamicMesh->EditMesh([&](FDynamicMesh3& EditMesh)
{
    // Modify mesh vertices/triangles here
}, EDynamicMeshChangeType::GeneralEdit);

Material Parameter Updates:

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

Enhanced Input Binding:

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