BallisticsDocs/docs/docs/tutorials/gun-blueprint-guide.md

Gun Blueprint Creation Guide

This guide covers creating fully functional gun blueprints using EasyBallistics' new Gun-Centric Architecture. The AEBGun class provides a complete weapon system with integrated barrel, magazine, and ammunition management.

🎨 Interactive Blueprint Visualization

This guide uses Klee for interactive Blueprint visualization. You can view, share, and experiment with the Blueprint examples directly in your browser. All Blueprint code snippets can be copied and visualized using Klee's web interface.

Prerequisites

• Basic knowledge of Unreal Engine Blueprints
• Understanding of Data Assets and Actor Components
• Familiarity with Unreal's event system
• EasyBallistics plugin installed and enabled
• Optional: Klee for Blueprint visualization and sharing

Architecture Overview

The Gun-Centric Architecture consists of:

• AEBGun: Main weapon actor with integrated systems
• UEBBarrel: Firing mechanism and ballistic calculations
• UEBMagazine: Ammunition storage and feeding
• UEBWeaponConfiguration: Centralized weapon parameters
• UEBBulletPropertiesAsset: Ammunition specifications

Step-by-Step Gun Creation

1. Create Required Data Assets

A. Create Bullet Properties Asset

1. Right-click in Content Browser → Ballistics → Bullet Properties
2. Name: BP_556NATO_BulletProperties
3. Configure properties:

   Basic Properties:
   - Grain Weight: 55.0
   - Diameter Inches: 0.224
   - Length Inches: 0.825
   - Bullet Type: Full Metal Jacket
   
   Ballistics:
   - Ballistic Coefficient G1: 0.151
   - Ballistic Coefficient G7: 0.076
   - Use G7 Model: false
   
   Penetration:
   - Bullet Hardness: 15.0
   - Penetration Energy Threshold: 58.0
   

B. Create Weapon Configuration Asset

1. Right-click in Content Browser → Ballistics → Weapon Configuration

2. Name: BP_M4_WeaponConfig

3. Configure sections:

   Weapon Info:

   - Weapon Name: "M4 Carbine"
   - Manufacturer: "Colt"
   - Model: "M4A1"
   - Caliber: "5.56x45mm NATO"
   - Description: "Standard issue carbine"
   

   Barrel Configuration:

   - Barrel Length: 14.5 inches
   - Rifling Twist: 7.0 (1:7 twist)
   - Bore Radius: 0.112 inches
   - Muzzle Velocity Min: 91440 cm/s (~3000 fps)
   - Muzzle Velocity Max: 91440 cm/s
   - Inherent Accuracy: 0.001 MOA (radians)
   - Spread Max: 0.001 radians
   - Recoil Multiplier: 1.0
   

   Fire Control Configuration:

   - Available Fire Modes: [Semi-Auto, Full Auto]
   - Default Fire Mode: Semi-Auto
   - Fire Rate Min: 600 RPM
   - Fire Rate Max: 750 RPM
   - Burst Count: 3
   - Has Safety: true
   - Default Safety On: false
   

   Ammunition:

   - Default Bullet Type: BP_556NATO_BulletProperties
   - Default Magazine Capacity: 30
   - Allow Mixed Ammo: true
   

2. Create the Gun Blueprint

A. Create Blueprint Class

1. Right-click in Content Browser → Blueprint Class
2. Search for: EBGun
3. Select: EBGun class
4. Name: BP_M4_Gun

B. Configure Gun Components

1. Open BP_M4_Gun blueprint
2. Components Panel:
   • GunMesh: Set your weapon's skeletal mesh
   • Barrel: Automatically positioned at "MuzzleSocket"
   • Magazine: Automatically created and configured

Important: Your weapon mesh must have a "MuzzleSocket" bone/socket for proper bullet spawning.

C. Set Weapon Configuration

1. Select the root BP_M4_Gun(self)
2. Details Panel:
   • Weapon Config: Set to BP_M4_WeaponConfig

3. Blueprint Event Graph Setup

A. Basic Initialization

Blueprint Graph: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_Event Name="K2Node_Event_BeginPlay"
EventReference=(MemberParent=Class'"/Script/Engine.Actor"',MemberName="ReceiveBeginPlay")
bOverrideFunction=True
NodeGuid=DA78E90542B5EA6FFF2BB580420BADA4
CustomProperties Pin (PinName="then",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_ApplyWeaponConfig"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="ApplyWeaponConfiguration")
NodePosX=288
NodeGuid=D94D72E348471465CF685AB3C289A168
CustomProperties Pin (PinName="WeaponConfig",PinType.PinCategory="object",DefaultValue="BP_M4_WeaponConfig")
End Object

📋 Blueprint Workflow:

1. Event BeginPlay: Triggers when the gun spawns
2. Apply Weapon Configuration: Sets up all gun parameters from the data asset
3. Load Magazine: Fills magazine with specified bullet types
4. Charging Handle: Chambers the first round
5. Bind Events: Connects gun events to response functions

B. Input Actions

Fire Input Blueprint: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_InputAction Name="K2Node_InputAction_Fire"
InputActionName="Fire"
bConsumeInput=True
NodeGuid=1A2B3C4D5E6F7890ABCDEF1234567890
CustomProperties Pin (PinName="Pressed",Direction="EGPD_Output",PinType.PinCategory="exec")
CustomProperties Pin (PinName="Released",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_CanFire"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="CanFire")
NodePosX=288
NodeGuid=2B3C4D5E6F7890ABCDEF1234567890AB
CustomProperties Pin (PinName="ReturnValue",Direction="EGPD_Output",PinType.PinCategory="bool")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_PullTrigger"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="PullTrigger")
NodePosX=576
NodeGuid=3C4D5E6F7890ABCDEF1234567890ABCD
End Object

🎮 Input Mapping:

• Fire (Pressed): Check Can Fire → Pull Trigger if valid
• Fire (Released): Always call Release Trigger
• Reload: Check magazine capacity → Execute reload sequence
• Toggle Safety: Get current state → Set opposite state
• Toggle Fire Mode: Cycle through available fire modes

Copy this Blueprint code and paste it into Klee to see the visual graph!

C. Reload System

Reload Blueprint: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_CustomEvent Name="K2Node_ReloadSequence"
CustomFunctionName="Reload Sequence"
NodeGuid=4D5E6F7890ABCDEF1234567890ABCDEF
CustomProperties Pin (PinName="then",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_EjectMagazine"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="EjectMagazine")
NodePosX=288
NodeGuid=5E6F7890ABCDEF1234567890ABCDEF12
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_InsertMagazine"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="InsertMagazine")
NodePosX=576
NodeGuid=6F7890ABCDEF1234567890ABCDEF1234
CustomProperties Pin (PinName="NewMagazine",PinType.PinCategory="object")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_ChargingHandle"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="ChargingHandle")
NodePosX=864
NodeGuid=7890ABCDEF1234567890ABCDEF123456
End Object

🔄 Reload Workflow:

1. Check Inventory: Verify player has ammunition available
2. Eject Magazine: Remove current magazine (empty or partial)
3. Animation Delay: Wait for reload animation timing
4. Insert Magazine: Add new magazine with fresh ammunition
5. Charging Handle: Chamber first round from new magazine
6. Audio Feedback: Play reload completion sound

Visualization Tip: Use Klee to see how the reload sequence flows and branches based on different conditions!

4. Event Response System

A. Gun State Management

State Management Blueprint: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_Event Name="K2Node_OnGunStateChanged"
EventReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="OnGunStateChanged")
NodeGuid=8901ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="NewState",PinType.PinCategory="byte",PinType.PinSubCategoryObject=Enum'"/Script/EasyBallistics.EGunState"')
CustomProperties Pin (PinName="then",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_Switch Name="K2Node_SwitchGunState"
IndexPinType.PinCategory="byte"
IndexPinType.PinSubCategoryObject=Enum'"/Script/EasyBallistics.EGunState"'
NodePosX=288
NodeGuid=9012ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="Ready",Direction="EGPD_Output",PinType.PinCategory="exec")
CustomProperties Pin (PinName="Firing",Direction="EGPD_Output",PinType.PinCategory="exec")
CustomProperties Pin (PinName="Empty",Direction="EGPD_Output",PinType.PinCategory="exec")
CustomProperties Pin (PinName="Jammed",Direction="EGPD_Output",PinType.PinCategory="exec")
CustomProperties Pin (PinName="SafetyOn",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

🎯 State Visualization:

• Ready (Green): Gun can fire normally
• Firing (Red): Gun is actively firing
• Empty (Gray): No ammunition available
• Jammed (Yellow): Malfunction occurred
• Safety On (Orange): Safety engaged, cannot fire

Interactive Demo: Paste this code into Klee to see how the state machine branches!

B. Firing Effects

Firing Effects Blueprint: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_Event Name="K2Node_OnGunFired"
EventReference=(MemberParent=Class'"/Script/EasyBallistics.EBGun"',MemberName="OnGunFired")
NodeGuid=0123ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="BulletType",PinType.PinCategory="object")
CustomProperties Pin (PinName="then",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_SpawnEmitterAttached"
FunctionReference=(MemberParent=Class'"/Script/Engine.GameplayStatics"',MemberName="SpawnEmitterAttached")
NodePosX=288
NodeGuid=1234ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="EmitterTemplate",PinType.PinCategory="object",DefaultValue="MuzzleFlash")
CustomProperties Pin (PinName="AttachToComponent",PinType.PinCategory="object")
CustomProperties Pin (PinName="AttachPointName",PinType.PinCategory="name",DefaultValue="MuzzleSocket")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_PlaySound2D"
FunctionReference=(MemberParent=Class'"/Script/Engine.GameplayStatics"',MemberName="PlaySound2D")
NodePosX=576
NodeGuid=2345ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="Sound",PinType.PinCategory="object",DefaultValue="GunFireSound")
End Object

💥 Effects Chain:

1. Muzzle Flash: Particle effect at barrel tip
2. Audio: Gunshot sound with 3D positioning
3. Camera Shake: Weapon recoil feedback
4. Player Impulse: Physical recoil force
5. Shell Casing: Ejected brass cartridge
6. UI Update: Ammunition counter refresh

Pro Tip: Use Klee's sharing feature to share your custom firing effects with the community!

C. Magazine Management

OnMagazineEmpty
├── Play Sound 2D (EmptyClickSound)
├── Show Reload Prompt UI
├── Set Can Fire (false)
└── Print String "Magazine Empty - Press R to Reload"

OnMagazineChanged (NewMagazine)
├── Branch (Is Valid: NewMagazine)
│   ├── True:
│   │   ├── Hide Reload Prompt
│   │   ├── Set Can Fire (true)
│   │   └── Play Reload Complete Sound
│   └── False:
│       ├── Show No Magazine Warning
│       └── Set Can Fire (false)
└── Update Magazine UI

5. Advanced Features

A. Multiple Ammunition Types

Function: Setup Mixed Ammo
├── Create Array (BulletTypes)
│   ├── Add Item: BP_556_FMJ x20
│   ├── Add Item: BP_556_AP x5
│   ├── Add Item: BP_556_HP x3
│   └── Add Item: BP_556_Tracer x2
├── Shuffle Array (BulletTypes)
└── Load Magazine (BulletTypes)

Function: Get Current Ammo Info
├── Get Chambered Bullet Type
├── Branch (Is Valid: Bullet Type)
│   ├── True: Get Bullet Info
│   │   ├── Bullet Name
│   │   ├── Damage Type
│   │   └── Special Properties
│   └── False: Return "No Round Chambered"
└── Update Ammo Type UI

B. Weapon Customization

Function: Apply Weapon Attachments
├── Input: Attachment Array
├── For Each Loop (Attachment)
│   ├── Switch on Attachment Type
│   │   ├── Scope:
│   │   │   ├── Modify Accuracy
│   │   │   └── Add Scope Mesh
│   │   ├── Suppressor:
│   │   │   ├── Reduce Noise
│   │   │   └── Modify Muzzle Flash
│   │   ├── Foregrip:
│   │   │   ├── Reduce Recoil
│   │   │   └── Improve Handling
│   │   └── Extended Magazine:
│   │       ├── Increase Capacity
│   │       └── Modify Reload Time
│   └── Update Weapon Stats
└── Refresh Weapon Model

C. Smart Targeting System

Function: Calculate Lead Target
├── Input: Target Actor
├── Get Target Velocity
├── Calculate Aim Direction
│   ├── Bullet Class: Current Bullet
│   ├── Target Location: Target Position
│   ├── Target Velocity: Movement Vector
│   └── Max Time: 10.0 seconds
├── Output: Predicted Aim Direction
└── Update Crosshair Position

Function: Predict Trajectory
├── Input: Aim Direction
├── Predict Hit
│   ├── Bullet Class: Current Bullet
│   ├── Max Time: 5.0 seconds
│   └── Step Size: 0.1 seconds
├── Output: Trajectory Points Array
└── Draw Trajectory Line

6. UI Integration

A. Weapon Status HUD

Widget: Weapon Status HUD
├── Ammo Counter
│   ├── Current Rounds: Get Rounds in Magazine
│   ├── Chambered Round: Get Chambered Bullet Type
│   └── Total Rounds: Get Total Rounds
├── Fire Mode Indicator
│   ├── Get Fire Mode
│   └── Display Mode Icon
├── Safety Indicator
│   ├── Get Safety State
│   └── Show/Hide Safety Icon
├── Weapon Status
│   ├── Get Gun State
│   └── Display Status Text
└── Crosshair
    ├── Dynamic Size: Based on Spread
    └── Hit Indicator: Based on Trajectory

B. Weapon Selection Menu

Widget: Weapon Selection
├── For Each Available Weapon
│   ├── Create Weapon Button
│   ├── Set Weapon Icon
│   ├── Set Weapon Name
│   └── Bind Selection Event
├── On Weapon Selected
│   ├── Destroy Current Weapon
│   ├── Spawn New Weapon
│   └── Equip Weapon
└── Update Selection UI

7. Multiplayer Support

A. Network Setup

Event BeginPlay
├── Branch (Has Authority)
│   ├── True: Server Setup
│   │   ├── Initialize Weapon Systems
│   │   ├── Set Replication Properties
│   │   └── Enable Authority Functions
│   └── False: Client Setup
│       ├── Bind to Replicated Events
│       ├── Setup Client Prediction
│       └── Enable Input Handling
└── Configure Network Settings
    ├── Replicate Variables: true
    ├── Replicate Shot Events: true
    └── Client Side Aim: true

B. Client Prediction

Function: Client Fire Prediction
├── Branch (Has Authority)
│   ├── True: Fire Immediately
│   └── False: Predicted Fire
│       ├── Play Effects Immediately
│       ├── Send Fire Request to Server
│       └── Wait for Server Confirmation
└── Handle Prediction Correction

8. Performance Optimization

A. LOD System

Event Tick
├── Branch (Should Update LOD)
│   └── True: Update LOD
│       ├── Get Distance to Player
│       ├── Calculate LOD Level
│       ├── Switch on LOD Level
│       │   ├── High: Full Detail
│       │   ├── Medium: Reduced Effects
│       │   └── Low: Minimal Detail
│       └── Apply LOD Settings
└── Set Should Update LOD (false)

B. Object Pooling

Manager: Weapon Pool
├── Initialize Pool
│   ├── Create Weapon Array
│   └── Pre-spawn Weapons
├── Get Weapon from Pool
│   ├── Find Available Weapon
│   ├── Configure Weapon
│   └── Return to Requester
└── Return Weapon to Pool
    ├── Reset Weapon State
    └── Mark as Available

9. Debugging and Testing

A. Debug Visualization

Debug System Blueprint: View in Klee

Begin Object Class=/Script/BlueprintGraph.K2Node_InputAction Name="K2Node_ToggleDebug"
InputActionName="ToggleDebug"
bConsumeInput=True
NodeGuid=3456ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="Pressed",Direction="EGPD_Output",PinType.PinCategory="exec")
End Object

Begin Object Class=/Script/BlueprintGraph.K2Node_CallFunction Name="K2Node_SetBulletDebugCategory"
FunctionReference=(MemberParent=Class'"/Script/EasyBallistics.EBBarrel"',MemberName="SetBulletDebugCategory")
NodePosX=576
NodeGuid=4567ABCDEF1234567890ABCDEF123456
CustomProperties Pin (PinName="CategoryName",PinType.PinCategory="string",DefaultValue="Trajectory")
CustomProperties Pin (PinName="bEnabled",PinType.PinCategory="bool",DefaultValue="true")
End Object

🔍 Debug Features:

• Trajectory Visualization: See bullet paths in real-time
• Impact Markers: Show where bullets hit surfaces
• Performance Metrics: Monitor FPS and trace counts
• Weapon Statistics: Display accuracy, recoil, etc.

Share Your Blueprints: Export your debug setup and share it with Klee for collaborative debugging!

B. Test Scenarios

Function: Run Weapon Tests
├── Test Basic Firing
│   ├── Load Magazine
│   ├── Fire Single Shot
│   └── Verify Bullet Spawned
├── Test Fire Modes
│   ├── Test Semi-Auto
│   ├── Test Full Auto
│   └── Test Burst Fire
├── Test Reload System
│   ├── Empty Magazine
│   ├── Reload Weapon
│   └── Verify New Ammo
└── Test Safety System
    ├── Enable Safety
    ├── Attempt Fire
    └── Verify Block

10. Common Issues and Solutions

A. Troubleshooting Guide

Gun Won't Fire:

• Check if magazine is loaded: Get Rounds in Magazine > 0
• Verify round is chambered: Get Chambered Bullet Type != None
• Check safety state: Get Safety State == false
• Verify gun state: Get Gun State == Ready

Bullets Don't Spawn:

• Check MuzzleSocket exists on mesh
• Verify barrel component is attached
• Check bullet class is valid
• Verify barrel has parent gun reference

Automatic Fire Won't Stop:

• Ensure Release Trigger is called
• Check fire mode is set correctly
• Verify trigger input is properly bound
• Check for infinite loop in firing logic

Networking Issues:

• Verify replication settings are enabled
• Check server authority for critical functions
• Ensure client prediction is configured
• Test with multiple clients

11. Best Practices

A. Code Organization

1. Separate Concerns: Keep weapon logic, UI, and effects separate
2. Use Events: Leverage the gun's event system for responsiveness
3. Validate Inputs: Always check for valid references
4. Handle Edge Cases: Account for empty magazines, jams, etc.

B. Performance Considerations

1. Limit Tick Usage: Use events instead of tick when possible
2. Pool Objects: Reuse bullets, effects, and UI elements
3. LOD Management: Reduce detail for distant weapons
4. Network Optimization: Minimize replicated data

C. User Experience

1. Responsive Feedback: Provide immediate visual/audio feedback
2. Clear State: Always show current weapon state
3. Intuitive Controls: Use standard FPS control schemes
4. Accessibility: Support different input methods

Blueprint Sharing with Klee

Exporting Your Gun Blueprints

1. Copy Blueprint Text: In Unreal Engine, select your Blueprint nodes and copy (Ctrl+C)
2. Open Klee: Navigate to Klee
3. Paste Code: Paste the Blueprint text into Klee's input field
4. Generate Visualization: Klee will create an interactive web visualization
5. Share URL: Copy the generated URL to share your Blueprint with others

Community Blueprint Gallery

Visit the Klee website to explore community-shared Blueprints:

• Weapon Systems: Complete gun implementations
• Fire Mode Variants: Different firing mechanisms
• Custom Ammunition: Specialized bullet behaviors
• Debug Utilities: Helpful debugging tools

Interactive Learning

Use Klee to:

• Visualize Complex Logic: See how event chains flow
• Share Solutions: Help others with Blueprint examples
• Collaborate: Work on multiplayer weapon systems together
• Learn from Examples: Study community implementations

Conclusion

The Gun-Centric Architecture provides a comprehensive, realistic weapon system that handles all aspects of firearm behavior. By following this guide, you'll create fully functional weapons with proper ammunition management, multiple fire modes, and networking support.

Enhanced with Klee: All Blueprint examples in this guide can be visualized and shared using Klee's web interface, making it easier to understand, debug, and collaborate on weapon systems.

The system is designed to be extensible, allowing you to add custom features while maintaining the core ballistic simulation accuracy that EasyBallistics is known for.

For additional examples and advanced techniques, refer to the other tutorials in this documentation set. Don't forget to check out community-shared Blueprints on Klee!