WeaponCustomHUD

WeaponCustomHUD is a configurable weapon input HUD system for Hytale item assets.

It allows asset creators and plugin developers to build custom weapon HUDs without replacing the entire default interface. Each weapon can define its own visible actions, icons, cooldowns, states, scale, placement, and screen position directly through JSON.

Built-in Support for Asset Creators

If you create weapon assets or asset packs, you can include a preconfigured WeaponCustomHUD block directly in your item JSON.

When WeaponCustomHUD is installed, the weapon will automatically use the configured HUD.

When WeaponCustomHUD is not installed, the additional JSON block is simply ignored. It will not prevent the item from loading or affect its normal behavior.

This allows asset creators to ship weapons with optional WeaponCustomHUD support without making the plugin a hard dependency.

⚠️ Important Hytale UI Disclaimer

Do not add the standard weapon category: "Categories": ["Weapons"]

Hytale uses this category to display its built-in weapon ability UI. When it is present, the default Hytale UI will be rendered on top of WeaponCustomHUD.

There is currently no other way to disable the built-in weapon UI. To use WeaponCustomHUD without overlapping interfaces, the item must not include the standard Weapons category.

Features

Configurable HUD for individual weapon items
Support for Primary, Secondary, Ability 1–3, Use and Dodge slots
Custom icons for every ability
Dynamic icons based on weapon state
Active and inactive slot states
Built-in cooldown progress display
Custom HUD scale and screen placement
Reusable JSON presets
Error flashes for failed interactions
Runtime state and cooldown control through JSON interactions
Public API for integration with other plugins

Made for Asset Creators

Most HUD behavior can be configured directly inside item JSON files.

WeaponCustomHUD also provides custom interactions for:

setting HUD states;
starting and resetting cooldowns;
checking active cooldowns;
displaying error feedback.

This means many custom weapon interfaces can be created without writing an additional plugin.

Plugin Integration

Other plugins can register their own dynamic HUD states and cooldown providers through the public WeaponCustomHUD API.

This can be used to display information such as:

reloading;
available ammunition;
aiming or scoping;
overheating;
attachment availability;
custom ability progress.

Documentation

Full configuration reference, JSON examples, interaction documentation, presets, and API usage:

WeaponCustomHUD Documentation

Basic Configuration

{
  "WeaponCustomHUD": {
    "Enabled": true,
    "Preset": "MyWeaponHUD",
    "Scale": 1.0,
    "Placement": "BottomRight",
    "Position": [50, 40]
  }
}

WeaponCustomHUD is designed to work as a standalone HUD system and can also be integrated with larger weapon plugins and custom asset packs.