Interactions

HyGuns Custom Interactions

This page documents every custom interaction registered by HyGuns.

The goal is simple:

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

Interaction Naming
Hyguns_Shoot
Hyguns_Reload
Hyguns_ReloadCheck
Hyguns_ShootCheck
Hyguns_CanShoot
Hyguns_Heat
Hyguns_CheckHeat
Hyguns_SetHeat
Hyguns_AddHeat
Hyguns_UseAmmo
Hyguns_CheckAmmo
Hyguns_CheckAmmoType
Hyguns_SetAmmoType
Hyguns_SetAmmo
Hyguns_AddAmmo
Hyguns_SyncAmmo
Hyguns_OpenAttachments
Hyguns_AttachmentsInstalled
Hyguns_PlayWeaponFireSound
Hyguns_SetItemState
Hyguns_CheckZoom
Hyguns_SetZoom
Hyguns_ResetZoom
Hyguns_CheckReloading
Hyguns_CancelReload
Hyguns_UpdateHud
Hyguns_HideHud
Hyguns_Holding
Hyguns_CheckDurability
WeaponCustomHUD Interactions
Scope_Zoom
Scope_Step_Zoom
Scope_Zoom_In
Scope_Zoom_Out

Interaction Naming

Most HyGuns interactions use the Hyguns_ prefix at runtime.

Examples:

Hyguns_Shoot
Hyguns_Reload
Hyguns_SetAmmo

Scope interactions use plain string keys:

Scope_Zoom
Scope_Step_Zoom
Scope_Zoom_In
Scope_Zoom_Out

Hyguns_Shoot

Shoots the current weapon, consumes loaded ammo, resolves effective weapon settings, spawns projectiles, cancels reload, and may apply ammo-based fire delay.

Effective settings include base HyGuns.WeaponSettings, this interaction's optional WeaponSettingsOverrides, installed attachment SettingsModifiers, and selected/loaded ammo SettingsModifiers.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_Shoot"`
`WeaponSettingsOverrides`	object	No	omitted	One-off partial weapon settings merged before attachment and ammo modifiers
`WeaponSettingsOverrides.Projectiles.Count`	integer	No	weapon default	Projectile count for this use
`WeaponSettingsOverrides.Projectiles.Spread`	number	No	weapon default	Projectile spread
`WeaponSettingsOverrides.Projectiles.Damage`	integer	No	weapon default	Per-projectile damage
`WeaponSettingsOverrides.Projectiles.ProjectileId`	string	No	weapon default	Projectile asset id
`WeaponSettingsOverrides.Projectiles.ProjectileID`	string	No	weapon default	Alias for `ProjectileId`
`WeaponSettingsOverrides.Projectiles.ConfigId`	string	No	weapon default	Projectile config id
`WeaponSettingsOverrides.Ammo.Capacity`	integer	No	weapon default	Max ammo override
`WeaponSettingsOverrides.Fire.Cooldown`	number	No	weapon default	Fire override if you still use it in this chain context
`WeaponSettingsOverrides.DealLethalDamage`	boolean	No	`false`	Whether this shot can deal lethal damage
`WeaponSettingsOverrides.AutoGuidance`	object	No	weapon default	One-off auto-guidance settings
`WeaponSettingsOverrides.WallPenetration`	object	No	weapon default	One-off wall-penetration settings

Full Example

{
  "Type": "Hyguns_Shoot",
  "WeaponSettingsOverrides": {
    "Projectiles": {
      "Count": 8,
      "Spread": 0.16,
      "Damage": 5,
      "ProjectileId": "Projectile_ShotgunPellet",
      "ConfigId": "Shotgun"
    },
    "Ammo": {
      "Capacity": 8
    },
    "Fire": {
      "Cooldown": 0.25
    },
    "DealLethalDamage": false
  }
}

Typical Usage

{
  "Type": "Hyguns_CanShoot",
  "Next": {
    "Type": "Hyguns_Shoot"
  }
}

Hyguns_Reload

Starts a reload on the held weapon. The actual completion is handled later by the runtime reload system.

Reload uses the same effective settings resolver as shooting, so attachment and ammo modifiers can change capacity, reload amount, reload time, and ammo item id.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_Reload"`
`WeaponSettingsOverrides`	object	No	omitted	One-off partial ammo settings merged before attachment and ammo modifiers
`WeaponSettingsOverrides.Ammo.ItemId`	string	No	weapon default	Exact ammo item id to use for reload
`WeaponSettingsOverrides.Ammo.Capacity`	integer	No	weapon default	Override runtime max ammo
`WeaponSettingsOverrides.Ammo.Reload.Amount`	integer	No	weapon default / full mag	How much ammo is loaded by one reload
`WeaponSettingsOverrides.Ammo.Reload.Time`	number	No	`1.5`	Reload duration in seconds

Full Example

{
  "Type": "Hyguns_Reload",
  "WeaponSettingsOverrides": {
    "Ammo": {
      "ItemId": "Ammo_Bullet_Base",
      "Capacity": 30,
      "Reload": {
        "Amount": 10,
        "Time": 0.85
      }
    }
  }
}

Typical Usage

{
  "Type": "Hyguns_ReloadCheck",
  "Next": {
    "Type": "Hyguns_Reload"
  }
}

Hyguns_ReloadCheck

Checks whether the held weapon can be reloaded right now.

Fails when:

player is already reloading
weapon is full
compatible ammo is not available
held item cannot be resolved properly

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_ReloadCheck"`

Full Example

{
  "Type": "Hyguns_ReloadCheck"
}

Typical Usage

{
  "Type": "Hyguns_ReloadCheck",
  "Next": {
    "Type": "Hyguns_Reload"
  }
}

Hyguns_ShootCheck

Checks whether the held weapon has initialized ammo and can currently shoot.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_ShootCheck"`

Full Example

{
  "Type": "Hyguns_ShootCheck"
}

Typical Usage

{
  "Type": "Hyguns_ShootCheck",
  "Next": {
    "Type": "Hyguns_Shoot"
  }
}

Hyguns_CanShoot

Checks whether the weapon is currently blocked by runtime fire delay.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CanShoot"`

Full Example

{
  "Type": "Hyguns_CanShoot"
}

Typical Usage

{
  "Type": "Hyguns_CanShoot",
  "Next": {
    "Type": "Hyguns_Shoot"
  }
}

Hyguns_Heat

Marks the held item as actively heating for the heat runtime.

The heat runtime system then handles:

heat gain while the interaction keeps being triggered
passive cooling after the item stops heating
forced cooling while the item is overheated

This interaction itself does not directly cool the item. It updates active heat state and fails while the item is still overheated.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_Heat"`
`OverheatEnabled`	boolean	No	`true`	`true` or `false`
`OverheatTime`	number	No	`10.0`	Time in seconds to go from `0.0` heat to `1.0` heat while continuously firing
`CooldownTime`	number	No	`10.0`	Time in seconds to go from `1.0` heat to `0.0` heat while cooling
`UI`	object	No	default heat HUD style	Optional heat HUD visual style applied by this interaction
`UI.Bar`	string	No	`"Bars/HalfCircular"`	Folder path relative to `Common/UI/Custom`. The folder must contain `Mask.png`, `Outline.png`, and `Overlay.png`. `UI.BarPath` is also accepted as an alias
`UI.Offset`	number array	No	`[0, 0]`	Root offset as `[Left, Top]`. Use this to move the whole heat HUD
`UI.Size`	number or number array	No	`[128, 128]`	Shared size applied to the progress bar and outline. Prefer `[Width, Height]`; a single number is treated as square size for compatibility
`UI.ValueRange`	number array	No	`[0.25, 0.75]`	Maps heat progress `0.0..1.0` into this progress bar value range
`UI.Heat.TexturePath`	string	No	`"<UI.Bar>/Mask.png"`	Optional explicit mask texture override for `#OverheatProgress`. Path is relative to `Common/UI/Custom`; if set, it has priority over `UI.Bar` for the mask only
`UI.Heat.Offset`	number array	No	`[0, 0]`	Progress bar anchor offset as `[Left, Top]`
`UI.HeatOutline.TexturePath`	string	No	`"<UI.Bar>/Outline.png"`	Optional explicit outline texture override for `#OverheatProgressOutline.Background`. Path is relative to `Common/UI/Custom`; if set, it has priority over `UI.Bar` for the outline only
`UI.HeatOutline.Offset`	number array	No	`[0, 0]`	Outline background anchor offset as `[Left, Top]`. Use only when a specific outline asset needs compensation
`UI.HeatOverlay.TexturePath`	string	No	`"<UI.Bar>/Overlay.png"`	Optional explicit overlay texture override for `#OverheatProgressOverlay.Background`. Path is relative to `Common/UI/Custom`; if set, it has priority over `UI.Bar` for the overlay only
`UI.HeatOverlay.Offset`	number array	No	`[0, 0]`	Overlay anchor offset as `[Left, Top]`
`UI.Gradient`	object or string array	No	white -> yellow -> orange -> red	Color gradient for heat progress. Object keys are stops `0.0..1.0`; arrays can contain any number of colors and are distributed evenly

Full Example

{
  "Type": "Hyguns_Heat",
  "OverheatEnabled": true,
  "OverheatTime": 4.0,
  "CooldownTime": 2.0,
  "UI": {
    "Bar": "Bars/CircularFlame",
    "Offset": [-12, 0],
    "Size": [128, 128],
    "ValueRange": [0.25, 1.0],
    "Heat": {
      "TexturePath": "Bars/CircularFlame/Mask.png",
      "Offset": [0, 0]
    },
    "HeatOutline": {
      "TexturePath": "Bars/CircularFlame/Outline.png",
      "Offset": [0, 0]
    },
    "HeatOverlay": {
      "TexturePath": "Bars/CircularFlame/Overlay.png",
      "Offset": [0, 0]
    },
    "Gradient": {
      "0": "#FF8800",
      "0.25": "#FF0000",
      "0.5": "#FFFF00",
      "1": "#FF00FF"
    }
  }
}

Hybrid bar example. This uses Bars/CircularFlame/Mask.png from UI.Bar, but overrides only the outline:

{
  "UI": {
    "Bar": "Bars/CircularFlame",
    "HeatOutline": {
      "TexturePath": "Bars/Circular/Outline.png"
    }
  }
}

Array gradient shorthand:

{
  "Gradient": ["#FF0000", "#00FF00", "#0000FF"]
}

The array can contain any number of colors. With three colors, stops are generated as 0.0, 0.5, and 1.0. With four colors, stops are generated as approximately 0.0, 0.333, 0.666, and 1.0. With five colors, stops are 0.0, 0.25, 0.5, 0.75, and 1.0, and so on.

Typical Usage

{
  "Type": "Hyguns_Heat",
  "OverheatEnabled": true,
  "OverheatTime": 10.0,
  "CooldownTime": 4.0,
  "UI": {
    "ValueRange": [0.25, 1.0],
    "Gradient": ["#FFFFFF", "#FFFF00", "#FF8000", "#FF0000"]
  },
  "Next": {
    "Type": "Hyguns_UseAmmo",
    "Amount": 1
  }
}

Hyguns_CheckHeat

Checks current runtime heat without changing it.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckHeat"`
`Overheated`	boolean	No	omitted	`true` or `false`; if omitted, overheated state is not checked
`MinHeat`	number	No	omitted	Minimum current heat value in range `0.0..1.0`
`MaxHeat`	number	No	omitted	Maximum current heat value in range `0.0..1.0`

Full Example

{
  "Type": "Hyguns_CheckHeat",
  "Overheated": false,
  "MinHeat": 0.25,
  "MaxHeat": 0.75
}

Typical Usage

{
  "Type": "Hyguns_CheckHeat",
  "Overheated": false,
  "MinHeat": 0.25,
  "MaxHeat": 0.75,
  "Next": {
    "Type": "Hyguns_AddHeat",
    "Amount": 0.1
  }
}

Hyguns_SetHeat

Sets held item heat directly as a normalized heat value.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SetHeat"`
`Amount`	number	No	`0.0`	Target heat value in range `0.0..1.0`

Full Example

{
  "Type": "Hyguns_SetHeat",
  "Amount": 0.5
}

Typical Usage

{
  "Type": "Hyguns_SetHeat",
  "Amount": 0.0
}

Hyguns_AddHeat

Adds to current held item heat directly as a normalized heat value.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_AddHeat"`
`Amount`	number	No	`0.0`	Heat to add in range `0.0..1.0`

Full Example

{
  "Type": "Hyguns_AddHeat",
  "Amount": 0.15
}

Typical Usage

{
  "Type": "Hyguns_AddHeat",
  "Amount": 0.1
}

Hyguns_UseAmmo

Consumes ammo without firing a projectile.

When this interaction changes loaded ammo on a held weapon, HyGuns now schedules metadata sync automatically on chain completion.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_UseAmmo"`
`Amount`	integer	No	`1`	Ammo amount to consume
`Available`	boolean	No	`false`	If `true`, consumes compatible ammo from inventory instead of loaded ammo

Full Example

{
  "Type": "Hyguns_UseAmmo",
  "Amount": 3,
  "Available": true
}

Typical Usage

{
  "Type": "Hyguns_UseAmmo",
  "Amount": 1
}

Hyguns_CheckAmmo

Checks whether enough ammo exists.

By default it checks loaded ammo. If Available = true, it checks compatible inventory ammo.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckAmmo"`
`Amount`	integer	No	`1`	Minimum required ammo
`Available`	boolean	No	`false`	`false` = loaded ammo, `true` = inventory ammo

Full Example

{
  "Type": "Hyguns_CheckAmmo",
  "Amount": 10,
  "Available": true
}

Typical Usage

{
  "Type": "Hyguns_CheckAmmo",
  "Amount": 1,
  "Available": false,
  "Next": {
    "Type": "Hyguns_Shoot"
  }
}

Hyguns_CheckAmmoType

Checks currently loaded or selected ammo type.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckAmmoType"`
`AmmoItemId`	string	Yes	none	Ammo asset id, for example `"Ammo_Bullet_Base_Incendiary"`
`Selected`	boolean	No	`false`	`false` = check loaded ammo type, `true` = check selected ammo type

Full Example

{
  "Type": "Hyguns_CheckAmmoType",
  "AmmoItemId": "Ammo_Bullet_Base_Incendiary",
  "Selected": true
}

Typical Usage

{
  "Type": "Hyguns_CheckAmmoType",
  "AmmoItemId": "Ammo_Bullet_Base_Incendiary",
  "Selected": false,
  "Next": {
    "Type": "Hyguns_SetAmmo",
    "ToMax": true
  }
}

Hyguns_SetAmmoType

Sets the weapon ammo type from the ammo registry.

This writes:

selected ammo item id
loaded ammo item id
loaded ammo icon

The interaction fails if the ammo type is not compatible with the held weapon.

When this interaction changes loaded ammo on a held weapon, HyGuns now schedules metadata sync automatically on chain completion.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SetAmmoType"`
`AmmoItemId`	string	Yes	none	Ammo asset id, for example `"Ammo_Bullet_Base_Incendiary"`

Full Example

{
  "Type": "Hyguns_SetAmmoType",
  "AmmoItemId": "Ammo_Bullet_Base_Incendiary"
}

Typical Usage

{
  "Type": "Hyguns_SetAmmoType",
  "AmmoItemId": "Ammo_Bullet_Base_Incendiary",
  "Next": {
    "Type": "Hyguns_SetAmmo",
    "ToMax": true
  }
}

Hyguns_SetAmmo

Sets loaded ammo amount directly.

No inventory items are added or removed.

When this interaction changes loaded ammo on a held weapon, HyGuns now schedules metadata sync automatically on chain completion.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SetAmmo"`
`Amount`	integer	No	`0`	Exact ammo amount to set when `ToMax` is `false`
`ToMax`	boolean	No	`false`	If `true`, fills ammo to max and ignores `Amount`

Full Example

{
  "Type": "Hyguns_SetAmmo",
  "Amount": 5,
  "ToMax": false
}

Typical Usage

{
  "Type": "Hyguns_SetAmmo",
  "Amount": 0,
  "ToMax": true
}

Hyguns_AddAmmo

Adds to currently loaded ammo and clamps to max ammo.

No inventory items are added or removed.

When this interaction changes loaded ammo on a held weapon, HyGuns now schedules metadata sync automatically on chain completion.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_AddAmmo"`
`Amount`	integer	No	`0`	Ammo amount to add when `ToMax` is `false`
`ToMax`	boolean	No	`false`	If `true`, fills ammo to max and ignores `Amount`

Full Example

{
  "Type": "Hyguns_AddAmmo",
  "Amount": 2,
  "ToMax": false
}

Typical Usage

{
  "Type": "Hyguns_AddAmmo",
  "Amount": 0,
  "ToMax": true
}

Hyguns_SyncAmmo

Commits current held weapon ammo runtime state into item metadata immediately.

You usually do not need this after Hyguns_UseAmmo, Hyguns_SetAmmo, Hyguns_AddAmmo, or Hyguns_SetAmmoType, because those interactions already schedule ammo sync automatically when the current interaction chain completes.

Use this when you explicitly want to force metadata persistence at a specific point in a chain.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SyncAmmo"`

Full Example

{
  "Type": "Hyguns_SyncAmmo"
}

Hyguns_OpenAttachments

Opens the held weapon attachment container. The interaction creates the item-stack container from HyGuns.WeaponSettings.AttachmentsDefinition.Slots and opens the custom attachment inventory page.

The page shows attachment grids over the configured weapon schema image and the player's inventory/hotbar grid. Drag-and-drop respects attachment type filters, wildcard rules, conflicts, and max-count limits.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_OpenAttachments"`

Full Example

{
  "Type": "Hyguns_OpenAttachments"
}

Hyguns_AttachmentsInstalled

Checks whether the held weapon has valid installed attachments of the requested types. Use this before zoom interactions when a weapon should only zoom with an installed optic.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_AttachmentsInstalled"`
`AttachmentTypes`	string array	No	`[]`	Attachment type ids to check
`RequireAll`	boolean	No	`false`	`false` = at least one requested type, `true` = all requested types

Full Example

{
  "Type": "Hyguns_AttachmentsInstalled",
  "AttachmentTypes": ["Scope"],
  "RequireAll": false,
  "Next": {
    "Type": "Scope_Zoom"
  },
  "Failed": {
    "Type": "Hyguns_ResetZoom"
  }
}

If AttachmentTypes is omitted or empty, the interaction succeeds when any valid, non-broken attachment is installed. The legacy typo AttachmentsTypes is also accepted as an alias for old assets, but new assets should use AttachmentTypes.

Hyguns_PlayWeaponFireSound

Plays weapon fire sound events with volume modified by installed attachments. Use this instead of putting fire sounds in the standard Effects block when suppressors or other sound-changing attachments should affect the shot.

If a suppressor or another sound-changing attachment breaks on the same shot, the last-shot volume modifier is still applied once and then cleared.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_PlayWeaponFireSound"`
`WorldSoundEventId`	string	No	omitted	3D sound event heard by nearby players
`LocalSoundEventId`	string	No	omitted	first-person sound event for the shooter; falls back to world sound when omitted

Full Example

{
  "Type": "Hyguns_PlayWeaponFireSound",
  "WorldSoundEventId": "Barret50_Fire",
  "LocalSoundEventId": "Barret50_Fire"
}

Attachment example:

{
  "HyGuns": {
    "AttachmentSettings": {
      "Type": "Suppressor",
      "FireSound": {
        "Volume": "*0.05"
      }
    }
  }
}

Do not keep the same fire sound in the standard Effects.WorldSoundEventId / Effects.LocalSoundEventId on the same shot interaction, otherwise both the standard sound and the HyGuns-modified sound will play.

Hyguns_SetItemState

Switches the held item to a Hytale item state while preserving metadata.

This can be used manually in interaction chains, but automatic attachment visual states should usually be configured through HyGuns.WeaponSettings.AttachmentsDefinition.Slots with Visual and Index.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SetItemState"`
`State`	string	Yes	none	State id, or `"Default"` to return to the base item

Full Example

{
  "Type": "Hyguns_SetItemState",
  "State": "NoScope"
}

Default restores the base item id. Normal states use Hytale withState, so the state must exist in the item JSON State block.

The interaction fails if the held item is empty or the requested state does not change the item stack.

Hyguns_CheckZoom

Checks zoom state and zoom step.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckZoom"`
`Zoomed`	boolean	No	omitted	If set, requires current zoom state to match
`MinStep`	integer	No	omitted	Minimum allowed zoom step
`MaxStep`	integer	No	omitted	Maximum allowed zoom step
`ExactStep`	integer	No	omitted	Exact required zoom step
`True`	interaction	No	omitted	Runs when the check matches
`False`	interaction	No	omitted	Runs when the check returns false; this is not treated as an interaction error
`Failed`	interaction	No	omitted	Runs when the check cannot be evaluated because of a real failure

Full Example

{
  "Type": "Hyguns_CheckZoom",
  "Zoomed": true,
  "True": {
    "Type": "Scope_Zoom_Out"
  },
  "False": {
    "Type": "Hyguns_OpenAttachments"
  }
}

Typical Usage

{
  "Type": "Hyguns_CheckZoom",
  "Zoomed": true,
  "True": {
    "Type": "Scope_Zoom_Out"
  },
  "False": {
    "Type": "Hyguns_OpenAttachments"
  }
}

Use False for an expected negative check result, such as "not zoomed". Use Failed only for a real failure branch when the check cannot be evaluated.

Hyguns_SetZoom

Enables zoom and optionally forces an exact zoom step.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_SetZoom"`
`OverlayTexturePath`	string	No	omitted	Overlay texture asset path
`MaxDistance`	number	No	zoom default	Max camera distance
`MinDistance`	number	No	zoom default	Min camera distance
`DefaultZoomMultiplier`	number	No	zoom default	Base zoom multiplier
`MaxZoomMultiplier`	number	No	zoom default	Max zoom multiplier
`ZoomMultiplierStep`	number	No	zoom default	Zoom step size
`ExactStep`	integer	No	`0`	Exact zoom step to apply immediately

Full Example

{
  "Type": "Hyguns_SetZoom",
  "OverlayTexturePath": "UI/Scope/ScopeOverlay.png",
  "MaxDistance": 18.0,
  "MinDistance": 1.0,
  "DefaultZoomMultiplier": 1.0,
  "MaxZoomMultiplier": 3.0,
  "ZoomMultiplierStep": 0.5,
  "ExactStep": 2
}

Typical Usage

{
  "Type": "Hyguns_SetZoom",
  "ExactStep": 1
}

Hyguns_ResetZoom

Disables the current zoom state.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_ResetZoom"`

Full Example

{
  "Type": "Hyguns_ResetZoom"
}

Typical Usage

{
  "Type": "Hyguns_ResetZoom"
}

Hyguns_CheckReloading

Checks whether the player is currently reloading.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckReloading"`
`Reloading`	boolean	No	`true`	`true` = require active reload, `false` = require no reload

Full Example

{
  "Type": "Hyguns_CheckReloading",
  "Reloading": false
}

Typical Usage

{
  "Type": "Hyguns_CheckReloading",
  "Reloading": false,
  "Next": {
    "Type": "Hyguns_Reload"
  }
}

Hyguns_CancelReload

Cancels the current player reload.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CancelReload"`

Full Example

{
  "Type": "Hyguns_CancelReload"
}

Typical Usage

{
  "Type": "Hyguns_CancelReload"
}

Hyguns_UpdateHud

Refreshes ammo HUD for the current player and held item.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_UpdateHud"`

Full Example

{
  "Type": "Hyguns_UpdateHud"
}

Typical Usage

{
  "Type": "Hyguns_UpdateHud"
}

Hyguns_HideHud

Hides ammo HUD for the current player.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_HideHud"`

Full Example

{
  "Type": "Hyguns_HideHud"
}

Typical Usage

{
  "Type": "Hyguns_HideHud"
}

Hyguns_Holding

Checks the active item in the main hand by default, independent of the interaction source.

The short type name Holding is also registered.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_Holding"` or `"Holding"`
`Utility`	boolean	No	`false`	`true` = active utility hand, `false` = active main hand
`ItemId`	string	No	omitted	Single accepted item asset id
`ItemIds`	string array	No	`[]`	Accepted item asset ids. The check passes if the active item matches any one of them
`Select`	object	No	`{}`	Optional map of matched item asset id to InteractionVars overrides. `Select` keys also count as accepted item ids. When the active item matches a key, its vars are overlaid before `Next` runs

Full Example

{
  "Type": "Holding",
  "Utility": true,
  "ItemIds": [
    "Ammo_Box_Tier_I",
    "Ammo_Box_Tier_II",
    "Ammo_Box_Tier_III"
  ],
  "Next": {
    "Type": "Hyguns_ReloadCheck",
    "Next": {
      "Type": "Hyguns_Reload"
    }
  },
  "Failed": {
    "Type": "Simple",
    "RunTime": 0.1
  }
}

Select Example

{
  "Type": "Holding",
  "Utility": true,
  "ItemIds": [
    "Furniture_Crude_Torch",
    "Furniture_Ancient_Torch",
    "Furniture_Temple_Emerald_Torch",
    "Furniture_Human_Ruins_Torch"
  ],
  "Select": {
    "Furniture_Temple_Emerald_Torch": {
      "Flamethrower_EffectInteraction": "Hyguns_Flamethrower_Emerald_Effect"
    }
  },
  "Next": "Hyguns_Flamethrower_Common",
  "Failed": {
    "Type": "Simple",
    "RunTime": 0.1
  }
}

Select does not run a separate branch by itself. It overlays the selected map onto the current InteractionVars, then the normal Next chain runs. Existing vars stay intact unless the selected map contains the same key.

If only Select is provided, its item ids are accepted item ids. If the held item passes ItemId / ItemIds but has no matching Select entry, no vars are changed and Next runs with the existing vars.

Typical Usage

{
  "Type": "Hyguns_Holding",
  "ItemId": "Weapon_Repair_Kit",
  "Next": {
    "Type": "Hyguns_UpdateHud"
  }
}

Hyguns_CheckDurability

Checks durability of the active item in the main hand by default.

The short type name CheckDurability is also registered.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Hyguns_CheckDurability"` or `"CheckDurability"`
`Utility`	boolean	No	`false`	`true` = active utility hand, `false` = active main hand
`Max`	boolean	No	`false`	`true` = compare against max durability, `false` = compare against current durability
`Amount`	string	No	`">0"`	`NumericOperations.Comparison` expression. Supported operators: `>`, `>=`, `=`, `<`, `<=` followed by a number

Full Example

{
  "Type": "CheckDurability",
  "Utility": false,
  "Max": false,
  "Amount": ">0",
  "Next": {
    "Type": "Hyguns_Heat"
  },
  "Failed": {
    "Type": "Simple",
    "RunTime": 0.1
  }
}

Max Durability Example

{
  "Type": "CheckDurability",
  "Utility": false,
  "Max": true,
  "Amount": ">=100",
  "Next": {
    "Type": "Hyguns_Heat"
  }
}

Utility Hand Example

{
  "Type": "Hyguns_CheckDurability",
  "Utility": true,
  "Max": false,
  "Amount": ">=1",
  "Next": {
    "Type": "Hyguns_Holding",
    "Utility": true,
    "ItemId": "Furniture_Crude_Torch"
  }
}

WeaponCustomHUD Interactions

These interactions are registered by the separate WeaponCustomHUD plugin. They are documented here because HyGuns weapons commonly use them in root interaction chains.

They are optional. Prefer the programmatic WeaponCustomHUD API for shared gameplay systems. Use these interactions when an asset author wants to drive simple HUD states, cooldowns, or error flashes directly from JSON.

WCHud_SetState

Sets a runtime HUD state for the current player.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"WCHud_SetState"`
`State`	string	Yes	none	State key used by `Display`, `Enabled`, or `Icons` maps
`Value`	boolean	Yes	`false`	Runtime value to set

Example

{
  "Type": "WCHud_SetState",
  "State": "Scoping",
  "Value": true,
  "Next": {
    "Type": "Scope_Zoom"
  }
}

WCHud_SetCooldown

Starts a manual HUD cooldown for the current player.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"WCHud_SetCooldown"`
`Target`	string	Yes	none	Slot key such as `Ability3`, or a custom cooldown provider key
`Duration`	number	Yes	none	Duration in seconds

Example

{
  "Type": "WCHud_SetCooldown",
  "Target": "Ability3",
  "Duration": 6.0
}

If Target is a custom key, reference the same key in the item HUD block:

{
  "WeaponCustomHUD": {
    "Enabled": true,
    "Abilities": {
      "Ability3": {
        "Display": true,
        "Cooldown": "VentCooldown"
      }
    }
  }
}

{
  "Type": "WCHud_SetCooldown",
  "Target": "VentCooldown",
  "Duration": 6.0
}

WCHud_ResetCooldown

Clears a manual HUD cooldown.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"WCHud_ResetCooldown"`
`Target`	string	Yes	none	Slot key or cooldown provider key

Example

{
  "Type": "WCHud_ResetCooldown",
  "Target": "Ability3"
}

WCHud_HasCooldown

Checks whether a manual HUD cooldown is active.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"WCHud_HasCooldown"`
`Target`	string	Yes	none	Slot key or cooldown provider key
`Value`	boolean	No	`true`	`true` requires an active cooldown; `false` requires no active cooldown

Example

{
  "Type": "WCHud_HasCooldown",
  "Target": "Ability3",
  "Value": false,
  "Next": {
    "Type": "Hyguns_SetHeat",
    "Amount": 0.0,
    "Next": {
      "Type": "WCHud_SetCooldown",
      "Target": "Ability3",
      "Duration": 6.0
    }
  },
  "Failed": {
    "Type": "WCHud_Error",
    "Target": "Ability3"
  }
}

WCHud_Error

Flashes a red error state for a HUD slot.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"WCHud_Error"`
`Target`	string	Yes	none	Slot key. Supported aliases include `MainAbility`, `Reload`, and `Attachments`

Example

{
  "Type": "WCHud_Error",
  "Target": "MainAbility"
}

Full Weapon Chain Example

This example checks for a scope attachment, updates the HUD state, and flashes the secondary slot when zoom is unavailable.

{
  "Type": "Hyguns_AttachmentsInstalled",
  "AttachmentTypes": ["Scope"],
  "Next": {
    "Type": "WCHud_SetState",
    "State": "ZoomAvailable",
    "Value": true,
    "Next": {
      "Type": "Scope_Zoom"
    }
  },
  "Failed": {
    "Type": "WCHud_SetState",
    "State": "ZoomAvailable",
    "Value": false,
    "Next": {
      "Type": "WCHud_Error",
      "Target": "Secondary"
    }
  }
}

This example blocks shooting while a manual primary cooldown is active.

{
  "Type": "WCHud_HasCooldown",
  "Target": "Primary",
  "Value": false,
  "Next": {
    "Type": "Hyguns_CanShoot",
    "Next": {
      "Type": "Hyguns_Shoot",
      "Next": {
        "Type": "WCHud_SetCooldown",
        "Target": "Primary",
        "Duration": 0.25
      }
    },
    "Failed": {
      "Type": "WCHud_Error",
      "Target": "Primary"
    }
  },
  "Failed": {
    "Type": "WCHud_Error",
    "Target": "Primary"
  }
}

Scope_Zoom

Toggles scope zoom mode.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Scope_Zoom"`
`OverlayTexturePath`	string	No	omitted	Overlay texture asset path
`MaxDistance`	number	No	zoom default	Max camera distance
`MinDistance`	number	No	zoom default	Min camera distance
`DefaultZoomMultiplier`	number	No	zoom default	Base zoom multiplier
`MaxZoomMultiplier`	number	No	zoom default	Max zoom multiplier
`ZoomMultiplierStep`	number	No	zoom default	Zoom step size

Full Example

{
  "Type": "Scope_Zoom",
  "OverlayTexturePath": "UI/Scope/ScopeOverlay.png",
  "MaxDistance": 20.0,
  "MinDistance": 1.0,
  "DefaultZoomMultiplier": 1.0,
  "MaxZoomMultiplier": 2.5,
  "ZoomMultiplierStep": 0.5
}

Typical Usage

{
  "Type": "Scope_Zoom"
}

Scope_Step_Zoom

Cycles to the next zoom step while already scoped.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Scope_Step_Zoom"`

Full Example

{
  "Type": "Scope_Step_Zoom"
}

Typical Usage

{
  "Type": "Scope_Step_Zoom"
}

Scope_Zoom_In

Increases zoom step while scoped.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Scope_Zoom_In"`

Full Example

{
  "Type": "Scope_Zoom_In"
}

Typical Usage

{
  "Type": "Scope_Zoom_In"
}

Scope_Zoom_Out

Decreases zoom step while scoped.

Fields

Field	Type	Required	Default	Accepted Values / Meaning
`Type`	string	Yes	none	Must be `"Scope_Zoom_Out"`

Full Example

{
  "Type": "Scope_Zoom_Out"
}

Typical Usage

{
  "Type": "Scope_Zoom_Out"
}

Interactions

HyGuns Custom Interactions

Table of Contents

Interaction Naming

Hyguns_Shoot

Fields

Full Example

Typical Usage

Hyguns_Reload

Fields

Full Example

Typical Usage

Hyguns_ReloadCheck

Fields

Full Example

Typical Usage

Hyguns_ShootCheck

Fields

Full Example

Typical Usage

Hyguns_CanShoot

Fields

Full Example

Typical Usage

Hyguns_Heat

Fields

Full Example

Typical Usage

Hyguns_CheckHeat

Fields

Full Example

Typical Usage

Hyguns_SetHeat

Fields

Full Example

Typical Usage

Hyguns_AddHeat

Fields

Full Example

Typical Usage

Hyguns_UseAmmo

Fields

Full Example

Typical Usage

Hyguns_CheckAmmo

Fields

Full Example

Typical Usage

Hyguns_CheckAmmoType

Fields

Full Example

Typical Usage

Hyguns_SetAmmoType

Fields

Full Example

Typical Usage

Hyguns_SetAmmo

Fields

Full Example

Typical Usage

Hyguns_AddAmmo

Fields

Full Example

Typical Usage

Hyguns_SyncAmmo

Fields

Full Example

Hyguns_OpenAttachments

Fields

Full Example

Hyguns_AttachmentsInstalled

Fields

Full Example

Hyguns_PlayWeaponFireSound

Fields

Full Example

Hyguns_SetItemState

Fields

Full Example

Hyguns_CheckZoom