Skip to content

HyGuns Content Reference

Jump to bottom
enso-x edited this page Mar 15, 2026 · 3 revisions

Complete reference for weapon settings and ammo settings in HyGuns v3.6.1.

This document lists all currently supported weapon settings, ammo settings, nested sections, aliases, defaults, and supported ammo interaction handlers.

Overview

HyGuns content is configured in two places:

  • weapon item JSONs
  • ammo item JSONs

Weapons use:

  • base item interaction settings under Interactions
  • HyGuns-specific settings under HyGuns.Settings

Ammo items use:

  • ammo metadata under HyGuns.AmmoSettings
  • optional weapon overrides under HyGuns.AmmoSettings.SettingsOverrides
  • optional hit logic under HyGuns.AmmoSettings.Interactions

Important Fire Cooldown Note

Weapon fire-rate currently has two layers:

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

They are not the same thing.

Interactions.Primary.Cooldown.Cooldown:

  • controls the base cadence of the item interaction itself
  • is required for normal repeat-fire behavior on automatic weapons
  • should stay on the weapon item JSON

HyGuns.Settings.Fire.Cooldown:

  • is an additional HyGuns server-side fire cooldown
  • can be overridden by ammo through SettingsOverrides.Fire.Cooldown
  • is used to block the shoot interaction if a special ammo type should fire more slowly

Recommended rule:

  • keep both values equal for the base weapon
  • use ammo overrides only when special ammo should make the weapon slower or otherwise change server-side fire gating

Weapon JSON Structure

Typical weapon structure:

{
  "Interactions": {
    "Primary": {
      "Cooldown": {
        "Cooldown": 0.1
      },
      "RequireNewClick": false,
      "Interactions": [
        {
          "Type": "Hyguns_Shoot"
        }
      ]
    }
  },
  "HyGuns": {
    "Settings": {
      "WeaponIcon": "Weapons/AK47.png",
      "DealLethalDamage": false,
      "Ammo": {
        "Family": "Bullet",
        "WeaponClass": ["Rifle"],
        "Capacity": 30,
        "Reload": {
          "Time": 2.4,
          "Amount": 30
        },
        "AmmoSave": {
          "Enabled": false,
          "Chance": 0.0
        }
      },
      "Fire": {
        "Cooldown": 0.1
      },
      "Projectiles": {
        "ConfigId": "Hyguns_Projectile_Config_Bullet",
        "ProjectileId": null,
        "Spread": 0.02,
        "Count": 1,
        "Damage": 17
      },
      "DamageModifier": {
        "Type": "MULTIPLY",
        "Value": 1.0
      },
      "DamageModifiers": {
        "Head": {
          "Type": "MULTIPLY",
          "Value": 1.5
        },
        "Body": {
          "Type": "MULTIPLY",
          "Value": 1.0
        },
        "*": {
          "Type": "MULTIPLY",
          "Value": 1.0
        }
      },
      "AutoGuidance": {
        "Enabled": false,
        "EffectId": null,
        "AffectsPlayers": false,
        "ConeDegrees": 25.0,
        "MaxDistance": 80.0,
        "TurnRate": 240.0
      },
      "WallPenetration": {
        "Enabled": false,
        "Blocks": 1.0,
        "DamageReductionModifier": 0.0,
        "DamageReductionDistance": 0.5
      }
    }
  }
}

Weapon Interaction Requirements

These are not inside HyGuns.Settings, but they are part of the practical weapon format.

Interactions.Primary

Recommended fields:

  • Cooldown.Cooldown
  • RequireNewClick
  • Interactions

Typical pattern:

"Primary": {
  "Cooldown": {
    "Cooldown": 0.1
  },
  "RequireNewClick": false,
  "Interactions": [
    {
      "Type": "Hyguns_Shoot",
      "Failed": "Gun_Shoot_Fail"
    }
  ]
}

Notes:

  • Primary.Cooldown.Cooldown should normally match HyGuns.Settings.Fire.Cooldown.
  • If Primary.Cooldown is missing, very fast automatic fire will not feel correct even if HyGuns.Settings.Fire.Cooldown is set.

Reload Input Pattern

Recommended reload/selection pattern:

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

Weapon Settings Reference

All HyGuns weapon settings live under:

"HyGuns": {
  "Settings": { ... }
}

WeaponIcon

Type:

  • string

Optional:

  • yes

Purpose:

  • weapon icon path for HyGuns HUD/UI

DealLethalDamage

Type:

  • boolean

Optional:

  • yes

Default:

  • false

Purpose:

  • enables lethal damage handling for the projectile hit flow

Ammo

Nested object:

  • HyGuns.Settings.Ammo

Supported fields:

  • Family
  • WeaponClass
  • ItemId
  • Capacity
  • Max alias for Capacity
  • Reload
  • AmmoSave

Ammo.Family

  • type: string

Ammo.WeaponClass

  • type: string or string array

Ammo.ItemId

  • type: string

Ammo.Capacity

  • type: positive integer
  • alias: Max
  • runtime fallback if missing: 1

Ammo.Reload.Time

  • type: double

Ammo.Reload.Amount

  • type: positive integer
  • runtime fallback if missing: weapon capacity

Ammo.AmmoSave.Enabled

  • type: boolean

Ammo.AmmoSave.Chance

  • type: double in range 0.0 to 1.0

Defaults:

  • Enabled = false
  • Chance = 0.0

Fire

Nested object:

  • HyGuns.Settings.Fire

Supported fields:

  • Cooldown

Fire.Cooldown

  • type: positive double
  • runtime fallback if missing: 0.0

Purpose:

  • HyGuns server-side fire cooldown

Projectiles

Nested object:

  • HyGuns.Settings.Projectiles

Supported fields:

  • ConfigId
  • ProjectileId
  • ProjectileID alias for ProjectileId
  • Spread
  • Count
  • Damage

Runtime fallbacks:

  • Spread = 0.075
  • Count = 1
  • Damage = 15

DamageModifier

Nested object:

  • HyGuns.Settings.DamageModifier

Supported fields:

  • Type
  • Value

Purpose:

  • applies one final damage modification to the base projectile damage before hit-part modifiers are evaluated

Supported Type values:

  • ADDITIVE
  • MULTIPLY
  • STATIC

Examples:

"DamageModifier": {
  "Type": "MULTIPLY",
  "Value": 0.5
}
"DamageModifier": {
  "Type": "STATIC",
  "Value": 0
}

DamageModifiers

Nested object:

  • HyGuns.Settings.DamageModifiers

Supported fields:

  • Head
  • Body
  • Fallback
  • * alias for Fallback

Each hit-part entry uses the same DamageModifier object format:

  • Type
  • Value

Defaults:

  • Head = MULTIPLY 1.5
  • Body = MULTIPLY 1.0
  • Fallback = MULTIPLY 1.0

AutoGuidance

Nested object:

  • HyGuns.Settings.AutoGuidance

Supported fields:

  • Enabled
  • EffectId
  • AffectsPlayers
  • ConeDegrees
  • MaxDistance
  • TurnRate

Defaults:

  • Enabled = false
  • EffectId = null
  • AffectsPlayers = false
  • ConeDegrees = 25.0
  • MaxDistance = 80.0
  • TurnRate = 240.0

Behavior:

  • if EffectId is set, guided projectiles first try to target the nearest valid entity with that entity effect;
  • if no matching marked target is found, guidance falls back to the normal nearest target inside the lock cone;
  • if EffectId is not set, only the normal lock-cone targeting mode is used.

WallPenetration

Nested object:

  • HyGuns.Settings.WallPenetration

Supported fields:

  • Enabled
  • Blocks
  • DamageReductionModifier
  • DamageReductionDistance

Defaults:

  • Enabled = false
  • Blocks = 1.0
  • DamageReductionModifier = 0.0
  • DamageReductionDistance = 0.5

Ammo Item JSON Structure

Ammo settings live under:

"HyGuns": {
  "AmmoSettings": { ... }
}

Ammo Settings Reference

Root Quality

Location:

  • root item field, not inside HyGuns.AmmoSettings

Type:

  • string

Purpose:

  • affects default ammo selection priority when multiple compatible ammo items exist

AmmoSettings.Family

  • type: string

AmmoSettings.WeaponClass

  • type: string

Note:

  • ammo items currently read a single weapon class string

AmmoSettings.Icon

  • type: string

AmmoSettings.SettingsOverrides

Type:

  • object

Supported override structure:

  • same nested structure as HyGuns.Settings

Supported override fields:

  • WeaponIcon
  • DealLethalDamage
  • Ammo
  • Fire
  • Projectiles
  • DamageModifier
  • DamageModifiers
  • AutoGuidance
  • WallPenetration

Notes:

  • SettingsOverrides.Fire.Cooldown affects the HyGuns server-side fire cooldown.
  • It does not replace the weapon item's base Interactions.Primary.Cooldown.Cooldown.

AmmoSettings.Interactions

Type:

  • object

Supported sections:

  • EntityHit
  • BlockHit
  • Miss

Each section:

  • array of interaction objects

Supported Ammo Interaction Handlers

Currently supported handler types:

  • ApplyEffect
  • ClearEntityEffect
  • TeleportToBlockHit

ApplyEffect

Supported fields:

  • Type
  • Entity
  • EffectId

Supported Entity values:

  • Target
  • Shooter
  • Source
  • User
  • Projectile

ClearEntityEffect

Supported fields:

  • Type
  • Entity
  • EntityEffectId

Supported Entity values:

  • Target
  • Shooter
  • Source
  • User
  • Projectile

TeleportToBlockHit

Supported fields:

  • Type

Current implementation:

  • works on block hit only
  • teleports the shooter to the hit block position

Compatibility Rules

Weapon and ammo compatibility:

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

Notes:

  • weapon Ammo.WeaponClass accepts a string or array
  • ammo AmmoSettings.WeaponClass is effectively a single class string
  • Ammo.ItemId on the weapon can force one exact ammo item

Runtime Defaults and Fallbacks

Useful runtime defaults:

  • weapon capacity fallback: 1
  • projectile damage fallback: 15
  • projectile count fallback: 1
  • projectile spread fallback: 0.075
  • fire cooldown fallback: 0.0
  • DamageModifier: none by default
  • DamageModifiers: Head MULTIPLY 1.5, Body MULTIPLY 1.0, Fallback MULTIPLY 1.0
  • AmmoSave: Enabled false, Chance 0.0
  • AutoGuidance: Enabled false, EffectId null, AffectsPlayers false, ConeDegrees 25.0, MaxDistance 80.0, TurnRate 240.0
  • WallPenetration: Enabled false, Blocks 1.0, DamageReductionModifier 0.0, DamageReductionDistance 0.5

Override Priority

HyGuns merges settings in this order:

  1. interaction overrides
  2. loaded ammo SettingsOverrides
  3. base weapon HyGuns.Settings

Minimal Working Weapon

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

Minimal Working Ammo

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

Practical Recommendations

  • Always configure both Interactions.Primary.Cooldown.Cooldown and HyGuns.Settings.Fire.Cooldown.
  • Always set weapon Ammo.Family and Ammo.WeaponClass.
  • Always set ammo AmmoSettings.Family and AmmoSettings.WeaponClass.
  • Give every ammo item an Icon if you use the HUD or ammo selection page.
  • Use SettingsOverrides.Fire.Cooldown only for special ammo behavior.

Clone this wiki locally