Skip to content

JSON Assets guide

Jump to bottom
enso-x edited this page Jun 21, 2026 · 5 revisions

HyGuns JSON Assets Guide

This page documents the main HyGuns JSON blocks used in weapon, ammo, attachment, and HyGuns NPC assets.

The goal is simple:

  • find the block by name
  • see every supported field
  • understand the field type and accepted values
  • copy a full JSON example and adjust it

Table of Contents

Root Layout

HyGuns reads its custom blocks from the item JSON root under:

  • HyGuns.WeaponSettings for weapons
  • HyGuns.AmmoSettings for ammo items
  • HyGuns.AttachmentSettings for attachment items
  • HyGuns.AmmoItemId inside NPC role assets that use HyGuns weapon attacks

Typical weapon root:

{
  "Id": "Weapon_Rifle_Base",
  "TranslationProperties": {
    "Name": "Base Rifle"
  },
  "HyGuns": {
    "WeaponSettings": {
      "WeaponIcon": "Weapons/AK47.png"
    }
  }
}

Typical ammo root:

{
  "Id": "Ammo_Bullet_Base",
  "TranslationProperties": {
    "Name": "Base Bullets"
  },
  "Quality": "Common",
  "HyGuns": {
    "AmmoSettings": {
      "Family": "Bullet",
      "WeaponClass": "Rifle"
    }
  }
}

HyGuns.WeaponSettings

Main weapon settings block.

This block is read from:

{
  "HyGuns": {
    "WeaponSettings": {}
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
WeaponIcon string No omitted Weapon HUD icon path relative to Common/UI/Custom, for example "Weapons/AK47.png"
DealLethalDamage boolean No omitted true or false
Ammo object No omitted Weapon ammo settings block
Fire object No omitted Weapon fire settings block
Projectiles object No omitted Weapon projectile settings block
DamageModifier object No omitted One final damage modifier
DamageModifiers object No defaults to built-in hit modifiers Per-hit-part damage modifiers
AutoGuidance object No omitted Projectile guidance settings
WallPenetration object No omitted Wall penetration settings
AttachmentsDefinition object No omitted Weapon attachment slot layout and attachment UI schema
DefaultAttachments object No omitted Attachment item ids created into the attachment container during first weapon initialization

Full Example

{
  "HyGuns": {
    "WeaponSettings": {
      "WeaponIcon": "Weapons/AK47.png",
      "DealLethalDamage": false,
      "Ammo": {
        "Family": "Bullet",
        "WeaponClass": [
          "Rifle",
          "Assault"
        ],
        "ItemId": "Ammo_Bullet_Base",
        "Capacity": 30,
        "Reload": {
          "Time": 1.5,
          "Amount": 30
        },
        "AmmoSave": {
          "Enabled": false,
          "Chance": 0.0
        }
      },
      "Fire": {
        "Cooldown": 0.08
      },
      "Projectiles": {
        "ConfigId": "Rifle",
        "ProjectileId": "Projectile_Bullet_Base",
        "Spread": 0.015,
        "Count": 1,
        "Damage": 8
      },
      "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,
        "AffectsPlayers": false,
        "ConeDegrees": 25.0,
        "MaxDistance": 80.0,
        "TurnRate": 240.0,
        "EffectId": "MarkedTarget"
      },
      "WallPenetration": {
        "Enabled": false,
        "Blocks": 1.0,
        "DamageReductionModifier": 0.0,
        "DamageReductionDistance": 0.5
      }
    }
  }
}

Typical Usage

{
  "HyGuns": {
    "WeaponSettings": {
      "WeaponIcon": "Weapons/DoubleBarrel.png",
      "Ammo": {
        "Family": "Shell",
        "WeaponClass": "Shotgun",
        "ItemId": "Ammo_Shell_Base",
        "Capacity": 8,
        "Reload": {
          "Time": 0.9,
          "Amount": 1
        }
      },
      "Projectiles": {
        "ConfigId": "Shotgun",
        "ProjectileId": "Projectile_Shell_Base",
        "Spread": 0.14,
        "Count": 8,
        "Damage": 5
      }
    }
  }
}

HyGuns.WeaponSettings.Ammo

Weapon ammo configuration.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Family string No omitted Ammo family id, for example "Bullet"
WeaponClass string or string[] No omitted Compatible weapon class or classes
ItemId string No omitted Default ammo item id
Capacity integer No omitted Magazine or chamber capacity, must be > 0
Max integer No omitted Alias for Capacity
Reload object No omitted Reload settings block
AmmoSave object No omitted Ammo save settings block

Full Example

{
  "Ammo": {
    "Family": "Bullet",
    "WeaponClass": [
      "Rifle",
      "Assault"
    ],
    "ItemId": "Ammo_Bullet_Base",
    "Capacity": 30,
    "Reload": {
      "Time": 1.25,
      "Amount": 30
    },
    "AmmoSave": {
      "Enabled": true,
      "Chance": 0.2
    }
  }
}

Typical Usage

{
  "Ammo": {
    "Family": "Rocket",
    "WeaponClass": "Launcher",
    "ItemId": "Ammo_Rocket_Base",
    "Capacity": 1,
    "Reload": {
      "Time": 2.0,
      "Amount": 1
    }
  }
}

HyGuns.WeaponSettings.Ammo.Reload

Reload timing and per-reload amount.

This block lives inside HyGuns.WeaponSettings.Ammo.

Fields

Field Type Required Default Accepted Values / Meaning
Time number No omitted Reload duration in seconds
Amount integer No omitted Ammo added by one reload action, must be > 0

Full Example

{
  "Reload": {
    "Time": 1.1,
    "Amount": 5
  }
}

Typical Usage

{
  "Reload": {
    "Time": 0.8,
    "Amount": 1
  }
}

HyGuns.WeaponSettings.Ammo.AmmoSave

Chance-based ammo preservation settings.

This block lives inside HyGuns.WeaponSettings.Ammo.

Fields

Field Type Required Default Accepted Values / Meaning
Enabled boolean No omitted true or false
Chance number No omitted Value from 0.0 to 1.0

Full Example

{
  "AmmoSave": {
    "Enabled": true,
    "Chance": 0.35
  }
}

Typical Usage

{
  "AmmoSave": {
    "Enabled": false,
    "Chance": 0.0
  }
}

HyGuns.WeaponSettings.Fire

Weapon fire configuration.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Cooldown number No omitted Fire cooldown in seconds, must be > 0

Full Example

{
  "Fire": {
    "Cooldown": 0.15
  }
}

Typical Usage

{
  "Fire": {
    "Cooldown": 0.05
  }
}

HyGuns.WeaponSettings.Projectiles

Projectile spawn and damage configuration.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
ConfigId string No omitted Projectile config id
ProjectileId string No omitted Projectile asset id
ProjectileID string No omitted Alias for ProjectileId
Spread number No omitted Projectile spread value
Count integer No omitted Projectile count, must be > 0
Damage integer No omitted Base damage, must be >= 0

Full Example

{
  "Projectiles": {
    "ConfigId": "Rifle",
    "ProjectileId": "Projectile_Bullet_Base",
    "Spread": 0.02,
    "Count": 1,
    "Damage": 7
  }
}

Typical Usage

{
  "Projectiles": {
    "ConfigId": "Shotgun",
    "ProjectileId": "Projectile_Shell_Base",
    "Spread": 0.14,
    "Count": 8,
    "Damage": 4
  }
}

HyGuns.WeaponSettings.DamageModifier

One final damage modifier applied before hit-part-specific modifiers.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Type string Yes none ADDITIVE, MULTIPLY, or STATIC
Value number Yes none Modifier value

Full Example

{
  "DamageModifier": {
    "Type": "MULTIPLY",
    "Value": 0.85
  }
}

Typical Usage

{
  "DamageModifier": {
    "Type": "ADDITIVE",
    "Value": 2.0
  }
}

HyGuns.WeaponSettings.DamageModifiers

Hit-part-specific damage modifiers.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Head object No built-in default DamageModifier object for head hits
Body object No built-in default DamageModifier object for body hits
Fallback object No built-in default DamageModifier object for all other hits
* object No built-in default Alias for Fallback

Full Example

{
  "DamageModifiers": {
    "Head": {
      "Type": "MULTIPLY",
      "Value": 2.0
    },
    "Body": {
      "Type": "MULTIPLY",
      "Value": 1.0
    },
    "*": {
      "Type": "MULTIPLY",
      "Value": 0.75
    }
  }
}

Typical Usage

{
  "DamageModifiers": {
    "Head": {
      "Type": "MULTIPLY",
      "Value": 1.5
    },
    "Body": {
      "Type": "MULTIPLY",
      "Value": 1.0
    },
    "*": {
      "Type": "MULTIPLY",
      "Value": 1.0
    }
  }
}

HyGuns.WeaponSettings.AutoGuidance

Projectile guidance configuration.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Enabled boolean No omitted true or false
AffectsPlayers boolean No omitted true or false
ConeDegrees number No omitted Lock cone in degrees, must be > 0
MaxDistance number No omitted Max targeting distance, must be > 0
TurnRate number No omitted Guidance turn rate, must be > 0
EffectId string No omitted Optional effect id used to prioritize marked targets

Full Example

{
  "AutoGuidance": {
    "Enabled": true,
    "AffectsPlayers": false,
    "ConeDegrees": 40.0,
    "MaxDistance": 120.0,
    "TurnRate": 300.0,
    "EffectId": "MarkedTarget"
  }
}

Typical Usage

{
  "AutoGuidance": {
    "Enabled": true,
    "ConeDegrees": 25.0,
    "MaxDistance": 80.0,
    "TurnRate": 240.0
  }
}

HyGuns.WeaponSettings.WallPenetration

Wall penetration configuration.

This block lives inside HyGuns.WeaponSettings.

Fields

Field Type Required Default Accepted Values / Meaning
Enabled boolean No omitted true or false
Blocks number No omitted How many blocks can be penetrated, must be > 0
DamageReductionModifier number No omitted Extra damage reduction modifier, must be >= 0
DamageReductionDistance number No omitted Added reduction distance factor, must be > 0

Full Example

{
  "WallPenetration": {
    "Enabled": true,
    "Blocks": 2.0,
    "DamageReductionModifier": 0.25,
    "DamageReductionDistance": 0.5
  }
}

Typical Usage

{
  "WallPenetration": {
    "Enabled": true,
    "Blocks": 1.0,
    "DamageReductionModifier": 0.1,
    "DamageReductionDistance": 0.25
  }
}

WeaponCustomHUD

The weapon input overlay is owned by the separate WeaponCustomHUD plugin. Its block is top-level, outside HyGuns.

HyGuns ships a default WeaponCustomHUD preset named HyGunsWeapon. Use it for normal HyGuns weapons and override only the slots you need.

{
  "WeaponCustomHUD": {
    "Enabled": true,
    "Preset": "HyGunsWeapon",
    "Scale": 0.75,
    "Placement": "BottomRight",
    "Position": [48, 38],
    "Abilities": {
      "Primary": {
        "Display": true,
        "Enabled": {
          "Default": true,
          "Reloading": false
        },
        "Cooldown": "FireDelay",
        "Icons": {
          "Default": "AbilityUI/Icons/ShootAbility.png"
        },
        "Signature": false
      }
    }
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
Enabled boolean No false true enables WeaponCustomHUD root interaction patching for this item
Preset string No standard preset Optional preset loaded from Server/WeaponCustomHUD/Presets
Scale number No 1.0 Scales HUD sizes and internal offsets. It does not scale Position
Placement string No BottomRight TopLeft, TopRight, BottomLeft, or BottomRight
Position integer array No [50, 40] Absolute [x, y] offset from the selected placement anchor
Abilities object No {} Per-slot Display, Enabled, Icons, Cooldown, and Signature settings

Supported ability slots are Primary, Secondary, Ability1, Ability2, Ability3, and Use.

Each ability can contain:

Field Type Meaning
Display boolean or state map Controls visibility
Enabled boolean or state map Controls active/inactive color
Icons string or state map Icon texture path
Cooldown number, string, or state map Constant progress or cooldown provider key
Signature boolean Renders this slot as the large signature slot

HyGuns registers these WCHUD states: Scoping, HasAmmo, Reloading, ZoomAvailable, and AttachmentAvailable. It also registers cooldown providers FireDelay and Reloading. SignatureReady is provided by WeaponCustomHUD by default as both a state and cooldown provider.

State maps start from Default and then apply active states in JSON order:

{
  "Enabled": {
    "Default": true,
    "Reloading": false,
    "HasAmmo": true
  },
  "Icons": {
    "Default": "WeaponCustomHUD/Icons/ScopeAbility.png",
    "Scoping": "WeaponCustomHUD/Icons/ZoomOutAbility.png"
  }
}

Preset files are loaded from:

Server/WeaponCustomHUD/Presets/<PresetId>.json

The preset file root is already the WeaponCustomHUD settings object. Do not wrap preset files in another WeaponCustomHUD key.

Example HyGuns weapon HUD:

{
  "WeaponCustomHUD": {
    "Enabled": true,
    "Preset": "HyGunsWeapon"
  }
}

WeaponCustomHUD also provides WCHud_* interactions for asset-only state/cooldown/error control. See WeaponCustomHUD Interactions.

Attachment Types

Attachment types are standalone JSON files under Server/HyGuns/AttachmentTypes.

The filename does not define the type. The Type field does.

{
  "Type": "Scope",
  "Icon": "Attachments/scope.png", 
  "Name": "Scope",
  "Description": "Allow use scoping",
  "AnyAllowed": false,
  "Accepts": ["Magazine"],
  "ConflictsWith": ["ThermalScope"],
  "MaxCount": 1
}

Fields

Field Type Required Default Accepted Values / Meaning
Type string Yes none Attachment type id, for example "Scope"
Icon string No omitted Attachment slot icon path relative to Common/UI/Custom, for example "Attachments/scope.png"
Name string No omitted Attachment name what displays on attachment slots
Description string No omitted Attachment description what displays in weapon tooltip
AnyAllowed boolean No true Whether this type may be placed into wildcard * slots
Accepts string[] No [] Extra attachment type ids accepted by dedicated slots of this type
ConflictsWith string[] No [] Attachment type ids that cannot be installed together with this type
MaxCount integer No unlimited Maximum installed attachments of this type on one weapon

AnyAllowed: false is useful for types like scopes where a weapon may have a dedicated Scope slot and also wildcard slots, but should still never accept a second scope in a wildcard slot.

Accepts is checked on the slot type. For example, a Bobbin type with "Accepts": ["Magazine"] means slots declared as "Bobbin" accept both Bobbin attachments and Magazine attachments. This does not affect wildcard * slots.

ConflictsWith is checked both ways. If either installed type says it conflicts with the other, the combination is rejected.

HyGuns.AttachmentSettings

Marks an item as a weapon attachment.

{
  "HyGuns": {
    "AttachmentSettings": {
      "Type": "Scope",
      "ZoomSettings": {
        "MaxDistance": 20.0,
        "MinDistance": 1.0,
        "DefaultZoomMultiplier": 1.0,
        "MaxZoomMultiplier": 6.0,
        "ZoomMultiplierStep": 1.0,
        "OverlayTexturePath": "Scopes/Scope_8x.png"
      },
      "FireSound": {
        "Volume": "*0.05"
      },
      "SettingsModifiers": {
        "Projectiles": {
          "Spread": "*0.75"
        },
        "AutoGuidance": {
          "Enabled": true
        }
      }
    }
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
Type string Yes none Attachment type id loaded from Server/HyGuns/AttachmentTypes
SettingsModifiers object No omitted Weapon Settings Modifiers applied while installed
ZoomSettings object No omitted Zoom settings supplied by this attachment
FireSound object No omitted Fire sound modifiers supplied by this attachment

Attachment durability is controlled by the normal item root field MaxDurability, not by HyGuns.AttachmentSettings.

{
  "Id": "DamageBooster_Tier_I",
  "MaxDurability": 300,
  "HyGuns": {
    "AttachmentSettings": {
      "Type": "DamageBooster",
      "SettingsModifiers": {
        "Projectiles": {
          "Damage": "+2"
        }
      }
    }
  }
}

If MaxDurability is absent or 0, the attachment is treated as unbreakable. If an installed attachment reaches 0 durability, HyGuns treats it as broken: its SettingsModifiers, ZoomSettings, and FireSound no longer apply, and Hyguns_AttachmentsInstalled ignores it. The attachment item tooltip still uses normal durability display; HyGuns does not append a separate (Broken) line.

ZoomSettings Fields

Field Type Required Default Accepted Values / Meaning
OverlayTexturePath string No interaction fallback Scope overlay texture path
MaxDistance number No interaction fallback Max zoom camera distance
MinDistance number No interaction fallback Min zoom camera distance
DefaultZoomMultiplier number No interaction fallback Base zoom multiplier
MaxZoomMultiplier number No interaction fallback Max zoom multiplier
ZoomMultiplierStep number No interaction fallback Zoom step size

ZoomSettings is optional and can be defined on any attachment type, not only scopes. When a weapon zoom interaction runs, the first installed valid attachment with ZoomSettings overrides the interaction zoom settings.

FireSound Fields

Field Type Required Default Accepted Values / Meaning
Volume string No omitted Numeric operation string applied to the sound event volume

FireSound.Volume is optional and is applied by Hyguns_PlayWeaponFireSound. It uses the same numeric operation syntax as settings modifiers, so "*0.05" multiplies the current fire sound volume by 0.05, and "-2.0" subtracts 2.0 from it. Negative final volume values are allowed.

Numeric modifier strings must start with an operation: *, /, +, -, or =.

HyGuns.WeaponSettings.AttachmentsDefinition

Declares the weapon attachment UI and attachment slots. This block lives inside HyGuns.WeaponSettings.

{
  "HyGuns": {
    "WeaponSettings": {
      "AttachmentsDefinition": {
        "WeaponSchema": {
          "Image": "AttachmentsUI/WeaponSchema/AK47.png",
          "Size": [780, 400],
          "AnimationDuration": 0.5,
          "AnimationTiming": "EaseOut"
        },
        "Slots": {
          "Scope": {
            "Count": 1,
            "Visual": true,
            "Index": 0,
            "StartPosition": [415, 140],
            "SlotPoint": "Left",
            "Position": [524, 44]
          },
          "Suppressor": {
            "Count": 1,
            "Visual": true,
            "Index": 1,
            "StartPosition": [80, 182],
            "SlotPoint": "Top",
            "Position": [0, 245]
          },
          "Magazine": {
            "Count": 2
          },
          "*": {
            "Count": 3,
            "LayoutPosition": "BottomRight",
            "Position": [0, 0]
          }
        }
      },
      "DefaultAttachments": {
        "Scope": "Scope_Barret50"
      }
    }
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
WeaponSchema object No omitted Attachment page weapon image and animation settings
Slots object No omitted Attachment slot definitions keyed by attachment type id or *

HyGuns.WeaponSettings.AttachmentsDefinition.WeaponSchema

Configures the large weapon schema image behind the attachment slots and the slot/line intro animation.

The image path is relative to Common/UI/Custom/Pages, so "AttachmentsUI/WeaponSchema/AK47.png" resolves to Common/UI/Custom/Pages/AttachmentsUI/WeaponSchema/AK47.png.

{
  "WeaponSchema": {
    "Image": "AttachmentsUI/WeaponSchema/AK47.png",
    "Size": [780, 400],
    "AnimationDuration": 0.5,
    "AnimationTiming": "Linear"
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
Image string No page default image Schema texture path relative to Common/UI/Custom/Pages
Size integer[2] No [780, 420] Rendered schema image size as [Width, Height]
AnimationDuration number No 0.5 Slot and line animation duration in seconds. 0 makes it complete immediately
AnimationTiming string No "Linear" Linear, EaseIn, EaseOut, EaseInOut, EaseInQuad, EaseOutQuad, EaseInOutQuad, EaseInCubic, EaseOutCubic, or EaseInOutCubic

The schema container is always 780x420. Size controls only the background image size inside that container.

HyGuns.WeaponSettings.AttachmentsDefinition.Slots

Declares attachment slots on a weapon. Keys are attachment type ids loaded from Server/HyGuns/AttachmentTypes.

The special key * creates wildcard slots. Wildcard slots accept only attachments whose type has AnyAllowed enabled.

Dedicated slots accept attachments of the same type as the slot key. They also accept extra types listed in that slot type's Accepts field.

Set Visual to true and assign an Index when an attachment type should participate in the weapon item state key. Indexed visual slots are ordered first in the attachment inventory; other named slots follow, and wildcard slots are always last.

Each named type is rendered as its own ItemGrid. If Count is greater than 1, that type gets one horizontal grid with Count slots. Wildcard slots are rendered as their own grid.

Slot Fields

Field Type Required Default Accepted Values / Meaning
Count integer No omitted Number of slots to create for this supported type
Visual boolean No false Whether this type contributes to visual state key generation
Index integer No omitted Ordering value for visual state key generation and front-of-grid slot ordering
LayoutPosition string No TopLeft for named slots, BottomRight for * Anchor corner used for Position. Accepted forms include TopLeft, LeftTop, TopRight, RightTop, BottomLeft, LeftBottom, BottomRight, RightBottom
Position integer[2] No [0, 0] Grid final position as [x, y], relative to the selected LayoutPosition. Negative values are allowed
StartPosition integer[2] No omitted Optional intro animation start point for this grid line/slot
SlotPoint string No Top Slot side used as the line endpoint and as the animated start anchor. Accepted values: Top, Bottom, Left, Right

If StartPosition is omitted, the grid is rendered at its final Position immediately and no connector line is drawn for that grid.

When multiple grids resolve to the same final anchor and Position, HyGuns automatically lays them out horizontally by shifting each following grid to the right by the previous grid width. This keeps default [0, 0] slots from overlapping.

If an attachment type has MaxCount, generated dedicated slots for that type are capped by it. For example, if Magazine has "MaxCount": 3, then "Magazine": { "Count": 4 } produces at most three usable magazine slots.

Wildcard slots do not bypass compatibility. They still reject non-attachment items, types with AnyAllowed: false, conflicts from ConflictsWith, and installs beyond MaxCount.

HyGuns.WeaponSettings.DefaultAttachments

Creates attachment item stacks automatically when a weapon is initialized for the first time. Values are real item asset ids, not attachment type ids.

{
  "HyGuns": {
    "WeaponSettings": {
      "AttachmentsDefinition": {
        "Slots": {
          "Scope": { "Count": 1 },
          "Magazine": { "Count": 1 }
        }
      },
      "DefaultAttachments": {
        "Scope": "Scope_Barret50",
        "Magazine": ["Magazine_Tier_II"]
      }
    }
  }
}

The key is the preferred slot type. The created item still has to pass the normal attachment compatibility checks, including type, conflicts, wildcard rules, and MaxCount. If default attachments produce a visual state key, the weapon model is updated during first initialization.

Weapon Attachment Visual States

Visual state switching is driven directly by AttachmentsDefinition.Slots. Every supported attachment type with Visual: true and an Index contributes its type id to the state key when a valid attachment of that type is installed. The key is built in Index order and joined with _.

{
  "HyGuns": {
    "WeaponSettings": {
      "AttachmentsDefinition": {
        "Slots": {
          "Scope": { "Count": 1, "Visual": true, "Index": 0 },
          "Suppressor": { "Count": 1, "Visual": true, "Index": 1 },
          "Magazine": { "Count": 2 }
        }
      }
    }
  },
  "State": {
    "Scope": {
      "Model": "Items/Weapons/Barret50/Barret50_Scope.blockymodel"
    },
    "Suppressor": {
      "Model": "Items/Weapons/Barret50/Barret50_Suppressor.blockymodel"
    },
    "Scope_Suppressor": {
      "Model": "Items/Weapons/Barret50/Barret50_Scope_Suppressor.blockymodel"
    }
  }
}

In this example:

  • only Scope installed uses state Scope
  • only Suppressor installed uses state Suppressor
  • both installed uses state Scope_Suppressor
  • no visual attachment installed returns to the base item id

The state key must exist in the item JSON State block. Embedded attachment containers, runtime id, and ammo metadata are preserved because item state switching keeps item metadata.

Automatic visual state updates are applied when a newly initialized weapon gets default attachments and when the attachment window is closed.

Use Hyguns_OpenAttachments to open the held weapon attachment container.

HyGuns.AmmoSettings

Main ammo item settings block.

This block is read from:

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

Fields

Field Type Required Default Accepted Values / Meaning
Family string or string[] No omitted Ammo family id. If an array is used, the first value is taken
WeaponClass string or string[] No omitted Ammo weapon class. If an array is used, the first value is taken
Icon string or string[] No omitted Ammo HUD icon path relative to Common/UI/Custom, for example "Ammo/Ammo_Pistol.png". If an array is used, the first value is taken
SettingsModifiers object No omitted Weapon settings modifier block applied when this ammo is used
Interactions object No omitted Ammo event interaction lists
Piles object No omitted Runtime-generated pile item settings
AmmoBox object No omitted Runtime-generated ammo box settings

Also read from the item root:

Field Type Required Default Accepted Values / Meaning
Quality string or string[] No omitted Ammo quality id. If an array is used, the first value is taken

Full Example

{
  "Quality": "Uncommon",
  "HyGuns": {
    "AmmoSettings": {
      "Family": "Bullet",
      "WeaponClass": "Rifle",
      "Icon": "Ammo/Ammo_Rifle.png",
      "SettingsModifiers": {
        "Projectiles": {
          "ProjectileId": "Projectile_Bullet_Incendiary",
          "ConfigId": "Incendiary",
          "Spread": "*0.75",
          "Count": 1,
          "Damage": "+2"
        },
        "Fire": {
          "Cooldown": "=0.25"
        },
        "DamageModifier": {
          "Type": "MULTIPLY",
          "Value": 1.25
        }
      },
      "Interactions": {
        "EntityHit": [
          {
            "Type": "ApplyEffect",
            "EffectId": "Burning"
          }
        ],
        "BlockHit": [
          {
            "Type": "SpawnParticles",
            "ParticleSystemId": "Impact_Fire"
          }
        ],
        "Miss": [
          {
            "Type": "SpawnParticles",
            "ParticleSystemId": "Miss_Fire"
          }
        ]
      },
      "Piles": {
        "Generate": true,
        "Variants": [
          {
            "Id": "Small",
            "Categories": [
              "HyGuns.Items"
            ],
            "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Small.blockymodel",
            "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
            "Icon": "Icons/ItemsGenerated/Pile_Ammo_Base_Small.png",
            "HitboxType": "Plant_Large",
            "Material": "Solid",
            "IconScale": 3.0,
            "Scale": 1.0,
            "Amount": 5
          }
        ]
      },
      "AmmoBox": {
        "Generate": true,
        "Categories": [
          "HyGuns.Furniture"
        ],
        "Model": "Blocks/AmmoBox/AmmoBox.blockymodel",
        "ModelTexture": "Blocks/AmmoBox/AmmoBox.png",
        "Icon": "Icons/ItemsGenerated/Ammo_Box_Tier_I.png",
        "HitboxType": "AmmoBox",
        "IconScale": 0.8,
        "RefillTime": 1.0,
        "RefillAmount": 5
      }
    }
  }
}

Typical Usage

{
  "Quality": "Rare",
  "HyGuns": {
    "AmmoSettings": {
      "Family": "Rocket",
      "WeaponClass": "Launcher",
      "Icon": "Ammo/Ammo_Rifle.png",
      "SettingsModifiers": {
        "Projectiles": {
          "ProjectileId": "Projectile_Rocket_Base",
          "ConfigId": "Rocket",
          "Damage": 24
        }
      }
    }
  }
}

Weapon Settings Modifiers

SettingsModifiers is used by ammo and attachment assets to change the effective weapon settings while that ammo or attachment is active.

Supported locations:

  • HyGuns.AmmoSettings.SettingsModifiers
  • HyGuns.AttachmentSettings.SettingsModifiers

The block follows the same shape as HyGuns.WeaponSettings, but numeric weapon stat fields may also be written as operation strings.

{
  "SettingsModifiers": {
    "Projectiles": {
      "Spread": "*0.75",
      "Damage": "+20"
    },
    "Ammo": {
      "Capacity": "+10",
      "Reload": {
        "Amount": "+10",
        "Time": "-0.2"
      }
    },
    "Fire": {
      "Cooldown": "=5.0"
    },
    "AutoGuidance": {
      "Enabled": true
    }
  }
}

Supported numeric operation tokens:

Token Meaning Example
* multiply current value "Spread": "*0.75"
/ divide current value "Cooldown": "/2"
+ add to current value "Capacity": "+10"
- subtract from current value "Reload": { "Time": "-0.2" }
= set final value "Fire": { "Cooldown": "=5.0" }

Supported numeric operation fields:

  • Ammo.Capacity
  • Ammo.Reload.Amount
  • Ammo.Reload.Time
  • Fire.Cooldown
  • Projectiles.Spread
  • Projectiles.Count
  • Projectiles.Damage
  • AutoGuidance.ConeDegrees
  • AutoGuidance.MaxDistance
  • AutoGuidance.TurnRate
  • WallPenetration.Blocks
  • WallPenetration.DamageReductionModifier
  • WallPenetration.DamageReductionDistance

Non-numeric values are merged as normal partial weapon settings. For example, "AutoGuidance": { "Enabled": true } enables guidance while the modifier is active.

Modifier order:

  1. interaction-level overrides are merged with the base weapon settings: WeaponSettingsOverrides for Hyguns_Shoot, WeaponSettingsOverrides for Hyguns_Reload
  2. installed attachment modifiers are applied in attachment slot order
  3. wildcard slots use their normal slot indexes, so left-to-right wildcard placement can change the final result
  4. selected/loaded ammo modifiers are applied after all attachments, so ammo remains the final authority

Numeric operations are applied in modifier order. For example, if one wildcard slot applies "Damage": "+10" and the next wildcard slot applies "Damage": "*1.5", the result differs from placing *1.5 first and +10 second.

This means ammo modifiers are applied after attachments. If ammo uses =5.0 for a field, it is the final set operation for that field and cannot be reduced by an attachment modifier.

Numeric weapon stat results are clamped to 0 or higher. FireSound.Volume is separate and is not clamped, so negative final volume values are allowed.

HyGuns.AmmoSettings.SettingsModifiers

Ammo-specific weapon settings modifier block.

This block uses the Weapon Settings Modifiers format and is applied while this ammo type is selected/loaded.

Fields

Field Type Required Default Accepted Values / Meaning
WeaponIcon string No omitted Weapon HUD icon path relative to Common/UI/Custom, for example "Weapons/AK47.png"
DealLethalDamage boolean No omitted Lethal damage flag
Ammo object No omitted Weapon ammo settings modifiers
Fire object No omitted Fire settings modifiers
Projectiles object No omitted Projectile settings modifiers
DamageModifier object No omitted Final damage modifier
DamageModifiers object No omitted Hit-part damage modifiers
AutoGuidance object No omitted Guidance settings modifiers
WallPenetration object No omitted Wall penetration settings modifiers

Full Example

{
  "SettingsModifiers": {
    "WeaponIcon": "Weapons/AK47.png",
    "DealLethalDamage": true,
    "Ammo": {
      "ItemId": "Ammo_Bullet_Base_Incendiary",
      "Capacity": 20,
      "Reload": {
        "Time": 1.4,
        "Amount": 20
      }
    },
    "Fire": {
      "Cooldown": "=0.3"
    },
    "Projectiles": {
      "ConfigId": "Incendiary",
      "ProjectileId": "Projectile_Bullet_Incendiary",
      "Spread": "*0.75",
      "Count": 1,
      "Damage": "+4"
    },
    "DamageModifier": {
      "Type": "MULTIPLY",
      "Value": 1.25
    },
    "DamageModifiers": {
      "Head": {
        "Type": "MULTIPLY",
        "Value": 1.75
      },
      "Body": {
        "Type": "MULTIPLY",
        "Value": 1.1
      },
      "*": {
        "Type": "MULTIPLY",
        "Value": 1.0
      }
    },
    "AutoGuidance": {
      "Enabled": true,
      "AffectsPlayers": true,
      "ConeDegrees": 30.0,
      "MaxDistance": 100.0,
      "TurnRate": 180.0,
      "EffectId": "MarkedTarget"
    },
    "WallPenetration": {
      "Enabled": true,
      "Blocks": 2.0,
      "DamageReductionModifier": 0.2,
      "DamageReductionDistance": 0.5
    }
  }
}

Typical Usage

{
  "SettingsModifiers": {
    "Projectiles": {
      "ProjectileId": "Projectile_Bullet_AP",
      "ConfigId": "ArmorPiercing",
      "Damage": "+3"
    },
    "WallPenetration": {
      "Enabled": true,
      "Blocks": 3.0,
      "DamageReductionModifier": 0.15,
      "DamageReductionDistance": 0.5
    }
  }
}

HyGuns.AmmoSettings.Interactions

Ammo-specific interaction lists.

These interaction lists are appended into the ammo behavior flow when this ammo is used.

Fields

Field Type Required Default Accepted Values / Meaning
EntityHit object[] No [] Interactions triggered on entity hit
BlockHit object[] No [] Interactions triggered on block hit
Miss object[] No [] Interactions triggered on miss

Full Example

{
  "Interactions": {
    "EntityHit": [
      {
        "Type": "ApplyEffect",
        "EffectId": "Burning"
      },
      {
        "Type": "DamageEntity",
        "Amount": 2
      }
    ],
    "BlockHit": [
      {
        "Type": "SpawnParticles",
        "ParticleSystemId": "Impact_Fire"
      }
    ],
    "Miss": [
      {
        "Type": "SpawnParticles",
        "ParticleSystemId": "Miss_Fire"
      }
    ]
  }
}

Typical Usage

{
  "Interactions": {
    "EntityHit": [
      {
        "Type": "ApplyEffect",
        "EffectId": "MarkedTarget"
      }
    ]
  }
}

HyGuns.AmmoSettings.Piles

Runtime generation settings for ammo pile items and their drop lists.

If enabled, HyGuns generates:

  • Pile_{AmmoType}_{VariantId} item ids
  • matching drop list ids with the same id

Fields

Field Type Required Default Accepted Values / Meaning
Generate boolean No false Must be true to generate piles
Variants object[] No [] List of generated pile variants

Full Example

{
  "Piles": {
    "Generate": true,
    "Variants": [
      {
        "Id": "Small",
        "Categories": [
          "HyGuns.Items"
        ],
        "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Small.blockymodel",
        "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
        "Icon": "Icons/ItemsGenerated/Pile_Ammo_Base_Small.png",
        "HitboxType": "Plant_Large",
        "Material": "Solid",
        "IconScale": 3.0,
        "Scale": 1.0,
        "Amount": 5
      },
      {
        "Id": "Medium",
        "Categories": [
          "HyGuns.Items"
        ],
        "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Medium.blockymodel",
        "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
        "Icon": "Icons/ItemsGenerated/Pile_Ammo_Base_Medium.png",
        "HitboxType": "Plant_Large",
        "Material": "Empty",
        "IconScale": 2.6,
        "Scale": 1.2,
        "Amount": 15
      }
    ]
  }
}

Typical Usage

{
  "Piles": {
    "Generate": true,
    "Variants": [
      {
        "Id": "Small",
        "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Small.blockymodel",
        "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
        "Amount": 5
      }
    ]
  }
}

HyGuns.AmmoSettings.Piles.Variants[]

One generated pile variant.

This block lives inside HyGuns.AmmoSettings.Piles.Variants.

Fields

Field Type Required Default Accepted Values / Meaning
Id string Yes none Variant id used in generated ids
Categories string[] No generator fallback Creative categories for the generated item
Model string Yes none Block model path
ModelTexture string Yes none Model texture path
Icon string No generator fallback Item icon path
HitboxType string No generator fallback Hitbox asset id
Material string No "Solid" "Solid" or "Empty"
IconScale number No 3.0 Item icon scale, must be >= 0
Scale number No generator fallback Model scale, must be >= 0
Amount integer Yes none Ammo amount represented by this pile, must be > 0

Full Example

{
  "Id": "Huge",
  "Categories": [
    "HyGuns.Items",
    "HyGuns.Debug"
  ],
  "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Huge.blockymodel",
  "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
  "Icon": "Icons/ItemsGenerated/Pile_Ammo_Base_Huge.png",
  "HitboxType": "Plant_Large",
  "Material": "Solid",
  "IconScale": 2.8,
  "Scale": 1.4,
  "Amount": 40
}

Typical Usage

{
  "Id": "Small",
  "Model": "Blocks/Piles/Ammo/Pile_Ammo_Base_Small.blockymodel",
  "ModelTexture": "Blocks/Piles/Ammo/Ammo_Bullet_Base.png",
  "Amount": 5
}

HyGuns.AmmoSettings.AmmoBox

Runtime generation settings for a creative/operator ammo refill box.

If enabled, HyGuns generates:

  • AmmoBox_{AmmoType} item id
  • Refill_AmmoBox_{AmmoType} interaction id
  • Root_Use_AmmoBox_{AmmoType} root interaction id

Behavior:

  • the box is generated with MaxStack = 1
  • the block uses VariantRotation = "NESW"
  • on use it runs Hyguns_SetAmmoType
  • if that succeeds it runs Hyguns_SetAmmo with ToMax = true

Fields

Field Type Required Default Accepted Values / Meaning
Generate boolean No false Must be true to generate the box
Categories string[] No ["HyGuns.Furniture"] Creative categories for the generated item
Model string Yes when enabled none Block model path
ModelTexture string Yes when enabled none Block model texture path
Icon string No generator fallback Item icon path
HitboxType string No "AmmoBox" Hitbox asset id
IconScale number No 0.8 Item icon scale, must be >= 0
RefillTime number Yes when enabled none Hold time in seconds, must be > 0
RefillAmount integer Yes when enabled none Stored config value, must be > 0

Full Example

{
  "AmmoBox": {
    "Generate": true,
    "Categories": [
      "HyGuns.Furniture",
      "HyGuns.Debug"
    ],
    "Model": "Blocks/AmmoBox/AmmoBox.blockymodel",
    "ModelTexture": "Blocks/AmmoBox/AmmoBox.png",
    "Icon": "Icons/ItemsGenerated/Ammo_Box_Tier_I.png",
    "HitboxType": "AmmoBox",
    "IconScale": 0.8,
    "RefillTime": 1.0,
    "RefillAmount": 5
  }
}

Typical Usage

{
  "AmmoBox": {
    "Generate": true,
    "Categories": [
      "HyGuns.Furniture"
    ],
    "Model": "Blocks/AmmoBox/AmmoBox.blockymodel",
    "ModelTexture": "Blocks/AmmoBox/AmmoBox.png",
    "RefillTime": 1.0,
    "RefillAmount": 5
  }
}

HyGuns NPC Role Settings

HyGuns can read a custom block from NPC role assets under Server/NPC/Roles. This is used by NPCs whose Behaviors.Attack points to a HyGuns weapon attack root interaction.

{
  "Id": "Skeleton_HyGuns_AK47",
  "Behaviors": {
    "Attack": "HyGuns_NPC_Attack_AK47"
  },
  "HyGuns": {
    "AmmoItemId": "Ammo_Bullet_Rifle"
  }
}

Fields

Field Type Required Default Accepted Values / Meaning
AmmoItemId string or string[] No resolver fallback Ammo item asset id used as the NPC's infinite reload source

If AmmoItemId is omitted, HyGuns tries to pick a compatible ammo item from the ammo registry using the weapon's configured ammo family and weapon class. NPC reloads still use the weapon reload duration; only reserve ammo is treated as infinite.

NPC role assets live under:

Server/NPC/Roles/<Folder>/<RoleId>.json

HyGuns uses the role file name as the lookup id when reading this block.

HyGuns NPC World Spawns

World spawn assets are normal Hytale WorldNPCSpawn assets. HyGuns does not define a custom schema here; the only HyGuns-specific requirement is that NPCs[].Id references a role that uses the HyGuns attack behavior and optional HyGuns.AmmoItemId.

Files live under:

Server/NPC/Spawn/World/<Folder>/<SpawnAssetId>.json

Example:

{
  "Environments": [
    "Zone1"
  ],
  "DayTimeRange": [
    0.0,
    1.0
  ],
  "NPCs": [
    {
      "Weight": 1,
      "Id": "Skeleton_HyGuns_AK47",
      "Flock": {
        "Min": 1,
        "Max": 2
      }
    }
  ]
}

Use Hytale spawn fields such as Environments, DayTimeRange, LightRanges, and NPCs exactly as normal. To edit HyGuns NPC drops, edit the role's normal DropList value and the matching drop list asset, not the spawn asset.

Dynamic Weapon Tooltips

HyGuns generates runtime tooltip details for weapon item stacks. The generated section is based on the current weapon item state, selected ammo, installed attachments, and effective weapon settings.

Generated data can include:

  • selected ammo name
  • effective damage, spread, cooldown, reload time, and clip size
  • positive/negative stat deltas from installed attachments
  • installed attachment names and types
  • attachment modifier details
  • special attachment effects such as zoom support or fire sound volume changes

Attachment item stacks also receive a one-time generated tooltip section. It uses the attachment type description first, then lists the same modifier/effect lines shown under installed attachments on weapon tooltips.

Tooltip updates are intentionally event-based. They run when a weapon is initialized or crafted, when the selected ammo changes, when attachments change, and once when a player joins the server. The plugin does not continuously rewrite weapon stacks every tick.

Numeric values in generated tooltip lines are rounded to at most 3 decimal places and trailing zeroes are removed.

Static item TranslationProperties.Description may still contain a short flavor description. Runtime weapon stats should come from the generated tooltip section instead of hard-coded language text.

Clone this wiki locally