Skip to content

Quick start

Jump to bottom
enso-x edited this page Mar 14, 2026 · 4 revisions

This page is the short version of the HyGuns content format.

If you want the full format reference, use:

1. Basic Weapon

Minimal working weapon:

{
  "Interactions": {
    "Primary": {
      "Cooldown": {
        "Cooldown": 0.1
      },
      "RequireNewClick": false,
      "Interactions": [
        {
          "Type": "Hyguns_Shoot",
          "Failed": "Gun_Shoot_Fail"
        }
      ]
    }
  },
  "HyGuns": {
    "Settings": {
      "WeaponIcon": "Weapons/AK47.png",
      "Ammo": {
        "Family": "Bullet",
        "WeaponClass": ["Rifle"],
        "Capacity": 30,
        "Reload": {
          "Time": 2.4,
          "Amount": 30
        }
      },
      "Fire": {
        "Cooldown": 0.1
      },
      "Projectiles": {
        "ConfigId": "Hyguns_Projectile_Config_Bullet",
        "Count": 1,
        "Spread": 0.02,
        "Damage": 17
      }
    }
  }
}

2. Basic Ammo

Minimal working ammo item:

{
  "Quality": "Common",
  "HyGuns": {
    "AmmoSettings": {
      "Family": "Bullet",
      "WeaponClass": "Rifle",
      "Icon": "Ammo/Ammo_Rifle.png"
    }
  }
}

3. Compatibility

Weapon and ammo matching works like this:

  • weapon Ammo.Family must match ammo AmmoSettings.Family
  • ammo AmmoSettings.WeaponClass must match one of the weapon Ammo.WeaponClass values

4. Special Ammo

Ammo can override weapon settings:

"SettingsOverrides": {
  "Fire": {
    "Cooldown": 5.0
  },
  "Projectiles": {
    "Damage": 24
  }
}

This is useful for:

  • teleport ammo
  • explosive ammo
  • armor-piercing ammo
  • utility ammo with long cooldowns

5. Important Fire Rule

Keep both of these on the weapon:

  • Interactions.Primary.Cooldown.Cooldown
  • HyGuns.Settings.Fire.Cooldown

Use the same base value on both.

6. Reload and Ammo Selection

Recommended reload input pattern:

{
  "Type": "Charging",
  "DisplayProgress": false,
  "AllowIndefiniteHold": false,
  "Next": {
    "0": {
      "Type": "Hyguns_Reload"
    },
    "0.25": {
      "Type": "OpenCustomUI",
      "Page": {
        "Id": "AmmoSelection"
      }
    }
  }
}

7. Full Docs

For the complete list of fields, defaults, aliases, and ammo interaction handlers:

Clone this wiki locally