BallisticsDocs/Documentation/Researcher_Guide.md

EasyBallistics JSON Configuration Guide for Researchers

Overview

This guide is designed for researchers, engineers, and scientists who need to configure ballistic simulation parameters without requiring knowledge of game development or Unreal Engine. The configuration files use self-documenting JSON format with embedded explanations.

Getting Started

Understanding the JSON Structure

Each configuration file follows this pattern:

{
  "ParameterName": {
    "_description": "What this parameter does",
    "_unit": "Units of measurement", 
    "_typical_values": "Expected ranges",
    "_examples": "Real-world examples",
    "value": actual_numeric_value
  }
}

Important: The underscore-prefixed fields (_description, _unit, etc.) are documentation only. The value field contains the actual parameter that affects the simulation.

File Types

1. Bullet Properties (Sample_BulletProperties.json) - Physical and ballistic characteristics of projectiles
2. Material Response (Sample_MaterialResponse.json) - How materials respond to ballistic impact

Bullet Properties Configuration

Essential Parameters

Mass and Dimensions

• GrainWeight: Projectile mass in grains (1 grain = 0.0647989 grams)

  • Small caliber: 20-80 grains
  • Medium caliber: 80-200 grains
  • Large caliber: 200-750+ grains

• DiameterInches: Bullet diameter in inches

  • Common values: 0.224" (5.56mm), 0.308" (7.62mm), 0.452" (45 ACP)

• LengthInches: Overall bullet length

  • Typically 0.4-2.0 inches depending on caliber

Ballistic Coefficients

Choose either G1 or G7 model (set UseG7Model accordingly):

• G1 Model: Traditional standard, good for round-nose bullets

  • Poor: 0.15-0.25
  • Average: 0.25-0.45
  • Excellent: 0.65+

• G7 Model: Better for modern pointed bullets

  • Typically 0.5-0.7× the G1 value
  • More accurate for boat-tail designs

Material Properties

• BulletHardness: Brinell Hardness Number

  • Lead: 5-15 BHN
  • Copper jacket: 15-25 BHN
  • Steel core: 150-600 BHN

• PenetrationEnergyThreshold: Minimum energy for penetration (ft-lbs)

  • Varies by intended use: 10-500+ ft-lbs

Research Applications

Ballistics Research

For academic ballistics research, focus on:

• Accurate ballistic coefficients from wind tunnel data
• Precise mass and dimensional measurements
• Material hardness from standardized testing

Terminal Ballistics Studies

For penetration and wound ballistics:

• Expansion characteristics (velocity thresholds, max expansion)
• Energy transfer parameters
• Material-specific hardness values

Forensic Applications

For bullet identification and trajectory analysis:

• Precise dimensional measurements
• Material composition data
• Manufacturer-specific variations

Material Response Configuration

Penetration Mechanics

Basic Penetration

• PenetrationDepthMultiplier: Scaling factor (0.1-10.0)

  • Use 1.0 as baseline, adjust based on experimental data
  • Values <1.0 for harder materials, >1.0 for softer

• PenetrationNormalization: Angle dependency (degrees)

  • 0-15°: Soft materials (wood, plastic)
  • 15-30°: Medium materials (aluminum, mild steel)
  • 30-60°: Hard materials (armor steel, ceramics)

Advanced Penetration Modeling

When UseMathematicalProperties is enabled:

• DensityGPerCm3: Material density from engineering handbooks
• TensileStrengthMPa: Ultimate tensile strength from material testing
• YieldStrengthMPa: Yield strength (typically 50-80% of tensile strength)
• BallisticLimitVelocity: V50 velocity from ballistic testing

Ricochet Behavior

Key Parameters

• RicochetProbabilityMultiplier: Likelihood scaling (0.0-5.0)

  • 0.0: No ricochets (soft materials)
  • 1.0: Normal probability
  • 2.0+: High ricochet materials (hardened steel, ice)

• RicochetRestitution: Energy retention (0.0-1.0)

  • Soft materials: 0.1-0.3
  • Hard materials: 0.7-0.9

Spalling and Fragmentation

When to Enable Spalling

Spalling is relevant for:

• Brittle materials (concrete, ceramics, glass)
• High-energy impacts (>2000 fps)
• Research into secondary fragmentation effects

Critical Parameters

• SpallVelocityThreshold: Minimum impact velocity (cm/s)

  • Glass: 15,000-30,000 cm/s
  • Concrete: 30,000-60,000 cm/s
  • Steel: 60,000+ cm/s

• SpallFragmentCount: Number of fragments (1-20)

  • Balance realism vs. computational cost
  • Typical: 3-8 fragments for most materials

Data Sources and Validation

Recommended References

Bullet Properties

1. Manufacturer Data: Official ballistic coefficients and specifications
2. Ballistic Tables: Sierra, Hornady, Nosler reloading manuals
3. Military Standards: NATO STANAG documents for military ammunition
4. SAAMI Standards: Sporting Arms and Ammunition Manufacturers' Institute

Material Properties

1. ASTM Standards: Material testing standards (E8, E10, etc.)
2. Engineering Handbooks: ASM Metals Handbook, Machinery's Handbook
3. Research Literature: Journal of Applied Physics, International Journal of Impact Engineering
4. Government Databases: NIST materials database, military research reports

Experimental Validation

Ballistic Testing

• Use chronographs for velocity measurements
• Ballistic gelatin for terminal performance
• Steel plate testing for penetration limits
• High-speed photography for fragment analysis

Material Testing

• Tensile testing per ASTM E8
• Hardness testing per ASTM E10
• Impact testing per ASTM E23
• Ballistic limit testing per MIL-STD protocols

Common Material Examples

Metals

// Mild Steel (A36)
"DensityGPerCm3": 7.85,
"MaterialHardness": 150.0,
"TensileStrengthMPa": 400.0,
"YieldStrengthMPa": 250.0

// Aluminum 6061-T6  
"DensityGPerCm3": 2.70,
"MaterialHardness": 95.0,
"TensileStrengthMPa": 310.0,
"YieldStrengthMPa": 276.0

// Hardened Steel (Armor)
"DensityGPerCm3": 7.85,
"MaterialHardness": 500.0,
"TensileStrengthMPa": 1200.0,
"YieldStrengthMPa": 1000.0

Ceramics and Composites

// Alumina Ceramic
"DensityGPerCm3": 3.95,
"MaterialHardness": 1500.0,
"TensileStrengthMPa": 300.0,
"YieldStrengthMPa": 300.0,
"EnableSpalling": true

// Kevlar Composite
"DensityGPerCm3": 1.44,
"MaterialHardness": 50.0,
"TensileStrengthMPa": 3500.0,
"YieldStrengthMPa": 3500.0,
"NeverRicochet": true

Quality Assurance

Parameter Validation

1. Physical Consistency: Ensure yield strength ≤ tensile strength
2. Unit Consistency: Verify all units match the documentation
3. Range Checking: Compare values against published material databases
4. Cross-Reference: Validate against multiple independent sources

Simulation Validation

1. Known Results: Test against published ballistic data
2. Sensitivity Analysis: Vary parameters to understand system response
3. Comparative Testing: Compare results between different bullet/material combinations
4. Literature Comparison: Validate results against peer-reviewed research

Troubleshooting

Common Issues

1. Unrealistic Penetration: Check density and hardness values
2. No Expansion: Verify expansion velocity threshold vs. impact velocity
3. Excessive Ricochets: Reduce ricochet probability multiplier
4. Performance Issues: Reduce spalling fragment count and density

Best Practices

1. Start Simple: Begin with basic parameters, add complexity gradually
2. Document Sources: Record where each value came from for traceability
3. Version Control: Keep track of parameter changes and their effects
4. Peer Review: Have other researchers validate your parameter choices

Advanced Research Applications

Multi-Material Studies

For composite armor or layered materials:

• Configure each layer separately
• Account for interface effects
• Consider cumulative energy absorption

Dynamic Effects

For high strain rate phenomena:

• Use dynamic strength values (typically 1.5-3× static)
• Account for temperature effects
• Consider strain rate sensitivity

Statistical Analysis

For probabilistic studies:

• Use parameter ranges rather than single values
• Apply Monte Carlo methods
• Document uncertainty and sensitivity

Contact and Support

For research collaborations or technical questions:

• Review the complete API documentation
• Consult the troubleshooting guide
• Consider experimental validation of critical parameters

This configuration system is designed to support serious ballistics research while maintaining computational efficiency. The self-documenting JSON format ensures that parameter choices are traceable and scientifically justified.