# Gun-Centric Architecture Guide

The EasyBallistics plugin has been refactored to use a gun-centric approach where weapons are the primary actors with modular components. This consolidates scattered settings and provides a more intuitive workflow for creating realistic weapons.

## Overview

The new architecture consists of:

1. **AEBGun** - Main weapon actor
2. **UEBMagazine** - Magazine component for ammunition storage
3. **UEBBarrel** - Refocused barrel component for ballistics
4. **UEBWeaponConfiguration** - Asset that consolidates all weapon settings
5. **UEBBulletPropertiesAsset** - Bullet characteristics (unchanged)

## Core Components

### Gun Actor (AEBGun)

The main weapon actor that brings everything together:

```cpp
// C++ Usage
AEBGun* MyGun = GetWorld()->SpawnActor<AEBGun>();
MyGun->ApplyWeaponConfiguration(MyM4Config);
MyGun->LoadMagazine(BulletArray);
MyGun->PullTrigger();
```

**Key Features:**
- Centralized weapon state management
- Realistic gun controls (safety, charging handle, trigger)
- Automatic configuration from weapon assets
- Full multiplayer support
- Event-driven architecture
- Support for both skeletal and static mesh guns
- Flexible muzzle positioning (socket-based for skeletal, transform-based for static)

### Mesh Configuration

The gun actor supports both skeletal and static mesh setups:

**Skeletal Mesh Mode (Default):**
```cpp
// Set gun to use skeletal mesh (default)
MyGun->SetMeshType(true);
MyGun->SetMuzzleSocketName("MuzzleFlash"); // Use socket for muzzle position
```

**Static Mesh Mode:**
```cpp
// Set gun to use static mesh
MyGun->SetMeshType(false);
MyGun->MuzzleTransform = FTransform(FVector(50, 0, 0)); // Set relative muzzle position
```

**Key Differences:**
- Skeletal meshes use sockets for precise muzzle positioning and can have animations
- Static meshes use relative transforms and are more performance-friendly for simple weapons
- Both modes maintain full compatibility with the firing system

### Magazine Component (UEBMagazine)

Handles ammunition storage and feeding:

**Magazine Types:**
- Standard Box Magazine
- Drum Magazine  
- Tube Magazine (shotguns)
- Stripper Clip
- Belt Fed (machine guns)
- Revolver Cylinder
- Internal Magazine (bolt-actions)

**Features:**
- Mixed ammunition support
- Malfunction simulation
- Bolt hold-open functionality
- Realistic capacity limits
- Feed rate control for belt-fed weapons

### Barrel Component (UEBBarrel)

Fully integrated with the gun system for comprehensive ballistics:

**Enhanced Integration:**
- **Parent Gun Reference**: Direct connection to main gun actor
- **Configuration Driven**: All settings applied from weapon configuration
- **Realistic Calculations**: Physics-based muzzle velocity and accuracy
- **Legacy Compatibility**: Maintains old ammo system for existing projects

**Barrel Properties Applied from Config:**
- Barrel length, rifling twist rate, bore radius
- Muzzle velocity range and variations
- Accuracy and spread characteristics
- Recoil direction and multipliers

**Smart Calculations:**
```cpp
// Barrel automatically calculates effective properties
float MuzzleVel = Gun->GetEffectiveMuzzleVelocity(); // Considers bullet weight, barrel length
float Accuracy = Gun->GetBarrelAccuracy();           // Factors in barrel length, rifling
FVector Recoil = Gun->CalculateRecoilImpulse();     // Physics-based recoil calculation
```

**Features:**
- Automatic muzzle velocity calculation based on barrel length and bullet weight
- Rifling twist optimization for different bullet types
- Physics-based recoil impulse generation
- Direct magazine and gun state integration

### Weapon Configuration Asset (UEBWeaponConfiguration)

Consolidates all weapon settings into a single, manageable asset:

**Configuration Sections:**
- **Barrel Configuration**: Length, rifling, muzzle velocity, accuracy
- **Fire Control**: Available fire modes, rates, burst settings
- **Reliability**: Malfunction rates, environmental factors
- **Ammunition**: Compatible bullet types and magazine settings
- **Physics**: Mathematical vs artistic ballistics settings

## Setting Up a New Weapon

### 1. Create Weapon Configuration Asset

1. In Content Browser, right-click and navigate to **Ballistics → Weapon Configuration**
2. Name it based on your weapon (e.g., "M4_Carbine_Config")
3. The factory will auto-configure based on the name:
   - M4/AR15 → Modern assault rifle settings
   - AK → AK-type weapon settings
   - Pistol/Glock/1911 → Handgun settings
   - Sniper/Bolt → Bolt-action rifle settings
   - Shotgun → Shotgun settings
   - LMG/Machine → Light machine gun settings

### 2. Configure Your Weapon

Open the weapon configuration asset and customize:

**Weapon Info:**
```
Weapon Name: "M4 Carbine"
Manufacturer: "Colt"
Model: "M4A1"
Caliber: "5.56x45mm NATO"
```

**Fire Control:**
```
Available Fire Modes: [Semi-Auto, Full Auto]
Default Fire Mode: Semi-Auto
Fire Rate Min: 700 RPM
Fire Rate Max: 950 RPM
Burst Count: 3
```

**Barrel Configuration:**
```
Barrel Length: 14.5 inches
Muzzle Velocity: 91440 cm/s (~3000 fps)
Inherent Accuracy: 0.001 radians
Spread Max: 0.001 radians
```

### 3. Create Gun Blueprint

1. Create a new Blueprint based on **EBGun**
2. Set the **Weapon Config** to your configuration asset
3. Configure the gun mesh and sockets
4. Set up animations for firing, reloading, etc.

### 4. Set Up Ammunition

1. Create **Bullet Properties Assets** for your ammunition types
2. Add them to the weapon configuration's **Compatible Bullet Types**
3. Set the **Default Bullet Type**

## Blueprint Usage

### Basic Firing

```cpp
// Event: Player Input Trigger Pressed
Gun->PullTrigger();

// Event: Player Input Trigger Released  
Gun->ReleaseTrigger();
```

### Ammunition Management

```cpp
// Load magazine with specific bullet types
TArray<UEBBulletPropertiesAsset*> Ammo;
Ammo.Add(M855_Bullet);
Ammo.Add(M193_Bullet);
Gun->LoadMagazine(Ammo);

// Check ammunition status
int32 RoundsLeft = Gun->GetRoundsInMagazine();
int32 TotalRounds = Gun->GetTotalRounds();
bool CanShoot = Gun->CanFire();
```

### Weapon Controls

```cpp
// Safety controls
Gun->SetSafety(true);  // Safety on
Gun->SetSafety(false); // Safety off

// Manual cycling (bolt-actions, pump shotguns)
Gun->ChargingHandle(); // Cycle action

// Fire mode selection
Gun->SetFireMode(EFireMode::FM_Burst);
```

### Events

```cpp
// Gun Events
Gun->OnGunFired.AddDynamic(this, &AMyWeapon::OnGunFired);
Gun->OnMagazineEmpty.AddDynamic(this, &AMyWeapon::OnMagazineEmpty);
Gun->OnGunStateChanged.AddDynamic(this, &AMyWeapon::OnStateChanged);

// Magazine Events
Magazine->OnBulletFed.AddDynamic(this, &AMyWeapon::OnBulletFed);
Magazine->OnMagazineJammed.AddDynamic(this, &AMyWeapon::OnJammed);
```

## Advanced Features

### Custom Magazine Types

```cpp
// Belt-fed machine gun
MagazineConfig.MagazineType = EMagazineType::MT_Belt;
MagazineConfig.MaxCapacity = 200;
MagazineConfig.FeedRate = 0.05f; // Fast feeding

// Tube magazine shotgun  
MagazineConfig.MagazineType = EMagazineType::MT_Tube;
MagazineConfig.MaxCapacity = 8;
MagazineConfig.bAllowMixedBulletTypes = true; // Different shell types
```

### Reliability Simulation

```cpp
// Environmental effects
ReliabilityConfig.DirtSensitivity = 0.3f;
ReliabilityConfig.TemperatureSensitivity = 0.002f;
ReliabilityConfig.MinOperatingTemp = -30.0f;
ReliabilityConfig.MaxOperatingTemp = 55.0f;

// Wear and maintenance
ReliabilityConfig.WearFactor = 0.0001f;
ReliabilityConfig.ServiceLife = 15000; // rounds
```

### Multi-Barrel Systems

```cpp
// For weapons with multiple barrels (like gatling guns)
BarrelConfig.GatlingSpoolUpTime = 2.0f;
BarrelConfig.GatlingSpoolDownTime = 3.0f;
FireControlConfig.AvailableFireModes.Add(EFireMode::FM_Gatling);
```

## Migration from Old System

### Before (Scattered Settings)
```cpp
// Settings spread across multiple components
Barrel->FireRate = 650.0f;
Barrel->Spread = 0.001f;
Barrel->MuzzleVelocity = 91440.0f;
Bullet->Mass = 0.004f;
Bullet->Diameter = 0.556f;
MaterialMap->PenetrationDepth = 15.0f;
```

### After (Centralized Configuration)
```cpp
// All settings in one place
WeaponConfig->FireControlConfig.FireRateMax = 650.0f;
WeaponConfig->BarrelConfig.SpreadMax = 0.001f;
WeaponConfig->BarrelConfig.MuzzleVelocityMax = 91440.0f;
WeaponConfig->DefaultBulletType = MyBulletAsset;
WeaponConfig->MaterialResponseMap = MyMaterialMap;

// Apply to gun
Gun->ApplyWeaponConfiguration(WeaponConfig);
```

## Benefits of New Architecture

1. **Centralized Settings**: All weapon parameters in one place
2. **Realistic Simulation**: Proper magazine, safety, and malfunction systems
3. **Modular Design**: Easy to swap magazines, barrels, configurations
4. **Better Workflow**: Intuitive gun-first approach
5. **Reduced Complexity**: No more hunting for scattered settings
6. **Multiplayer Ready**: Built-in replication and authority handling
7. **Asset Reuse**: Share configurations between similar weapons

## Best Practices

1. **Use Weapon Configurations**: Always create configuration assets for your weapons
2. **Group Similar Weapons**: Share configurations between variants (M4A1, M4A3, etc.)
3. **Plan Magazine Types**: Choose appropriate magazine types for realism
4. **Test Reliability**: Adjust malfunction rates for your game's difficulty
5. **Configure Events**: Use the event system for UI updates and effects
6. **Consider Physics Mode**: Choose mathematical vs artistic based on your needs

This new architecture provides a much more intuitive and consolidated approach to weapon creation while maintaining all the advanced ballistics features of EasyBallistics.