BallisticsDocs/CLAUDE.md

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
• Material Penetration: Configurable penetration depth per material
• Ricochet System: Angle-based ricochet probability with energy loss
• Multiplayer Support: Full replication with client-side prediction
• Performance Optimization: Object pooling for high-rate fire scenarios
• Shotgun Support: Multi-projectile spawning with configurable spread

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