BallisticsDocs/Documentation/Gun_Centric_Architecture.md

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:

// 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):

// Set gun to use skeletal mesh (default)
MyGun->SetMeshType(true);
MyGun->SetMuzzleSocketName("MuzzleFlash"); // Use socket for muzzle position

Static Mesh Mode:

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

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

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

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

Ammunition Management

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

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

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

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

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

// 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)

// 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)

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