{
  "_description": "Material Response Configuration File",
  "_notes": "This file defines how materials respond to ballistic impact, including penetration, ricochet, and fragmentation characteristics. Values are based on material science and ballistics research.",
  "_example": "Mild Steel Plate - Typical structural steel properties",
  "_warning": "These parameters significantly affect simulation realism. Consult ballistics literature for accurate values.",

  "PenTraceType": {
    "_description": "Method used to calculate penetration through material",
    "_options": {
      "0": "Back Trace - Traces backwards from exit point to calculate thickness",
      "1": "By Component - Uses component bounds for thickness calculation", 
      "2": "Double Sided Geometry - Treats geometry as having entry and exit surfaces"
    },
    "_recommendation": "Use Back Trace (0) for most materials, Double Sided (2) for thin plates",
    "value": 0
  },

  "NeverPenetrate": {
    "_description": "Forces material to be completely impenetrable regardless of impact energy",
    "_use_cases": [
      "Armor plates in arcade-style games",
      "Indestructible barriers", 
      "Ultra-hard materials like tungsten carbide armor"
    ],
    "_note": "Overrides all other penetration calculations when true",
    "value": false
  },

  "PenetrationDepthMultiplier": {
    "_description": "Scaling factor for calculated penetration depth",
    "_unit": "multiplier (1.0 = normal penetration)",
    "_range": "0.1-10.0 typical",
    "_effects": {
      "0.5": "Half normal penetration (hardened armor)",
      "1.0": "Normal penetration (standard calculation)",
      "2.0": "Double penetration (soft materials)",
      "5.0": "Very high penetration (foam, fabric)"
    },
    "_applications": "Adjust for material hardness variations not captured in other parameters",
    "value": 1.0
  },

  "PenetrationNormalization": {
    "_description": "Reduces penetration effectiveness at oblique impact angles",
    "_unit": "degrees (0-90)",
    "_explanation": "At angles greater than this value, penetration is reduced",
    "_typical_values": {
      "soft_materials": "0-15 degrees (wood, plastic)",
      "medium_materials": "15-30 degrees (aluminum, mild steel)",
      "hard_materials": "30-45 degrees (hardened steel, armor)",
      "very_hard": "45-60 degrees (ceramics, tungsten)"
    },
    "_physics": "Represents material's resistance to angled impacts",
    "value": 0.0
  },

  "PenetrationNormalizationGrazing": {
    "_description": "Additional normalization for very shallow (grazing) angles",
    "_unit": "degrees (0-90)",
    "_explanation": "Applied in addition to PenetrationNormalization for extreme angles",
    "_typical_range": "60-85 degrees",
    "_effect": "Simulates bullet deflection at very shallow impact angles",
    "value": 0.0
  },

  "PenetrationEntryAngleSpread": {
    "_description": "Random deviation of bullet path when entering material",
    "_unit": "degrees of cone spread",
    "_range": "0-15 degrees typical",
    "_causes": [
      "Material inhomogeneity",
      "Surface roughness",
      "Bullet deformation on impact"
    ],
    "_typical_values": {
      "homogeneous": "0-2 degrees (steel, aluminum)",
      "layered": "2-5 degrees (plywood, composites)",
      "granular": "5-10 degrees (concrete, soil)",
      "irregular": "10+ degrees (rock, masonry)"
    },
    "value": 0.0
  },

  "PenetrationExitAngleSpread": {
    "_description": "Random deviation of bullet path when exiting material",
    "_unit": "degrees of cone spread", 
    "_explanation": "Usually larger than entry spread due to bullet tumbling and material displacement",
    "_typical_values": {
      "thin_plates": "1-3 degrees",
      "medium_thickness": "3-8 degrees", 
      "thick_materials": "8-15 degrees",
      "very_thick": "15+ degrees"
    },
    "_factors": "Increases with material thickness and bullet instability",
    "value": 0.0
  },

  "NeverRicochet": {
    "_description": "Prevents bullets from ricocheting off this material",
    "_use_cases": [
      "Soft materials (rubber, sand)",
      "Materials that always absorb bullets",
      "Gameplay balance (prevent unintended ricochets)"
    ],
    "_note": "Overrides ricochet calculations when true",
    "value": false
  },

  "RicochetProbabilityMultiplier": {
    "_description": "Scaling factor for ricochet probability calculations",
    "_unit": "multiplier (1.0 = normal ricochet probability)",
    "_range": "0.0-5.0 typical",
    "_effects": {
      "0.0": "No ricochets (same as NeverRicochet)",
      "0.5": "Reduced ricochet probability",
      "1.0": "Normal ricochet probability",
      "2.0": "Increased ricochet probability",
      "5.0": "Very high ricochet probability"
    },
    "_material_examples": {
      "concrete": "0.8-1.2",
      "steel": "1.0-1.5", 
      "water": "0.3-0.7",
      "ice": "1.2-1.8"
    },
    "value": 1.0
  },

  "RicochetRestitution": {
    "_description": "Energy retention coefficient during ricochet",
    "_unit": "ratio (0.0-1.0)",
    "_explanation": "Fraction of kinetic energy retained after ricochet",
    "_physics": "Based on coefficient of restitution in collision physics",
    "_typical_values": {
      "very_soft": "0.1-0.3 (sand, mud)",
      "soft": "0.3-0.5 (wood, concrete)",
      "medium": "0.5-0.7 (steel, aluminum)",
      "hard": "0.7-0.9 (hardened steel, tungsten)",
      "ideal": "0.9-1.0 (theoretical perfectly elastic)"
    },
    "_note": "Higher values mean bullets retain more energy after ricochet",
    "value": 0.5
  },

  "RicochetRestitutionInfluence": {
    "_description": "How much material properties affect restitution calculation",
    "_unit": "influence factor (0.0-1.0)",
    "_explanation": "0.0 = fixed restitution, 1.0 = fully material-dependent",
    "_typical_range": "0.0-0.5",
    "_usage": "Allows fine-tuning of material influence on energy loss",
    "value": 0.0
  },

  "RicochetFriction": {
    "_description": "Friction coefficient affecting ricochet angle and spin",
    "_unit": "coefficient of friction (0.0-2.0 typical)",
    "_physics": "Determines tangential force during ricochet contact",
    "_typical_values": {
      "smooth_metal": "0.1-0.3",
      "rough_metal": "0.3-0.6",
      "concrete": "0.6-0.9",
      "rubber": "0.8-1.2",
      "very_rough": "1.2+ (textured surfaces)"
    },
    "_effects": [
      "Higher friction increases bullet spin",
      "Affects ricochet angle deviation",
      "Influences energy loss during contact"
    ],
    "value": 0.5
  },

  "RicochetFrictionInfluence": {
    "_description": "How much friction affects the ricochet calculation",
    "_unit": "influence factor (0.0-1.0)",
    "_explanation": "0.0 = friction ignored, 1.0 = full friction effects",
    "_typical_range": "0.0-0.8",
    "_usage": "Allows realistic friction effects while maintaining performance",
    "value": 0.0
  },

  "RicochetSpread": {
    "_description": "Random angular deviation added to ricochet direction",
    "_unit": "degrees of cone spread",
    "_causes": [
      "Surface irregularities",
      "Bullet deformation",
      "Material inhomogeneity"
    ],
    "_typical_values": {
      "smooth_surfaces": "0-5 degrees",
      "rough_surfaces": "5-15 degrees",
      "very_rough": "15-30 degrees",
      "irregular": "30+ degrees"
    },
    "_realism": "Real ricochets are rarely perfectly predictable",
    "value": 0.0
  },

  "EnableSpalling": {
    "_description": "Whether this material generates spalling fragments when impacted",
    "_explanation": "Spalling occurs when material fractures and ejects fragments from impact",
    "_occurs_in": [
      "Brittle materials (concrete, ceramics, glass)",
      "Layered materials (armor plates)",
      "Materials under tension stress"
    ],
    "_note": "Computationally expensive - use selectively",
    "value": false
  },

  "SpallVelocityThreshold": {
    "_description": "Minimum impact velocity to generate spalling fragments",
    "_unit": "centimeters per second (cm/s)",
    "_conversion": "1 fps = 30.48 cm/s, 1 m/s = 100 cm/s",
    "_typical_thresholds": {
      "glass": "15000-30000 cm/s (500-1000 fps)",
      "concrete": "30000-60000 cm/s (1000-2000 fps)",
      "mild_steel": "60000-120000 cm/s (2000-4000 fps)",
      "hardened_steel": "120000+ cm/s (4000+ fps)"
    },
    "_physics": "Based on material's dynamic fracture strength",
    "value": 50000.0
  },

  "SpallFragmentCount": {
    "_description": "Maximum number of spall fragments generated per impact",
    "_unit": "count (integer)",
    "_range": "1-20 typical (performance considerations)",
    "_factors": [
      "Impact energy",
      "Material brittleness", 
      "Thickness",
      "Computational limitations"
    ],
    "_typical_values": {
      "small_impact": "1-3 fragments",
      "medium_impact": "3-8 fragments",
      "large_impact": "8-15 fragments",
      "massive_impact": "15+ fragments"
    },
    "value": 3
  },

  "SpallSpreadAngle": {
    "_description": "Cone angle for spall fragment ejection",
    "_unit": "degrees (0-180)",
    "_physics": "Fragments typically eject in forward cone from impact point",
    "_typical_values": {
      "focused": "15-30 degrees (hard materials)",
      "moderate": "30-60 degrees (typical materials)",
      "wide": "60-90 degrees (soft/brittle materials)",
      "hemispherical": "90+ degrees (extreme cases)"
    },
    "_note": "Larger angles create more dispersed fragment patterns",
    "value": 45.0
  },

  "SpallVelocityMultiplier": {
    "_description": "Fraction of impact velocity inherited by spall fragments",
    "_unit": "ratio (0.0-1.0)",
    "_physics": "Conservation of momentum with energy losses",
    "_typical_values": {
      "low_energy": "0.1-0.2 (material absorbs most energy)",
      "medium_energy": "0.2-0.4 (typical spalling)",
      "high_energy": "0.4-0.6 (explosive spalling)",
      "extreme": "0.6+ (theoretical maximum)"
    },
    "_factors": "Material brittleness, fragment size, impact energy",
    "value": 0.3
  },

  "SpallMassMultiplier": {
    "_description": "Fraction of projectile mass inherited by each spall fragment",
    "_unit": "ratio (0.0-1.0)",
    "_calculation": "Fragment mass = bullet mass × multiplier ÷ fragment count",
    "_typical_values": {
      "fine_fragments": "0.01-0.05 (dust-like)",
      "small_fragments": "0.05-0.15 (typical)",
      "large_fragments": "0.15-0.3 (dangerous sized)",
      "very_large": "0.3+ (rare, massive impacts)"
    },
    "_realism": "Total fragment mass should be reasonable fraction of material displaced",
    "value": 0.1
  },

  "UseMathematicalProperties": {
    "_description": "Enable detailed material science calculations",
    "_explanation": "Uses engineering properties for more accurate ballistic modeling",
    "_benefits": [
      "More realistic penetration calculations",
      "Temperature and strain rate effects",
      "Scientific accuracy for research"
    ],
    "_cost": "Increased computational complexity",
    "value": true
  },

  "MathematicalProperties": {
    "_description": "Detailed material science properties for accurate ballistic modeling",
    "_note": "Values should be obtained from material testing or engineering handbooks",
    "_reference": "ASTM standards, engineering material databases, scientific literature",

    "DensityGPerCm3": {
      "_description": "Material density",
      "_unit": "grams per cubic centimeter (g/cm³)",
      "_conversion": "1 g/cm³ = 1000 kg/m³ = 62.43 lb/ft³",
      "_typical_values": {
        "aluminum": "2.70 g/cm³",
        "steel_mild": "7.85 g/cm³",
        "steel_stainless": "8.0 g/cm³",
        "titanium": "4.5 g/cm³",
        "lead": "11.34 g/cm³",
        "tungsten": "19.3 g/cm³",
        "concrete": "2.4 g/cm³",
        "wood_oak": "0.75 g/cm³",
        "kevlar": "1.44 g/cm³"
      },
      "_importance": "Affects momentum transfer and penetration resistance",
      "value": 7.85
    },

    "MaterialHardness": {
      "_description": "Brinell hardness of the material",
      "_unit": "Brinell Hardness Number (HB or BHN)",
      "_test": "10mm steel ball, 3000kg load, 30 seconds",
      "_typical_values": {
        "aluminum_pure": "15-30 HB",
        "aluminum_alloy": "30-150 HB",
        "steel_mild": "120-200 HB",
        "steel_carbon": "200-400 HB",
        "steel_tool": "400-700 HB",
        "titanium": "200-400 HB",
        "brass": "60-200 HB",
        "concrete": "20-40 HB (estimated)"
      },
      "_penetration_effect": "Harder materials resist penetration and deformation",
      "value": 200.0
    },

    "TensileStrengthMPa": {
      "_description": "Ultimate tensile strength - maximum stress before failure",
      "_unit": "Megapascals (MPa)",
      "_conversion": "1 MPa = 145.04 psi = 0.145 ksi",
      "_typical_values": {
        "aluminum_1100": "90-165 MPa",
        "aluminum_6061": "240-310 MPa", 
        "steel_mild": "400-550 MPa",
        "steel_carbon": "550-1000 MPa",
        "steel_stainless": "500-750 MPa",
        "titanium_cp": "240-550 MPa",
        "concrete": "3-5 MPa (compression much higher)",
        "kevlar_fiber": "3000-3500 MPa"
      },
      "_ballistic_relevance": "Determines material failure under impact stress",
      "value": 400.0
    },

    "YieldStrengthMPa": {
      "_description": "Yield strength - stress at which permanent deformation begins",
      "_unit": "Megapascals (MPa)",
      "_typical_ratio": "Usually 50-80% of tensile strength",
      "_typical_values": {
        "aluminum_1100": "35-145 MPa",
        "aluminum_6061": "240-276 MPa",
        "steel_mild": "250-400 MPa", 
        "steel_carbon": "400-700 MPa",
        "steel_stainless": "200-300 MPa",
        "titanium_cp": "170-485 MPa"
      },
      "_ballistic_relevance": "Determines when material begins permanent deformation during impact",
      "value": 250.0
    },

    "ElasticModulusGPa": {
      "_description": "Young's modulus - material stiffness",
      "_unit": "Gigapascals (GPa)", 
      "_conversion": "1 GPa = 1000 MPa = 145,038 psi",
      "_typical_values": {
        "aluminum": "69-70 GPa",
        "steel": "200-210 GPa",
        "titanium": "105-120 GPa",
        "concrete": "20-50 GPa",
        "kevlar": "60-125 GPa",
        "carbon_fiber": "150-500 GPa"
      },
      "_ballistic_relevance": "Affects stress wave propagation and material response time",
      "value": 200.0
    },

    "BallisticLimitVelocity": {
      "_description": "Velocity at which 50% of impacts will just penetrate completely",
      "_unit": "feet per second (fps)",
      "_conversion": "1 fps = 0.3048 m/s",
      "_determination": "Experimental testing with specific projectile/material combinations",
      "_typical_ranges": {
        "thin_aluminum": "800-1500 fps",
        "mild_steel_plate": "1500-3000 fps",
        "hardened_steel": "2500-4500 fps",
        "ceramic_armor": "2000-3500 fps",
        "kevlar_vest": "1200-1800 fps"
      },
      "_note": "Highly dependent on projectile type, material thickness, and impact conditions",
      "value": 2000.0
    },

    "PerforationCoefficient": {
      "_description": "Empirical factor for perforation calculations",
      "_unit": "dimensionless coefficient",
      "_typical_range": "0.5-2.0",
      "_usage": "Adjusts theoretical calculations to match experimental data",
      "_values": {
        "soft_materials": "0.5-0.8",
        "typical_metals": "0.8-1.2", 
        "hard_materials": "1.2-2.0"
      },
      "value": 1.0
    },

    "EnergyAbsorptionCoefficient": {
      "_description": "Fraction of projectile kinetic energy absorbed by material",
      "_unit": "ratio (0.0-1.0)",
      "_physics": "Energy dissipated through deformation, fracture, heat",
      "_typical_values": {
        "very_soft": "0.9-1.0 (sand, foam)",
        "soft": "0.7-0.9 (wood, plastic)",
        "medium": "0.5-0.7 (aluminum, mild steel)",
        "hard": "0.3-0.5 (hardened steel, ceramics)",
        "very_hard": "0.1-0.3 (tungsten, depleted uranium)"
      },
      "_note": "Higher values mean more energy absorbed, less exit velocity",
      "value": 0.7
    },

    "EnableMathematicalSpalling": {
      "_description": "Use physics-based spalling calculations instead of simple model",
      "_benefits": [
        "Stress-based fragment generation",
        "Realistic fragment size distribution",
        "Velocity-dependent fragment count"
      ],
      "_cost": "Significantly more computational overhead",
      "value": false
    },

    "SpallStrengthMPa": {
      "_description": "Dynamic tensile strength - stress required to cause spalling",
      "_unit": "Megapascals (MPa)",
      "_physics": "Material's resistance to tensile failure under shock loading",
      "_typical_values": {
        "concrete": "2-8 MPa",
        "aluminum": "100-300 MPa",
        "mild_steel": "150-400 MPa",
        "hardened_steel": "200-600 MPa",
        "ceramics": "50-200 MPa",
        "composites": "20-100 MPa"
      },
      "_note": "Usually lower than static tensile strength due to high strain rates",
      "value": 150.0
    },

    "CriticalStressFactor": {
      "_description": "Multiplier for stress calculations in spalling",
      "_unit": "dimensionless factor",
      "_typical_range": "1.5-4.0", 
      "_physics": "Accounts for stress concentration, dynamic effects, material flaws",
      "_calibration": "Adjust to match experimental spalling thresholds",
      "value": 2.5
    },

    "FragmentVelocityEfficiency": {
      "_description": "Efficiency of momentum transfer to spall fragments",
      "_unit": "ratio (0.0-1.0)",
      "_physics": "Based on conservation of momentum and energy dissipation",
      "_typical_values": {
        "brittle_materials": "0.1-0.3",
        "ductile_materials": "0.2-0.4",
        "optimal_conditions": "0.3-0.5"
      },
      "_factors": "Fragment size, material properties, impact energy",
      "value": 0.25
    },

    "AverageFragmentMassRatio": {
      "_description": "Average mass of fragments relative to total spalled material",
      "_unit": "ratio (0.0-1.0)",
      "_explanation": "Controls fragment size distribution - smaller ratios create more, smaller fragments",
      "_typical_values": {
        "fine_fragmentation": "0.01-0.05",
        "normal_fragmentation": "0.05-0.15",
        "coarse_fragmentation": "0.15-0.3"
      },
      "value": 0.08
    },

    "FragmentSizeExponent": {
      "_description": "Power law exponent for fragment size distribution",
      "_unit": "dimensionless exponent",
      "_physics": "Based on fracture mechanics - typically negative values",
      "_typical_range": "-2.5 to -1.0",
      "_meaning": {
        "-2.5": "Many small fragments, few large ones",
        "-2.0": "Moderate distribution",
        "-1.5": "More uniform fragment sizes",
        "-1.0": "Tendency toward larger fragments"
      },
      "_reference": "Mott fragmentation theory, Weibull distributions",
      "value": -1.6
    },

    "MaxFragmentDensity": {
      "_description": "Maximum number of fragments per unit impact area",
      "_unit": "fragments per square centimeter",
      "_purpose": "Prevents excessive fragment generation that could impact performance",
      "_typical_limits": {
        "low_detail": "10-25 fragments/cm²",
        "medium_detail": "25-75 fragments/cm²", 
        "high_detail": "75-150 fragments/cm²",
        "research_quality": "150+ fragments/cm²"
      },
      "_balance": "Higher values increase realism but reduce performance",
      "value": 50.0
    }
  }
}