BallisticsDocs/docs/docs/troubleshooting.md

Troubleshooting Guide

Common issues and solutions for EasyBallistics.

Installation Issues

Plugin Not Appearing in Plugin Manager

Symptoms:

• EasyBallistics doesn't show up in Edit → Plugins
• No Ballistics category in asset creation menu

Solutions:

1. Check UE Version Compatibility

   Required: Unreal Engine 5.6.0 or later
   Current: Check Help → About Unreal Editor
   

2. Verify Plugin Location

   Correct path: YourProject/Plugins/EasyBallistics/
   Check for: EasyBallistics.uplugin file
   

3. Regenerate Project Files

   • Right-click your .uproject file
   • Select "Generate Visual Studio project files"
   • Restart Unreal Engine

4. Clear Derived Data Cache

   • Edit → Developer → Derived Data
   • Click "Clear"
   • Restart editor

Compilation Errors

Error: "Module 'EasyBallistics' could not be loaded"

// Add to YourProject.Build.cs
PublicDependencyModuleNames.AddRange(new string[] {
    "Core",
    "CoreUObject", 
    "Engine",
    "EasyBallistics"  // Add this line
});

Error: "Failed to import class 'EBBullet'"

1. Ensure plugin is enabled
2. Check that EasyBallistics.Build.cs exists
3. Verify all source files are present
4. Clean and rebuild project

Runtime Issues

Bullets Not Spawning

Symptoms:

• Fire input triggers but no bullets appear
• No muzzle flash or effects

Debugging Steps:

1. Check Barrel Configuration

   // Verify these are set:
   BulletClass = AEBBullet::StaticClass()
   BulletPropertiesAsset = Valid asset
   MuzzleVelocityMin > 0
   MuzzleVelocityMax > 0
   

2. Verify Spawning Logic

   // Add debug logging
   UE_LOG(LogTemp, Warning, TEXT("Attempting to fire bullet"));
   
   if (!BulletClass)
   {
       UE_LOG(LogTemp, Error, TEXT("BulletClass is null!"));
       return;
   }
   

3. Check World Reference

   // Ensure valid world context
   UWorld* World = GetWorld();
   if (!World)
   {
       UE_LOG(LogTemp, Error, TEXT("No valid world for bullet spawn"));
       return;
   }
   

Bullets Spawning But Not Moving

Symptoms:

• Bullets appear at muzzle but don't travel
• Static bullet actors in world

Solutions:

1. Check Initial Velocity

   // Bullet velocity should be set on spawn
   Bullet->Velocity = MuzzleDirection * MuzzleVelocity;
   
   // Verify velocity is not zero
   if (Bullet->Velocity.IsNearlyZero())
   {
       UE_LOG(LogTemp, Warning, TEXT("Bullet velocity is zero!"));
   }
   

2. Verify Actor Tick

   // In bullet constructor, ensure:
   PrimaryActorTick.bCanEverTick = true;
   

3. Check Physics Settings

   // Ensure physics simulation is enabled
   Bullet->SetActorEnableCollision(true);
   

No Impact Detection

Symptoms:

• Bullets pass through objects without impact
• No impact events or effects

Debugging Steps:

1. Check Collision Settings

   // Verify collision channel
   TraceChannel = ECC_WorldStatic  // or appropriate channel
   TraceComplex = true  // for complex collision
   

2. Verify Target Collision

   • Ensure target has collision enabled
   • Check collision response to bullet trace channel
   • Verify mesh has collision geometry

3. Debug Visualization

   // Enable debug traces
   Bullet->DebugEnabled = true;
   Bullet->DebugTrailTime = 2.0f;
   

Incorrect Penetration/Ricochet Behavior

Symptoms:

• Bullets always penetrate or never penetrate
• Ricochet behavior doesn't match material properties

Solutions:

1. Check Material Response Map

   // Verify material is in response map
   if (!MaterialResponseMap->Map.Contains(PhysicalMaterial))
   {
       UE_LOG(LogTemp, Warning, TEXT("Material not found in response map"));
   }
   

2. Verify Physical Material Assignment

   • Check target mesh has Physical Material assigned
   • Ensure Physical Material is not null in hit result

3. Check New Impact System

   // Ensure new system is enabled
   Bullet->UseNewImpactSystem = true;
   
   // Verify component exists
   if (!Bullet->BallisticImpactComponent)
   {
       UE_LOG(LogTemp, Error, TEXT("BallisticImpactComponent is null"));
   }
   

Performance Issues

Low Frame Rate with Many Bullets

Symptoms:

• FPS drops when firing rapidly
• Hitches during bullet simulation

Optimization Steps:

1. Enable Object Pooling

   Bullet->EnablePooling = true;
   Bullet->MaxPoolSize = 50;  // Adjust based on needs
   

2. Reduce Trace Complexity

   // Reduce traces per step
   Bullet->MaxTracesPerStep = 4;  // Down from 8
   
   // Use simple collision for distant bullets
   Bullet->TraceComplex = false;
   

3. Implement LOD System

   // Distance-based quality scaling
   float Distance = FVector::Dist(Bullet->GetActorLocation(), PlayerLocation);
   if (Distance > 5000.0f)
   {
       Bullet->FixedStepSeconds = 0.2f;  // Lower frequency
   }
   

4. Profile Performance

   // Use built-in profiling
   stat game
   stat engine
   stat collision
   

Memory Usage Issues

Symptoms:

• Increasing memory usage over time
• Out of memory errors during extended play

Solutions:

1. Check Pool Cleanup

   // Ensure bullets are properly deactivated
   void AEBBullet::Deactivate()
   {
       SetActorHiddenInGame(true);
       SetActorEnableCollision(false);
       DeactivateToPool();  // Return to pool
   }
   

2. Limit Pool Sizes

   // Prevent unlimited pool growth
   Bullet->MaxPoolSize = 100;  // Hard limit
   

3. Monitor Actor Count

   // Debug actor counts
   UE_LOG(LogTemp, Warning, TEXT("Active bullets: %d"), 
       GetWorld()->GetActorCount<AEBBullet>());
   

Network Issues

Bullets Not Replicating

Symptoms:

• Bullets visible on server but not clients
• Desync between players

Solutions:

1. Check Replication Settings

   // In bullet constructor
   bReplicates = true;
   SetReplicateMovement(true);
   

2. Verify Network Role

   // Only spawn bullets on server
   if (HasAuthority())
   {
       SpawnBullet();
   }
   

3. Check Bandwidth Usage

   net.PackageMap.DebugObject BulletClass
   stat net
   

Prediction Issues

Symptoms:

• Laggy bullet impacts
• Bullets appear to "jump" position

Solutions:

1. Enable Client Prediction

   // Allow client-side impact prediction
   Bullet->bNetUseOwnerRelevancy = true;
   

2. Adjust Prediction Settings

   // Fine-tune prediction parameters
   Bullet->NetCullDistanceSquared = 10000000.0f;  // 1000m
   

Blueprint Issues

Events Not Firing

Symptoms:

• OnBallisticImpact events don't trigger
• Custom impact logic not executing

Solutions:

1. Check Event Binding

   // Verify event is bound in BeginPlay
   BallisticImpactComponent->OnBallisticImpact.AddDynamic(
       this, &AMyActor::HandleImpact);
   

2. Verify Component Reference

   • Ensure BallisticImpactComponent exists on actor
   • Check component is properly initialized

3. Debug Event Calls

   // Add logging to verify events
   void HandleImpact(/* parameters */)
   {
       UE_LOG(LogTemp, Warning, TEXT("Impact event received"));
   }
   

Asset References Not Working

Symptoms:

• Bullet Properties Asset shows as None
• Material Response Map not found

Solutions:

1. Check Asset Paths

   // Verify asset references are valid
   if (!BulletPropertiesAsset)
   {
       UE_LOG(LogTemp, Error, TEXT("BulletPropertiesAsset is null"));
   }
   

2. Recreate Asset References

   • Delete and reassign asset references
   • Check for missing asset redirects

Debug Tools

Enable Debug Visualization

// In bullet settings
DebugEnabled = true
DebugTrailTime = 2.0
DebugTrailWidth = 1.0
DebugTrailColorFast = Green
DebugTrailColorSlow = Red

Impact Information Widget

EasyBallistics includes a widget to display detailed information about bullet impacts in real-time. This is useful for debugging penetration, ricochets, and material responses.

How to Enable:

1. Enable on Barrel: On your EBBarrel component, set the DebugImpactInfo boolean property to true.
2. Create a Widget Blueprint:
   • In the Content Browser, click "Add New" -> "User Interface" -> "Widget Blueprint".
   • In the "Pick Parent Class" dialog, search for and select EBDebugImpactWidget.
   • Name and save your new widget Blueprint. You can customize its appearance here.
3. Assign to Bullet: On your EBBullet asset, find the DebugWidgetClass property and assign the Widget Blueprint you just created.

Displayed Information:

When enabled, a widget will appear at the location of an impact, showing the following:

• Impact Type: Whether the bullet RICOCHET, PENETRATION, or was STOPPED.
• Material: The name of the UPhysicalMaterial that was hit.
• Velocity: The bullet's velocity at impact, in meters per second (m/s) and kilometers per hour (km/h).
• Mass: The effective mass of the bullet in kilograms (kg).
• Diameter: The effective diameter of the bullet in centimeters (cm).
• Energy: The kinetic energy of the bullet at impact, in Joules (J).
• Penetration: The depth of penetration in centimeters (cm).

Console Commands

// Show bullet debug info
showdebug collision
showdebug physics

// Network debugging  
net.PackageMap.DebugObject AEBBullet
stat net

// Performance profiling
stat game
stat collision
stat memory

Logging Categories

Add to DefaultEngine.ini:

[Core.Log]
LogEasyBallistics=VeryVerbose
LogNetPlayerMovement=Verbose
LogCollision=Warning

Getting Help

Before Reporting Issues

1. Check Documentation

   • Review relevant API documentation
   • Check tutorials for similar setups

2. Gather Information

   • UE version and platform
   • Plugin version
   • Minimal reproduction steps
   • Error logs and stack traces

3. Search Existing Issues

   • Check GitHub issues
   • Search community forums

Support Channels

• GitHub Issues: Report bugs and feature requests
• Discord: Real-time community support
• Forums: Unreal Engine community forums
• Email: support@easyballistics.com

Issue Template

When reporting issues, include:

**Environment:**
- UE Version: 5.6.0
- Platform: Windows 10
- Plugin Version: 2.83

**Issue Description:**
Brief description of the problem

**Steps to Reproduce:**
1. Step one
2. Step two
3. Expected vs actual behavior

**Logs:**
Attach relevant log files

**Additional Context:**
Screenshots, videos, or other helpful information