GunSpec

All 39 single-call tools

Free recoil

  • gunspec_firearm_recoil
  • Builder
  • Read-only

Returns the free recoil of one to five firearms firing a load: the velocity each is pushed back at, the energy it takes and the impulse, by the free recoil formula SAAMI publishes, from the firearm's recorded mass and the muzzle velocity its own barrel gives the load. Use this tool when the question is how hard one firearm kicks against another. The catalog holds no powder charge, so without powder_charge_g only the bullet is counted and every figure is a lower bound; say so when you quote it. It is free recoil, not felt recoil, and does not count a muzzle brake.

Example usage

  1. 1

    A person asks

    • How much free recoil does an HK416 have against an M4 carbine firing M855?
  2. 2

    The assistant calls the tool

    tools/call
    json
    {  "name": "gunspec_firearm_recoil",  "arguments": {    "ids": [      "hk416",      "m4-carbine"    ],    "ammo_id": "m855"  }}
  3. 3

    The server answers

    Result
    json
    {  "method": {    "id": "saami-free-recoil",    "name": "SAAMI free recoil",    "equation": "I (N·s) = m_b·v + m_c·f·v; V (m/s) = I / M; E (J) = ½·M·V²; m_b the bullet and m_c the powder charge in kg, v the muzzle velocity from this barrel in m/s, f the gas velocity factor for the class of firearm, M the firearm in kg. Without a po…",    "citations": [      {        "authors": "Sporting Arms and Ammunition Manufacturers' Institute (SAAMI)",        "year": 2018,        "title": "Gun Recoil, Technical: Free Recoil Energy",        "journal": "SAAMI technical sheet, Rev. 7/9/2018",        "doi": null,        "url": "https://saami.org/wp-content/uploads/2025/03/Gun-Recoil-Formulae-2018-07-9.pdf"      },      {        "authors": "Hatcher JS",        "year": 1957,        "title": "Hatcher's Notebook, second edition, chapter The Theory of Recoil",        "journal": "The Military Service Publishing Company",        "doi": null,        "url": "https://archive.org/details/hatchers-notebook-by-julian-s.-hatcher"      }    ],    "gasFactors": {      "rifle": 1.75,      "shotgun": 1.5,      "shotgun_long_barrel": 1.25,      "handgun": 1.5    }  },  "shot": {    "mass": "loaded",    "powderChargeG": null,    "gasClass": null,    "lowerBound": true,    "defaulted": [      "mass",      "powder_charge_g",      "gas_class"    ]  },  "results": [    {      "firearm": {        "id": "hk416",        "name": "HK416",        "categoryId": "assault-rifle",        "barrelLengthMm": 264      },      "ammunition": {        "id": "m855",        "name": "M855 Ball (SS109)",        "caliberId": "5-56x45mm-nato",        "bulletWeightG": 4.02      },      "mass": {        "firearmG": 3420,        "basis": "loaded",        "source": "catalogue"      },      "muzzleVelocityMps": 777,      "gas": {        "class": "rifle",        "label": "High powered rifles",        "factor": 1.75,        "velocityMps": null,        "chargeG": null,        "classSource": "category"      },      "recoil": {        "impulseNs": 3.125,        "bulletImpulseNs": 3.125,        "gasImpulseNs": null,        "velocityMps": 0.914,        "energyJ": 1.43,        "lowerBound": true      },      "delta": null,      "warnings": [],      "error": null    },    {      "firearm": {        "id": "m4-carbine",        "name": "M4 Carbine",        "categoryId": "carbine",        "barrelLengthMm": 368      },      "ammunition": {        "id": "m855",        "name": "M855 Ball (SS109)",        "caliberId": "5-56x45mm-nato",        "bulletWeightG": 4.02      },      "mass": {        "firearmG": 3320,        "basis": "loaded",        "source": "catalogue"      },      "muzzleVelocityMps": 856,      "gas": {        "class": "rifle",        "label": "High powered rifles",        "factor": 1.75,        "velocityMps": null,        "chargeG": null,        "classSource": "category"      },      "recoil": {        "impulseNs": 3.442,        "bulletImpulseNs": 3.442,        "gasImpulseNs": null,        "velocityMps": 1.037,        "energyJ": 1.78,        "lowerBound": true      },      "delta": {        "energyJ": 0.36,        "velocityMps": 0.123,        "impulseNs": 0.316      },      "warnings": [],      "error": null    }  ]}

    Captured from the live API on Oct 22, 2026. Lists and long text are shortened for display.

Related references

Arguments

  • string[]required

    One to five firearm slugs.

    Sent as
    ?ids=
  • string

    The load every firearm fires. Leave it out to fire each with the load its ballistic profile uses.

    Sent as
    ?ammo_id=
  • stringdefaultloaded

    Which recorded weight recoils.

    Accepts
    Sent as
    ?mass=
  • number

    The load's powder charge in grams, when the user states one. Needs ammo_id.

    Range
    0 – 100
    Sent as
    ?powder_charge_g=
  • string

    The SAAMI class whose gas velocity factor applies, in place of the one read from the category.

    Accepts
    Sent as
    ?gas_class=

Each argument is sent to GET /v1/firearms/recoil as the parameter shown, so the same request can be made to the API directly, with your key, if you want to shape what comes back.

json