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