Gun Centric Refactor Start

2025-07-04 03:26:03 -07:00
parent 1f0381506a
commit e7989cfe0a
30 changed files with 3783 additions and 96 deletions
@@ -0,0 +1,291 @@
+# 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
+
+### 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.