Migration guide v3.6.0

This release changes both weapon JSON and ammo JSON. If you keep the old 3.5.2 format, weapons will not read ammo capacity, reload values, projectile values, or ammo compatibility correctly.

1. Update weapon settings format

Move flat values from HyGuns.Settings into nested Ammo, Fire, and Projectiles groups.

Field mapping

• MaxAmmo -> Ammo.Capacity
• ReloadTime -> Ammo.Reload.Time
• ReloadAmountPerInteraction -> Ammo.Reload.Amount
• AmmoItemType -> Ammo.ItemId only if the weapon must use one exact ammo item
• keep interaction Primary.Cooldown.Cooldown on the item
• also add the same base value to Fire.Cooldown
• ProjectileConfigId / ProjectileConfigID -> Projectiles.ConfigId
• ProjectileId / ProjectileID -> Projectiles.ProjectileId
• NumProjectiles -> Projectiles.Count
• Spread -> Projectiles.Spread
• Damage -> Projectiles.Damage
• AmmoIcon -> remove from weapon config; ammo icon now belongs to the ammo item

What stays where it was

• WeaponIcon
• DealLethalDamage
• AmmoGuidance
• WallPenetration
• damage multipliers already supported in HyGuns.Settings

After (3.6.0)

{
  "Interactions": {
    "Primary": {
      "Cooldown": {
        "Cooldown": 0.1
      }
    }
  },
  "HyGuns": {
    "Settings": {
      "WeaponIcon": null,
      "Ammo": {
        "Family": "Bullet",
        "WeaponClass": ["Rifle"],
        "Capacity": 30,
        "Reload": {
          "Time": 1.2,
          "Amount": 30
        }
      },
      "Fire": {
        "Cooldown": 0.1
      },
      "Projectiles": {
        "ConfigId": "Hyguns_Projectile_Config_Bullet",
        "Count": 1,
        "Spread": 0.02,
        "Damage": 10
      }
    }
  }
}

Fire cooldown note:

• Interactions.Primary.Cooldown.Cooldown is still required for normal repeat-fire behavior.
• HyGuns.Settings.Fire.Cooldown is an additional HyGuns server-side cooldown.
• Keep them in sync for the base weapon.
• Ammo may override only HyGuns.Settings.Fire.Cooldown.
• If ammo sets a longer cooldown, HyGuns will block the shoot interaction for that longer period on the server side.

2. Define ammo compatibility on the weapon

Recommended fields:

• HyGuns.Settings.Ammo.Family
• HyGuns.Settings.Ammo.WeaponClass

Notes:

• WeaponClass on the weapon may be a string or an array.
• Ammo.ItemId is optional and should be used only when you want a fixed ammo item.

3. Create or update ammo items

Ammo is configured on the ammo item itself through HyGuns.AmmoSettings.

Required for ammo items

• HyGuns.AmmoSettings.Family
• HyGuns.AmmoSettings.WeaponClass

Recommended

• HyGuns.AmmoSettings.Icon
• root Quality

4. Move ammo-specific behavior into the ammo item

Ammo can override weapon stats through:

• HyGuns.AmmoSettings.SettingsOverrides

Example:

"SettingsOverrides": {
  "Fire": {
    "Cooldown": 5.0
  },
  "Projectiles": {
    "Damage": 14,
    "Spread": 0.01
  },
  "WallPenetration": {
    "Enabled": true,
    "Blocks": 2.0
  }
}

Important behavior:

• ammo overrides affect HyGuns.Settings.Fire.Cooldown, not Interactions.Primary.Cooldown.Cooldown;
• special ammo can therefore make a weapon slower on the server side;
• base repeat-fire cadence still depends on the item Primary.Cooldown.

5. Move ammo impact logic into the ammo item

Ammo-specific hit behavior belongs in:

• HyGuns.AmmoSettings.Interactions.EntityHit
• HyGuns.AmmoSettings.Interactions.BlockHit

Supported handlers:

• ApplyEffect
• ClearEntityEffect
• TeleportToBlockHit

6. Update reload interaction if you want ammo selection UI

Recommended pattern:

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

7. Practical migration checklist

For every weapon:

• move flat ammo fields into HyGuns.Settings.Ammo
• keep Interactions.Primary.Cooldown.Cooldown
• copy the same base value into HyGuns.Settings.Fire.Cooldown
• move projectile fields into HyGuns.Settings.Projectiles
• remove weapon-level AmmoIcon
• define Ammo.Family
• define Ammo.WeaponClass

For every ammo item:

• add HyGuns.AmmoSettings
• set Family
• set WeaponClass
• set Icon
• add SettingsOverrides only for special ammo
• add Interactions only for special on-hit behavior