# CLAUDE.md

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

## Project Overview

This is EasyBallistics_C, an Unreal Engine 5.6 plugin that provides realistic ballistics simulation for projectiles. The plugin implements advanced physics calculations including atmospheric effects, material penetration, ricochets, and drag curves.

## Build System

This is an Unreal Engine plugin that uses Unreal's build system. The plugin compiles as part of the host project using UnrealBuildTool.

### Build Configuration
- **Module**: EasyBallistics (Runtime module)
- **Engine Version**: 5.6.0
- **Platforms**: Win64, Linux, Mac, Android
- **Build File**: `Source/EasyBallistics/EasyBallistics.Build.cs`

### Dependencies
- **Public**: Core
- **Private**: CoreUObject, Engine, PhysicsCore

## Architecture

### Core Components

1. **AEBBullet** (`EBBullet.h/.cpp`) - Main bullet actor
   - Handles physics simulation, atmospheric effects, penetration
   - Implements pooling system for performance
   - Supports complex ballistics including drag curves, wind effects
   - Manages collision detection and material responses

2. **UEBBarrel** (`EBBarrel.h/.cpp`) - Weapon barrel component
   - Manages firing mechanics (auto, semi-auto, burst, gatling modes)
   - Handles ammo cycling and reloading
   - Implements spread patterns and muzzle velocity variations
   - Supports networked replication for multiplayer

3. **UEBMaterialResponseMap** (`EBMaterialResponseMap.h`) - Material system
   - Maps physical materials to ballistic responses
   - Configures penetration depth, ricochet probability, friction
   - Supports different penetration trace types

### Key Features

- **Realistic Physics**: Atmospheric density, temperature, pressure effects
- **Mathematical Ballistics**: Physics-based penetration using Taylor-Hopkinson and Recht-Ipson models
- **Material Penetration**: Configurable penetration depth per material with physical material integration
- **Ricochet System**: Angle-based ricochet probability with energy loss
- **Spalling System**: Secondary fragment generation on high-energy impacts
- **Ballistic Impact Component**: Event-driven impact handling with Blueprint events
- **Multiplayer Support**: Full replication with client-side prediction
- **Performance Optimization**: Object pooling, LOD systems for high-rate fire scenarios
- **Shotgun Support**: Multi-projectile spawning with configurable spread
- **Editor Integration**: Asset factories, smart material recognition, JSON import/export

### File Structure

```
Source/EasyBallistics/
├── EasyBallistics.Build.cs          # Build configuration
├── Public/
│   ├── EasyBallistics.h            # Module header
│   ├── EBBarrel.h                  # Barrel component
│   ├── EBBullet.h                  # Bullet actor
│   └── EBMaterialResponseMap.h     # Material response system
└── Private/
    ├── EasyBallistics.cpp          # Module implementation
    ├── EBBarrel.cpp                # Barrel implementation
    ├── EBBullet.cpp                # Bullet implementation
    └── [Additional implementation files]
```

## Development Notes

### Networking
- Uses Unreal's replication system extensively
- Supports both reliable and unreliable multicast for performance
- Client-side aim prediction for responsive gameplay

### Performance Considerations
- Object pooling enabled by default for bullets
- Fixed timestep simulation option for consistent physics
- Configurable trace complexity and collision margins

### Physics Integration
- Integrates with Unreal's physics system for impulse application
- Supports both simple and complex collision detection
- Atmospheric model supports Earth-like conditions or custom curves

## Documentation Structure

The plugin includes comprehensive documentation in the `/docs` directory:

### Documentation Categories
- **Getting Started**: Installation and quick start guides
- **Core Concepts**: Mathematical ballistics, spalling system, impact components
- **Tutorials**: Step-by-step guides for material setup and advanced weapons
- **Advanced Guides**: Multiplayer, performance optimization, editor integration
- **API Reference**: Complete class and function documentation
- **Troubleshooting**: Common issues and debugging techniques

### Key Documentation Files
- `docs/docs/intro.md` - Main introduction and overview
- `docs/docs/core-concepts/mathematical-ballistics.md` - Physics calculations
- `docs/docs/core-concepts/spalling-system.md` - Fragment generation system
- `docs/docs/tutorials/material-setup-guide.md` - Material configuration tutorial
- `docs/docs/advanced/json-import-export.md` - Data import/export tools
- `docs/docs/api/bullet-reference.md` - Complete AEBBullet API
- `docs/docs/api/material-properties-reference.md` - Material system API

### Documentation Build System
- Uses Docusaurus 2 for static site generation
- Configuration in `docs/docusaurus.config.js`
- Sidebar structure in `docs/sidebars.js`
- Supports local development: `npm run start` in docs directory