docs

docs/docs/advanced/editor-integration.md

@@ -0,0 +1,506 @@
+# Editor Integration
+
+EasyBallistics provides comprehensive editor integration to streamline ballistic asset creation and management. The editor tools include asset factories, custom property panels, and seamless Physical Material integration.
+
+## Asset Creation System
+
+### Ballistics Asset Menu
+
+EasyBallistics adds a dedicated "Ballistics" category to the Content Browser's asset creation menu:
+
+1. **Right-click** in Content Browser
+2. Navigate to **"Ballistics"** category
+3. Choose from available asset types:
+   - **Bullet Properties** - Define projectile characteristics
+   - **Material Response Map** - Configure material interactions
+   - **Material Properties** - Advanced material ballistic properties
+
+### Asset Factories
+
+The plugin provides specialized asset factories for streamlined creation:
+
+```cpp
+// Bullet Properties Factory
+class EASYBALLISTICSEDITOR_API UEBBulletPropertiesFactory : public UFactory
+{
+    GENERATED_BODY()
+
+public:
+    UEBBulletPropertiesFactory();
+    
+    virtual UObject* FactoryCreateNew(UClass* Class, UObject* InParent, 
+                                     FName Name, EObjectFlags Flags, 
+                                     UObject* Context, FFeedbackContext* Warn) override;
+    
+    virtual bool ShouldShowInNewMenu() const override { return true; }
+};
+```
+
+### Smart Asset Configuration
+
+Assets are automatically configured with sensible defaults based on naming conventions:
+
+```cpp
+// Automatic configuration based on asset name
+if (AssetName.Contains("556") || AssetName.Contains("NATO"))
+{
+    // Configure for 5.56x45mm NATO
+    BulletProperties.GrainWeight = 55.0f;
+    BulletProperties.DiameterInches = 0.224f;
+    BulletProperties.BallisticCoefficientG1 = 0.151f;
+}
+else if (AssetName.Contains("762") || AssetName.Contains("308"))
+{
+    // Configure for 7.62x51mm NATO
+    BulletProperties.GrainWeight = 147.0f;
+    BulletProperties.DiameterInches = 0.308f;
+    BulletProperties.BallisticCoefficientG1 = 0.43f;
+}
+```
+
+## Physical Material Integration
+
+### Ballistic Properties Panel
+
+Physical Materials now include a dedicated "Ballistic Properties" section:
+
+1. **Open Physical Material** in editor
+2. **Ballistic Properties** section appears automatically
+3. **"Create New"** button generates ballistic properties
+4. **Auto-detection** configures properties based on material name
+
+### Smart Material Recognition
+
+The system automatically recognizes common materials:
+
+```cpp
+// Material name-based auto-configuration
+void AutoConfigureMaterial(UPhysicalMaterial* PhysMat)
+{
+    FString MaterialName = PhysMat->GetName().ToLower();
+    
+    if (MaterialName.Contains("steel"))
+    {
+        Properties.DensityGPerCm3 = 7.85f;
+        Properties.MaterialHardness = 200.0f;
+        Properties.TensileStrengthMPa = 400.0f;
+    }
+    else if (MaterialName.Contains("aluminum"))
+    {
+        Properties.DensityGPerCm3 = 2.70f;
+        Properties.MaterialHardness = 95.0f;
+        Properties.TensileStrengthMPa = 310.0f;
+    }
+    else if (MaterialName.Contains("concrete"))
+    {
+        Properties.DensityGPerCm3 = 2.40f;
+        Properties.MaterialHardness = 20.0f;
+        Properties.TensileStrengthMPa = 4.0f;
+    }
+    // ... more materials
+}
+```
+
+### Custom Property Panels
+
+EasyBallistics provides custom detail panels for enhanced editing:
+
+```cpp
+// Custom details panel for Physical Materials
+class FEBPhysicalMaterialCustomization : public IDetailCustomization
+{
+public:
+    virtual void CustomizeDetails(IDetailLayoutBuilder& DetailBuilder) override;
+    
+private:
+    void AddBallisticPropertiesSection(IDetailLayoutBuilder& DetailBuilder);
+    void HandleCreateBallisticProperties();
+    void HandleAutoConfigureMaterial();
+    
+    TWeakObjectPtr<UPhysicalMaterial> PhysicalMaterial;
+};
+```
+
+## Asset Editors
+
+### Bullet Properties Editor
+
+Enhanced property editor for bullet characteristics:
+
+#### Basic Properties Section
+- **Grain Weight**: Automatic grain-to-kilogram conversion
+- **Diameter**: Inches with metric conversion display
+- **Length**: Bullet length with sectional density calculation
+- **Bullet Type**: Dropdown with common types (FMJ, HP, AP, etc.)
+- **Material**: Bullet material selection
+
+#### Ballistic Properties Section
+- **Ballistic Coefficient G1**: Traditional BC model
+- **Ballistic Coefficient G7**: Modern BC model
+- **Use G7 Model**: Toggle between G1 and G7
+- **Sectional Density**: Auto-calculated or manual override
+
+#### Penetration Properties Section
+- **Bullet Hardness**: Brinell hardness scale
+- **Energy Threshold**: Minimum energy for penetration
+- **Expansion Velocity**: Threshold for bullet expansion
+- **Max Expansion**: Maximum expansion multiplier
+
+### Material Response Map Editor
+
+Comprehensive editor for material interaction rules:
+
+#### Material List
+- **Visual Material List**: All configured materials
+- **Add Material**: Drag-and-drop Physical Materials
+- **Quick Actions**: Duplicate, remove, copy settings
+
+#### Response Configuration
+- **Penetration Settings**: Depth multipliers and normalization
+- **Ricochet Settings**: Probability and restitution factors
+- **Mathematical Integration**: Toggle physics-based calculations
+- **Spalling Configuration**: Fragment generation settings
+
+### Validation and Warnings
+
+The editor provides real-time validation:
+
+```cpp
+// Validation system
+void ValidateBulletProperties(const FMathematicalBulletProperties& Props)
+{
+    if (Props.GrainWeight <= 0.0f)
+    {
+        LogWarning(TEXT("Grain weight must be positive"));
+    }
+    
+    if (Props.DiameterInches <= 0.0f)
+    {
+        LogWarning(TEXT("Diameter must be positive"));
+    }
+    
+    if (Props.BallisticCoefficientG1 <= 0.0f)
+    {
+        LogWarning(TEXT("Ballistic coefficient must be positive"));
+    }
+    
+    // Check for realistic values
+    if (Props.GrainWeight > 1000.0f)
+    {
+        LogWarning(TEXT("Grain weight unusually high - verify value"));
+    }
+}
+```
+
+## Debug and Visualization Tools
+
+### Ballistic Debug Overlay
+
+In-editor debug visualization for ballistic calculations:
+
+```cpp
+// Debug overlay in viewport
+void DrawBallisticDebugInfo(const FSceneView* View, FPrimitiveDrawInterface* PDI)
+{
+    if (bShowBallisticDebug)
+    {
+        // Draw trajectory predictions
+        DrawDebugLine(PDI, MuzzleLocation, PredictedImpactLocation, 
+                     FColor::Green, false, 0.0f, 0, 2.0f);
+        
+        // Draw impact predictions
+        DrawDebugSphere(PDI, PredictedImpactLocation, 10.0f, 
+                       12, FColor::Red, false, 0.0f);
+        
+        // Draw penetration depth
+        DrawDebugLine(PDI, ImpactLocation, 
+                     ImpactLocation + (ImpactNormal * PenetrationDepth),
+                     FColor::Blue, false, 0.0f, 0, 3.0f);
+    }
+}
+```
+
+### Performance Profiling
+
+Built-in performance monitoring tools:
+
+```cpp
+// Performance tracking
+DEFINE_STAT(STAT_BallisticCalculationTime);
+DEFINE_STAT(STAT_PenetrationCalculations);
+DEFINE_STAT(STAT_RicochetCalculations);
+
+void TrackBallisticPerformance()
+{
+    SCOPE_CYCLE_COUNTER(STAT_BallisticCalculationTime);
+    
+    // Track calculation counts
+    INC_DWORD_STAT(STAT_PenetrationCalculations);
+    
+    // Monitor memory usage
+    SET_MEMORY_STAT(STAT_BallisticMemoryUsage, GetBallisticMemoryUsage());
+}
+```
+
+## Asset Management
+
+### Batch Operations
+
+Efficient batch operations for multiple assets:
+
+```cpp
+// Batch configure bullet properties
+void BatchConfigureBulletProperties(TArray<UEBBulletPropertiesAsset*> Assets)
+{
+    for (UEBBulletPropertiesAsset* Asset : Assets)
+    {
+        // Apply common settings
+        Asset->BulletProperties.UseG7Model = true;
+        Asset->BulletProperties.BulletMaterial = EBulletMaterial::BM_CopperJacket;
+        
+        // Auto-configure based on name
+        AutoConfigureBulletProperties(Asset);
+        
+        // Mark as modified
+        Asset->MarkPackageDirty();
+    }
+}
+```
+
+### Asset Validation
+
+Comprehensive asset validation system:
+
+```cpp
+// Asset validation
+class FEBAssetValidator
+{
+public:
+    static bool ValidateBulletProperties(UEBBulletPropertiesAsset* Asset);
+    static bool ValidateMaterialResponseMap(UEBMaterialResponseMap* Asset);
+    static bool ValidateMaterialProperties(UEBMaterialPropertiesAsset* Asset);
+    
+private:
+    static void ReportValidationError(const FString& Message);
+    static void ReportValidationWarning(const FString& Message);
+};
+```
+
+## Import/Export
+
+### Ballistic Data Import
+
+Import ballistic data from external sources:
+
+```cpp
+// CSV import for bullet properties
+void ImportBulletPropertiesFromCSV(const FString& FilePath)
+{
+    TArray<FString> Lines;
+    FFileHelper::LoadFileToStringArray(Lines, *FilePath);
+    
+    for (const FString& Line : Lines)
+    {
+        TArray<FString> Values;
+        Line.ParseIntoArray(Values, TEXT(","));
+        
+        if (Values.Num() >= 5)
+        {
+            // Create new bullet properties asset
+            UEBBulletPropertiesAsset* NewAsset = CreateBulletPropertiesAsset();
+            
+            // Parse values
+            NewAsset->BulletProperties.GrainWeight = FCString::Atof(*Values[0]);
+            NewAsset->BulletProperties.DiameterInches = FCString::Atof(*Values[1]);
+            NewAsset->BulletProperties.BallisticCoefficientG1 = FCString::Atof(*Values[2]);
+            
+            // Save asset
+            SaveAsset(NewAsset);
+        }
+    }
+}
+```
+
+### Configuration Export
+
+Export configurations for sharing:
+
+```cpp
+// Export material response map to JSON
+void ExportMaterialResponseMapToJSON(UEBMaterialResponseMap* ResponseMap)
+{
+    TSharedPtr<FJsonObject> JsonObject = MakeShareable(new FJsonObject);
+    
+    for (const auto& Entry : ResponseMap->Map)
+    {
+        TSharedPtr<FJsonObject> MaterialEntry = MakeShareable(new FJsonObject);
+        
+        MaterialEntry->SetNumberField("PenetrationDepthMultiplier", 
+                                    Entry.Value.PenetrationDepthMultiplier);
+        MaterialEntry->SetNumberField("RicochetProbabilityMultiplier", 
+                                    Entry.Value.RicochetProbabilityMultiplier);
+        MaterialEntry->SetBoolField("UseMathematicalProperties", 
+                                  Entry.Value.UseMathematicalProperties);
+        
+        JsonObject->SetObjectField(Entry.Key->GetName(), MaterialEntry);
+    }
+    
+    // Write to file
+    FString OutputString;
+    TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&OutputString);
+    FJsonSerializer::Serialize(JsonObject.ToSharedRef(), Writer);
+    
+    FFileHelper::SaveStringToFile(OutputString, *GetExportPath());
+}
+```
+
+## Integration with Unreal Editor
+
+### Content Browser Integration
+
+Custom thumbnails and asset actions:
+
+```cpp
+// Custom thumbnail renderer
+class FEBBulletPropertiesThumbnailRenderer : public UDefaultSizedThumbnailRenderer
+{
+public:
+    virtual void Draw(UObject* Object, int32 X, int32 Y, uint32 Width, uint32 Height, 
+                     FRenderTarget* RenderTarget, FCanvas* Canvas, 
+                     bool bAdditionalViewFamily) override;
+    
+private:
+    void DrawBulletDiagram(FCanvas* Canvas, const FMathematicalBulletProperties& Props,
+                          int32 X, int32 Y, uint32 Width, uint32 Height);
+};
+```
+
+### Context Menu Actions
+
+Custom context menu actions for ballistic assets:
+
+```cpp
+// Custom asset actions
+class FEBBulletPropertiesAssetActions : public FAssetTypeActions_Base
+{
+public:
+    virtual FText GetName() const override;
+    virtual FColor GetTypeColor() const override;
+    virtual UClass* GetSupportedClass() const override;
+    virtual void GetActions(const TArray<UObject*>& InObjects, 
+                           FMenuBuilder& MenuBuilder) override;
+    
+private:
+    void ExecuteValidate(TArray<TWeakObjectPtr<UObject>> Objects);
+    void ExecuteAutoConfig(TArray<TWeakObjectPtr<UObject>> Objects);
+    void ExecuteExportData(TArray<TWeakObjectPtr<UObject>> Objects);
+};
+```
+
+## Workflow Optimization
+
+### Quick Setup Wizards
+
+Guided setup for common scenarios:
+
+```cpp
+// Quick setup wizard for common bullet types
+class FEBBulletSetupWizard
+{
+public:
+    static void ShowWizard();
+    
+private:
+    static void HandleBulletTypeSelection(ECommonBulletType BulletType);
+    static void CreateBulletPropertiesForType(ECommonBulletType BulletType);
+    static void ConfigureMaterialResponseMap(ECommonBulletType BulletType);
+};
+```
+
+### Templates and Presets
+
+Pre-configured templates for common use cases:
+
+```cpp
+// Template system
+class FEBAssetTemplates
+{
+public:
+    static UEBBulletPropertiesAsset* CreateFromTemplate(EBulletTemplate Template);
+    static UEBMaterialResponseMap* CreateMaterialMapFromTemplate(EMaterialTemplate Template);
+    
+private:
+    static void ApplyRifleTemplate(UEBBulletPropertiesAsset* Asset);
+    static void ApplyPistolTemplate(UEBBulletPropertiesAsset* Asset);
+    static void ApplyShotgunTemplate(UEBBulletPropertiesAsset* Asset);
+};
+```
+
+## Error Handling and Debugging
+
+### Comprehensive Error Reporting
+
+Detailed error messages with solutions:
+
+```cpp
+// Error reporting system
+class FEBEditorErrorReporter
+{
+public:
+    static void ReportError(const FString& Message, const FString& Solution = "");
+    static void ReportWarning(const FString& Message, const FString& Suggestion = "");
+    static void ReportInfo(const FString& Message);
+    
+private:
+    static void ShowNotification(const FString& Message, SNotificationItem::ECompletionState State);
+};
+```
+
+### Debug Console Commands
+
+Editor console commands for debugging:
+
+```cpp
+// Debug console commands
+static FAutoConsoleCommand DebugBallisticAssets(
+    TEXT("EB.DebugAssets"),
+    TEXT("Debug all ballistic assets in project"),
+    FConsoleCommandDelegate::CreateStatic([]()
+    {
+        FEBEditorUtils::DebugAllBallisticAssets();
+    })
+);
+
+static FAutoConsoleCommand ValidateBallisticAssets(
+    TEXT("EB.ValidateAssets"),
+    TEXT("Validate all ballistic assets in project"),
+    FConsoleCommandDelegate::CreateStatic([]()
+    {
+        FEBEditorUtils::ValidateAllBallisticAssets();
+    })
+);
+```
+
+## Future Enhancements
+
+### Planned Features
+
+- **Visual Scripting**: Blueprint nodes for ballistic calculations
+- **Material Editor**: Enhanced material property visualization
+- **Performance Analyzer**: Real-time performance monitoring
+- **Asset Browser**: Specialized browser for ballistic assets
+- **Ballistic Calculator**: Built-in trajectory calculator
+
+### Integration Roadmap
+
+- **Sequencer Support**: Ballistic effect sequencing
+- **World Partition**: Large-world ballistic optimization
+- **Chaos Physics**: Enhanced physics integration
+- **Niagara VFX**: Advanced effect system integration
+
+## See Also
+
+- [Getting Started](../getting-started/installation) - Initial setup and installation
+- [Asset Creation](../tutorials/asset-creation) - Creating ballistic assets
+- [Performance Optimization](performance-optimization) - Optimizing editor performance
+- [Troubleshooting](../troubleshooting) - Common editor issues 

docs/docs/core-concepts/ballistic-impact-component.md

@@ -0,0 +1,586 @@
+# Ballistic Impact Component
+
+The `UEBBallisticImpactComponent` is the centerpiece of EasyBallistics' new event-driven impact system. This component provides sophisticated impact handling, event broadcasting, and physics-based calculations for realistic ballistic behavior.
+
+## Overview
+
+The Ballistic Impact Component replaces the old direct impact calculation system with a modern, event-driven architecture that offers:
+
+- **Event-Driven Architecture**: Clean separation between impact detection and response
+- **Physics-Based Calculations**: Realistic penetration and ricochet modeling
+- **Flexible Configuration**: Easy customization through Blueprint events
+- **Performance Optimization**: Efficient calculations with caching
+- **Multiplayer Support**: Network-optimized impact handling
+
+## Component Architecture
+
+### Core Components
+
+```cpp
+UCLASS(ClassGroup=(Ballistics), meta=(BlueprintSpawnableComponent))
+class EASYBALLISTICS_API UEBBallisticImpactComponent : public UActorComponent
+{
+    // Event delegates
+    UPROPERTY(BlueprintAssignable, Category = "Ballistics Events")
+    FOnBallisticImpact OnBallisticImpact;
+    
+    UPROPERTY(BlueprintAssignable, Category = "Ballistics Events")
+    FOnBallisticRicochet OnBallisticRicochet;
+    
+    // Configuration
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Ballistics")
+    UEBMaterialResponseMap* MaterialResponseMap;
+    
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Ballistics")
+    bool bEnableBallisticCalculations = true;
+    
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Ballistics")
+    bool bUseMathematicalPenetration = false;
+};
+```
+
+### Event Delegates
+
+#### OnBallisticImpact
+Fired when a projectile impacts a surface:
+
+```cpp
+DECLARE_DYNAMIC_MULTICAST_DELEGATE_FiveParams(FOnBallisticImpact, 
+    FVector, ImpactLocation,     // World location of impact
+    FVector, ImpactNormal,       // Surface normal at impact
+    UPhysicalMaterial*, HitMaterial, // Material that was hit
+    float, PenetrationDepth,     // Calculated penetration depth
+    bool, bDidPenetrate          // Whether projectile penetrated
+);
+```
+
+#### OnBallisticRicochet
+Fired when a projectile ricochets off a surface:
+
+```cpp
+DECLARE_DYNAMIC_MULTICAST_DELEGATE_FourParams(FOnBallisticRicochet,
+    FVector, RicochetLocation,   // Location of ricochet
+    FVector, RicochetDirection,  // New direction after ricochet
+    UPhysicalMaterial*, HitMaterial, // Material that caused ricochet
+    float, EnergyRetained        // Energy retained after ricochet (0-1)
+);
+```
+
+## Setup and Configuration
+
+### Adding to Actors
+
+Add the component to any actor that should respond to ballistic impacts:
+
+```cpp
+// C++ Constructor
+AMyTargetActor::AMyTargetActor()
+{
+    // Create ballistic impact component
+    BallisticImpactComponent = CreateDefaultSubobject<UEBBallisticImpactComponent>(
+        TEXT("BallisticImpactComponent")
+    );
+    
+    // Configure component
+    BallisticImpactComponent->bEnableBallisticCalculations = true;
+    BallisticImpactComponent->bUseMathematicalPenetration = true;
+    BallisticImpactComponent->MaterialResponseMap = DefaultMaterialResponseMap;
+}
+```
+
+### Blueprint Setup
+
+1. **Add Component**: In Blueprint editor, add `EB Ballistic Impact Component`
+2. **Configure Properties**: Set material response map and calculation mode
+3. **Bind Events**: Connect `OnBallisticImpact` and `OnBallisticRicochet` events
+
+### Material Response Map
+
+Configure how different materials respond to impacts:
+
+```cpp
+// Create material response map
+UEBMaterialResponseMap* ResponseMap = NewObject<UEBMaterialResponseMap>();
+
+// Configure steel response
+FEBMaterialResponseMapEntry SteelEntry;
+SteelEntry.PenetrationDepthMultiplier = 0.3f;
+SteelEntry.RicochetProbabilityMultiplier = 2.0f;
+SteelEntry.UseMathematicalProperties = true;
+ResponseMap->Map.Add(SteelMaterial, SteelEntry);
+
+// Configure wood response
+FEBMaterialResponseMapEntry WoodEntry;
+WoodEntry.PenetrationDepthMultiplier = 2.0f;
+WoodEntry.RicochetProbabilityMultiplier = 0.1f;
+ResponseMap->Map.Add(WoodMaterial, WoodEntry);
+
+// Assign to component
+BallisticImpactComponent->MaterialResponseMap = ResponseMap;
+```
+
+## Impact Calculations
+
+### Penetration Calculation
+
+The component calculates penetration depth based on physics or artistic models:
+
+```cpp
+FVector CalculateBallisticImpact(
+    const FVector& ImpactLocation,
+    const FVector& ProjectileVelocity,
+    const FMathematicalBulletProperties& BulletProperties,
+    UPhysicalMaterial* HitMaterial,
+    float& OutPenetrationDepth,
+    bool& bOutDidPenetrate,
+    FVector& OutExitLocation
+);
+```
+
+#### Mathematical Mode
+Uses physics-based calculations:
+- **Taylor-Hopkinson Formula**: For ductile materials
+- **Recht-Ipson Model**: For thick targets
+- **Energy Transfer**: Realistic energy absorption
+
+#### Artistic Mode
+Uses configurable artistic properties:
+- **Multiplier-Based**: Simple penetration multipliers
+- **Material-Specific**: Different values per material
+- **Designer Control**: Full artistic control
+
+### Ricochet Calculation
+
+Determines ricochet probability and direction:
+
+```cpp
+FVector CalculateRicochet(
+    const FVector& ImpactLocation,
+    const FVector& ImpactNormal,
+    const FVector& ProjectileVelocity,
+    const FMathematicalBulletProperties& BulletProperties,
+    UPhysicalMaterial* HitMaterial,
+    float& OutEnergyRetained,
+    bool& bOutDidRicochet
+);
+```
+
+#### Ricochet Factors
+- **Impact Angle**: Critical angle for ricochet
+- **Surface Hardness**: Harder surfaces ricochet more
+- **Projectile Velocity**: Higher velocity reduces ricochet
+- **Material Properties**: Surface roughness and composition
+
+## Event Handling Patterns
+
+### Basic Impact Response
+
+```cpp
+void AMyTargetActor::BeginPlay()
+{
+    Super::BeginPlay();
+    
+    // Bind to impact events
+    if (BallisticImpactComponent)
+    {
+        BallisticImpactComponent->OnBallisticImpact.AddDynamic(
+            this, &AMyTargetActor::HandleBallisticImpact
+        );
+        
+        BallisticImpactComponent->OnBallisticRicochet.AddDynamic(
+            this, &AMyTargetActor::HandleBallisticRicochet
+        );
+    }
+}
+
+void AMyTargetActor::HandleBallisticImpact(
+    FVector ImpactLocation,
+    FVector ImpactNormal, 
+    UPhysicalMaterial* HitMaterial,
+    float PenetrationDepth,
+    bool bDidPenetrate)
+{
+    // Spawn appropriate effects
+    if (bDidPenetrate)
+    {
+        SpawnPenetrationEffect(ImpactLocation, ImpactNormal);
+        
+        // Apply damage or destruction
+        if (PenetrationDepth > DestructionThreshold)
+        {
+            DestroySection(ImpactLocation);
+        }
+    }
+    else
+    {
+        SpawnImpactEffect(ImpactLocation, ImpactNormal);
+    }
+    
+    // Apply impulse to physics objects
+    if (UPrimitiveComponent* PrimComp = GetComponentByClass<UPrimitiveComponent>())
+    {
+        FVector ImpactForce = CalculateImpactForce(PenetrationDepth);
+        PrimComp->AddImpulseAtLocation(ImpactForce, ImpactLocation);
+    }
+}
+
+void AMyTargetActor::HandleBallisticRicochet(
+    FVector RicochetLocation,
+    FVector RicochetDirection,
+    UPhysicalMaterial* HitMaterial,
+    float EnergyRetained)
+{
+    // Spawn ricochet effects
+    SpawnRicochetEffect(RicochetLocation, RicochetDirection);
+    
+    // Play ricochet sound
+    if (RicochetSound)
+    {
+        UGameplayStatics::PlaySoundAtLocation(
+            this, RicochetSound, RicochetLocation
+        );
+    }
+    
+    // Create secondary projectile if needed
+    if (bCreateRicochetProjectile && EnergyRetained > 0.3f)
+    {
+        SpawnRicochetProjectile(RicochetLocation, RicochetDirection, EnergyRetained);
+    }
+}
+```
+
+### Advanced Impact Handling
+
+```cpp
+void AArmorPlate::HandleBallisticImpact(
+    FVector ImpactLocation,
+    FVector ImpactNormal,
+    UPhysicalMaterial* HitMaterial,
+    float PenetrationDepth,
+    bool bDidPenetrate)
+{
+    // Calculate damage to armor
+    float ArmorDamage = CalculateArmorDamage(PenetrationDepth);
+    CurrentArmorIntegrity -= ArmorDamage;
+    
+    // Check for armor failure
+    if (CurrentArmorIntegrity <= 0.0f)
+    {
+        // Armor failed - allow full penetration
+        bArmorFailed = true;
+        OnArmorFailed.Broadcast(ImpactLocation);
+        
+        // Spawn armor failure effects
+        SpawnArmorFailureEffect(ImpactLocation);
+    }
+    else if (bDidPenetrate)
+    {
+        // Partial penetration - reduce projectile energy
+        float EnergyReduction = CalculateEnergyReduction(PenetrationDepth);
+        OnEnergyReduced.Broadcast(EnergyReduction);
+    }
+    
+    // Update armor visual state
+    UpdateArmorVisuals(ImpactLocation, PenetrationDepth);
+}
+```
+
+## Blueprint Integration
+
+### Blueprint Events
+
+The component automatically calls Blueprint events when impacts occur:
+
+```cpp
+// Blueprint implementable events
+UFUNCTION(BlueprintImplementableEvent, Category = "Ballistics")
+void OnBallisticImpactBP(
+    FVector ImpactLocation,
+    FVector ImpactNormal,
+    UPhysicalMaterial* HitMaterial,
+    float PenetrationDepth,
+    bool bDidPenetrate
+);
+
+UFUNCTION(BlueprintImplementableEvent, Category = "Ballistics")
+void OnBallisticRicochetBP(
+    FVector RicochetLocation,
+    FVector RicochetDirection,
+    UPhysicalMaterial* HitMaterial,
+    float EnergyRetained
+);
+```
+
+### Blueprint Utilities
+
+```cpp
+// Get material properties in Blueprint
+UFUNCTION(BlueprintCallable, Category = "Ballistics")
+UEBMaterialPropertiesAsset* GetMaterialProperties(UPhysicalMaterial* PhysicalMaterial);
+
+// Get material response configuration
+UFUNCTION(BlueprintCallable, Category = "Ballistics")
+FEBMaterialResponseMapEntry GetMaterialResponse(UPhysicalMaterial* PhysicalMaterial);
+```
+
+## Performance Considerations
+
+### Calculation Optimization
+
+```cpp
+// Cache frequently used calculations
+struct FBallisticCalculationCache
+{
+    UPhysicalMaterial* LastMaterial;
+    float LastVelocity;
+    float LastPenetrationDepth;
+    float LastRicochetProbability;
+    
+    bool IsValid(UPhysicalMaterial* Material, float Velocity) const
+    {
+        return LastMaterial == Material && 
+               FMath::IsNearlyEqual(LastVelocity, Velocity, 1.0f);
+    }
+};
+```
+
+### LOD System
+
+```cpp
+// Reduce calculation complexity based on distance
+void UpdateCalculationLOD(float DistanceToPlayer)
+{
+    if (DistanceToPlayer > 1000.0f)
+    {
+        // Simplified calculations for distant impacts
+        bUseMathematicalPenetration = false;
+        bEnableBallisticCalculations = false;
+    }
+    else
+    {
+        // Full calculations for nearby impacts
+        bUseMathematicalPenetration = true;
+        bEnableBallisticCalculations = true;
+    }
+}
+```
+
+## Networking
+
+### Network Optimization
+
+```cpp
+// Efficient impact replication
+UFUNCTION(NetMulticast, Reliable)
+void MulticastBallisticImpact(
+    FVector_NetQuantize ImpactLocation,
+    FVector_NetQuantizeNormal ImpactNormal,
+    uint8 MaterialIndex,
+    float PenetrationDepth,
+    bool bDidPenetrate
+);
+```
+
+### Authority Handling
+
+```cpp
+void ProcessBallisticImpact(...)
+{
+    if (GetOwner()->HasAuthority())
+    {
+        // Server performs authoritative calculations
+        float AuthoritativePenetration = CalculateAuthoritativePenetration(...);
+        
+        // Replicate to clients
+        MulticastBallisticImpact(ImpactLocation, ImpactNormal, 
+                               MaterialIndex, AuthoritativePenetration, bDidPenetrate);
+    }
+    else
+    {
+        // Client performs predictive calculations
+        float PredictivePenetration = CalculatePredictivePenetration(...);
+        
+        // Apply local effects immediately
+        ApplyLocalEffects(ImpactLocation, PredictivePenetration);
+    }
+}
+```
+
+## Debug and Visualization
+
+### Debug Features
+
+```cpp
+// Enable debug visualization
+void EnableDebugVisualization(bool bEnable)
+{
+    if (bEnable)
+    {
+        // Show impact locations
+        DrawDebugSphere(GetWorld(), LastImpactLocation, 10.0f, 
+                       12, FColor::Red, false, 2.0f);
+        
+        // Show penetration depth
+        DrawDebugLine(GetWorld(), LastImpactLocation, 
+                     LastImpactLocation + (LastImpactNormal * LastPenetrationDepth),
+                     FColor::Blue, false, 2.0f, 0, 2.0f);
+        
+        // Display calculation values
+        UE_LOG(LogTemp, Warning, TEXT("Penetration: %f cm"), LastPenetrationDepth);
+        UE_LOG(LogTemp, Warning, TEXT("Ricochet Probability: %f"), LastRicochetProbability);
+    }
+}
+```
+
+### Performance Monitoring
+
+```cpp
+// Monitor impact calculation performance
+void MonitorPerformance()
+{
+    SCOPE_CYCLE_COUNTER(STAT_BallisticImpactCalculation);
+    
+    // Track calculation times
+    double StartTime = FPlatformTime::Seconds();
+    
+    // Perform calculations...
+    
+    double EndTime = FPlatformTime::Seconds();
+    double CalculationTime = EndTime - StartTime;
+    
+    // Warn if calculations are taking too long
+    if (CalculationTime > 0.001) // 1ms threshold
+    {
+        UE_LOG(LogTemp, Warning, TEXT("Ballistic calculation took %f ms"), 
+               CalculationTime * 1000.0);
+    }
+}
+```
+
+## Common Use Cases
+
+### Destructible Objects
+
+```cpp
+class ADestructibleTarget : public AActor
+{
+private:
+    UPROPERTY(VisibleAnywhere)
+    UEBBallisticImpactComponent* BallisticImpactComponent;
+    
+    UPROPERTY(EditAnywhere)
+    float DestructionThreshold = 50.0f;
+    
+    UFUNCTION()
+    void HandleBallisticImpact(FVector ImpactLocation, FVector ImpactNormal,
+                              UPhysicalMaterial* HitMaterial, float PenetrationDepth,
+                              bool bDidPenetrate)
+    {
+        if (PenetrationDepth > DestructionThreshold)
+        {
+            // Destroy the object
+            SpawnDestructionEffect(ImpactLocation);
+            Destroy();
+        }
+        else
+        {
+            // Add damage/wear
+            AddDamageDecal(ImpactLocation, ImpactNormal);
+        }
+    }
+};
+```
+
+### Reactive Armor Systems
+
+```cpp
+class AReactiveArmor : public AActor
+{
+private:
+    UPROPERTY(VisibleAnywhere)
+    UEBBallisticImpactComponent* BallisticImpactComponent;
+    
+    UPROPERTY(EditAnywhere)
+    float ReactiveArmorEffectiveness = 0.7f;
+    
+    UFUNCTION()
+    void HandleBallisticImpact(FVector ImpactLocation, FVector ImpactNormal,
+                              UPhysicalMaterial* HitMaterial, float PenetrationDepth,
+                              bool bDidPenetrate)
+    {
+        if (bDidPenetrate && !bArmorTriggered)
+        {
+            // Trigger reactive armor
+            TriggerReactiveArmor(ImpactLocation);
+            bArmorTriggered = true;
+            
+            // Reduce effective penetration
+            float ReducedPenetration = PenetrationDepth * (1.0f - ReactiveArmorEffectiveness);
+            
+            // Check if reduced penetration is sufficient
+            if (ReducedPenetration < ArmorThickness)
+            {
+                // Armor successfully stopped the projectile
+                OnArmorSuccess.Broadcast();
+            }
+        }
+    }
+};
+```
+
+## Migration from Legacy System
+
+### Enabling New System
+
+```cpp
+// Enable new impact system on bullets
+void EnableNewImpactSystem(AEBBullet* Bullet)
+{
+    Bullet->UseNewImpactSystem = true;
+    Bullet->UseMathematicalPhysics = true;
+    
+    // Ensure ballistic impact component is configured
+    if (Bullet->BallisticImpactComponent)
+    {
+        Bullet->BallisticImpactComponent->bEnableBallisticCalculations = true;
+        Bullet->BallisticImpactComponent->MaterialResponseMap = DefaultMaterialResponseMap;
+    }
+}
+```
+
+### Converting Legacy Impact Handlers
+
+```cpp
+// Old system
+void OldImpactHandler(FHitResult HitResult, float Damage)
+{
+    // Direct damage application
+    if (AActor* HitActor = HitResult.GetActor())
+    {
+        HitActor->TakeDamage(Damage, ...);
+    }
+}
+
+// New system
+void NewImpactHandler(FVector ImpactLocation, FVector ImpactNormal,
+                     UPhysicalMaterial* HitMaterial, float PenetrationDepth,
+                     bool bDidPenetrate)
+{
+    // Event-driven impact handling
+    if (bDidPenetrate)
+    {
+        float Damage = CalculateDamageFromPenetration(PenetrationDepth);
+        ApplyDamage(Damage);
+    }
+    
+    // Trigger additional effects
+    OnImpactEffects.Broadcast(ImpactLocation, ImpactNormal, bDidPenetrate);
+}
+```
+
+## See Also
+
+- [Spalling System](spalling-system) - Secondary fragment generation
+- [Mathematical Ballistics](mathematical-ballistics) - Physics calculations
+- [Material Response System](material-response-system) - Material configuration
+- [Performance Optimization](../advanced/performance-optimization) - Optimization techniques 

docs/docs/core-concepts/mathematical-ballistics.md

@@ -0,0 +1,465 @@
+# Mathematical Ballistics System
+
+The EasyBallistics mathematical ballistics system provides scientifically accurate calculations for projectile behavior, penetration, and material interactions. This system enables realistic ballistic simulation based on real-world physics principles.
+
+## Overview
+
+The mathematical ballistics system uses empirical formulas and physics-based calculations to determine:
+
+- **Penetration Depth**: Realistic material penetration calculations
+- **Residual Velocity**: Bullet velocity after penetration
+- **Ricochet Probability**: Angle-dependent ricochet calculations
+- **Energy Transfer**: Kinetic energy and momentum calculations
+- **Material Interactions**: Physics-based material responses
+
+## Core Calculations
+
+### Penetration Physics
+
+The system uses multiple penetration models:
+
+#### Taylor-Hopkinson Formula
+Used for calculating perforation limits in ductile materials:
+
+```cpp
+float PenetrationLimit = UEBMathematicalBallistics::CalculateTaylorHopkinsonLimit(
+    BulletProperties,
+    MaterialProperties
+);
+```
+
+**Formula**: `P = (ρ_p * L * v²) / (σ_t * ρ_t)`
+
+Where:
+- `P` = Penetration depth
+- `ρ_p` = Projectile density
+- `L` = Projectile length
+- `v` = Impact velocity
+- `σ_t` = Target material tensile strength
+- `ρ_t` = Target material density
+
+#### Recht-Ipson Model
+Advanced penetration calculation for thick targets:
+
+```cpp
+float PerforationVelocity = UEBMathematicalBallistics::CalculateRechtIpsonVelocity(
+    BulletProperties,
+    MaterialProperties,
+    ThicknessCM
+);
+```
+
+**Applications**:
+- Armor penetration calculations
+- Thick plate perforation
+- Ballistic limit determination
+
+### Ricochet Calculations
+
+#### Critical Angle Determination
+Calculate the minimum angle for ricochet:
+
+```cpp
+float CriticalAngle = UEBMathematicalBallistics::CalculateCriticalRicochetAngle(
+    BulletProperties,
+    MaterialProperties,
+    VelocityMPS
+);
+```
+
+**Factors Affecting Ricochet**:
+- **Impact Angle**: Grazing angles increase ricochet probability
+- **Velocity**: Higher velocity reduces ricochet probability
+- **Material Hardness**: Harder materials increase ricochet
+- **Bullet Shape**: Pointed bullets ricochet less than blunt bullets
+
+#### Probability Calculation
+Physics-based ricochet probability:
+
+```cpp
+float RicochetProbability = UEBMathematicalBallistics::CalculateRicochetProbability(
+    BulletProperties,
+    MaterialProperties,
+    VelocityMPS,
+    ImpactAngleDegrees
+);
+```
+
+### Energy and Momentum
+
+#### Kinetic Energy
+```cpp
+float KineticEnergy = UEBMathematicalBallistics::CalculateKineticEnergy(
+    BulletProperties,
+    VelocityMPS
+);
+// Formula: KE = (1/2) * m * v²
+```
+
+#### Momentum Transfer
+```cpp
+float Momentum = UEBMathematicalBallistics::CalculateMomentum(
+    BulletProperties,
+    VelocityMPS
+);
+// Formula: p = m * v
+```
+
+## Advanced Features
+
+### Bullet Expansion Modeling
+
+The system models bullet expansion based on impact conditions:
+
+```cpp
+float ExpansionDiameter = UEBMathematicalBallistics::CalculateBulletExpansion(
+    BulletProperties,
+    MaterialProperties,
+    VelocityMPS
+);
+```
+
+**Expansion Factors**:
+- **Velocity Threshold**: Minimum velocity for expansion
+- **Bullet Type**: Hollow point vs. full metal jacket
+- **Target Material**: Soft vs. hard materials
+- **Impact Angle**: Angle affects expansion pattern
+
+### Drag Coefficient Calculation
+
+Realistic drag based on ballistic coefficient:
+
+```cpp
+float DragCoefficient = UEBMathematicalBallistics::CalculateDragCoefficient(
+    BulletProperties,
+    MachNumber
+);
+```
+
+**Ballistic Coefficient Models**:
+- **G1 Model**: Traditional standard projectile reference
+- **G7 Model**: Modern boat-tail reference (more accurate)
+- **Custom Models**: Application-specific drag curves
+
+## Material Properties Integration
+
+### Physical Material Properties
+
+The system uses comprehensive material data:
+
+```cpp
+struct FMathematicalMaterialProperties
+{
+    float DensityGPerCm3;        // Material density
+    float MaterialHardness;       // Brinell hardness
+    float TensileStrengthMPa;    // Tensile strength
+    float YieldStrengthMPa;      // Yield strength
+    float ElasticModulusGPa;     // Elastic modulus
+    float BallisticLimitVelocity; // Ballistic limit
+    float PerforationCoefficient; // Perforation factor
+    float EnergyAbsorptionCoefficient; // Energy absorption
+};
+```
+
+### Smart Material Recognition
+
+The system can automatically configure properties based on material names:
+
+```cpp
+// Automatically configured materials
+"Steel" -> Steel properties (density 7.85 g/cm³, hardness 200 HB)
+"Aluminum" -> Aluminum properties (density 2.70 g/cm³, hardness 95 HB)
+"Concrete" -> Concrete properties (density 2.40 g/cm³, hardness 20 HB)
+"Kevlar" -> Kevlar properties (density 1.44 g/cm³, high tensile strength)
+```
+
+## Bullet Properties System
+
+### Comprehensive Bullet Definition
+
+```cpp
+struct FMathematicalBulletProperties
+{
+    // Basic Properties
+    float GrainWeight;           // Weight in grains
+    float DiameterInches;        // Diameter in inches
+    float LengthInches;          // Length in inches
+    EBulletType BulletType;      // Type (FMJ, HP, AP, etc.)
+    EBulletMaterial BulletMaterial; // Material composition
+    
+    // Ballistic Properties
+    float BallisticCoefficientG1; // G1 BC
+    float BallisticCoefficientG7; // G7 BC
+    bool UseG7Model;             // Use G7 instead of G1
+    float SectionalDensity;      // Sectional density
+    
+    // Penetration Properties
+    float BulletHardness;        // Bullet hardness
+    float PenetrationEnergyThreshold; // Energy threshold
+    float ExpansionVelocityThreshold; // Expansion velocity
+    float MaxExpansionMultiplier;     // Maximum expansion
+};
+```
+
+### Bullet Type Effects
+
+Different bullet types have different mathematical properties:
+
+#### Full Metal Jacket (FMJ)
+- **High Penetration**: Maintains shape on impact
+- **Low Expansion**: Minimal deformation
+- **Deep Penetration**: Passes through multiple barriers
+
+#### Hollow Point (HP)
+- **Rapid Expansion**: Expands quickly in soft materials
+- **Energy Transfer**: Transfers energy efficiently
+- **Reduced Penetration**: Expansion limits penetration depth
+
+#### Armor Piercing (AP)
+- **Hardened Core**: Tungsten or steel core
+- **High Penetration**: Designed for hard targets
+- **Minimal Expansion**: Maintains shape through armor
+
+## Utility Functions
+
+### Unit Conversions
+
+The system provides comprehensive unit conversion:
+
+```cpp
+// Velocity conversions
+float MPS = UEBMathematicalBallistics::ConvertFPStoMPS(2800.0f);
+float FPS = UEBMathematicalBallistics::ConvertMPStoFPS(853.44f);
+
+// Energy conversions
+float Joules = UEBMathematicalBallistics::ConvertFtLbsToJoules(1800.0f);
+float FtLbs = UEBMathematicalBallistics::ConvertJoulesToFtLbs(2441.0f);
+```
+
+### Sectional Density Calculation
+
+```cpp
+float SectionalDensity = BulletProperties.GetSectionalDensity();
+// Formula: SD = Weight(grains) / (7000 * Diameter²(inches))
+```
+
+## Performance Optimization
+
+### Calculation Complexity
+
+The mathematical system offers multiple complexity levels:
+
+#### Simple Mode
+- Basic penetration calculations
+- Reduced computational cost
+- Suitable for mobile platforms
+
+#### Full Physics Mode
+- Complete ballistic calculations
+- All material interactions
+- Maximum accuracy
+
+#### Hybrid Mode
+- Essential calculations only
+- Balanced performance/accuracy
+- Recommended for most applications
+
+### Caching System
+
+```cpp
+// Results cached for repeated calculations
+struct BallisticCache
+{
+    float LastVelocity;
+    float LastPenetration;
+    float LastRicochetProbability;
+    // Cache invalidated when conditions change
+};
+```
+
+## Integration Examples
+
+### Basic Penetration Check
+
+```cpp
+void CheckPenetration(AEBBullet* Bullet, UPhysicalMaterial* Material, float Velocity)
+{
+    float PenetrationDepth = UEBMathematicalBallistics::CalculatePenetrationDepth(
+        Bullet->BulletPropertiesAsset->BulletProperties,
+        GetMaterialProperties(Material),
+        Velocity,
+        0.0f // Impact angle
+    );
+    
+    if (PenetrationDepth > MaterialThickness)
+    {
+        // Bullet penetrates
+        float ResidualVelocity = UEBMathematicalBallistics::CalculateResidualVelocity(
+            Bullet->BulletPropertiesAsset->BulletProperties,
+            GetMaterialProperties(Material),
+            Velocity,
+            MaterialThickness
+        );
+        
+        // Continue bullet with reduced velocity
+        Bullet->Velocity = Bullet->Velocity.GetSafeNormal() * ResidualVelocity;
+    }
+}
+```
+
+### Ricochet Determination
+
+```cpp
+void HandleRicochet(AEBBullet* Bullet, FVector ImpactNormal, UPhysicalMaterial* Material)
+{
+    float ImpactAngle = FMath::Acos(FVector::DotProduct(
+        Bullet->Velocity.GetSafeNormal(), 
+        -ImpactNormal
+    ));
+    
+    float RicochetProbability = UEBMathematicalBallistics::CalculateRicochetProbability(
+        Bullet->BulletPropertiesAsset->BulletProperties,
+        GetMaterialProperties(Material),
+        Bullet->Velocity.Size(),
+        FMath::RadiansToDegrees(ImpactAngle)
+    );
+    
+    if (FMath::RandRange(0.0f, 1.0f) < RicochetProbability)
+    {
+        // Calculate ricochet direction
+        FVector RicochetDirection = UKismetMathLibrary::GetReflectionVector(
+            Bullet->Velocity.GetSafeNormal(),
+            ImpactNormal
+        );
+        
+        // Reduce velocity based on energy loss
+        float EnergyRetention = CalculateRicochetEnergyRetention(Material, ImpactAngle);
+        Bullet->Velocity = RicochetDirection * (Bullet->Velocity.Size() * EnergyRetention);
+    }
+}
+```
+
+## Validation and Testing
+
+### Empirical Validation
+
+The mathematical models are validated against:
+
+- **Ballistic Gelatin Tests**: Standard FBI protocol
+- **Armor Testing**: NIJ standards
+- **Academic Research**: Published ballistic studies
+- **Military Data**: Declassified test results
+
+### Debug Visualization
+
+```cpp
+void DebugMathematicalBallistics(AEBBullet* Bullet)
+{
+    if (Bullet->DebugEnabled)
+    {
+        // Display calculated values
+        UE_LOG(LogTemp, Warning, TEXT("Kinetic Energy: %f J"), 
+            UEBMathematicalBallistics::CalculateKineticEnergy(
+                Bullet->BulletPropertiesAsset->BulletProperties,
+                Bullet->Velocity.Size()
+            ));
+        
+        UE_LOG(LogTemp, Warning, TEXT("Sectional Density: %f"), 
+            Bullet->BulletPropertiesAsset->BulletProperties.GetSectionalDensity());
+    }
+}
+```
+
+## Common Applications
+
+### Armor Penetration Analysis
+
+```cpp
+bool CanPenetrateArmor(
+    const FMathematicalBulletProperties& Bullet,
+    const FMathematicalMaterialProperties& Armor,
+    float Velocity,
+    float ArmorThickness
+)
+{
+    float RequiredVelocity = UEBMathematicalBallistics::CalculateRechtIpsonVelocity(
+        Bullet, Armor, ArmorThickness
+    );
+    
+    return Velocity >= RequiredVelocity;
+}
+```
+
+### Ballistic Gelatin Testing
+
+```cpp
+void SimulateGelatinTest(AEBBullet* Bullet)
+{
+    // Standard FBI gelatin properties
+    FMathematicalMaterialProperties Gelatin;
+    Gelatin.DensityGPerCm3 = 1.06f;
+    Gelatin.TensileStrengthMPa = 0.15f;
+    
+    float PenetrationDepth = UEBMathematicalBallistics::CalculatePenetrationDepth(
+        Bullet->BulletPropertiesAsset->BulletProperties,
+        Gelatin,
+        Bullet->Velocity.Size(),
+        0.0f
+    );
+    
+    // Standard: 12-18 inches penetration in gelatin
+    bool PassesTest = (PenetrationDepth >= 30.48f && PenetrationDepth <= 45.72f);
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Unrealistic Penetration Values
+- **Check Material Properties**: Verify density and strength values
+- **Validate Bullet Properties**: Ensure correct mass and dimensions
+- **Review Velocity Units**: Confirm m/s vs. ft/s conversion
+
+#### Incorrect Ricochet Behavior
+- **Impact Angle Calculation**: Verify angle measurement
+- **Material Hardness**: Check hardness values
+- **Velocity Thresholds**: Ensure realistic velocity ranges
+
+#### Performance Issues
+- **Calculation Frequency**: Avoid recalculating unchanged values
+- **Use Caching**: Implement result caching for repeated calculations
+- **Simplify Models**: Use appropriate complexity for platform
+
+### Validation Tests
+
+```cpp
+void ValidateCalculations()
+{
+    // Test known ballistic scenarios
+    FMathematicalBulletProperties NATO556;
+    NATO556.GrainWeight = 55.0f;
+    NATO556.DiameterInches = 0.224f;
+    NATO556.BallisticCoefficientG1 = 0.151f;
+    
+    FMathematicalMaterialProperties Steel;
+    Steel.DensityGPerCm3 = 7.85f;
+    Steel.TensileStrengthMPa = 400.0f;
+    
+    float TestVelocity = 853.44f; // 2800 fps in m/s
+    float Penetration = UEBMathematicalBallistics::CalculatePenetrationDepth(
+        NATO556, Steel, TestVelocity, 0.0f
+    );
+    
+    // Validate against known test data
+    checkf(Penetration > 0.0f && Penetration < 100.0f, 
+        TEXT("Penetration calculation out of expected range"));
+}
+```
+
+## See Also
+
+- [Bullet Properties](bullet-properties) - Configure bullet characteristics
+- [Material Response System](material-response-system) - Material interactions
+- [Ballistic Impact Component](ballistic-impact-component) - Impact event handling
+- [Performance Optimization](../advanced/performance-optimization) - Optimization techniques 

docs/docs/core-concepts/overview.md

@@ -57,6 +57,14 @@ The material system consists of:
 - **Material Properties**: Ballistic characteristics (density, hardness)
 - **Material Response Maps**: Gameplay rules for interactions
 
+### 5. Spalling System
+
+**Secondary Fragment Generation** handles:
+- Physics-based fragment creation on high-energy impacts
+- Fragment mass and velocity distribution
+- Spalling thresholds based on material properties
+- Performance optimization for fragment management
+
 ## Data Flow
 
 ### Firing Sequence

docs/docs/core-concepts/spalling-system.md

@@ -0,0 +1,254 @@
+# Spalling System
+
+The EasyBallistics spalling system simulates the generation of secondary fragments when bullets impact materials at high velocity. This advanced feature adds realistic ballistic behavior for high-energy impacts.
+
+## What is Spalling?
+
+Spalling occurs when a high-velocity projectile impacts a material surface, causing fragments of the target material to break away from the back surface. This is particularly common with:
+
+- Armor penetration scenarios
+- Concrete and masonry impacts
+- Metal plate impacts at high velocity
+- Composite material failures
+
+## Physics-Based Calculations
+
+The spalling system uses realistic physics calculations:
+
+### Energy Distribution
+- **Impact Energy Analysis**: Calculates kinetic energy of the primary projectile
+- **Spalling Energy Fraction**: Typically 5-20% of impact energy creates spalling
+- **Fragment Energy Distribution**: Energy distributed among multiple fragments
+
+### Fragment Generation
+- **Fragment Count**: Based on impact energy and material hardness
+- **Mass Distribution**: Realistic fragment mass distribution (smaller fragments more common)
+- **Velocity Calculation**: Fragment velocities calculated from energy conservation
+
+### Directional Physics
+- **Spall Cone**: Fragments ejected in a cone away from the impact surface
+- **Angle Dependence**: Grazing impacts create wider spall patterns
+- **Surface Normal Influence**: Fragment direction combines reflection and surface normal
+
+## Configuration
+
+### Enable Spalling on Bullets
+
+```cpp
+// In bullet configuration
+Bullet->EnableSpalling = true;
+Bullet->UseNewImpactSystem = true;
+```
+
+### Material Response Map Setup
+
+Configure spalling properties for each material:
+
+```yaml
+Material Response Map Entry:
+  Enable Spalling: true
+  Spall Velocity Threshold: 1500.0 # fps
+  Spall Fragment Count: 8
+  Spall Fragment Class: BP_SpallFragment
+  Spall Mass Multiplier: 1.0
+```
+
+### Physical Material Properties
+
+Spalling calculations consider material properties:
+
+```yaml
+Material Properties:
+  Density: 7.85 # g/cm³ (affects fragment count)
+  Material Hardness: 200.0 # Brinell (affects fragmentation)
+  Tensile Strength: 400.0 # MPa (affects spalling threshold)
+```
+
+## Spalling Thresholds
+
+### Velocity-Based Thresholds
+- **Base Threshold**: Set per material type
+- **Density Scaling**: Denser materials require higher velocity
+- **Dynamic Adjustment**: Threshold adjusted based on impact angle
+
+### Energy-Based Thresholds
+- **Minimum Energy**: 50 J * material density
+- **Impact Angle**: Perpendicular impacts more effective
+- **Material Resistance**: Harder materials resist spalling
+
+## Fragment Behavior
+
+### Fragment Properties
+- **Mass Range**: 2-20% of parent bullet mass
+- **Velocity Range**: 200-800 m/s typical
+- **Lifetime**: Short-lived, despawn quickly
+- **Damage**: Reduced compared to primary projectile
+
+### Fragment Physics
+- **Drag**: Higher drag coefficient due to irregular shape
+- **Trajectory**: Affected by gravity and air resistance
+- **Secondary Impacts**: Can cause additional damage
+
+## Blueprint Integration
+
+### Spalling Events
+
+```cpp
+// Handle spalling fragment generation
+UFUNCTION(BlueprintImplementableEvent, Category = "Spalling")
+void OnSpallFragmentGenerated(
+    FVector FragmentLocation,
+    FVector FragmentVelocity,
+    float FragmentMass,
+    UPhysicalMaterial* Material
+);
+```
+
+### Custom Spalling Logic
+
+```cpp
+// Override spalling behavior
+UFUNCTION(BlueprintNativeEvent, Category = "Spalling")
+bool ShouldGenerateSpalling(
+    FVector ImpactVelocity,
+    UPhysicalMaterial* Material
+) const;
+
+// Custom fragment generation
+UFUNCTION(BlueprintCallable, Category = "Spalling")
+void GenerateSpallFragments(
+    FVector ImpactLocation,
+    FVector ImpactVelocity,
+    FVector ImpactNormal,
+    UPhysicalMaterial* Material,
+    AActor* HitActor
+);
+```
+
+## Performance Considerations
+
+### Optimization Settings
+- **Fragment Pooling**: Reuse fragment objects for performance
+- **LOD System**: Reduce fragment count at distance
+- **Culling**: Despawn fragments outside view
+- **Max Fragments**: Limit simultaneous fragment count
+
+### Platform Scaling
+```cpp
+// Performance scaling by platform
+#if PLATFORM_MOBILE
+    SpallFragmentCount = 3;  // Reduced for mobile
+#elif PLATFORM_CONSOLE
+    SpallFragmentCount = 6;  // Moderate for consoles
+#else
+    SpallFragmentCount = 12; // Full detail for PC
+#endif
+```
+
+## Material-Specific Behavior
+
+### Steel/Metal
+- **High Fragment Count**: 8-12 fragments typical
+- **High Velocity**: Fragments retain significant energy
+- **Sharp Angles**: Metallic spalling creates sharp fragments
+
+### Concrete/Masonry
+- **Moderate Fragment Count**: 4-8 fragments
+- **Lower Velocity**: Concrete fragments slower
+- **Dust and Debris**: Additional particle effects recommended
+
+### Composite Materials
+- **Variable Behavior**: Depends on material composition
+- **Fiber Separation**: Different fragment patterns
+- **Delamination**: Layer separation effects
+
+## Spalling Applications
+
+### Armor Systems
+- **Spall Liner**: Modeling spall protection systems
+- **Penetration Analysis**: Realistic armor penetration
+- **Fragment Containment**: Spall suppression systems
+
+### Destructible Environments
+- **Wall Penetration**: Fragments through walls
+- **Cover Degradation**: Spalling reduces cover effectiveness
+- **Environmental Damage**: Realistic destruction patterns
+
+### Gameplay Mechanics
+- **Area Denial**: Spalling creates danger zones
+- **Ricochet Patterns**: Complex fragment trajectories
+- **Suppression Effects**: Psychological impact of spalling
+
+## Common Issues and Solutions
+
+### No Spalling Generated
+- Check `EnableSpalling = true` on bullet
+- Verify material has spalling properties configured
+- Ensure impact velocity exceeds threshold
+- Confirm `UseNewImpactSystem = true`
+
+### Too Many Fragments
+- Reduce `SpallFragmentCount` in material response
+- Implement distance-based LOD
+- Use fragment pooling
+- Consider performance budget
+
+### Poor Fragment Physics
+- Verify material density settings
+- Check impact angle calculations
+- Ensure proper fragment mass distribution
+- Review energy conservation calculations
+
+## Advanced Features
+
+### Custom Fragment Classes
+```cpp
+// Create specialized fragment types
+UCLASS(BlueprintType)
+class MYGAME_API AMetalSpallFragment : public AEBBullet
+{
+    GENERATED_BODY()
+
+public:
+    // Custom fragment behavior
+    virtual void BeginPlay() override;
+    virtual void OnImpact(...) override;
+};
+```
+
+### Multi-Stage Spalling
+```cpp
+// Fragments that can generate sub-fragments
+void ASpallFragment::OnImpact(...)
+{
+    if (CanGenerateSubFragments())
+    {
+        GenerateSubSpalling();
+    }
+}
+```
+
+### Spalling Visualization
+```cpp
+// Debug visualization for spalling
+void AEBBullet::DebugSpalling()
+{
+    if (DebugEnabled && EnableSpalling)
+    {
+        DrawDebugSphere(GetWorld(), 
+            SpallOrigin, 
+            SpallRadius, 
+            16, 
+            FColor::Orange, 
+            false, 
+            2.0f);
+    }
+}
+```
+
+## See Also
+
+- [Material Response System](material-response-system) - Configure spalling properties
+- [Ballistic Impact Component](ballistic-impact-component) - Event handling
+- [Performance Optimization](../advanced/performance-optimization) - Spalling performance
+- [Mathematical Ballistics](mathematical-ballistics) - Physics calculations 

docs/docs/intro.md

@@ -69,13 +69,19 @@ graph TD
 2. **[Quick Start](getting-started/quick-start)** - Create your first weapon in 10 minutes
 3. **[Core Concepts](core-concepts/overview)** - Understand the system architecture
 
+## Core Systems
+
+4. **[Mathematical Ballistics](core-concepts/mathematical-ballistics)** - Physics-based calculations and formulas
+5. **[Ballistic Impact Component](core-concepts/ballistic-impact-component)** - Event-driven impact handling
+6. **[Spalling System](core-concepts/spalling-system)** - Secondary fragment generation
+
 ## Advanced Topics
 
-4. **[Advanced Weapon Systems](tutorials/advanced-weapon-systems)** - Smart ammunition and complex firing modes
-5. **[Multiplayer Guide](advanced/multiplayer-guide)** - Network optimization and server authority
-6. **[Performance Optimization](advanced/performance-optimization)** - Achieve optimal performance
-7. **[Editor Tools](advanced/editor-tools)** - Streamlined asset creation workflows
-8. **[Migration Guide](advanced/migration-guide)** - Upgrade from older versions
+7. **[Advanced Weapon Systems](tutorials/advanced-weapon-systems)** - Smart ammunition and complex firing modes
+8. **[Multiplayer Guide](advanced/multiplayer-guide)** - Network optimization and server authority
+9. **[Performance Optimization](advanced/performance-optimization)** - Achieve optimal performance
+10. **[Editor Integration](advanced/editor-integration)** - Asset creation and workflow optimization
+11. **[Migration Guide](advanced/migration-guide)** - Upgrade from older versions
 
 ## Support
 

docs/sidebars.js

@@ -31,6 +31,9 @@ const sidebars = {
         'core-concepts/overview',
         'core-concepts/gatling-mechanics',
         'core-concepts/trajectory-prediction',
+        'core-concepts/mathematical-ballistics',
+        'core-concepts/ballistic-impact-component',
+        'core-concepts/spalling-system',
       ],
     },
     {
@@ -47,6 +50,7 @@ const sidebars = {
         'advanced/multiplayer-guide',
         'advanced/performance-optimization',
         'advanced/editor-tools',
+        'advanced/editor-integration',
         'advanced/migration-guide',
       ],
     },