BallisticsDocs/docs/docs/api/debug-commands-reference.md

Debug Commands Reference

EasyBallistics provides a comprehensive set of debug commands and visualization tools to help developers troubleshoot and optimize their ballistic systems.

Console Commands

Core Debug Commands

eb.debug.toggle

Toggle debug display for all EasyBallistics systems.

eb.debug.toggle

Usage: Enables or disables all debug visualization globally.

eb.debug.category

Toggle specific debug categories for fine-grained control.

eb.debug.category <CategoryName> <0|1>

Parameters:

• CategoryName: The debug category to toggle
• 0|1: Disable (0) or enable (1) the category

Available Categories:

• Trajectory - Bullet path visualization
• Impact - Impact point and penetration visualization
• Physics - Physics forces and atmospheric effects
• Performance - Performance metrics and profiling
• Ballistics - Mathematical ballistic calculations
• Spalling - Secondary fragment generation
• Pooling - Object pooling statistics

Examples:

eb.debug.category Trajectory 1      # Enable trajectory visualization
eb.debug.category Impact 1          # Enable impact visualization
eb.debug.category Physics 0         # Disable physics debug

eb.debug.clear

Clear all debug visualization elements.

eb.debug.clear

Usage: Removes all debug lines, text, and visualization elements from the screen.

eb.debug.info

Display comprehensive debug information for all active bullets.

eb.debug.info

Usage: Shows detailed information about bullet states, physics calculations, and system performance.

Editor-Only Commands

EasyBallistics.OpenImportExportTool

Open the JSON Import/Export tool window.

EasyBallistics.OpenImportExportTool

Usage: Opens the dedicated tool for importing and exporting ballistic data as JSON files.

Debug Categories

Trajectory Debug

Visualizes bullet flight paths and trajectory information.

Features:

• Trail Visualization: Shows bullet path with color-coded velocity
• Velocity Vectors: Displays velocity direction and magnitude
• Path Prediction: Shows predicted trajectory
• Atmospheric Effects: Visualizes wind and air density impacts

Configuration:

// In bullet configuration
Bullet->DebugTrajectory = true;
Bullet->ShowTrail = true;
Bullet->ShowVelocityVectors = true;
Bullet->ShowPathPrediction = true;

Impact Debug

Shows impact points, penetration depth, and material interactions.

Features:

• Impact Points: Marks where bullets hit surfaces
• Penetration Depth: Shows how deep bullets penetrate
• Ricochet Angles: Displays ricochet probability and angles
• Material Information: Shows material properties at impact
• Surface Normals: Visualizes surface normal vectors

Configuration:

// In bullet configuration
Bullet->DebugImpact = true;
Bullet->ShowImpactPoints = true;
Bullet->ShowPenetrationDepth = true;
Bullet->ShowRicochetAngles = true;
Bullet->ShowMaterialInfo = true;

Physics Debug

Visualizes physics forces and atmospheric effects.

Features:

• Drag Forces: Shows air resistance effects
• Gravity Visualization: Displays gravitational effects
• Wind Effects: Shows wind force vectors
• Atmospheric Data: Displays air density and temperature

Configuration:

// In bullet configuration
Bullet->DebugPhysics = true;
Bullet->ShowDragForces = true;
Bullet->ShowGravityEffect = true;
Bullet->ShowWindEffect = true;
Bullet->ShowAtmosphericData = true;

Performance Debug

Shows performance metrics and profiling information.

Features:

• Trace Count: Number of traces per frame
• Frame Timing: Performance impact measurements
• Pooling Statistics: Object pooling efficiency
• Memory Usage: Memory allocation tracking

Configuration:

// In bullet configuration
Bullet->DebugPerformance = true;
Bullet->ShowTraceCount = true;
Bullet->ShowFrameTiming = true;
Bullet->ShowPoolingStats = true;

Ballistics Debug

Displays mathematical ballistic calculations.

Features:

• Energy Calculations: Kinetic energy and momentum
• Mathematical Comparison: Artistic vs mathematical mode comparison
• Ballistic Coefficient: Real-time BC calculations
• Penetration Formulas: Shows mathematical penetration results

Configuration:

// In bullet configuration
Bullet->DebugBallistics = true;
Bullet->ShowEnergyCalculations = true;
Bullet->ShowMathematicalComparison = true;
Bullet->ShowBallisticCoefficient = true;

Spalling Debug

Visualizes secondary fragment generation.

Features:

• Fragment Generation: Shows where spalling occurs
• Fragment Trajectories: Displays fragment paths
• Spall Cones: Shows fragment dispersion patterns
• Energy Distribution: Visualizes energy transfer to fragments

Configuration:

// In bullet configuration
Bullet->DebugSpalling = true;
Bullet->ShowSpallGeneration = true;
Bullet->ShowFragmentTrajectories = true;
Bullet->ShowSpallCones = true;

Debug Configuration

Blueprint Configuration

Debug settings can be configured through Blueprint:

// Get bullet reference
AEBBullet* Bullet = GetBullet();

// Enable debug categories
Bullet->SetBulletDebugCategory("Trajectory", true);
Bullet->SetBulletDebugCategory("Impact", true);

// Configure visualization
Bullet->DebugTrailTime = 2.0f;
Bullet->ImpactDebugTime = 5.0f;
Bullet->WorldTextScale = 1.2f;

Barrel-Level Debug Control

The barrel component provides debug control for all bullets it fires:

// Get barrel reference
UEBBarrel* Barrel = GetBarrel();

// Set debug categories for all bullets
Barrel->SetBulletDebugCategory("Trajectory", true);
Barrel->SetAllBulletDebugCategories(true);

// Clear debug display
Barrel->ClearAllBulletDebugDisplay();

Visualization Options

Color Coding

Debug visualizations use color coding to convey information:

Trajectory Colors:

• Green: High velocity (fast bullets)
• Yellow: Medium velocity
• Red: Low velocity (slow bullets)

Impact Colors:

• Green: Successful penetration
• Yellow: Ricochet
• Red: Stopped/blocked impact

Physics Colors:

• Blue: Drag forces
• Purple: Gravity forces
• Cyan: Wind forces

Text Display Options

Debug text can be displayed in world space or as on-screen messages:

// Configure text display
Bullet->UseWorldSpaceText = true;
Bullet->UseOnScreenMessages = true;
Bullet->WorldTextScale = 1.0f;
Bullet->MaxOnScreenMessages = 10;

Performance Considerations

Debug Impact on Performance

Debug visualization can impact performance, especially with many active bullets:

• Trajectory trails: High impact with many bullets
• Text rendering: Moderate impact
• Line drawing: Low to moderate impact
• On-screen messages: Low impact

Optimization Tips

1. Use Specific Categories: Enable only needed debug categories
2. Limit Debug Time: Reduce debug display duration
3. Batch Operations: Use barrel-level debug control
4. Conditional Debugging: Enable debug only during development

// Conditional debug enabling
#if WITH_EDITOR
    Bullet->DebugEnabled = true;
#else
    Bullet->DebugEnabled = false;
#endif

Troubleshooting Debug Issues

Common Problems

Debug Not Showing

• Check if debug is enabled globally: eb.debug.toggle
• Verify specific categories are enabled: eb.debug.category <name> 1
• Ensure bullets are configured for debug: Bullet->DebugEnabled = true

Performance Issues

• Disable expensive debug categories (Trajectory, Spalling)
• Reduce debug display times
• Limit number of active bullets during debug

Visual Clutter

• Use eb.debug.clear to remove old debug elements
• Enable only essential debug categories
• Reduce text scale and message count

Debug Information Output

Get comprehensive debug information:

// Get debug info string
FString DebugInfo = Bullet->GetDebugInfoString();
UE_LOG(LogTemp, Warning, TEXT("%s"), *DebugInfo);

Advanced Debug Features

Custom Debug Widgets

Create custom debug widgets for impact visualization:

// Create custom impact widget
Bullet->CreateDebugImpactWidget(
    ImpactLocation,
    bRicochet,
    bPenetration,
    ImpactVelocity,
    PenetrationDepth,
    HitMaterial
);

Debug Event Binding

Bind to debug events for custom visualization:

// Bind to impact debug event
Bullet->OnImpact.AddDynamic(this, &AMyClass::OnBulletImpact);

UFUNCTION()
void OnBulletImpact(/* impact parameters */)
{
    // Custom debug visualization
    DrawCustomDebugInfo();
}

Best Practices

1. Development Only: Use debug features only during development
2. Selective Enabling: Enable only necessary debug categories
3. Performance Monitoring: Monitor FPS impact when using debug
4. Clean Up: Use eb.debug.clear to remove debug clutter
5. Consistent Settings: Use barrel-level debug control for consistency

Integration with Profiling Tools

EasyBallistics debug features integrate with Unreal's profiling tools:

// Enable profiling-friendly debug
Bullet->DebugPerformance = true;

// Use with stat commands
// stat EasyBallistics
// stat Memory
// stat RenderThreadCommands

This comprehensive debug system provides powerful tools for developing, testing, and optimizing ballistic systems in EasyBallistics.