# 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**:
```cpp
// 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**:
```cpp
// 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**:
```cpp
// 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**:
```cpp
// 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**:
```cpp
// 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**:
```cpp
// 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:

```cpp
// 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:

```cpp
// 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:

```cpp
// 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

```cpp
// 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:

```cpp
// 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:

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

### Debug Event Binding

Bind to debug events for custom visualization:

```cpp
// 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:

```cpp
// 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.